CreateOTADynamicUpgradeJob - IoT Platform - Centro de documentación de Alibaba Cloud

Crea un lote de actualización dinámica.

Notas de uso

Al llamar a la operación CreateOTAFirmware, puede especificar que no es necesario verificar un paquete de actualización. De lo contrario, asegúrese de que el paquete esté verificado antes de llamar a la operación CreateOTADynamicUpgradeJob para crear un lote de actualización. Para obtener más información sobre cómo crear una tarea de verificación de paquetes de actualización, consulte CreateOTAVerifyJob.
Cada dispositivo solo puede tener el estado pending o actualizándose en una única tarea de actualización. Si inicia otra tarea para un dispositivo que ya se encuentra en alguno de estos estados, la nueva tarea fallará.
Cada paquete de actualización solo puede tener una tarea de actualización dinámica en estado de running.
Si un dispositivo está incluido en directivas de actualización dinámica de diferentes paquetes, ejecutará la actualización dinámica más reciente.
Una vez creada una tarea de actualización dinámica, el sistema genera automáticamente la directiva correspondiente. Puede llamar a la operación CancelOTAStrategyByJob para cancelar dicha directiva.
Solo los dispositivos en la región China (Shanghai) pueden descargar paquetes de actualización mediante el protocolo MQTT.

Límites de QPS

Cada cuenta de Alibaba Cloud puede ejecutar un máximo de 20 consultas por segundo (QPS).

Nota

Los usuarios de Resource Access Management (RAM) de una cuenta de Alibaba Cloud comparten la cuota de dicha cuenta.

Depuración

OpenAPI Explorer calcula automáticamente el valor de la firma. Para su comodidad, le recomendamos llamar a esta operación desde OpenAPI Explorer. Esta herramienta genera dinámicamente el código de ejemplo de la operación para diferentes SDK.

Parámetros de solicitud

