Como utilizar a API REST do IoT Central para criar e gerir trabalhos

Artigo
10/27/2023

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

Liste vagas e veja os detalhes da vaga em sua inscrição.
Crie trabalhos na sua aplicação.
Parar, retomar e executar novamente trabalhos em seu aplicativo.
Agende trabalhos e visualize os detalhes do trabalho agendado em seu aplicativo.

Os trabalhos agendados são criados para serem executados no 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 /jobs/{job_id} API para controlar dispositivos em massa. Você também pode controlar dispositivos individualmente.

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

Para obter a documentação de referência da API REST do IoT Central, consulte 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 em seu aplicativo do Azure IoT Central.

Gorjeta

Você pode usar o Postman para experimentar as chamadas de API REST descritas neste artigo. Faça o download da coleção IoT Central Postman 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 úteis de trabalho

Muitas das APIs descritas neste artigo incluem uma definição semelhante ao seguinte trecho 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 tabela a seguir descreve os campos no trecho JSON anterior:

Campo	Descrição
`id`	Um ID exclusivo para a vaga na sua candidatura.
`displayName`	O nome para exibição do trabalho em seu aplicativo.
`description`	Uma descrição do trabalho.
`group`	A ID do grupo de dispositivos ao qual o trabalho se aplica. Use a `deviceGroups` API REST de visualização para obter uma lista dos grupos de dispositivos em seu aplicativo.
`status`	O status do trabalho. Um dos `complete`, , , `failedcancelled`, , `runningpending`. `stopped`
`batch`	Se presente, esta seção define como agrupar os dispositivos no trabalho.
`batch/type`	O tamanho de cada lote é um do total de dispositivos no grupo ou um `percentagenumber` de dispositivos.
`batch/value`	A percentagem de dispositivos ou o número de dispositivos em cada lote.
`cancellationThreshold`	Se presente, esta seção define o limite de cancelamento para o trabalho.
`cancellationThreshold/batch`	`true` ou `false`. Se verdadeiro, o limite de cancelamento é definido para cada lote. Se `false`, o limite de cancelamento aplica-se a todo o trabalho.
`cancellationThreshold/type`	O limite de cancelamento para o trabalho é um ou um `percentagenumber` dos dispositivos.
`cancellationThreshold/value`	A percentagem de dispositivos ou o número de dispositivos que definem o limiar de cancelamento.
`data`	Uma matriz de operações que o trabalho executa.
`data/type`	Um de `PropertyJobData`, , `CloudPropertyJobDataCommandJobData`, ou `DeviceTemplateMigrationJobData`. A versão de visualização da API inclui `DeviceManifestMigrationJobData`.
`data/target`	O ID do modelo dos dispositivos de destino.
`data/path`	O nome da propriedade, comando ou propriedade de nuvem.
`data/value`	O valor da propriedade a ser definida ou o parâmetro de comando a ser enviado.

Obter informações sobre o emprego

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

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

A resposta a essa solicitação se parece com o exemplo a seguir:

{
  "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 por ID:

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

A resposta a essa solicitação se parece com o exemplo a seguir:

{
  "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 se parece com o exemplo a seguir:

{
  "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 seguinte solicitação para criar um trabalho:

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

O group campo 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 chamada de API REST. O exemplo a seguir cria um grupo de dispositivos com group1 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 todas as propriedades a serem correspondentes. O exemplo a seguir cria um grupo de dispositivos que contém todos os dispositivos associados ao modelo de dispositivo "dtmi:modelDefinition:dtdlv2" onde a provisioned propriedade é 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 se parece com o exemplo a seguir:

{
  "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 id valor 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 se parece 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 novamente trabalhos

Use a seguinte solicitação para interromper 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 bem-sucedida, ela retornará uma 204 - No Content resposta.

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

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

Se a solicitação for bem-sucedida, ela retornará uma 204 - No Content resposta.

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 útil para um trabalho agendado é semelhante a um trabalho padrão, mas inclui os seguintes campos extras:

Campo	Descrição
Horário/Início	A data e hora de início do trabalho no formato ISO 8601
Horário/Recorrência	Um dos `daily`, , `monthlyyearly \|`
Horário/Fim	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 de 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 se parece com o exemplo a seguir:

{
    "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 se parece com o exemplo a seguir:

{
    "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 se parece com o exemplo a seguir:

{
    "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 de solicitação que atualiza um trabalho agendado.

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

A resposta a essa solicitação se parece com o exemplo a seguir:

{
    "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óximos passos

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

Como utilizar a API REST do IoT Central para criar e gerir trabalhos

Cargas úteis de trabalho

Obter informações sobre o emprego

Criar um trabalho

Parar, retomar e executar novamente trabalhos

Criar um trabalho agendado

Obter um trabalho agendado

Listar trabalhos agendados

Atualizar um trabalho agendado

Excluir um trabalho agendado

Próximos passos

Recursos adicionais