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

Artigo
10/22/2024

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. Trabalhos não programados 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.

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

O conteúdo 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.

Compartilhar via

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

Comentários

Recursos adicionais