CreateOTAStaticUpgradeJob - IoT Platform - Centre de documentation Alibaba Cloud

Notes d'utilisation

Si vous spécifiez qu'un package de mise à jour ne nécessite pas de vérification lors de l'appel à l'opération CreateOTAFirmware, assurez-vous que le package est vérifié avant d'appeler l'opération CreateOTAStaticUpgradeJob pour créer un lot de mise à jour. Pour plus d'informations sur la création d'une tâche de vérification de package, consultez l'opération CreateOTAVerifyJob.
Vous pouvez initier des tâches de mise à jour pour un maximum de 200 appareils par appel. Si vous utilisez un fichier de liste d'appareils, vous pouvez initier des tâches pour un maximum de 1 000 000 d'appareils. Vous devez toutefois appeler l'opération GenerateDeviceNameListURL afin de générer une URL pour le fichier de liste d'appareils, puis suivre les instructions pour télécharger ce fichier.
Lorsque vous lancez des tâches de mise à jour pour plusieurs appareils, ceux qui possèdent déjà la version cible du firmware sont ignorés.
Un appareil ne peut être en attente ou en cours de mise à jour que dans une seule tâche. Si vous tentez de lancer une autre tâche de mise à jour pour un appareil déjà dans l'un de ces états, la nouvelle tâche échoue.
Il est possible de créer plusieurs lots de mise à jour statiques à partir d'un seul package de mise à jour.
Le téléchargement des packages de mise à jour via le protocole MQTT n'est pris en charge que dans les régions Chine (Shanghai), Chine (Pékin) et Chine (Shenzhen).

Limites

Chaque compte Alibaba Cloud peut effectuer un maximum de 20 requêtes par seconde (QPS).

Remarque

Les utilisateurs RAM (Resource Access Management) d'un compte Alibaba Cloud partagent le quota de ce compte.

Débogage

OpenAPI Explorer calcule automatiquement la valeur de signature. Pour plus de commodité, nous vous recommandons d'appeler cette opération dans OpenAPI Explorer. Celui-ci génère dynamiquement l'exemple de code de l'opération pour différents SDK.

Paramètres de requête

