Programación de trabajos en varios dispositivos

  • Artículo

Azure IoT Hub habilita cierto número de bloques de creación, como etiquetas y propiedades de dispositivos gemelos y métodos directos. Normalmente, las aplicaciones de back-end permiten a los administradores y operadores de dispositivos actualizar e interactuar con dispositivos de IoT de forma masiva y a la hora programada. Los trabajos ejecutan las actualizaciones de los dispositivos gemelos y los métodos directos con un conjunto de dispositivos a la hora programada. Por ejemplo, un operador puede usar una aplicación de back-end que inicie y realice un seguimiento de un trabajo para reiniciar un conjunto de dispositivos en la compilación 43 y la planta 3 sin perturbar las operaciones de la creación.

Nota

Las características descritas en este artículo solo están disponibles en el nivel estándar de IoT Hub. Para obtener más información sobre los niveles Básico y Estándar o Gratis de IoT Hub, consulte Elección del nivel adecuado de IoT Hub para la solución.

Le recomendamos que tenga en cuenta la posibilidad de usar trabajos cuando necesite programar y realizar un seguimiento del progreso de cualquiera de las siguientes actividades en un conjunto de dispositivos:

  • Actualizar las propiedades deseadas
  • Actualizar etiquetas
  • Invocar métodos directos

Ciclo de vida de trabajo

