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

Crea una tarea de distribución de dispositivos. De forma predeterminada, se distribuye el producto al que pertenecen los dispositivos.

Notas de uso

Para distribuir dispositivos, siga estos pasos:

Llame a esta operación de forma asíncrona para crear una tarea de distribución de dispositivos y obtener el parámetro JobId.
Use JobId como parámetro de solicitud y llame repetidamente a la operación QueryDeviceDistributeJob para obtener el parámetro Status.

Nota
Controle la frecuencia de las llamadas según el límite de QPS de la operación QueryDeviceDistributeJob.

La tarea de distribución finaliza cuando el parámetro Status devuelve alguno de los siguientes valores:

2: La tarea se completó. Este valor no indica que los dispositivos se hayan distribuido. Para obtener el resultado de distribución de cada dispositivo, continúe con el siguiente paso.
3: La distribución se interrumpió inesperadamente. Una vez resuelto el error, inicie nuevamente una tarea de distribución de dispositivos.

Use el valor de JobId devuelto en el paso 1 como parámetro de solicitud y llame a la operación QueryDeviceDistributeDetail para obtener el parámetro File, que contiene la URL del archivo con los resultados de la distribución.

Nota
La URL del archivo tiene una validez de 10 minutos.
Descargue los resultados de la distribución desde la URL del archivo. El parámetro Code indica si un dispositivo se distribuyó correctamente. Un valor de 200 para Code indica éxito.

Si la distribución falla, repita los pasos anteriores para volver a distribuir los dispositivos.

Límites

Esta operación solo puede invocarse mediante el siguiente endpoint: iot.cn-shanghai.aliyuncs.com.
No se admite la distribución de dispositivos entre cuentas.
Cada cuenta de Alibaba Cloud puede crear un máximo de 10 tareas para distribuir productos o dispositivos. Para más información sobre cómo crear una tarea de distribución de productos, consulte CreateProductDistributeJob.
Cada cuenta de Alibaba Cloud puede ejecutar un máximo de 2 consultas por segundo (QPS).

Nota
Los usuarios 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 invocar 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í	CreateDeviceDistributeJob	La operación que desea ejecutar. Establezca el valor en CreateDeviceDistributeJob.
DeviceName.N	RepeatList	Sí	RepeatList	Los nombres de los dispositivos por distribuir. Puede especificar un máximo de 10,000 nombres de dispositivos.
ProductKey	String	Sí	a1BwAGV****	El ProductKey del producto al que pertenece el dispositivo.
SourceInstanceId	String	Sí	iot-060***	El ID de la instancia de origen a la que pertenece el dispositivo. Los ID de las instancias públicas en diferentes regiones: China (Shanghai): iotx-oxssharez200. Japan (Tokyo): iotx-oxssharez300. Singapore (Singapore): iotx-oxssharez400. US (Silicon Valley): iotx-oxssharez500. US (Virginia): iotx-oxssharez600. Germany (Frankfurt): iotx-oxssharez700. Los ID de las instancias Enterprise Edition: 1. Inicie sesión en la consola de IoT Platform. Seleccione una región en la lista desplegable de la esquina superior izquierda de la barra de navegación superior. 2. En la página Overview, haga clic en el nombre de la instancia. En la página Instance Details, consulte el ID de la instancia en la sección Basic Information.
Strategy	Integer	Sí	0	La directiva de distribución. Valor predeterminado: 0. 0: distribuye dispositivos a instancias en una región específica. 1: configura ID de instancia en varias regiones y distribuye los dispositivos a las regiones más cercanas según sus direcciones IP.
TargetInstanceConfig.N.TargetInstanceId	String	Sí	iot-cn-6ja***	La configuración de la instancia de destino a la que se distribuye el dispositivo. Para obtener información sobre los ID de instancia, consulte la descripción del parámetro SourceInstanceId. Si el valor del parámetro Strategy es 1, puede especificar varios ID de instancia. Si el valor del parámetro Strategy es 0, solo puede especificar un ID de instancia.
TargetUid	String	No	198***	El ID de la cuenta de Alibaba Cloud a la que pertenece el dispositivo. Para consultar el ID de la cuenta, inicie sesión en la consola de IoT Platform, haga clic en la foto de perfil y vaya a la página Security Settings. Debe especificar como mínimo uno de los siguientes parámetros: TargetUid o TargetAliyunId.
TargetAliyunId	String	No	io****@example.com	La cuenta de Alibaba Cloud a la que pertenece el dispositivo. Para consultar la cuenta, inicie sesión en la consola de IoT Platform, haga clic en la foto de perfil y vaya a la página Security Settings. Debe especificar como mínimo uno de los siguientes parámetros: TargetUid o TargetAliyunId.

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 invocar esta operación. Para más información, consulte Parámetros de solicitud 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 más información, consulte Códigos de error.
ErrorMessage	String	A system exception occurred.	El mensaje de error devuelto si la llamada falla.
JobId	String	UbmsMHmkqv0PiAG****010001	El ID de tarea único global devuelto si la llamada se ejecuta correctamente.
RequestId	String	E55E50B7-40EE-4B6B-8BBE-D3ED55CCF565	El ID de la solicitud.
Success	Boolean	true	Indica si la llamada se ejecutó correctamente. true: La llamada se ejecutó correctamente. false: La llamada falló.

Ejemplos

Solicitudes de ejemplo

http(s)://iot.cn-shanghai.aliyuncs.com/?Action=CreateDeviceDistributeJob
&DeviceName.1=RepeatList
&ProductKey=a1BwAGV****
&SourceInstanceId=iot-060***
&Strategy=0
&TargetInstanceConfig.1.TargetInstanceId=iot-cn-6ja***
&TargetAliyunId=io****@example.com
&<Common request parameters>

Respuestas exitosas de ejemplo

Formato XML

<CreateDeviceDistributeJobResponse>
  <RequestId>E55E50B7-40EE-4B6B-8BBE-D3ED55CCF565</RequestId>
  <JobId>UbmsMHmkqv0PiAG****010001</JobId>
  <Success>true</Success>
</CreateDeviceDistributeJobResponse>

Formato JSON

{
    "RequestId": "E55E50B7-40EE-4B6B-8BBE-D3ED55CCF565",
    "JobId": "UbmsMHmkqv0PiAG****010001",
    "Success": true
}

Códigos de error

Para obtener una lista de códigos de error, visite el Centro de errores de API.