Come usare l'API REST IoT Central per creare e gestire i processi

Articolo
06/14/2023

L'API REST di IoT Central consente di sviluppare applicazioni client integrate con le applicazioni IoT Central. È possibile usare l'API REST per creare e gestire processi nell'applicazione IoT Central. L'API REST di IoT Central consente di:

Elencare i processi e visualizzare i dettagli del processo nell'applicazione.
Creare processi nell'applicazione.
Arrestare, riprendere ed eseguire nuovamente i processi nell'applicazione.
Pianificare i processi e visualizzare i dettagli del processo pianificato nell'applicazione.

I processi pianificati vengono creati per l'esecuzione in un momento futuro. È possibile impostare una data e un'ora di inizio per un processo pianificato per l'esecuzione una tantum, giornaliera o settimanale. I processi non pianificati vengono eseguiti una sola volta.

Questo articolo descrive come usare l'API /jobs/{job_id} per controllare i dispositivi in blocco. È anche possibile controllare i dispositivi singolarmente.

Ogni chiamata API REST di IoT Central richiede un'intestazione di autorizzazione. Per altre informazioni, vedere Come autenticare e autorizzare le chiamate API REST di IoT Central.

Per la documentazione di riferimento per l'API REST di IoT Central, vedere Informazioni di riferimento sull'API REST di Azure IoT Central.

Per informazioni su come creare e gestire processi nell'interfaccia utente, vedere Gestire i dispositivi in blocco nell'applicazione Azure IoT Central.

Suggerimento

È possibile usare Postman per provare le chiamate API REST descritte in questo articolo. Scaricare la raccolta Postman di IoT Central e importarla in Postman. Nella raccolta sarà necessario impostare variabili come il sottodominio dell'app e il token di amministratore.

Payload del processo

Molte delle API descritte in questo articolo includono una definizione simile al frammento JSON seguente:

{
  "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"
}

La tabella seguente descrive i campi nel frammento JSON precedente:

Campo	Descrizione
`id`	ID univoco per il processo nell'applicazione.
`displayName`	Nome visualizzato per il processo nell'applicazione.
`description`	Descrizione del processo.
`group`	ID del gruppo di dispositivi a cui si applica il processo. Usare l'API `deviceGroups` REST di anteprima per ottenere un elenco dei gruppi di dispositivi nell'applicazione.
`status`	Stato del processo. Uno di `complete`, `cancelled`, `failedpending`, `running`, , `stopped`.
`batch`	Se presente, questa sezione definisce come eseguire il batch dei dispositivi nel processo.
`batch/type`	Le dimensioni di ogni batch sono uno `percentage` dei dispositivi totali nel gruppo o in un `number` dispositivo.
`batch/value`	Percentuale di dispositivi o numero di dispositivi in ogni batch.
`cancellationThreshold`	Se presente, questa sezione definisce la soglia di annullamento per il processo.
`cancellationThreshold/batch`	`true` o `false`. Se true, la soglia di annullamento viene impostata per ogni batch. Se `false`, la soglia di annullamento si applica all'intero processo.
`cancellationThreshold/type`	La soglia di annullamento per il processo è o `percentage` una `number` di dispositivi.
`cancellationThreshold/value`	Percentuale di dispositivi o numero di dispositivi che definiscono la soglia di annullamento.
`data`	Matrice di operazioni eseguite dal processo.
`data/type`	Uno di `PropertyJobData`, `CommandJobData`, `CloudPropertyJobData`o `DeviceTemplateMigrationJobData`. La versione di anteprima dell'API include `DeviceManifestMigrationJobData`.
`data/target`	ID modello dei dispositivi di destinazione.
`data/path`	Nome della proprietà, del comando o della proprietà cloud.
`data/value`	Valore della proprietà da impostare o il parametro di comando da inviare.

Ottenere informazioni sul processo

Usare la richiesta seguente per recuperare l'elenco dei processi nell'applicazione:

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

La risposta a questa richiesta è simile all'esempio seguente:

{
  "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"
    }
  ]
}

