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

Artigo
08/08/2024

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.

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`, `cancelled`, `failed`, , `pending`, `running`. `stopped`
`batch`	Se presente, esta seção define como agrupar os dispositivos no trabalho.
`batch/type`	O tamanho de cada lote é um `percentage` do total de dispositivos no grupo ou um `number` 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 `percentage` ou um `number` 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`, `CommandJobData`, `CloudPropertyJobData`, 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`, `monthly`, `yearly \|`
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.

Partilhar via

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

Comentários

Recursos adicionais