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

Cree un lote de actualización estática.

Notas de uso

Si al llamar a la operación CreateOTAFirmware especificó que no es necesario verificar un paquete de actualización, asegúrese de que el paquete se verifique antes de llamar a la operación CreateOTAStaticUpgradeJob 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.
En cada llamada puede iniciar tareas de actualización para un máximo de 200 dispositivos. Si utiliza un archivo de lista de dispositivos, puede iniciar tareas de actualización para un máximo de 1,000,000 de dispositivos. No obstante, debe llamar a la operación GenerateDeviceNameListURL para generar una URL del archivo de lista de dispositivos. Posteriormente, siga las indicaciones para cargar dicho archivo.
Cuando inicia tareas de actualización para varios dispositivos, se omiten aquellos que ya tienen instalada la versión de firmware de destino.
Cada dispositivo solo puede tener el estado pendiente o en actualización dentro de una única tarea de actualización. Si inicia otra tarea de actualización para un dispositivo que se encuentra en estado pendiente o en actualización, la nueva tarea fallará.
Puede crear varios lotes de actualización estática mediante un solo paquete de actualización.
La descarga de paquetes de actualización mediante el protocolo MQTT solo es compatible en la región China (Shanghai).

、华北2（北京）和华南1（深圳）

Límites

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 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í	CreateOTAStaticUpgradeJob	La operación que desea realizar. Establezca el valor en CreateOTAStaticUpgradeJob.
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 de actualización. 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. La clave 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 les envía notificaciones de actualización. Nota Las etiquetas del lote de actualización son opcionales. Si desea especificar una etiqueta, debe definir los parámetros Tag.N.Value y Tag.N.Key como un par.
Tag.N.Value	String	Sí	value1	El valor de la etiqueta del lote de actualización. El valor debe tener entre 1 y 1,024 caracteres. Puede agregar hasta 10 etiquetas por cada lote de actualización. La longitud total combinada de las claves y valores de etiqueta de todos los lotes de actualización no puede exceder los 4,096 caracteres. Nota Las etiquetas del lote de actualización son opcionales. Si desea especificar una etiqueta, debe definir los parámetros Tag.N.Value y Tag.N.Key como un par.
TargetSelection	String	Sí	ALL	El alcance del lote de actualización. Valores válidos: ALL: actualiza todos los dispositivos. SPECIFIC: actualiza dispositivos específicos. GRAY: realiza una actualización gradual. GROUP: actualiza grupos específicos.
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. Si no especifica el ID de la instancia, la llamada fallará. Si su instancia no tiene una página Overview o no se ha generado un ID, no necesita configurar este parámetro. Para obtener más información, consulte Overview.
SrcVersion.N	RepeatList	No	V1.0.1	La lista de versiones de firmware que se actualizarán. Nota Este parámetro está disponible si establece el parámetro TargetSelection en `ALL` o `GRAY`. Si utiliza un paquete de actualización diferencial para realizar una actualización completa o gradual, el valor de este parámetro debe coincidir con el valor del parámetro SrcVersion. Este parámetro no está disponible si establece el parámetro TargetSelection en `SPECIFIC` o `GROUP`. 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 dentro de la lista. Puede especificar un máximo de 10 números de versión.
ScheduleTime	Long	No	1577808000000	La hora de inicio de la actualización OTA (over-the-air). La hora programada debe situarse entre 5 minutos y 7 días después de la hora actual. El valor debe ser una marca de tiempo de 13 dígitos. Si no especifica este parámetro, la actualización comienza inmediatamente.
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 de inmediato. 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 valor 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, también debe especificar 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, es posible que el paquete se envíe repetidamente al dispositivo porque este se conecta y desconecta varias veces. La hora de inicio del período de actualización permanece sin cambios. Si una actualización falla debido a un 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.
GrayPercent	String	No	33.33	La proporción de la actualización gradual. El valor es un porcentaje en formato de cadena. Admite hasta tres decimales. El número calculado de dispositivos se redondea hacia abajo al entero más cercano. Debe especificar como mínimo un dispositivo para una actualización gradual. Por ejemplo, si establece la proporción de actualización gradual en 33.33 para 100 dispositivos, el número de dispositivos que se actualizarán será 33. Debe especificar este parámetro si establece el parámetro TargetSelection en `GRAY`.
TargetDeviceName.N	RepeatList	No	deviceName1	La lista de nombres de dispositivos. Nota Si establece el parámetro TargetSelection en `SPECIFIC`, debe especificar este parámetro o el parámetro DnListFileUrl. No puede especificar ambos parámetros simultáneamente. Si utiliza un paquete de actualización diferencial para realizar una actualización específica, la versión del módulo OTA del dispositivo que se va a actualizar debe coincidir con el valor del parámetro SrcVersion. Puede llamar a la operación QueryDeviceDetail y consultar el parámetro FirmwareVersion en la respuesta. Los dispositivos de la lista deben pertenecer al mismo producto que el paquete de actualización. Los nombres de los dispositivos deben ser únicos dentro de la lista. La lista puede contener hasta 200 nombres de dispositivos.
ScheduleFinishTime	Long	No	1577909000000	La hora de finalización de la actualización. La hora de finalización debe situarse entre 1 hora y 30 días después de la hora de inicio especificada por el parámetro ScheduleTime. El valor debe ser una marca de tiempo de 13 dígitos. Si no especifica este parámetro, la actualización no finalizará de manera forzada.
OverwriteMode	Integer	No	1	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 de actualización, se ejecuta la tarea anterior. 2: la tarea de actualización anterior se sobrescribe. Solo se ejecuta la tarea de actualización actual. En este caso, no puede establecer MultiModuleMode en true. Nota La tarea de actualización que se encuentra en curso no se sobrescribe.
DnListFileUrl	String	No	https://iotx-ota.oss-cn-shanghai.aliyuncs.com/ota/65dfcda0473be29836dfde585472**/ck2nfzljo00023g7kysg0**.bin	La URL del archivo de lista de dispositivos que se utiliza para realizar una actualización específica. Nota Si establece el parámetro TargetSelection en `SPECIFIC`, debe especificar este parámetro o el parámetro TargetDeviceName.N. No puede especificar ambos parámetros simultáneamente. Puede llamar a la operación GenerateDeviceNameListURL para generar una URL de archivo. Posteriormente, siga las indicaciones para cargar el archivo de lista de dispositivos. Durante una actualización completa, se omiten los dispositivos que ya se han actualizado. Durante una actualización delta, se omiten los dispositivos que ya se han actualizado y aquellos cuyos números de versión inicial difieren del paquete de actualización.
NeedPush	Boolean	No	true	Especifica si IoT Platform debe enviar automáticamente las tareas de actualización 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 de actualización a los dispositivos en línea especificados. En este caso, un dispositivo aún puede iniciar una solicitud para obtener la información de la tarea de actualización OTA desde IoT Platform. false: el dispositivo debe iniciar una solicitud para obtener la información de 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 sus necesidades. Valor predeterminado: false. Valores válidos: false: el dispositivo obtiene la información de 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. Después, el dispositivo podrá obtener la información de la tarea de actualización OTA según el parámetro NeedPush.
GroupId	String	No	CtjzCkNuOx***	El ID del grupo. Si establece el parámetro TargetSelection en `GROUP`, debe especificar este parámetro y el parámetro GroupType. Puede llamar a la operación QueryDeviceGroupList para consultar el parámetro GroupId.
GroupType	String	No	LINK_PLATFORM	El tipo de grupo. Valor válido: LINK_PLATFORM. Si establece el parámetro TargetSelection en `GROUP`, debe especificar este parámetro y el parámetro GroupId.
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 de actualización enviada por IoT Platform, utiliza este protocolo para descargar el paquete. Importante Si necesita descargar el paquete de actualización mediante MQTT, tenga en cuenta lo siguiente: Su servicio debe estar desplegado en la región China (Shanghai), China (Beijing) o China (Shenzhen). El paquete de actualización OTA solo puede contener un archivo, y el tamaño del archivo 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 permiten realizar actualizaciones OTA y descargar archivos mediante MQTT. Para obtener más información, consulte Sample code.
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 del mismo módulo se sobrescriben. Las tareas de actualización en curso no se sobrescriben. Las tareas de actualización de los distintos módulos no se afectan entre sí. Importante Solo es compatible con instancias Enterprise Edition y nuevas instancias públicas. Debe utilizar Link SDK for C 4.x para desarrollar el dispositivo. Para obtener más información, consulte Overview.

Además de los parámetros de solicitud 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 Common parameters.

Parámetros de respuesta

Parámetro	Tipo	Ejemplo	Descripción
Code	String	MissingFirmwareId	El código de error devuelto si la llamada falla. Para obtener más información, consulte Error codes.
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	wahVIzGkCMuAUE2gDERM02****	El identificador único del lote de actualización.
UtcCreate	String	2019-11-04T06:22:19.566Z	La hora en que se creó el lote de actualización. La hora se muestra en formato UTC.
ErrorMessage	String	FirmwareId is mandatory for this action.	El mensaje de error devuelto si la llamada falla.
RequestId	String	29EC7245-0FA4-4BB6-B4F5-5F04818FDFB1	El ID de la solicitud.
Success	Boolean	true	Indica si la llamada fue exitosa. Valores válidos: true: la solicitud fue exitosa. false: la solicitud falló.

Ejemplos

Solicitudes de ejemplo

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>

Respuestas exitosas de ejemplo

Formato XML

<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>

Formato JSON

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

Códigos de error

Para obtener una lista de códigos de error, consulte IoT Platform error codes.