Usare la richiesta seguente per recuperare un singolo processo in base all'ID:

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

La risposta a questa richiesta è simile all'esempio seguente:

{
  "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"
}

Usare la richiesta seguente per recuperare i dettagli dei dispositivi in un processo:

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

La risposta a questa richiesta è simile all'esempio seguente:

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

Creare un processo

Usare la richiesta seguente per creare un processo:

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

Il group campo nel corpo della richiesta identifica un gruppo di dispositivi nell'applicazione IoT Central. Un processo usa un gruppo di dispositivi per identificare il set di dispositivi su cui opera il processo.

Se non si ha già un gruppo di dispositivi appropriato, è possibile crearne uno con una chiamata API REST. L'esempio seguente crea un gruppo di dispositivi con group1 come ID gruppo:

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

Quando si crea un gruppo di dispositivi, si definisce un filter oggetto che seleziona i dispositivi da includere nel gruppo. Un filtro identifica un modello di dispositivo e tutte le proprietà da associare. Nell'esempio seguente viene creato un gruppo di dispositivi contenente tutti i dispositivi associati al modello di dispositivo "dtmi:modelDefinition:dtdlv2" in cui la provisioned proprietà è true.

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

La risposta a questa richiesta è simile all'esempio seguente:

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

È ora possibile usare il id valore della risposta per creare un nuovo processo.

{
  "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"
    }
  ]
}

La risposta a questa richiesta è simile all'esempio seguente. Lo stato iniziale del processo è 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"
}

Arrestare, riprendere ed eseguire di nuovo i processi

Usare la richiesta seguente per arrestare un processo in esecuzione:

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

Se la richiesta ha esito positivo, restituisce una 204 - No Content risposta.

Usare la richiesta seguente per riprendere un processo arrestato:

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

Se la richiesta ha esito positivo, restituisce una 204 - No Content risposta.

Usare il comando seguente per rieseguire un processo esistente in qualsiasi dispositivo non riuscito:

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

Creare un processo pianificato

Il payload per un processo pianificato è simile a un processo standard, ma include i campi aggiuntivi seguenti:

Campo	Descrizione
pianificazione/avvio	Data e ora di inizio per il processo in formato ISO 8601
pianificazione/ricorrenza	Uno di `daily`, `monthly`, `yearly \|`
pianificazione/fine	Campo facoltativo che specifica il numero di occorrenze per il processo o una data di fine nel formato ISO 8601

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

Nell'esempio seguente viene illustrato un corpo della richiesta che crea un processo pianificato.

{
    "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"
        }
    }
}

La risposta a questa richiesta è simile all'esempio seguente:

{
    "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\""
}

Ottenere un processo pianificato

Usare la richiesta seguente per ottenere un processo pianificato:

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

La risposta a questa richiesta è simile all'esempio seguente:

{
    "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\""
}

Elencare i processi pianificati

Usare la richiesta seguente per ottenere un elenco di processi pianificati:

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

La risposta a questa richiesta è simile all'esempio seguente:

{
    "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\""
        }
    ]
}

Aggiornare un processo pianificato

Usare la richiesta seguente per aggiornare un processo pianificato:

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

L'esempio seguente mostra un corpo della richiesta che aggiorna un processo pianificato.

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

La risposta a questa richiesta è simile all'esempio seguente:

{
    "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\""
}

Eliminare un processo pianificato

Usare la richiesta seguente per eliminare un processo pianificato

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

Passaggi successivi

Dopo aver appreso come gestire i processi con l'API REST, un passaggio successivo consigliato consiste nell'apprendere come usare l'API REST per gestire un'applicazione Azure IoT Central.

Condividi tramite

Come usare l'API REST IoT Central per creare e gestire i processi

Payload del processo

Ottenere informazioni sul processo

Creare un processo

Arrestare, riprendere ed eseguire di nuovo i processi

Creare un processo pianificato

Ottenere un processo pianificato

Elencare i processi pianificati

Aggiornare un processo pianificato

Eliminare un processo pianificato

Passaggi successivi

Risorse aggiuntive