Paramètre	Type	Obligatoire	Exemple	Description
Action	String	Oui	CreateOTAStaticUpgradeJob	L'opération que vous souhaitez effectuer. Définissez la valeur sur CreateOTAStaticUpgradeJob.
FirmwareId	String	Oui	nx3xxVvFdwvn6dim50PY03****	L'ID du package de mise à jour. Un ID de package de mise à jour est renvoyé lorsque vous appelez l'opération CreateOTAFirmware pour créer le package. Vous pouvez également appeler l'opération ListOTAFirmware pour obtenir cet ID.
ProductKey	String	Oui	a1Le6d0****	La ProductKey du produit auquel appartient le package de mise à jour. Une ProductKey est l'identifiant unique d'un produit dans IoT Platform. Vous pouvez consulter les informations sur tous les produits de votre compte Alibaba Cloud actuel dans la console IoT Platform ou en appelant l'opération QueryProductList.
Tag.N.Key	String	Oui	key1	La clé du tag du lot de mise à jour. La clé doit comporter entre 1 et 30 caractères et peut contenir des lettres, des chiffres et des points (.). Vous pouvez ajouter jusqu'à 10 tags par lot de mise à jour. Les tags d'un lot de mise à jour sont envoyés aux appareils lorsque IoT Platform leur transmet les notifications de mise à jour. Remarque Les tags de lot de mise à jour sont facultatifs. Si vous souhaitez spécifier un tag, vous devez renseigner les paramètres Tag.N.Value et Tag.N.Key par paire.
Tag.N.Value	String	Oui	value1	La valeur du tag du lot de mise à jour. La valeur doit comporter entre 1 et 1 024 caractères. Vous pouvez ajouter jusqu'à 10 tags par lot de mise à jour. La longueur totale des clés et des valeurs de tous les tags ne doit pas dépasser 4 096 caractères. Remarque Les tags de lot de mise à jour sont facultatifs. Si vous souhaitez spécifier un tag, vous devez renseigner les paramètres Tag.N.Value et Tag.N.Key par paire.
TargetSelection	String	Oui	ALL	La portée du lot de mise à jour. Valeurs valides : ALL : met à jour tous les appareils. SPECIFIC : met à jour des appareils spécifiques. GRAY : effectue une mise à jour progressive. GROUP : met à jour des groupes spécifiques.
IotInstanceId	String	Non	iot-cn-0pp1n8t****	L'ID de l'instance. Vous pouvez consulter l'ID d'une instance sur la page Overview de la console IoT Platform. Important Si votre instance possède un ID, vous devez le spécifier pour ce paramètre. À défaut, l'appel échouera. Si aucune page Overview ni aucun ID n'a été généré pour votre instance, il n'est pas nécessaire de configurer ce paramètre. Pour plus d'informations, consultez la rubrique Overview.
SrcVersion.N	RepeatList	Non	V1.0.1	La liste des versions de firmware à mettre à jour. Remarque Ce paramètre est disponible si vous définissez le paramètre TargetSelection sur `ALL` ou `GRAY`. Si vous utilisez un package de mise à jour différentiel pour effectuer une mise à jour complète ou progressive, la valeur de ce paramètre doit être identique à celle du paramètre SrcVersion. Ce paramètre n'est pas disponible si vous définissez le paramètre TargetSelection sur `SPECIFIC` ou `GROUP`. Vous pouvez appeler l'opération QueryDeviceDetail et consulter le paramètre FirmwareVersion dans la réponse. Les numéros de version doivent être uniques dans la liste. Vous pouvez spécifier un maximum de 10 numéros de version.
ScheduleTime	Long	Non	1577808000000	L'heure de début de la mise à jour OTA (Over-The-Air). L'heure planifiée doit se situer entre 5 minutes et 7 jours après l'heure actuelle. La valeur doit être un horodatage de 13 chiffres. Si vous ne spécifiez pas ce paramètre, la mise à jour démarre immédiatement.
RetryInterval	Integer	Non	60	L'intervalle de nouvelle tentative automatique en cas d'échec de la mise à jour d'un appareil. Unité : minutes. Valeurs valides : 0 : Une nouvelle tentative est effectuée immédiatement. 10 : Une nouvelle tentative est effectuée après 10 minutes. 30 : Une nouvelle tentative est effectuée après 30 minutes. 60 : Une nouvelle tentative est effectuée après 60 minutes (1 heure). 1440 : Une nouvelle tentative est effectuée après 1 440 minutes (24 heures). Important La valeur du paramètre RetryInterval doit être inférieure à celle du paramètre TimeoutInMinutes. Exemples : Si la valeur du paramètre TimeoutInMinutes est définie sur 60, la valeur maximale du paramètre RetryInterval est 30. Si la valeur du paramètre TimeoutInMinutes est définie sur 1440, la valeur maximale du paramètre RetryInterval est 60. Si la valeur du paramètre RetryInterval est définie sur 1440, nous vous recommandons de ne pas spécifier le paramètre TimeoutInMinutes. En cas de délai d'attente de la mise à jour, aucune nouvelle tentative n'est effectuée. Si vous ne spécifiez pas ce paramètre, aucune nouvelle tentative n'est effectuée.
RetryCount	Integer	Non	1	Le nombre de nouvelles tentatives automatiques. Si vous spécifiez le paramètre RetryInterval, vous devez également spécifier ce paramètre. Valeurs valides : 1 : une nouvelle tentative. 2 : deux nouvelles tentatives. 5 : cinq nouvelles tentatives.
TimeoutInMinutes	Integer	Non	1440	Le délai d'expiration de la mise à jour. Si l'appareil n'est pas mis à jour dans le délai imparti, une erreur de délai d'expiration se produit. Unité : minutes. Valeurs valides : 1 à 1440. Remarque Le délai d'expiration commence au moment où l'appareil spécifié soumet la progression de la mise à jour pour la première fois. Pendant la mise à jour, le package peut être envoyé plusieurs fois à l'appareil en raison de ses connexions et déconnexions successives. L'heure de début de la période de mise à jour reste inchangée. Si une mise à jour échoue en raison d'un délai d'expiration, aucune nouvelle tentative n'est déclenchée. Si vous ne spécifiez pas ce paramètre, aucune erreur de délai d'expiration ne se produit.
MaximumPerMinute	Integer	Non	1000	Le nombre maximal d'appareils auxquels l'URL de téléchargement du package de mise à jour est envoyée par minute. Valeurs valides : 10 à 10000. Valeur par défaut : 10000.
GrayPercent	String	Non	33,33	Le ratio de la mise à jour progressive. La valeur est un pourcentage au format chaîne. Elle peut comporter jusqu'à trois décimales. Le nombre calculé d'appareils est arrondi à l'entier inférieur. Vous devez spécifier au moins un appareil pour une mise à jour progressive. Par exemple, si vous définissez le ratio de mise à jour progressive sur 33,33 pour 100 appareils, le nombre d'appareils à mettre à jour sera de 33. Vous devez spécifier ce paramètre si vous définissez le paramètre TargetSelection sur `GRAY`.
TargetDeviceName.N	RepeatList	Non	deviceName1	La liste des noms d'appareils. Remarque Si vous définissez le paramètre TargetSelection sur `SPECIFIC`, vous devez spécifier ce paramètre ou le paramètre DnListFileUrl. Vous ne pouvez pas spécifier les deux paramètres simultanément. Si vous utilisez un package de mise à jour différentiel pour effectuer une mise à jour spécifique, la version du module OTA de l'appareil à mettre à jour doit être identique à la valeur du paramètre SrcVersion. Vous pouvez appeler l'opération QueryDeviceDetail et consulter le paramètre FirmwareVersion dans la réponse. Les appareils de la liste doivent appartenir au même produit que le package de mise à jour. Les noms d'appareils doivent être uniques dans la liste. La liste peut contenir jusqu'à 200 noms d'appareils.
ScheduleFinishTime	Long	Non	1577909000000	L'heure de fin de la mise à jour. L'heure de fin doit se situer entre 1 heure et 30 jours après l'heure de début spécifiée par le paramètre ScheduleTime. La valeur doit être un horodatage de 13 chiffres. Si vous ne spécifiez pas ce paramètre, la mise à jour n'est pas arrêtée de force.
OverwriteMode	Integer	Non	1	Indique s'il faut écraser la tâche de mise à jour précédente. Valeur par défaut : 1. Valeurs valides : 1 : La tâche de mise à jour précédente n'est pas écrasée. Si un appareil possède déjà une tâche de mise à jour, celle-ci est exécutée. 2 : La tâche de mise à jour précédente est écrasée. Seule la tâche de mise à jour actuelle est exécutée. Dans ce cas, vous ne pouvez pas définir MultiModuleMode sur true. Remarque La tâche de mise à jour en cours d'exécution n'est pas écrasée.
DnListFileUrl	String	Non	https://iotx-ota.oss-cn-shanghai.aliyuncs.com/ota/65dfcda0473be29836dfde585472**/ck2nfzljo00023g7kysg0**.bin	L'URL du fichier de liste d'appareils utilisé pour effectuer une mise à jour spécifique. Remarque Si vous définissez le paramètre TargetSelection sur `SPECIFIC`, vous devez spécifier ce paramètre ou le paramètre TargetDeviceName.N. Vous ne pouvez pas spécifier les deux paramètres simultanément. Vous pouvez appeler l'opération GenerateDeviceNameListURL pour générer une URL de fichier. Ensuite, suivez les instructions pour télécharger le fichier de liste d'appareils. Lors d'une mise à jour complète, les appareils déjà mis à jour sont ignorés. Lors d'une mise à jour différentielle, les appareils déjà mis à jour et ceux dont les versions initiales diffèrent du package de mise à jour sont ignorés.
NeedPush	Boolean	Non	true	Indique s'il faut envoyer automatiquement les tâches de mise à jour depuis IoT Platform vers les appareils. Valeur par défaut : true. Valeurs valides : true : Après la création d'un lot de mise à jour, IoT Platform envoie automatiquement les tâches de mise à jour aux appareils en ligne spécifiés. Dans ce cas, un appareil peut toujours initier une requête pour obtenir les informations sur la tâche de mise à jour OTA depuis IoT Platform. false : Un appareil doit initier une requête pour obtenir les informations sur la tâche de mise à jour OTA depuis IoT Platform.
NeedConfirm	Boolean	Non	false	Indique s'il faut contrôler la mise à jour via une application mobile. Vous devez développer l'application mobile selon vos besoins. Valeur par défaut : false. Valeurs valides : false : Un appareil obtient les informations sur la tâche de mise à jour OTA en fonction du paramètre NeedPush. true : Pour effectuer une mise à jour OTA sur un appareil, vous devez confirmer la mise à jour via votre application mobile. Ensuite, l'appareil peut obtenir les informations sur la tâche de mise à jour OTA en fonction du paramètre NeedPush.
GroupId	String	Non	CtjzCkNuOx***	L'ID du groupe. Si vous définissez le paramètre TargetSelection sur `GROUP`, vous devez spécifier ce paramètre ainsi que le paramètre GroupType. Vous pouvez appeler l'opération QueryDeviceGroupList pour interroger le paramètre GroupId.
GroupType	String	Non	LINK_PLATFORM	Le type de groupe. Valeur valide : LINK_PLATFORM. Si vous définissez le paramètre TargetSelection sur `GROUP`, vous devez spécifier ce paramètre ainsi que le paramètre GroupId.
DownloadProtocol	String	Non	HTTPS	Le protocole de téléchargement du package de mise à jour. Valeurs valides : HTTPS et MQTT. Valeur par défaut : HTTPS. Après réception des informations sur le package de mise à jour envoyées par IoT Platform, l'appareil utilise ce protocole pour télécharger le package. Important Si vous devez télécharger le package de mise à jour via MQTT, tenez compte des éléments suivants : Votre service doit être déployé dans la région Chine (Shanghai), Chine (Pékin) ou Chine (Shenzhen). Le package de mise à jour OTA ne peut contenir qu'un seul fichier, dont la taille ne doit pas dépasser 16 Mo. Vous devez utiliser la dernière version du Link SDK for C pour développer les fonctionnalités de l'appareil afin d'effectuer des mises à jour OTA et de télécharger des fichiers via MQTT. Pour plus d'informations, consultez les exemples de code.
MultiModuleMode	Boolean	Non	false	Indique si l'appareil prend en charge les mises à jour simultanées de plusieurs modules. Valeur par défaut : false. Valeurs valides : false true : Dans ce cas, ne définissez pas OverwriteMode sur 2. Les tâches de mise à jour pour le même module sont écrasées. Les tâches de mise à jour en cours d'exécution ne sont pas écrasées. Les tâches de mise à jour des modules n'ont pas d'incidence les unes sur les autres. Important Seules les instances Enterprise Edition et les nouvelles instances publiques sont prises en charge. Vous devez utiliser Link SDK for C 4.x pour développer l'appareil. Pour plus d'informations, consultez la rubrique Overview.

