Vytváření a správa úloh s využitím rozhraní IoT Central REST API

Článek
10/22/2024

Rozhraní IoT Central REST API umožňuje vyvíjet klientské aplikace, které se integrují s aplikacemi IoT Central. Rozhraní REST API můžete použít k vytváření a správě úloh v aplikaci IoT Central. Rozhraní REST API umožňuje:

Výpis úloh a zobrazení podrobností o úloze ve vaší aplikaci
Vytváření úloh v aplikaci
Zastavte, obnovte a spusťte úlohy ve vaší aplikaci znovu.
Naplánujte úlohy a prohlédněte si podrobnosti naplánované úlohy ve vaší aplikaci.

Naplánované úlohy se vytvoří tak, aby běžely v budoucnu. Můžete nastavit počáteční datum a čas naplánované úlohy tak, aby běžela jednorázově, denně nebo týdně. Neplánované úlohy spouštějí jenom jednorázově.

Tento článek popisuje, jak používat /jobs/{job_id} rozhraní API k hromadnému řízení zařízení. Zařízení můžete ovládat také jednotlivě.

Každé volání rozhraní REST API služby IoT Central vyžaduje autorizační hlavičku. Další informace najdete v tématu Ověřování a autorizace volání rozhraní REST API služby IoT Central.

Referenční dokumentaci k rozhraní IoT Central REST API najdete v referenčních informacích k rozhraní REST API služby Azure IoT Central.

Informace o vytváření a správě úloh v uživatelském rozhraní najdete v tématu Hromadná správa zařízení v aplikaci Azure IoT Central.

Datové části úloh

Mnoho rozhraní API popsaných v tomto článku obsahuje definici, která vypadá jako následující fragment kódu 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"
}

Následující tabulka popisuje pole v předchozím fragmentu kódu JSON:

Pole	Popis
`id`	Jedinečné ID úlohy ve vaší aplikaci.
`displayName`	Zobrazovaný název úlohy ve vaší aplikaci.
`description`	Popis úlohy.
`group`	ID skupiny zařízení, na kterou se úloha vztahuje. `deviceGroups` Pomocí rozhraní REST API ve verzi Preview získáte seznam skupin zařízení ve vaší aplikaci.
`status`	Stav úlohy. Jeden z `complete`, , `failedcancelled`, `pending`, `running`, , `stopped`.
`batch`	Pokud je k dispozici, tato část definuje, jak v úloze dávkot zařízení.
`batch/type`	Velikost každé dávky je buď `percentage` celková zařízení ve skupině, nebo `number` zařízení.
`batch/value`	Procento zařízení nebo počet zařízení v každé dávce.
`cancellationThreshold`	Pokud je k dispozici, tato část definuje prahovou hodnotu zrušení pro úlohu.
`cancellationThreshold/batch`	`true` nebo `false`. Pokud je hodnota true, prahová hodnota zrušení se nastaví pro každou dávku. Pokud `false`se prahová hodnota zrušení vztahuje na celou úlohu.
`cancellationThreshold/type`	Prahová hodnota zrušení pro úlohu je buď zařízení `percentage` , nebo `number` zařízení.
`cancellationThreshold/value`	Procento zařízení nebo počet zařízení, která definují prahovou hodnotu zrušení.
`data`	Pole operací, které úloha provádí.
`data/type`	Jeden z `PropertyJobData`, `CommandJobData`, `CloudPropertyJobData`nebo `DeviceTemplateMigrationJobData`. Verze Preview rozhraní API zahrnuje `DeviceManifestMigrationJobData`.
`data/target`	ID modelu cílových zařízení.
`data/path`	Název vlastnosti, příkazu nebo cloudové vlastnosti.
`data/value`	Hodnota vlastnosti, která se má nastavit, nebo parametr příkazu k odeslání.

Získání informací o úloze

Pomocí následujícího požadavku načtěte seznam úloh ve vaší aplikaci:

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

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Pomocí následujícího požadavku načtěte jednotlivé úlohy podle ID:

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

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Pomocí následujícího požadavku načtěte podrobnosti o zařízeních v úloze:

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

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Vytvoření úlohy

K vytvoření úlohy použijte následující požadavek:

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

Pole group v textu požadavku identifikuje skupinu zařízení v aplikaci IoT Central. Úloha používá skupinu zařízení k identifikaci sady zařízení, na kterých úloha pracuje.

Pokud ještě nemáte vhodnou skupinu zařízení, můžete ji vytvořit pomocí volání rozhraní REST API. Následující příklad vytvoří skupinu zařízení s group1 ID skupiny:

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

Když vytvoříte skupinu zařízení, definujete filter , která vybere zařízení, která se mají do skupiny zahrnout. Filtr identifikuje šablonu zařízení a všechny vlastnosti, které se mají shodovat. Následující příklad vytvoří skupinu zařízení, která obsahuje všechna zařízení přidružená k šabloně zařízení dtmi:modelDefinition:dtdlv2, kde provisioned je truevlastnost .

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

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

K vytvoření nové úlohy teď můžete použít id hodnotu z odpovědi.

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

Odpověď na tento požadavek vypadá jako v následujícím příkladu. Počáteční stav úlohy je 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"
}

Zastavení, obnovení a opětovné spuštění úloh

K zastavení spuštěné úlohy použijte následující požadavek:

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

Pokud požadavek proběhne úspěšně, vrátí 204 - No Content odpověď.

K obnovení zastavené úlohy použijte následující požadavek:

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

Pokud požadavek proběhne úspěšně, vrátí 204 - No Content odpověď.

Pomocí následujícího příkazu znovu spusťte existující úlohu na všech neúspěšných zařízeních:

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

Vytvoření naplánované úlohy

Datová část naplánované úlohy se podobá standardní úloze, ale obsahuje následující pole navíc:

Pole	Popis
schedule/start	Počáteční datum a čas úlohy ve formátu ISO 8601
schedule/recurrence	Jeden z `daily`, , `monthlyyearly \|`
schedule/end	Volitelné pole, které určuje počet výskytů úlohy nebo koncové datum ve formátu ISO 8601

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

Následující příklad ukazuje text požadavku, který vytvoří naplánovanou úlohu.

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

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Získání naplánované úlohy

K získání naplánované úlohy použijte následující požadavek:

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

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Výpis naplánovaných úloh

Seznam naplánovaných úloh získáte pomocí následujícího požadavku:

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

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Aktualizace naplánované úlohy

K aktualizaci naplánované úlohy použijte následující požadavek:

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

Následující příklad ukazuje text požadavku, který aktualizuje naplánovanou úlohu.

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

Odpověď na tento požadavek vypadá jako v následujícím příkladu:

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

Odstranění naplánované úlohy

Pomocí následujícího požadavku odstraňte naplánovanou úlohu.

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

Další kroky

Teď, když jste se naučili spravovat úlohy pomocí rozhraní REST API, je navrhovaným dalším krokem kurz : Použití rozhraní REST API ke správě aplikace Azure IoT Central.

Sdílet prostřednictvím

Vytváření a správa úloh s využitím rozhraní IoT Central REST API

Datové části úloh

Získání informací o úloze

Vytvoření úlohy

Zastavení, obnovení a opětovné spuštění úloh

Vytvoření naplánované úlohy

Získání naplánované úlohy

Výpis naplánovaných úloh

Aktualizace naplánované úlohy

Odstranění naplánované úlohy

Další kroky

Váš názor

Další materiály