Programar tarefas em vários dispositivos

Hub IoT do Azure permite uma série de blocos de construção como propriedades gémeas do dispositivo e etiquetas e métodos diretos. Normalmente, as aplicações back-end permitem aos administradores e operadores de dispositivos atualizar e interagir com dispositivos IoT a granel e a uma hora programada. Os trabalhos executam duas atualizações e métodos diretos contra um conjunto de dispositivos numa hora programada. Por exemplo, um operador usaria uma aplicação back-end que inicia e rastreia um trabalho para reiniciar um conjunto de dispositivos no edifício 43 e no piso 3 de cada vez que não seria perturbador para as operações do edifício.

Nota

As funcionalidades descritas neste artigo estão disponíveis apenas no nível padrão de Hub IoT. Para obter mais informações sobre os níveis básicos e standard/free Hub IoT, consulte escolha o nível Hub IoT certo para a sua solução.

Considere usar empregos quando precisar de agendar e acompanhar o progresso de qualquer uma das seguintes atividades num conjunto de dispositivos:

  • Atualizar as propriedades pretendidas
  • Etiquetas de atualização
  • Invocar métodos diretos

Ciclo de vida do trabalho

Os postos de trabalho são iniciados pela solução de fundo e mantidos por Hub IoT. Pode iniciar um trabalho através de um URI virado para o serviço (PUT https://<iot hub>/jobs/v2/<jobID>?api-version=2021-04-12) e consultar o progresso de um trabalho de execução através de um URI virado para o serviço (GET https://<iot hub>/jobs/v2/<jobID?api-version=2021-04-12). Para refrescar o estado de gestão de empregos uma vez iniciado um trabalho, executar uma consulta de trabalho.

Nota

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

Nota

O jobId campo deve ter 64 caracteres ou menos e só pode conter letras, números e caracteres- US-ASCII.

Empregos para executar métodos diretos

O seguinte corte mostra os dados do pedido HTTPS 1.1 para a execução de um método direto num conjunto de dispositivos utilizando 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 do dispositivo ou em uma lista de IDs do dispositivo, como mostrado nos seguintes exemplos:

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

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

O seguinte corte mostra o pedido e a resposta para um trabalho programado para chamar um método direto chamado 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"}

Empregos para atualizar propriedades gémeas do dispositivo

O seguinte corte mostra os detalhes do pedido HTTPS 1.1 para atualizar 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>
}

Nota

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

O seguinte corte mostra o pedido e a resposta de um trabalho programado para atualizar as propriedades gémeas do dispositivo para dispositivo de teste 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"}

Consulta do progresso dos postos de trabalho

O seguinte corte mostra os dados do pedido HTTPS 1.1 para consulta de emprego:

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

A continuação Doken é fornecida a partir da resposta.

Pode consultar o estado de execução de emprego em cada dispositivo utilizando a linguagem de consulta Hub IoT para gémeos, empregos e encaminhamento de mensagens.

Propriedades de Emprego

A lista a seguir mostra as propriedades e descrições correspondentes, que podem ser utilizadas na consulta de empregos ou resultados de emprego.

Propriedade Descrição
jobId A candidatura forneceu identificação para o trabalho.
horário de início A aplicação forneceu a hora de início (ISO-8601) para o trabalho.
endTime Hub IoT data prevista (ISO-8601) para quando o trabalho estiver concluído. Válido apenas após o trabalho chegar ao estado "concluído".
tipo Tipos de empregos:
scheduleUpdateTwin: Um trabalho usado para atualizar um conjunto de propriedades ou tags desejadas.
agendaDeviceMethod: Um trabalho usado para invocar um método de dispositivo num conjunto de gémeos do dispositivo.
estado Estado atual do trabalho. Valores possíveis para o estado:
pendente: Agendado e à espera de ser recolhido pelo serviço de trabalho.
agendado: Agendado para um momento no futuro.
funcionando: Atualmente em vigor.
cancelado: O trabalho foi cancelado.
falhou: Trabalho falhou.
concluído: Trabalho concluído.
dispositivoJobStatistics Estatísticas sobre a execução do trabalho.
propriedades do dispositivoJobStatistics :
dispositivoJobStatistics.deviceCont: Número de dispositivos no trabalho.
dispositivoJobStatistics.failedCount: Número de dispositivos onde o trabalho falhou.
deviceJobStatistics.succeeddCount: Número de dispositivos onde o trabalho foi bem sucedido.
dispositivoJobStatistics.runningCount: Número de dispositivos que estão atualmente a executar o trabalho.
dispositivoJobStatistics.pendentes: Número de dispositivos pendentes para executar o trabalho.

Material de referência adicional

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

Passos seguintes

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