En plus des paramètres de requête spécifiques à l'opération mentionnés ci-dessus, vous devez spécifier les paramètres de requête communs lors de l'appel à cette opération. Pour plus d'informations, consultez la rubrique Paramètres communs.

Paramètres de réponse

Paramètre	Type	Exemple	Description
Code	String	MissingFirmwareId	Le code d'erreur renvoyé en cas d'échec de l'appel. Pour plus d'informations, consultez la rubrique Codes d'erreur.
Data	Struct		Les informations sur le lot de mise à jour renvoyées en cas de succès de l'appel. Pour plus d'informations, consultez Data.
JobId	String	wahVIzGkCMuAUE2gDERM02****	L'identifiant unique du lot de mise à jour.
UtcCreate	String	2019-11-04T06:22:19.566Z	L'heure de création du lot de mise à jour. L'heure est affichée au format UTC.
ErrorMessage	String	FirmwareId is mandatory for this action.	Le message d'erreur renvoyé en cas d'échec de l'appel.
RequestId	String	29EC7245-0FA4-4BB6-B4F5-5F04818FDFB1	L'ID de la requête.
Success	Boolean	true	Indique si l'appel a réussi. Valeurs valides : true : La requête a réussi. false : La requête a échoué.

Exemples

Exemple de requête

