Jak tworzyć zadania i zarządzać nimi przy użyciu interfejsu API REST usługi IoT Central

Artykuł
10/22/2024

Interfejs API REST usługi IoT Central umożliwia tworzenie aplikacji klienckich, które integrują się z aplikacjami usługi IoT Central. Interfejs API REST umożliwia tworzenie zadań i zarządzanie nimi w aplikacji usługi IoT Central. Interfejs API REST umożliwia:

Wyświetlanie listy zadań i wyświetlanie szczegółów zadań w aplikacji.
Tworzenie zadań w aplikacji.
Zatrzymywanie, wznawianie i ponowne uruchamianie zadań w aplikacji.
Zaplanuj zadania i wyświetl szczegóły zaplanowanego zadania w aplikacji.

Zaplanowane zadania są tworzone do uruchamiania w przyszłości. Możesz ustawić datę i godzinę rozpoczęcia zaplanowanego zadania, aby było uruchamiane jednorazowo, codziennie lub co tydzień. Nieplanowane zadania są uruchamiane tylko jednorazowo.

W tym artykule opisano sposób używania interfejsu API do zbiorczego /jobs/{job_id} sterowania urządzeniami. Urządzenia można również kontrolować indywidualnie.

Każde wywołanie interfejsu API REST usługi IoT Central wymaga nagłówka autoryzacji. Aby dowiedzieć się więcej, zobacz Jak uwierzytelniać i autoryzować wywołania interfejsu API REST usługi IoT Central.

Aby uzyskać dokumentację referencyjną interfejsu API REST usługi IoT Central, zobacz Dokumentacja interfejsu API REST usługi Azure IoT Central.

Aby dowiedzieć się, jak tworzyć zadania i zarządzać nimi w interfejsie użytkownika, zobacz Zarządzanie urządzeniami zbiorczo w aplikacji usługi Azure IoT Central.

Ładunki zadań

Wiele interfejsów API opisanych w tym artykule zawiera definicję podobną do następującego fragmentu kodu 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"
}

W poniższej tabeli opisano pola w poprzednim fragmencie kodu JSON:

Pole	opis
`id`	Unikatowy identyfikator zadania w aplikacji.
`displayName`	Nazwa wyświetlana zadania w aplikacji.
`description`	Opis zadania.
`group`	Identyfikator grupy urządzeń, do którego ma zastosowanie zadanie. Użyj interfejsu `deviceGroups` API REST w wersji zapoznawczej, aby uzyskać listę grup urządzeń w aplikacji.
`status`	Stan zadania. Jeden z `complete`, , `failedcancelled`, `pending`, `running`, . `stopped`
`batch`	Jeśli istnieje, w tej sekcji zdefiniowano sposób dzielenia urządzeń w partie w zadaniu.
`batch/type`	Rozmiar każdej partii to `percentage` łączna liczba urządzeń w grupie lub `number` urządzeniach.
`batch/value`	Procent urządzeń lub liczba urządzeń w każdej partii.
`cancellationThreshold`	Jeśli istnieje, w tej sekcji zdefiniowano próg anulowania zadania.
`cancellationThreshold/batch`	Usługa `true` lub `false`. Jeśli wartość true, dla każdej partii zostanie ustawiony próg anulowania. Jeśli `false`wartość progowa anulowania ma zastosowanie do całego zadania.
`cancellationThreshold/type`	Próg anulowania zadania to lub `percentage` urządzenia `number` .
`cancellationThreshold/value`	Procent urządzeń lub liczba urządzeń, które definiują próg anulowania.
`data`	Tablica operacji wykonywanych przez zadanie.
`data/type`	`PropertyJobData`Jeden z , `CommandJobData`, `CloudPropertyJobData`lub `DeviceTemplateMigrationJobData`. Wersja zapoznawcza interfejsu API zawiera `DeviceManifestMigrationJobData`element .
`data/target`	Identyfikator modelu urządzeń docelowych.
`data/path`	Nazwa właściwości, polecenia lub właściwości w chmurze.
`data/value`	Wartość właściwości do ustawienia lub parametru polecenia do wysłania.

Pobieranie informacji o zadaniu

Użyj następującego żądania, aby pobrać listę zadań w aplikacji:

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

Odpowiedź na to żądanie wygląda następująco:

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

Użyj następującego żądania, aby pobrać pojedyncze zadanie według identyfikatora:

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

Odpowiedź na to żądanie wygląda następująco:

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

