Compartilhar via

Agendar trabalhos do Hub IoT do Azure em vários dispositivos

O Hub IoT do Azure permite vários blocos de construção, como propriedades do dispositivo gêmeo, marcas e métodos diretos. Normalmente, os aplicativos de back-end permitem que os administradores e operadores de dispositivo atualizem e interajam com dispositivos IoT em massa e em um horário agendado. Trabalhos executam atualizações do dispositivo gêmeo e métodos diretos em 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 reinicializar um conjunto de dispositivos no edifício 43 e 3 de cada vez que não seriam disruptivos para as operações do edifício.

Observação

Os recursos descritos neste artigo estão disponíveis apenas na camada padrão do Hub IoT. Para obter mais informações sobre as camadas básicas e padrão/gratuitas do Hub IoT, consulte Escolher a camada e o tamanho corretos 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 em um conjunto de dispositivos:

  • Atualizar as propriedades desejadas
  • Atualizar marcas
  • 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 em um trabalho em execução por meio de um URI (GET https://<iot hub>/jobs/v2/<jobID?api-version=2021-04-12voltado para o serviço). Para atualizar o status dos trabalhos em execução depois que um trabalho for iniciado, execute uma consulta de trabalho. Não há limpeza explícita do histórico de trabalhos, mas eles têm um TTL de 30 dias. 

Observação

Quando você inicia um trabalho, os nomes de propriedade e os valores só podem conter US-ASCII alfanumérico imprimível, exceto qualquer um 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 (-).

Trabalhos para executar métodos diretos

O snippet 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 uma única ID do dispositivo ou em uma lista de IDs de dispositivo, conforme mostrado nos seguintes exemplos:

"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 snippet a seguir mostra a solicitação e a resposta de um trabalho agendado 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 as propriedades do dispositivo gêmeo

O snippet a seguir mostra os detalhes da solicitação HTTPS 1.1 para atualizar as propriedades do dispositivo gêmeo 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 snippet a seguir mostra a solicitação e a resposta de um trabalho agendado para atualizar as propriedades do dispositivo gêmeo para o dispositivo de teste 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 em trabalhos

O snippet a seguir mostra os detalhes da solicitação HTTPS 1.1 para consultar 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 status de execução do trabalho em cada dispositivo usando a linguagem de consulta do Hub IoT para dispositivos gêmeos, trabalhos e roteamento de mensagens.

Propriedades de trabalhos

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

Propriedade Description
jobId ID fornecida pelo aplicativo para o trabalho.
startTime O aplicativo forneceu a hora de início (ISO-8601) para o trabalho.
endTime Data fornecida pelo Hub IoT (ISO-8601) para quando o trabalho foi concluído. Válido somente depois que o trabalho atingir o estado 'concluído'.
maxExecutionTimeInSeconds O aplicativo forneceu o tempo total máximo permitido de quando o trabalho é iniciado até ser concluído.
type Tipos de trabalhos:
scheduleUpdateTwin: um trabalho usado para atualizar um conjunto de propriedades ou marcas desejadas.
scheduleDeviceMethod: um trabalho usado para invocar um método de dispositivo em um conjunto de dispositivos gêmeos.
estado Estado atual do trabalho. Valores possíveis para o status:
pendente: agendada e aguardando ser recolhida pelo serviço de trabalho.
agendado: agendado para um horário no futuro.
em execução: trabalho ativo no momento.
cancelado: o trabalho foi cancelado.
falha: falha no trabalho.
concluído: o trabalho foi concluído.
deviceJobStatistics Estatísticas sobre a execução do trabalho.
propriedades deviceJobStatistics:
deviceJobStatistics.deviceCount: número de dispositivos no trabalho.
deviceJobStatistics.failedCount: número de dispositivos em que 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 executando o trabalho no momento.
deviceJobStatistics.pendingCount: número de dispositivos pendentes para executar o trabalho.

Material de referência adicional

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

Próximas etapas

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

  • Last updated on