Los trabajos se inician mediante el back-end de solución y se mantienen mediante IoT Hub. Puede iniciar un trabajo a través de un URI orientado a servicios (PUT https://<iot hub>/jobs/v2/<jobID>?api-version=2021-04-12) y una consulta para el progreso de un trabajo en ejecución a través de un URI orientado a servicios (GET https://<iot hub>/jobs/v2/<jobID?api-version=2021-04-12). Para actualizar el estado de los trabajos en ejecución una vez que se inicia un trabajo, ejecute una consulta de trabajo. No hay ninguna purga explícita del historial de trabajos, pero tienen un TTL de 30 días. 

Nota

Cuando se inicia un trabajo, los valores y los nombres de propiedad solo pueden contener caracteres alfanuméricos US-ASCII imprimibles, excepto los del siguiente conjunto: $ ( ) < > @ , ; : \ " / [ ] ? = { } SP HT

Nota

El campo jobId debe tener 64 caracteres o menos y solo puede contener letras US-ASCII, números y el carácter de guion (-).

Trabajos para ejecutar métodos directos

El siguiente fragmento de código muestra los detalles de la solicitud HTTP 1.1 para ejecutar un método directo en un conjunto de dispositivos mediante un trabajo:

PUT /jobs/v2/<jobId>?api-version=2021-04-12

Authorization: <config.sharedAccessSignature>
Content-Type: application/json; charset=utf-8

{
    "jobId": "<jobId>",
    "type": "scheduleDeviceMethod",
    "cloudToDeviceMethod": {
        "methodName": "<methodName>",
        "payload": <payload>,
        "responseTimeoutInSeconds": methodTimeoutInSeconds
    },
    "queryCondition": "<queryOrDevices>", // query condition
    "startTime": <jobStartTime>,          // as an ISO-8601 date string
    "maxExecutionTimeInSeconds": <maxExecutionTimeInSeconds>
}

La condición de consulta puede estar también en un solo identificador de dispositivo o en una lista de identificadores de dispositivo, como se muestra en los ejemplos siguientes:

"queryCondition" = "deviceId = 'MyDevice1'"
"queryCondition" = "deviceId IN ['MyDevice1','MyDevice2']"
"queryCondition" = "deviceId IN ['MyDevice1']"

Lenguaje de consulta de IoT Hub aborda el lenguaje de consulta de IoT Hub con más detalle.

En este fragmento de código se muestra la solicitud y la respuesta para un trabajo programado para llamar a un método directo denominado testMethod en todos los dispositivos de contoso-hub-1:

PUT https://contoso-hub-1.azure-devices.net/jobs/v2/job01?api-version=2021-04-12 HTTP/1.1
Authorization: SharedAccessSignature sr=contoso-hub-1.azure-devices.net&sig=68iv------------------------------------v8Hxalg%3D&se=1556849884&skn=iothubowner
Content-Type: application/json; charset=utf-8
Host: contoso-hub-1.azure-devices.net
Content-Length: 317

{
    "jobId": "job01",
    "type": "scheduleDeviceMethod",
    "cloudToDeviceMethod": {
        "methodName": "testMethod",
        "payload": {},
        "responseTimeoutInSeconds": 30
    },
    "queryCondition": "*",
    "startTime": "2019-05-04T15:53:00.077Z",
    "maxExecutionTimeInSeconds": 20
}

HTTP/1.1 200 OK
Content-Length: 65
Content-Type: application/json; charset=utf-8
Vary: Origin
Server: Microsoft-HTTPAPI/2.0
Date: Fri, 03 May 2019 01:46:18 GMT

{"jobId":"job01","type":"scheduleDeviceMethod","status":"queued"}

Trabajos para actualizar las propiedades del dispositivo gemelo

El siguiente fragmento de código muestra los detalles de la solicitud HTTP 1.1 para la actualización de las propiedades del dispositivo gemelo con un trabajo:

PUT /jobs/v2/<jobId>?api-version=2021-04-12

Authorization: <config.sharedAccessSignature>
Content-Type: application/json; charset=utf-8

{
    "jobId": "<jobId>",
    "type": "scheduleUpdateTwin",
    "updateTwin": <patch>                 // Valid JSON object
    "queryCondition": "<queryOrDevices>", // query condition
    "startTime": <jobStartTime>,          // as an ISO-8601 date string
    "maxExecutionTimeInSeconds": <maxExecutionTimeInSeconds>
}

Nota

La propiedad updateTwin necesita una coincidencia de etag válida; por ejemplo, etag="*".

En este fragmento de código se muestra la solicitud y la respuesta para un trabajo programado para actualizar propiedades del dispositivo gemelo para dispositivo para test-device en contoso-hub-1:

PUT https://contoso-hub-1.azure-devices.net/jobs/v2/job02?api-version=2021-04-12 HTTP/1.1
Authorization: SharedAccessSignature sr=contoso-hub-1.azure-devices.net&sig=BN0U-------------------------------------RuA%3D&se=1556925787&skn=iothubowner
Content-Type: application/json; charset=utf-8
Host: contoso-hub-1.azure-devices.net
Content-Length: 339

{
    "jobId": "job02",
    "type": "scheduleUpdateTwin",
    "updateTwin": {
      "properties": {
        "desired": {
          "test1": "value1"
        }
      },
     "etag": "*"
     },
    "queryCondition": "deviceId = 'test-device'",
    "startTime": "2019-05-08T12:19:56.868Z",
    "maxExecutionTimeInSeconds": 20
}

HTTP/1.1 200 OK
Content-Length: 63
Content-Type: application/json; charset=utf-8
Vary: Origin
Server: Microsoft-HTTPAPI/2.0
Date: Fri, 03 May 2019 22:45:13 GMT

{"jobId":"job02","type":"scheduleUpdateTwin","status":"queued"}

Consulta del progreso de los trabajos

El siguiente fragmento de código muestra los detalles de la solicitud HTTPS 1.1 para consultar trabajos:

GET /jobs/v2/query?api-version=2021-04-12[&jobType=<jobType>][&jobStatus=<jobStatus>][&pageSize=<pageSize>][&continuationToken=<continuationToken>]

Authorization: <config.sharedAccessSignature>
Content-Type: application/json; charset=utf-8

Se proporciona el continuationToken de la respuesta.

Puede consultar el estado de ejecución del trabajo en cada dispositivo mediante el lenguaje de consulta de IoT Hub para dispositivos gemelos, trabajos y enrutamiento de mensajes.

Propiedades de trabajos

La siguiente lista muestra las propiedades y las descripciones correspondientes, que se pueden utilizar al consultar trabajos o resultados de trabajos.

Propiedad Descripción
jobId Id. proporcionado de la aplicación para el trabajo.
startTime Hora de inicio proporcionada de la aplicación (ISO 8601) para el trabajo.
endTime Fecha proporcionada de IoT Hub (ISO 8601) cuando hay un trabajo completado. Válido solo después de que el trabajo alcance el estado 'completado'.
type Tipos de trabajos:
scheduleUpdateTwin: un trabajo que se usa para actualizar un conjunto de propiedades deseadas o etiquetas.
scheduleDeviceMethod: un trabajo que se utiliza para invocar un método de dispositivo en un conjunto de dispositivos gemelos.
status Estado actual del trabajo. Posibles valores para el estado:
pending: programado y en espera a que lo recopile el servicio de trabajo.
scheduled: programado para una hora futura.
running: trabajo activo actualmente.
cancelled: el trabajo se ha cancelado.
failed: trabajo erróneo.
completed: el trabajo se ha completado.
deviceJobStatistics Estadísticas sobre la ejecución del trabajo.
Propiedades deviceJobStatistics:
deviceJobStatistics.deviceCount: número de dispositivos en el trabajo.
deviceJobStatistics.failedCount: número de dispositivos en los que no se produjo un error del trabajo.
deviceJobStatistics.succeededCount: número de dispositivos en los que el trabajo se realizó correctamente.
deviceJobStatistics.runningCount: número de dispositivos que están ejecutando el trabajo en estos momentos.
deviceJobStatistics.pendingCount: número de dispositivos que tienen pendiente ejecutar el trabajo.

Material de referencia adicional

Otros temas de referencia en la guía del desarrollador de IoT Hub son los siguientes:

Pasos siguientes

Para probar algunos de los conceptos descritos en este artículo, vea el siguiente tutorial de IoT Hub: