Custom task update message topic and Alink data format - IoT Platform

IoT Platform de Alibaba Cloud ofrece servicios de configuración y gestión para trabajos de dispositivo. Utiliza el protocolo Alink tanto para tareas de invocación de servicios por lotes como para tareas de establecimiento de propiedades por lotes en dispositivos. Este tema describe la personalización del tema de mensaje de actualización de tareas y el formato de datos Alink, lo que incluye la actualización del estado del trabajo de dispositivo, las solicitudes de información más reciente sobre trabajos por parte del dispositivo y las actualizaciones de estado de subtareas.

Contexto

Para implementar tareas personalizadas, debe desarrollar capacidades de gestión de tareas en el lado del dispositivo. Para operaciones detalladas, consulte Device Jobs.
En las tareas de invocación de servicios por lotes y de establecimiento de propiedades por lotes, si el Link SDK del dispositivo ya integró las funciones de invocación de servicios y establecimiento de propiedades, no es necesario desarrollar capacidades adicionales de gestión de tareas para ejecutar los trabajos de dispositivo.

Para conocer los métodos de integración de funciones de invocación de servicios y establecimiento de propiedades en el Link SDK del dispositivo, consulte los métodos de desarrollo de Thing Specification Language correspondientes al Link SDK en Device Access Overview.

Para obtener una explicación del protocolo Alink utilizado en la invocación de servicios y el establecimiento de propiedades, consulte Device Properties, Events, and Services.

Notificación de actualización de estado de trabajo de dispositivo

Nota

Las notificaciones se envían al dispositivo únicamente cuando el estado del trabajo cambia a in progress, canceled o deleted.

Sentido descendente (downstream).

Tema: /sys/${productKey}/${deviceName}/thing/job/notify.

Ejemplo de solicitud en formato Alink JSON:

{
    "id": "7542940",
    "version": "1.0",
    "params": {
        "task": {
            "taskId": "i5Ks6***pF010101",
            "status": "SENT",
            "jobDocument": {},
            "jobFile":{
                "signMethod":"Md5",
                "sign":"wssxff56dhdsd***",
                "fileUrl": "https://iotx-***.oss-cn-shanghai.aliyuncs.com/***.zip"
            }
        }
    }
}

Tabla 1. Descripción de parámetros de solicitud

