Partilhar via

Programar tarefas em vários dispositivos

O Hub IoT do Azure habilita vários blocos de construção, como propriedades e tags gêmeas de dispositivo e métodos diretos. Normalmente, os aplicativos back-end permitem que os administradores e operadores de dispositivos atualizem e interajam com dispositivos IoT em massa e em um horário agendado. Os trabalhos executam atualizações gêmeas de dispositivos e direcionam métodos em relação a um conjunto de dispositivos em um horário agendado. Por exemplo, um operador usaria um aplicativo de back-end que inicia e rastreia um trabalho para reiniciar um conjunto de dispositivos no edifício 43 e no piso 3 em um momento que não seria perturbador para as operações do edifício.

Observação

Os recursos descritos neste artigo estão disponíveis somente na camada padrão do Hub IoT. Para obter mais informações sobre as camadas básica e padrão/gratuita do Hub IoT, consulte Escolha a camada e o tamanho certos do Hub IoT para sua solução.

Considere o uso de trabalhos quando precisar agendar e acompanhar o progresso de qualquer uma das seguintes atividades num conjunto de dispositivos.

  • Atualizar propriedades desejadas
  • Atualizar tags
  • Invocar métodos diretos

Ciclo de vida do trabalho

Os trabalhos são iniciados pelo back-end da solução e mantidos pelo Hub IoT. Você pode iniciar um trabalho por meio de um URI voltado para o serviço (PUT https://<iot hub>/jobs/v2/<jobID>?api-version=2021-04-12) e consultar o progresso de um trabalho em execução por meio de um URI voltado para o serviço (GET https://<iot hub>/jobs/v2/<jobID?api-version=2021-04-12). Para atualizar o status dos trabalhos em execução depois que um trabalho for iniciado, execute uma consulta de trabalho. Não há um expurgo explícito do histórico de trabalho, mas eles têm um TTL de 30 dias. 

Observação

Ao iniciar um trabalho, os nomes e valores de propriedade só podem conter caracteres alfanuméricos imprimíveis US-ASCII, exceto quaisquer presentes no seguinte conjunto: $ ( ) < > @ , ; : \ " / [ ] ? = { } SP HT

Observação

O jobId campo deve ter 64 caracteres ou menos e só pode conter US-ASCII letras, números e o caractere traço (-).

Tarefas para executar métodos diretos

O trecho a seguir mostra os detalhes da solicitação HTTPS 1.1 para executar um método direto em um conjunto de dispositivos usando um trabalho:

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 em um único ID de dispositivo ou em uma lista de IDs de dispositivo, conforme mostrado nos exemplos a seguir:

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

A Linguagem de Consulta do Hub IoT aborda a linguagem de consulta do Hub IoT em detalhes adicionais.

O trecho a seguir mostra a solicitação e a resposta para uma tarefa agendada para chamar um método direto chamado testMethod em todos os dispositivos no 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"}

Trabalhos para atualizar propriedades gêmeas do dispositivo

O trecho a seguir mostra os detalhes da solicitação HTTPS 1.1 para atualizar as propriedades gêmeas do dispositivo usando um trabalho:

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

Observação

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

O trecho a seguir mostra a solicitação e a resposta para um trabalho agendado para atualizar as propriedades gêmeas do dispositivo para test-device no 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"}

Consultando o progresso dos trabalhos

O trecho a seguir mostra os detalhes da solicitação HTTPS 1.1 para consulta de trabalhos:

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

O continuationToken é fornecido a partir da resposta.

Você pode consultar o estado de execução do trabalho em cada dispositivo usando a linguagem de consulta do Hub IoT para gêmeos de dispositivo, trabalhos e roteamento de mensagens.

Propriedades de Empregos

A lista a seguir mostra as propriedades e descrições correspondentes, que podem ser usadas ao consultar trabalhos ou resultados de trabalho.

Propriedade Descrição
jobId A aplicação forneceu o ID para a tarefa.
startTime A aplicação forneceu a hora de início (ISO-8601) para o trabalho.
endTime O Hub IoT forneceu a data (ISO-8601) para quando o trabalho foi concluído. Válido somente após a tarefa atingir o estado 'concluído'.
tipo Tipos de emprego:
scheduleUpdateTwin: Um trabalho usado para atualizar um conjunto de propriedades ou tags desejadas.
scheduleDeviceMethod: Um trabalho usado para invocar um método de dispositivo em um conjunto de gêmeos de dispositivo.
status Estado atual do trabalho. Valores possíveis para o status:
pendente: Agendado e à espera de ser levantado pelo serviço de tarefas.
programado: Agendado para um momento no futuro.
executando: Trabalho atualmente ativo.
foi cancelado: O trabalho foi cancelado.
falhou: A tarefa falhou.
concluído: O trabalho foi concluído.
deviceJobStatistics Estatísticas sobre a execução do trabalho.
propriedades do deviceJobStatistics
deviceJobStatistics.deviceCount: Número de dispositivos na tarefa.
deviceJobStatistics.failedCount: Número de dispositivos onde o trabalho falhou.
deviceJobStatistics.succeededCount: Número de dispositivos em que o trabalho foi bem-sucedido.
deviceJobStatistics.runningCount: Número de dispositivos que estão presentemente a executar a tarefa.
deviceJobStatistics.pendingCount: Número de dispositivos pendentes para executar o trabalho.

Material de referência adicional

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

Próximos passos

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