Parámetro	Tipo	Obligatorio	Ejemplo	Descripción
Action	String	Sí	CreateOTADynamicUpgradeJob	La operación que desea ejecutar. Establezca el valor en CreateOTADynamicUpgradeJob.
FirmwareId	String	Sí	nx3xxVvFdwvn6dim50PY03****	El ID del paquete de actualización. Se devuelve un ID de paquete de actualización cuando llama a la operación CreateOTAFirmware para crear el paquete. También puede llamar a la operación ListOTAFirmware para obtener el ID.
ProductKey	String	Sí	a1Le6d0****	La clave ProductKey del producto al que pertenece el paquete de actualización. Una clave ProductKey es el identificador único de un producto en IoT Platform. Puede consultar la información de todos los productos de la cuenta actual de Alibaba Cloud en la consola de IoT Platform o mediante la operación QueryProductList.
Tag.N.Key	String	Sí	key1	La clave de la etiqueta del lote de actualización. Debe tener entre 1 y 30 caracteres y puede contener letras, dígitos y puntos (.). Puede agregar hasta 10 etiquetas por cada lote de actualización. Las etiquetas de un lote de actualización se envían a los dispositivos cuando IoT Platform envía notificaciones de actualización. Nota Las etiquetas del lote de actualización son opcionales. Si desea especificar una etiqueta, debe especificar los parámetros Tag.N.Value y Tag.N.Key en conjunto.
Tag.N.Value	String	Sí	value1	El valor de la etiqueta del lote de actualización. Debe tener entre 1 y 1,024 caracteres. Puede agregar hasta 10 etiquetas por cada lote de actualización. La longitud total combinada de claves y valores de etiqueta de todos los lotes no puede exceder los 4,096 caracteres. Nota Las etiquetas del lote de actualización son opcionales. Si desea especificar una etiqueta, debe especificar los parámetros Tag.N.Value y Tag.N.Key en conjunto.
IotInstanceId	String	No	iot-cn-0pp1n8t****	El ID de la instancia. Puede consultar el ID de una instancia en la página Overview de la consola de IoT Platform. Importante Si su instancia tiene un ID, debe especificarlo en este parámetro. De lo contrario, la llamada fallará. Si no se ha generado ningún ID para su instancia, no es necesario configurar este parámetro. Para obtener más información, consulte Descripción general.
SrcVersion.N	RepeatList	No	V1.0.1	La lista de versiones de firmware por actualizar. Si especifica este parámetro, no especifique los parámetros GroupId y GroupType. Si no especifica este parámetro, debe especificar los parámetros GroupId y GroupType. Nota Si utiliza paquetes de actualización diferencial para tareas de actualización dinámica basadas en versiones, el valor de este parámetro debe coincidir con el de SrcVersion. Si utiliza paquetes de actualización diferencial para tareas de actualización dinámica en grupos dinámicos, no es necesario especificar este parámetro. Puede llamar a la operación QueryDeviceDetail y consultar el parámetro FirmwareVersion en la respuesta. Los números de versión deben ser únicos en la lista. Puede especificar un máximo de 30 números de versión.
RetryInterval	Integer	No	60	El intervalo de reintento automático si falla la actualización de un dispositivo. Unidad: minutos. Valores válidos: 0: Se realiza un reintento automático inmediatamente. 10: Se realiza un reintento automático después de 10 minutos. 30: Se realiza un reintento automático después de 30 minutos. 60: Se realiza un reintento automático después de 60 minutos (1 hora). 1440: Se realiza un reintento automático después de 1,440 minutos (24 horas). Importante El valor del parámetro RetryInterval debe ser menor que el del parámetro TimeoutInMinutes. Ejemplos: Si el valor del parámetro TimeoutInMinutes se establece en 60, el valor máximo del parámetro RetryInterval es 30. Si el valor del parámetro TimeoutInMinutes se establece en 1440, el valor máximo del parámetro RetryInterval es 60. Si el valor del parámetro RetryInterval se establece en 1440, se recomienda no especificar el parámetro TimeoutInMinutes. Si una actualización supera el tiempo de espera, no se realizará ningún reintento. Si no especifica este parámetro, no se realizará ningún reintento.
RetryCount	Integer	No	1	El número de reintentos automáticos. Si especifica el parámetro RetryInterval, debe especificar también este parámetro. Valores válidos: 1: reintenta una vez. 2: reintenta dos veces. 5: reintenta cinco veces.
TimeoutInMinutes	Integer	No	1440	El período de tiempo de espera de la actualización. Si el dispositivo no se actualiza dentro del período especificado, se produce un error de tiempo de espera. Unidad: minutos. Valores válidos: de 1 a 1440. Nota El período de tiempo de espera comienza cuando el dispositivo especificado reporta el progreso de la actualización por primera vez. Durante la actualización, el paquete podría enviarse repetidamente al dispositivo debido a que este se conecta y desconecta varias veces; sin embargo, la hora de inicio del período de actualización permanece sin cambios. Si una actualización falla por tiempo de espera agotado, no se activa ningún reintento. Si no especifica este parámetro, no se producirán errores de tiempo de espera.
MaximumPerMinute	Integer	No	1000	El número máximo de dispositivos a los que se envía la URL de descarga del paquete de actualización por minuto. Valores válidos: de 10 a 10000. Valor predeterminado: 10000.
OverwriteMode	Integer	No	2	Especifica si se debe sobrescribir la tarea de actualización anterior. Valor predeterminado: 1. Valores válidos: 1: La tarea de actualización anterior no se sobrescribe. Si un dispositivo ya tiene una tarea asignada, se ejecuta la anterior. 2: La tarea de actualización anterior se sobrescribe. Solo se ejecuta la tarea actual. En este caso, no puede establecer MultiModuleMode en true. Nota La tarea de actualización en curso no se sobrescribe.
DynamicMode	Integer	No	1	El modo de actualización dinámica. Valor predeterminado: 1. Valores válidos: 1: actualiza constantemente los dispositivos que cumplen las condiciones. 2: actualiza solo los dispositivos que posteriormente reportan las versiones de firmware más recientes.
NeedPush	Boolean	No	true	Especifica si se deben enviar automáticamente las tareas de actualización desde IoT Platform a los dispositivos. Valor predeterminado: true. Valores válidos: true: Después de crear un lote de actualización, IoT Platform envía automáticamente las tareas a los dispositivos en línea especificados. En este caso, un dispositivo aún puede iniciar una solicitud para obtener la información sobre la tarea de actualización over-the-air (OTA) desde IoT Platform. false: El dispositivo debe iniciar una solicitud para obtener la información sobre la tarea de actualización OTA desde IoT Platform.
NeedConfirm	Boolean	No	false	Especifica si se debe controlar la actualización mediante una aplicación móvil. Debe desarrollar la aplicación móvil según sea necesario. Valor predeterminado: false. Valores válidos: false: El dispositivo obtiene la información sobre la tarea de actualización OTA según el parámetro NeedPush. true: Para realizar una actualización OTA en un dispositivo, debe confirmar la actualización mediante su aplicación móvil. Posteriormente, el dispositivo puede obtener la información sobre la tarea de actualización OTA según el parámetro NeedPush.
GroupId	String	No	IwOwQj7DJ***	El ID del grupo. Si especifica este parámetro, también debe especificar el parámetro GroupType. En este caso, no especifique el parámetro SrcVersion.N. Si no especifica este parámetro, no es necesario especificar el parámetro GroupType. En este caso, debe especificar el parámetro SrcVersion.N. Puede llamar a la operación QueryDeviceGroupList para consultar el parámetro GroupId.
GroupType	String	No	LINK_PLATFORM_DYNAMIC	El tipo de grupo. Valor válido: LINK_PLATFORM_DYNAMIC. Si especifica este parámetro, también debe especificar el parámetro GroupId. En este caso, no especifique el parámetro SrcVersion.N. Si no especifica este parámetro, no es necesario especificar el parámetro GroupId. En este caso, debe especificar el parámetro SrcVersion.N.
DownloadProtocol	String	No	HTTPS	El protocolo de descarga del paquete de actualización. Valores válidos: HTTPS y MQTT. Valor predeterminado: HTTPS. Una vez que el dispositivo recibe la información del paquete enviada por IoT Platform, utiliza este protocolo para descargarlo. Importante Si necesita descargar el paquete de actualización mediante MQTT, tenga en cuenta los siguientes puntos: Su servicio debe estar desplegado en la región China (Shanghai). El paquete de actualización OTA solo puede contener un archivo y su tamaño no puede superar los 16 MB. Debe utilizar la versión más reciente de Link SDK for C para desarrollar las funciones del dispositivo que permitan realizar actualizaciones OTA y descargar archivos mediante MQTT. Para obtener más información, consulte Código de ejemplo.
MultiModuleMode	Boolean	No	false	Especifica si el dispositivo admite actualizaciones simultáneas de varios módulos. Valor predeterminado: false. Valores válidos: false true: En este caso, no establezca OverwriteMode en 2. Las tareas de actualización para el mismo módulo se sobrescriben, pero las tareas en curso no. Las tareas de actualización de los módulos son independientes entre sí. Importante Solo se admiten instancias Enterprise Edition y nuevas instancias públicas. Debe utilizar Link SDK for C 4.x para desarrollar el dispositivo. Si inicia un lote de actualización dinámica basado en grupos, las configuraciones de MultiModuleMode y OverwriteMode deben coincidir con las del lote de actualización dinámica existente del grupo. Para obtener más información, consulte Descripción general.

Además de los parámetros específicos de la operación mencionados anteriormente, debe especificar los parámetros de solicitud comunes al llamar a esta operación. Para obtener más información, consulte Parámetros comunes.

Parámetros de respuesta

Parámetro	Tipo	Ejemplo	Descripción
Code	String	iot.system.SystemException	El código de error devuelto si la llamada falla. Para obtener más información, consulte Códigos de error.
Data	Struct		La información del lote de actualización devuelta si la llamada es exitosa. Para obtener más información, consulte Data.
JobId	String	XUbmsMHmkqv0PiAG****010001	El identificador único del lote de actualización.
UtcCreate	String	2019-05-10T02:18:53.000Z	La hora en que se creó el lote de actualización. La hora se muestra en formato UTC.
ErrorMessage	String	A system exception occurred.	El mensaje de error devuelto si la llamada falla.
RequestId	String	9F41D14E-CB5F-4CCE-939C-057F39E688F5	El ID de la solicitud.
Success	Boolean	true	Indica si la llamada fue exitosa. true: La solicitud fue exitosa. false: La solicitud falló.

Ejemplos

Solicitudes de ejemplo

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

Respuesta exitosa de ejemplo

XML formato

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

JSON formato

{
  "Data": {
    "JobId": "XUbmsMHmkqv0PiAG****010001",
    "UtcCreate": "2019-05-10T02:18:53.000Z"
  },
  "RequestId": "9F41D14E-CB5F-4CCE-939C-057F39E688F5",
  "Success": true
}

Códigos de error

Para obtener una lista de códigos de error, consulte Códigos de error del servicio.