Parámetro	Tipo	Descripción
id	String	The message ID. Must be a unique numeric string on the device. Valid values: 0 to 4294967295.
version	String	The protocol version. Set this parameter to 1.0.
params	Object	The business request parameters.
task	Object	Parámetros de la subtarea.
taskId	String	ID de la subtarea, que funciona como identificador único global.
status	String	Estado de la subtarea. SENT: Programada. REMOVED: Eliminada. CANCELLED: Cancelada.
jobDocument	Object	Documento de trabajo que describe las reglas de ejecución de la tarea. Nota Si status es REMOVED o CANCELLED, este campo permanece vacío.
jobFile	Object	Información del archivo cargado al crear una tarea personalizada. signMethod: Método de firma. Actualmente admite `Md5` y `Sha256`. sign: Parámetro de firma generado según el método de firma correspondiente. fileUrl: URL de descarga del archivo de tarea, válida durante 1 hora. Nota ```html Si status es REMOVED o CANCELLED, este campo permanece vacío.

Ejemplo de respuesta en formato Alink JSON:

{
    "id": "7542940",
    "code": 200,
    "data": {}
}

Tabla 2. Descripción de parámetros de respuesta

Parámetro	Tipo	Descripción
id	String	The message ID. Must be a unique numeric string on the device. Valid values: 0 to 4294967295.
code	Integer	Código de resultado. El valor 200 indica éxito; otros valores indican error. Para más información, consulte Error codes received by devices.
data	Object	Datos devueltos por el dispositivo. La notificación de actualización de trabajo de dispositivo devuelve datos de resultado vacíos.

Obtención de detalles del trabajo de dispositivo

Sentido ascendente (upstream).

Tema de solicitud: /sys/${productKey}/${deviceName}/thing/job/get.
Tema de respuesta: /sys/${productKey}/${deviceName}/thing/job/get_reply.

Ejemplo de solicitud en formato Alink JSON:

{
    "id": "123",
    "version": "1.0",
    "params": {
        "taskId": "i5Ks***F010101"
    }
}

Tabla 3. Descripción de parámetros de solicitud

Parámetro	Tipo	Descripción
id	String	The message ID. Must be a unique numeric string on the device. Valid values: 0 to 4294967295.
version	String	The protocol version. Set this parameter to 1.0.
params	Object	The business request parameters.
taskId	String	Existen tres métodos de valor que permiten devolver información de tareas con distintos estados. ID de la subtarea: Devuelve información detallada sobre la tarea correspondiente al ID de trabajo. `$next`: Devuelve información sobre una tarea ejecutable. `$list`: Devuelve una lista de tareas ejecutables, con un máximo predeterminado de 10.

Los valores de taskId varían y el formato de datos de respuesta Alink también difiere.

Cuando taskId es el ID de la subtarea:

{
    "id": "1234",
    "code": 200,
    "data": {
        "statusDetails":{"devs":"test","status":"init"},
        "taskId": "i5Ks***F010101",
        "task":{
            "taskId": "i5Ks***F010101",
            "status": "IN_PROGRESS",
            "jobDocument": {},
            "jobFile":{
                "signMethod":"Md5",
                "sign":"wssxff56dhdsd***",
                "fileUrl": "https://iotx-***.oss-cn-shanghai.aliyuncs.com/***.zip"
            }
        }
    }
}

Cuando taskId es $next:

{
    "id": "1234",
    "code": 200,
    "data": {
        "statusDetails":{"devs":"test","status":"init"},
        "taskId": "$next",
        "task":{
            "taskId": "i5Ks***F010101",
            "status": "IN_PROGRESS",
            "jobDocument": {},
            "jobFile":{
                "signMethod":"Md5",
                "sign":"wssxff56dhdsd***",
                "fileUrl": "https://iotx-***.oss-cn-shanghai.aliyuncs.com/***.zip"
            }
        }
    }
}

Cuando taskId es $list:

{
    "id": "1234",
    "code": 200,
    "data": {
        "statusDetails":{"devs":"test","status":"init"},
        "taskId": "$list",
        "task":[
            {
                "taskId": "i5Ks***",
                "status": "IN_PROGRESS"
            },
            {
                "taskId": "i61s***",
                "status": "IN_PROGRESS"
            }
        ]
    }
}

Tabla 4. Descripción de parámetros de respuesta

Parámetro	Tipo	Descripción
id	String	The message ID. Must be a unique numeric string on the device. Valid values: 0 to 4294967295.
code	Integer	The result code. 200 indicates success. Other values indicate failure. For more information, see Error codes received by devices.
data	Object	Datos devueltos por el dispositivo.
task	Object	Parámetros de la subtarea.
taskId	String	ID de la subtarea, que funciona como identificador único global.
status	String	Estado de la subtarea. QUEUED: En cola. SENT: Programada. IN_PROGRESS: En curso. TIMED_OUT: Tiempo agotado. FAILED: Con errores. SUCCEEDED: Correcta. CANCELLED: Cancelada. REJECTED: Rechazada.
statusDetails	JSON	Configuración definida por el usuario al crear una tarea en el dispositivo.
jobDocument	Object	Documento de trabajo que describe las reglas de ejecución de la tarea.
jobFile	Object	Información del archivo cargado al crear una tarea personalizada. signMethod: Método de firma. Actualmente admite `Md5` y `Sha256`. sign: Parámetro de firma generado según el método de firma correspondiente. fileUrl: URL de descarga del archivo de tarea, válida durante 1 hora.

Actualización de estado de subtarea

Sentido ascendente (upstream).

Tema de solicitud: /sys/${productKey}/${deviceName}/thing/job/update.
Tema de respuesta: /sys/${productKey}/${deviceName}/thing/job/update_reply.

Ejemplo de solicitud en formato Alink JSON:

{
    "id": "123",
    "version": "1.0",
    "params": {
        "taskId": "i5Ks***F010101",
        "status": "IN_PROGRESS",
        "statusDetails": {
            "key": "value"
        },
        "progress": 50
    }
}

Tabla 5. Descripción de parámetros de solicitud

Parámetro	Tipo	Descripción
id	String	The message ID. Must be a unique numeric string on the device. Valid values: 0 to 4294967295.
version	String	The protocol version. Set this parameter to 1.0.
params	Object	The business request parameters.
taskId	String	ID de la subtarea, que funciona como identificador único global.
status	String	Estado de la subtarea. Valores válidos: SUCCEEDED: Completada correctamente. FAILED: Error en la ejecución. IN_PROGRESS: Ejecutándose actualmente. REJECTED: Ejecución rechazada.
statusDetails	Object	Detalles de estado personalizados definidos por el usuario. Se pueden consultar en la página Device Management > Tasks > Task Details de la consola de IoT Platform.
progress	Integer	Porcentaje de progreso de ejecución de la subtarea.

Ejemplo de respuesta en formato Alink JSON:

{
    "id":"123",
    "code":200,
    "data":{
        "taskId":"i5Ks***F010101"
    }
}

Tabla 6. Descripción de parámetros de respuesta

Parámetro	Tipo	Descripción
id	String	The message ID. Must be a unique numeric string on the device. Valid values: 0 to 4294967295.
code	Integer	Código de resultado. El valor 200 indica éxito; otros valores indican error. Para más información, consulte Error codes received by devices.
data	Object	Datos devueltos por el dispositivo.
taskId	String	ID de la subtarea, que funciona como identificador único global.