Użyj następującego żądania, aby pobrać szczegóły urządzeń w zadaniu:

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

Odpowiedź na to żądanie wygląda następująco:

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

Tworzenie zadania

Aby utworzyć zadanie, użyj następującego żądania:

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

Pole group w treści żądania identyfikuje grupę urządzeń w aplikacji usługi IoT Central. Zadanie używa grupy urządzeń do identyfikowania zestawu urządzeń, na których działa zadanie.

Jeśli nie masz jeszcze odpowiedniej grupy urządzeń, możesz go utworzyć za pomocą wywołania interfejsu API REST. W poniższym przykładzie zostanie utworzona grupa urządzeń z group1 identyfikatorem grupy:

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

Podczas tworzenia grupy urządzeń należy zdefiniować element filter , który wybiera urządzenia do uwzględnienia w grupie. Filtr identyfikuje szablon urządzenia i wszystkie właściwości, które mają być zgodne. Poniższy przykład obejmuje tworzenie grupy urządzeń zawierającej wszystkie urządzenia skojarzone z szablonem urządzenia "dtmi:modelDefinition:dtdlv2", w którym provisioned właściwość to true.

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

Odpowiedź na to żądanie wygląda następująco:

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

Teraz możesz użyć id wartości z odpowiedzi, aby utworzyć nowe zadanie.

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

Odpowiedź na to żądanie wygląda podobnie do poniższego przykładu. Początkowy stan zadania to 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"
}

Zatrzymywanie, wznawianie i ponowne uruchamianie zadań

Użyj następującego żądania, aby zatrzymać uruchomione zadanie:

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

Jeśli żądanie zakończy się powodzeniem 204 - No Content , zwraca odpowiedź.

Użyj następującego żądania, aby wznowić zatrzymane zadanie:

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

Jeśli żądanie zakończy się powodzeniem 204 - No Content , zwraca odpowiedź.

Użyj następującego polecenia, aby ponownie uruchomić istniejące zadanie na wszystkich urządzeniach, które zakończyły się niepowodzeniem:

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

Tworzenie zaplanowanego zadania

Ładunek zaplanowanego zadania jest podobny do zadania standardowego, ale zawiera następujące dodatkowe pola:

Pole	opis
harmonogram/uruchamianie	Data i godzina rozpoczęcia zadania w formacie ISO 8601
harmonogram/cykl	`daily`Jeden z , , `monthlyyearly \|`
harmonogram/koniec	Opcjonalne pole, które określa liczbę wystąpień zadania lub datę zakończenia w formacie ISO 8601

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

W poniższym przykładzie przedstawiono treść żądania, która tworzy zaplanowane zadanie.

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

Odpowiedź na to żądanie wygląda następująco:

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

Pobieranie zaplanowanego zadania

Użyj następującego żądania, aby pobrać zaplanowane zadanie:

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

Odpowiedź na to żądanie wygląda następująco:

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

Wyświetlanie listy zaplanowanych zadań

Użyj następującego żądania, aby uzyskać listę zaplanowanych zadań:

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

Odpowiedź na to żądanie wygląda następująco:

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

Aktualizowanie zaplanowanego zadania

Użyj następującego żądania, aby zaktualizować zaplanowane zadanie:

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

W poniższym przykładzie przedstawiono treść żądania, która aktualizuje zaplanowane zadanie.

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

Odpowiedź na to żądanie wygląda następująco:

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

Usuwanie zaplanowanego zadania

Użyj następującego żądania, aby usunąć zaplanowane zadanie

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

Następne kroki

Teraz, gdy wiesz już, jak zarządzać zadaniami za pomocą interfejsu API REST, sugerowanym następnym krokiem jest zapoznanie się z samouczkiem : zarządzanie aplikacją usługi Azure IoT Central przy użyciu interfejsu API REST.

Udostępnij za pośrednictwem

Jak tworzyć zadania i zarządzać nimi przy użyciu interfejsu API REST usługi IoT Central

Ładunki zadań

Pobieranie informacji o zadaniu

Tworzenie zadania

Zatrzymywanie, wznawianie i ponowne uruchamianie zadań

Tworzenie zaplanowanego zadania

Pobieranie zaplanowanego zadania

Wyświetlanie listy zaplanowanych zadań

Aktualizowanie zaplanowanego zadania

Usuwanie zaplanowanego zadania

Następne kroki

Opinia

Dodatkowe zasoby