Programar tarefas em vários dispositivos

  • Artigo

Hub IoT do Azure permite vários blocos modulares, como propriedades e etiquetas do dispositivo duplo e métodos diretos. Normalmente, as aplicações de back-end permitem que os administradores e operadores de dispositivos atualizem e interajam com dispositivos IoT em massa e numa hora agendada. As tarefas executam atualizações de dispositivos duplos e métodos diretos num conjunto de dispositivos numa hora agendada. Por exemplo, um operador utilizaria uma aplicação de back-end que inicia e monitoriza uma tarefa para reiniciar um conjunto de dispositivos no edifício 43 e piso 3 de cada vez que não seria problemático para as operações do edifício.

Nota

As funcionalidades descritas neste artigo só estão disponíveis no escalão padrão do Hub IoT. Para obter mais informações sobre os escalões de Hub IoT básico e standard/gratuito, consulte Escolher o escalão de Hub IoT certo para a sua solução.

Considere utilizar tarefas quando precisar de agendar e controlar o progresso de qualquer uma das seguintes atividades num conjunto de dispositivos:

  • Atualizar as propriedades pretendidas
  • Atualizar etiquetas
  • Invocar métodos diretos

Ciclo de vida da tarefa

As tarefas são iniciadas pelo back-end da solução e mantidas por Hub IoT. Pode iniciar uma tarefa através de um URI com acesso ao serviço (PUT https://<iot hub>/jobs/v2/<jobID>?api-version=2021-04-12) e consultar o progresso de uma tarefa de execução através de um URI destinado ao serviço (GET https://<iot hub>/jobs/v2/<jobID?api-version=2021-04-12). Para atualizar o estado das tarefas em execução assim que uma tarefa é iniciada, execute uma consulta de tarefa. Não existe nenhuma remoção explícita do histórico de tarefas, mas têm um TTL de 30 dias. 

Nota

Quando inicia uma tarefa, os nomes de propriedades e valores só podem conter alfanuméricos imprimíveis US-ASCII, exceto qualquer um no seguinte conjunto: $ ( ) < > @ , ; : \ " / [ ] ? = { } SP HT

Nota

O jobId campo tem de ter 64 carateres ou menos e só pode conter letras, números e o caráter travessão (-).

Tarefas para executar métodos diretos

O fragmento seguinte mostra os detalhes do pedido HTTPS 1.1 para executar um método direto num conjunto de dispositivos com uma tarefa:

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

A condição de consulta também pode estar num único ID de dispositivo ou numa lista de IDs de dispositivo, conforme mostrado nos seguintes exemplos:

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

Hub IoT Linguagem de Consulta abrange Hub IoT linguagem de consulta em detalhes adicionais.

O fragmento seguinte mostra o pedido e a resposta de uma tarefa agendada para chamar um método direto denominado testMethod em todos os dispositivos em 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"}

Tarefas para atualizar as propriedades dos dispositivos duplos

O fragmento seguinte mostra os detalhes do pedido HTTPS 1.1 para atualizar as propriedades do dispositivo duplo com uma tarefa:

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

A propriedade updateTwin requer uma correspondência de etag válida; por exemplo, etag="*".

O fragmento seguinte mostra o pedido e a resposta de uma tarefa agendada para atualizar as propriedades do dispositivo duplo para test-device em 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"}

Consultar o progresso das tarefas

O fragmento seguinte mostra os detalhes do pedido HTTPS 1.1 para consultar tarefas:

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

ContinuationToken é fornecido a partir da resposta.

Pode consultar o estado de execução da tarefa em cada dispositivo com a linguagem de consulta Hub IoT para dispositivos duplos, tarefas e encaminhamento de mensagens.

Propriedades das Tarefas

A lista seguinte mostra as propriedades e as descrições correspondentes, que podem ser utilizadas ao consultar tarefas ou resultados da tarefa.

Propriedade Descrição
jobId ID fornecido pela aplicação para a tarefa.
startTime A aplicação forneceu a hora de início (ISO-8601) para a tarefa.
endTime Hub IoT data indicada (ISO-8601) para quando a tarefa estiver concluída. Válido apenas depois de a tarefa atingir o estado "concluído".
tipo Tipos de tarefas:
scheduleUpdateTwin: uma tarefa utilizada para atualizar um conjunto de propriedades ou etiquetas pretendidas.
scheduleDeviceMethod: uma tarefa utilizada para invocar um método de dispositivo num conjunto de dispositivos duplos.
estado Estado atual da tarefa. Valores possíveis para o estado:
pendente: agendado e à espera de ser recolhido pelo serviço de tarefas.
agendado: agendado para uma hora no futuro.
em execução: tarefa atualmente ativa.
cancelado: a tarefa foi cancelada.
falha: A tarefa falhou.
concluído: a tarefa foi concluída.
deviceJobStatistics Estatísticas sobre a execução da tarefa.
propriedades deviceJobStatistics :
deviceJobStatistics.deviceCount: número de dispositivos na tarefa.
deviceJobStatistics.failedCount: número de dispositivos em que a tarefa falhou.
deviceJobStatistics.succeededCount: número de dispositivos em que a tarefa foi bem-sucedida.
deviceJobStatistics.runningCount: número de dispositivos que estão atualmente a executar a tarefa.
deviceJobStatistics.pendingCount: número de dispositivos pendentes para executar a tarefa.

Material de referência adicional

Outros tópicos de referência no guia do programador do Hub IoT incluem:

Passos seguintes

Para experimentar alguns dos conceitos descritos neste artigo, veja o seguinte tutorial Hub IoT: