Como usar a API REST do IoT Central para criar e gerenciar trabalhos

Artigo
06/14/2023

A API REST do IoT Central permite que você desenvolva aplicativos cliente que se integram aos aplicativos do IoT Central. Você pode usar a API REST para criar e gerenciar trabalhos em seu aplicativo do IoT Central. A API REST permite que você:

Liste trabalhos e exibir detalhes do trabalho em seu aplicativo.
Crie trabalhos em seu aplicativo.
Pare, retome e execute novamente os trabalhos em seu aplicativo.
Agende trabalhos e visualize os detalhes do trabalho agendado em seu aplicativo.

Trabalhos agendados são criados para serem executados em um momento futuro. Você pode definir uma data e hora de início para que um trabalho agendado seja executado uma vez, diariamente ou semanalmente. Os trabalhos não agendados são executados apenas uma vez.

Este artigo descreve como usar a API /jobs/{job_id} para controlar dispositivos em massa. Você também pode controlar os dispositivos individualmente.

Cada chamada à API REST do IoT Central exige um cabeçalho de autorização. Para saber mais, confira Como autenticar e autorizar chamadas à API REST do IoT Central.

Para obter a documentação de referência da API REST do IoT Central, confira Referência da API REST do Azure IoT Central.

Para saber como criar e gerenciar trabalhos na interface do usuário, consulte Gerenciar dispositivos em massa no seu aplicativo Azure IoT Central.

Dica

Você pode usar o Postman para experimentar as chamadas à API REST descritas neste artigo. Baixe a coleção do Postman do IoT Central e importe-a para o Postman. Na coleção, você precisará definir variáveis como o subdomínio do aplicativo e o token de administrador.

Cargas de trabalho

Muitas das APIs descritas neste artigo incluem uma definição semelhante ao seguinte snippet JSON:

{
  "id": "job-014",
  "displayName": "Set target temperature",
  "description": "Set target temperature for all thermostat devices",
  "group": "833d7a7d-8f99-4e04-9e56-745806bdba6e",
  "batch": {
    "type": "percentage",
    "value": 25
  },
  "cancellationThreshold": {
    "type": "percentage",
    "value": 10,
    "batch": false
  },
  "data": [
    {
      "type": "PropertyJobData",
      "target": "dtmi:modelDefinition:zomtmdxh:eqod32zbyl",
      "path": "targetTemperature",
      "value": "56"
    }
  ],
  "status": "complete"
}

A seguinte tabela descreve os campos no snippet JSON anterior:

Campo	Descrição
`id`	Uma ID exclusiva para o trabalho em seu aplicativo.
`displayName`	O nome de exibição do trabalho em seu aplicativo.
`description`	Uma descrição do trabalho.
`group`	A ID do grupo de dispositivos ao que o trabalho se aplica. Use a API REST em versão prévia `deviceGroups` para obter uma lista dos grupos de dispositivos em seu aplicativo.
`status`	O status do trabalho. Uma opção entre `complete`, `cancelled`, `failed`, `pending`, `running` ou `stopped`.
`batch`	Se presente, esta seção define como colocar em lote os dispositivos no trabalho.
`batch/type`	O tamanho de cada lote é um `percentage` dos dispositivos totais no grupo ou um `number` de dispositivos.
`batch/value`	O percentual ou o número de dispositivos em cada lote.
`cancellationThreshold`	Se presente, esta seção define o limite de cancelamento do trabalho.
`cancellationThreshold/batch`	`true` ou `false`. Se for true, o limite de cancelamento será definido para cada lote. Se `false`, o limite de cancelamento se aplicará a todo o trabalho.
`cancellationThreshold/type`	O limite de cancelamento do trabalho é um `percentage` ou um `number` dos dispositivos.
`cancellationThreshold/value`	O percentual ou o número de dispositivos que definem o limite de cancelamento.
`data`	Uma matriz de operações que o trabalho executa.
`data/type`	Uma opção entre `PropertyJobData`, `CommandJobData`, `CloudPropertyJobData` ou `DeviceTemplateMigrationJobData`. A versão prévia da API inclui `DeviceManifestMigrationJobData`.
`data/target`	A ID de modelo dos dispositivos de destino.
`data/path`	O nome da propriedade, comando ou propriedade de nuvem.
`data/value`	O valor da propriedade a ser definido ou o parâmetro de comando a ser enviado.

Obter informações do trabalho

Use a seguinte solicitação para recuperar a lista de trabalhos no aplicativo:

GET https://{your app subdomain}.azureiotcentral.com/api/jobs?api-version=2022-07-31

A resposta a essa solicitação é parecida com o seguinte exemplo:

{
  "value": [
    {
      "id": "job-006",
      "displayName": "Set customer name",
      "description": "Set the customer name cloud property",
      "group": "4fcbec3b-5ee8-4324-855d-0f03b56bcf7f",
      "data": [
        {
          "type": "CloudPropertyJobData",
          "target": "dtmi:modelDefinition:bojo9tfju:yfvu5gv2vl",
          "path": "CustomerName",
          "value": "Contoso"
        }
      ],
      "status": "complete"
    },
    {
      "id": "job-005",
      "displayName": "Set target temperature",
      "description": "Set target temperature device property",
      "group": "833d7a7d-8f99-4e04-9e56-745806bdba6e",
      "data": [
        {
          "type": "PropertyJobData",
          "target": "dtmi:modelDefinition:zomtmdxh:eqod32zbyl",
          "path": "targetTemperature",
          "value": 56
        }
      ],
      "status": "complete"
    },
    {
      "id": "job-004",
      "displayName": "Run device report",
      "description": "Call command to run the device reports",
      "group": "833d7a7d-8f99-4e04-9e56-745806bdba6e",
      "batch": {
        "type": "percentage",
        "value": 25
      },
      "cancellationThreshold": {
        "type": "percentage",
        "value": 10,
        "batch": false
      },
      "data": [
        {
          "type": "CommandJobData",
          "target": "dtmi:modelDefinition:zomtmdxh:eqod32zbyl",
          "path": "getMaxMinReport",
          "value": "2021-06-15T05:00:00.000Z"
        }
      ],
      "status": "complete"
    }
  ]
}

Use a seguinte solicitação para recuperar um trabalho individual pela ID:

GET https://{your app subdomain}.azureiotcentral.com/api/jobs/job-004?api-version=2022-07-31

A resposta a essa solicitação é parecida com o seguinte exemplo:

{
  "id": "job-004",
  "displayName": "Run device report",
  "description": "Call command to run the device reports",
  "group": "833d7a7d-8f99-4e04-9e56-745806bdba6e",
  "batch": {
    "type": "percentage",
    "value": 25
  },
  "cancellationThreshold": {
    "type": "percentage",
    "value": 10,
    "batch": false
  },
  "data": [
    {
      "type": "CommandJobData",
      "target": "dtmi:modelDefinition:zomtmdxh:eqod32zbyl",
      "path": "getMaxMinReport",
      "value": "2021-06-15T05:00:00.000Z"
    }
  ],
  "status": "complete"
}

Use a seguinte solicitação para recuperar os detalhes dos dispositivos em um trabalho:

GET https://{your app subdomain}.azureiotcentral.com/api/jobs/job-004/devices?api-version=2022-07-31

A resposta a essa solicitação é parecida com o seguinte exemplo:

{
  "value": [
    {
      "id": "therm-01",
      "status": "completed"
    },
    {
      "id": "therm-02",
      "status": "completed"
    },
    {
      "id": "therm-03",
      "status": "completed"
    },
    {
      "id": "therm-04",
      "status": "completed"
    }
  ]
}

Criar um trabalho

Use a solicitação a seguir para criar um trabalho:

PUT https://{your app subdomain}.azureiotcentral.com/api/jobs/job-006?api-version=2022-07-31

O campo group no corpo da solicitação identifica um grupo de dispositivos em seu aplicativo IoT Central. Um trabalho usa um grupo de dispositivos para identificar o conjunto de dispositivos em que o trabalho opera.

Se você ainda não tiver um grupo de dispositivos adequado, poderá criar um com a chamada à API REST. O exemplo a seguir cria um grupo de dispositivos com group1 como a ID do grupo:

PUT https://{your app subdomain}/api/deviceGroups/group1?api-version=2022-07-31

Ao criar um grupo de dispositivos, você define um filter que seleciona os dispositivos a serem incluídos no grupo. Um filtro identifica um modelo de dispositivo e qualquer propriedade a ser correspondente. O exemplo a seguir cria um grupo de dispositivos que contém todos os dispositivos associados ao modelo de dispositivo "dtmi:modelDefinition:dtdlv2" em que a propriedade provisioned é true.

{
  "displayName": "Device group 1",
  "description": "Custom device group.",
  "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true"
}

A resposta a essa solicitação é parecida com o seguinte exemplo:

{
  "id": "group1",
  "displayName": "Device group 1",
  "description": "Custom device group.",
  "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true"
}

Agora você pode usar o valor id da resposta para criar um novo trabalho.

{
  "displayName": "Set target temperature",
  "description": "Set target temperature device property",
  "group": "group1",
  "batch": {
    "type": "percentage",
    "value": 25
  },
  "cancellationThreshold": {
    "type": "percentage",
    "value": 10,
    "batch": false
  },
  "data": [
    {
      "type": "PropertyJobData",
      "target": "dtmi:modelDefinition:zomtmdxh:eqod32zbyl",
      "path": "targetTemperature",
      "value": "55"
    }
  ]
}

A resposta a essa solicitação é parecida com o exemplo a seguir. O status inicial do trabalho é pending:

{
  "id": "job-006",
  "displayName": "Set target temperature",
  "description": "Set target temperature device property",
  "group": "group1",
  "batch": {
    "type": "percentage",
    "value": 25
  },
  "cancellationThreshold": {
    "type": "percentage",
    "value": 10,
    "batch": false
  },
  "data": [
    {
      "type": "PropertyJobData",
      "target": "dtmi:modelDefinition:zomtmdxh:eqod32zbyl",
      "path": "targetTemperature",
      "value": "55"
    }
  ],
  "status": "pending"
}

Parar, retomar e executar trabalhos novamente

Use a seguinte solicitação para parar um trabalho em execução:

POST https://{your app subdomain}.azureiotcentral.com/api/jobs/job-006/stop?api-version=2022-07-31

Se a solicitação for realizada com sucesso, ela retornará uma resposta 204 - No Content.

Use a seguinte solicitação para retomar um trabalho parado:

POST https://{your app subdomain}.azureiotcentral.com/api/jobs/job-006/resume?api-version=2022-07-31

Se a solicitação for realizada com sucesso, ela retornará uma resposta 204 - No Content.

Use o seguinte comando para executar novamente um trabalho existente em qualquer dispositivo com falha:

PUT https://{your app subdomain}.azureiotcentral.com/api/jobs/job-006/rerun/rerun-001?api-version=2022-07-31

Criar um trabalho agendado

A carga de um trabalho agendado é semelhante a um trabalho padrão, mas inclui os seguintes campos extras:

Campo	Descrição
agendar/iniciar	A data e hora de início do trabalho no formato ISO 8601
agendar/recorrência	`daily`, `monthly` ou `yearly \|`
agendar/encerrar	Um campo opcional que especifica o número de ocorrências para o trabalho ou uma data de término no formato ISO 8601

PUT https://{your app subdomain}.azureiotcentral.com/api/scheduledJobs/scheduled-Job-001?api-version=2022-07-31

O exemplo a seguir mostra um corpo da solicitação que cria um trabalho agendado.

{
    "displayName": "New Scheduled Job",
    "group": "6fecf96f-a26c-49ed-8076-6960f8efba31",
    "data": [
        {
            "type": "cloudProperty",
            "target": "dtmi:eclipsethreadx:devkit:hlby5jgib2o",
            "path": "Company",
            "value": "Contoso"
        }
    ],
    "schedule": {
        "start": "2022-10-24T22:29:01Z",
        "recurrence": "daily",
        "end": {
            "type": "date",
            "date": "2022-12-30"
        }
    }
}

A resposta a essa solicitação é parecida com o seguinte exemplo:

{
    "id": "scheduled-Job-001",
    "displayName": "New Scheduled Job",
    "description": "",
    "group": "6fecf96f-a26c-49ed-8076-6960f8efba31",
    "data": [
        {
            "type": "cloudProperty",
            "target": "dtmi:eclipsethreadx:devkit:hlby5jgib2o",
            "path": "Company",
            "value": "Contoso"
        }
    ],
    "schedule": {
        "start": "2022-10-24T22:29:01Z",
        "recurrence": "daily",
        "end": {
            "type": "date",
            "date": "2022-12-30"
        }
    },
    "enabled": false,
    "completed": false,
    "etag": "\"88003877-0000-0700-0000-631020670000\""
}

Obter um trabalho agendado

Use a seguinte solicitação para obter um trabalho agendado:

GET https://{your app subdomain}.azureiotcentral.com/api/scheduledJobs/scheduled-Job-001?api-version=2022-07-31

A resposta a essa solicitação é parecida com o seguinte exemplo:

{
    "id": "scheduled-Job-001",
    "displayName": "New Scheduled Job",
    "description": "",
    "group": "6fecf96f-a26c-49ed-8076-6960f8efba31",
    "data": [
        {
            "type": "cloudProperty",
            "target": "dtmi:eclipsethreadx:devkit:hlby5jgib2o",
            "path": "Company",
            "value": "Contoso"
        }
    ],
    "schedule": {
        "start": "2022-10-24T22:29:01Z",
        "recurrence": "daily"
    },
    "enabled": false,
    "completed": false,
    "etag": "\"88003877-0000-0700-0000-631020670000\""
}

Listar trabalhos agendados

Use a seguinte solicitação para obter uma lista de trabalhos agendados:

GET https://{your app subdomain}.azureiotcentral.com/api/scheduledJobs?api-version=2022-07-31

A resposta a essa solicitação é parecida com o seguinte exemplo:

{
    "value": [
        {
            "id": "scheduled-Job-001",
            "displayName": "New Scheduled Job",
            "description": "",
            "group": "6fecf96f-a26c-49ed-8076-6960f8efba31",
            "data": [
                {
                    "type": "cloudProperty",
                    "target": "dtmi:eclipsethreadx:devkit:hlby5jgib2o",
                    "path": "Company",
                    "value": "Contoso"
                }
            ],
            "schedule": {
                "start": "2022-10-24T22:29:01Z",
                "recurrence": "daily"
            },
            "enabled": false,
            "completed": false,
            "etag": "\"88003877-0000-0700-0000-631020670000\""
        },
        {
            "id": "46480dff-dc22-4542-924e-a5d45bf347aa",
            "displayName": "test",
            "description": "",
            "group": "cdd04344-bb55-425b-a55a-954d68383289",
            "data": [
                {
                    "type": "cloudProperty",
                    "target": "dtmi:rigado:evxfmi0xim",
                    "path": "test",
                    "value": 2
                }
            ],
            "schedule": {
                "start": "2022-09-01T03:00:00.000Z"
            },
            "enabled": true,
            "completed": true,
            "etag": "\"88000f76-0000-0700-0000-631020310000\""
        }
    ]
}

Atualizar um trabalho agendado

Use a seguinte solicitação para atualizar um trabalho agendado:

PATCH https://{your app subdomain}.azureiotcentral.com/api/scheduledJobs/scheduled-Job-001?api-version=2022-07-31

O exemplo a seguir mostra um corpo da solicitação que atualiza um trabalho agendado.

{
  "schedule": {
    "start": "2022-10-24T22:29:01Z",
    "recurrence": "weekly"
  }
}

A resposta a essa solicitação é parecida com o seguinte exemplo:

{
    "id": "scheduled-Job-001",
    "displayName": "New Scheduled Job",
    "description": "",
    "group": "6fecf96f-a26c-49ed-8076-6960f8efba31",
    "data": [
        {
            "type": "cloudProperty",
            "target": "dtmi:eclipsethreadx:devkit:hlby5jgib2o",
            "path": "Company",
            "value": "Contoso"
        }
    ],
    "schedule": {
        "start": "2022-10-24T22:29:01Z",
        "recurrence": "weekly"
    },
    "enabled": false,
    "completed": false,
    "etag": "\"88003877-0000-0700-0000-631020670000\""
}

Excluir um trabalho agendado

Use a seguinte solicitação para excluir um trabalho agendado

GET https://{your app subdomain}.azureiotcentral.com/api/scheduledJobs/scheduled-Job-001?api-version=2022-07-31

Próximas etapas

Agora que você aprendeu a gerencias trabalhos com a API REST, uma próxima etapa sugerida é aprender a Tutorial: Usar a API REST para gerenciar um aplicativo do Azure IoT Central.

Como usar a API REST do IoT Central para criar e gerenciar trabalhos

Cargas de trabalho

Obter informações do trabalho

Criar um trabalho

Parar, retomar e executar trabalhos novamente

Criar um trabalho agendado

Obter um trabalho agendado

Listar trabalhos agendados

Atualizar um trabalho agendado

Excluir um trabalho agendado

Próximas etapas

Recursos adicionais