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

Rozhraní REST API služby IoT Central 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 v aplikaci
  • Vytvářejte úlohy v aplikaci.
  • Zastavte, obnovte a znovu spusťte úlohy ve vaší aplikaci.

Důležité

Rozhraní API úloh je aktuálně ve verzi Preview. Všechna volání rozhraní REST API popsaná v tomto článku by měla obsahovat ?api-version=1.2-preview.

Tento článek popisuje, jak pomocí /jobs/{job_id} rozhraní API ovládat zařízení hromadně. 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í dokumentace k rozhraní REST API služby IoT Central 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.

Tip

Pomocí Nástroje Postman můžete vyzkoušet volání rozhraní REST API popsaná v tomto článku. Stáhněte si kolekci IoT Central Postman a naimportujte ji do Postmanu. V kolekci budete muset nastavit proměnné, jako je subdoména aplikace a token správce.

Informace o správě úloh pomocí uživatelského rozhraní IoT Central 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 Description
id Jedinečné ID úlohy ve vaší aplikaci.
displayName Zobrazovaný název úlohy v 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, , , cancelled, runningfailedpending, stopped.
batch V případě přítomnosti tato část definuje, jak dávkot zařízení v úloze.
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 V případě přítomnosti tato část definuje prahovou hodnotu zrušení úlohy.
cancellationThreshold/batch true nebo false: Pokud ano, je prahová hodnota zrušení nastavená pro každou dávku. Pokud falsese prahová hodnota zrušení vztahuje na celou úlohu.
cancellationThreshold/type Prahová hodnota zrušení úlohy je buď a 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, CommandJobDatanebo CloudPropertyJobData
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 pro 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=1.2-preview

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

K načtení jednotlivé úlohy podle ID použijte následující požadavek:

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

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=1.2-preview

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=1.2-preview

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

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://{subdomain}.{baseDomain}/api/deviceGroups/group1?api-version=1.2-preview

Při vytváření skupiny zařízení definujete filter , která vybere zařízení, která se mají zahrnout do skupiny. 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

Pomocí následujícího požadavku zastavte spuštěnou úlohu:

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

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

Pokud chcete obnovit zastavenou úlohu, použijte následující požadavek:

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

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=1.2-preview

Další kroky

Teď, když jste se dozvěděli, jak spravovat úlohy pomocí rozhraní REST API, je navrhovaným dalším krokem informace o správě aplikací IoT Central pomocí rozhraní REST API.