http(s)://iot.cn-shanghai.aliyuncs.com/?Action=CreateOTAStaticUpgradeJob
&FirmwareId=nx3xxVvFdwvn6dim50PY03****
&ProductKey=a1Le6d0****
&Tag.1.Key=key1
&Tag.1.Value=value1
&TargetSelection=ALL
&MaximumPerMinute=1000
&RetryCount=1
&RetryInterval=60
&TimeoutInMinutes=1440
&SrcVersion.1=V1.0.1
&<Common request parameters>

Exemple de réponse réussie

XML format

<CreateOTAStaticUpgradeJobResponse>
   <Data>
       <JobId>wahVIzGkCMuAUE2gDERM02****</JobId>
       <UtcCreate>2019-11-04T06:22:19.566Z</UtcCreate>
   </Data>
   <RequestId>29EC7245-0FA4-4BB6-B4F5-5F04818FDFB1</RequestId>
   <Success>true</Success>
</CreateOTAStaticUpgradeJobResponse>

JSON format

{
  "Data": {
    "JobId": "wahVIzGkCMuAUE2gDERM02****",
    "UtcCreate": "2019-11-04T06:22:19.566Z"
  },
  "RequestId": "29EC7245-0FA4-4BB6-B4F5-5F04818FDFB1",
  "Success": true
}

Codes d'erreur

Pour obtenir la liste des codes d'erreur, consultez la rubrique Codes d'erreur IoT Platform.