Freigeben über

Verwenden der IoT Central-REST-API zum Erstellen und Verwalten von Aufträgen

  • Artikel

Mit der IoT Central-REST-API können Sie Clientanwendungen entwickeln, die in IoT Central-Anwendungen integriert werden. Mit der REST-API können Sie in Ihrer IoT Central-Anwendung Aufträge erstellen und verwalten. Mit der REST-API können Sie Folgendes durchführen:

  • Auflisten von Aufträgen und Anzeigen von Auftragsdetails in Ihrer Anwendung.
  • Erstellen von Aufträgen in Ihrer Anwendung.
  • Beenden, Fortsetzen und erneutes Ausführen von Aufträgen in Ihrer Anwendung.
  • Planen von Aufträgen und Anzeigen der Details geplanter Aufträge in Ihrer Anwendung.

Geplante Aufträge werden für die Ausführung zu einem späteren Zeitpunkt erstellt. Sie können ein Startdatum und eine Startzeit für einen geplanten Auftrag festlegen und angeben, ob er einmal, täglich oder wöchentlich ausgeführt werden soll. Nicht geplante Aufträge werden nur einmal ausgeführt.

In diesem Artikel wird beschrieben, wie Sie die Auftrags-API (/jobs/{job_id}) zum Steuern von Geräten in einem Massenvorgang verwenden. Sie können Geräte auch einzeln steuern.

Jeder IoT Central-REST-API-Aufruf erfordert einen Autorisierungsheader. Weitere Informationen finden Sie unter Authentifizieren und Autorisieren von IoT Central-REST-API-Aufrufen.

Die Referenzdokumentation für die IoT Central-REST-API finden Sie unter Azure IoT Central: Referenz zur REST-API.

Informationen zum Erstellen und Verwalten von Aufträgen in der Benutzeroberfläche finden Sie unter Verwalten von Geräten per Massenvorgang in Ihrer Azure IoT Central-Anwendung.

Tipp

Sie können Postman verwenden, um die in diesem Artikel beschriebenen REST-API-Aufrufe auszuprobieren. Laden Sie die IoT Central Postman-Sammlung herunter, und importieren Sie sie in Postman. In der Sammlung müssen Sie Variablen wie Ihre App-Unterdomäne und Ihr Administratortoken festlegen.

Auftragsnutzlasten

Viele der in diesem Artikel beschriebenen APIs enthalten eine Definition, die wie der folgende JSON-Codeausschnitt aussieht:

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

In der folgenden Tabelle werden die Felder im vorstehenden JSON-Codeausschnitt beschrieben:

Feld Beschreibung
id Eine eindeutige ID für den Auftrag in Ihrer Anwendung.
displayName Der Anzeigename für den Auftrag in Ihrer Anwendung.
description Eine Beschreibung des Auftrags.
group Die ID der Gerätegruppe, für die der Auftrag gilt. Verwenden Sie die Vorschau-REST-API deviceGroupszum Abrufen einer Liste der Gerätegruppen in Ihrer Anwendung.
status Der Status des Auftrags. Einer der folgenden Werte: complete, cancelled, failed, pending, running, stopped.
batch Falls vorhanden, wird in diesem Abschnitt definiert, wie die Geräte im Auftrag batchweise ausgeführt werden.
batch/type Die Größe jedes Batches ist entweder ein percentage der gesamten Geräte in der Gruppe oder eine number von Geräten,
batch/value also entweder der Prozentsatz der Geräte oder die Anzahl der Geräte in jedem Batch.
cancellationThreshold Falls vorhanden, wird in diesem Abschnitt der Abbruchschwellenwert für den Auftrag definiert.
cancellationThreshold/batch true oder false „true“ gibt an, dass der Abbruchschwellenwert für jeden Batch festgelegt wird. false gibt an, dass der Abbruchschwellenwert für den gesamten Auftrag gilt.
cancellationThreshold/type Der Abbruchschwellenwert für den Auftrag ist entweder ein percentage oder eine number von Geräten,
cancellationThreshold/value also entweder der Prozentsatz der Geräte oder die Anzahl der Geräte, die den Abbruchschwellenwert definieren.
data Ein Array von Vorgängen, die der Auftrag ausführt.
data/type Einer der folgenden Werte: PropertyJobData, CommandJobData, CloudPropertyJobData oder DeviceTemplateMigrationJobData. Die Vorschauversion der API enthält DeviceManifestMigrationJobData.
data/target Die Modell-ID der Zielgeräte.
data/path Der Name der Eigenschaft, des Befehls oder der Cloudeigenschaft.
data/value Der festzulegende Eigenschaftswert oder der zu sendende Befehlsparameter.

Abrufen von Auftragsinformationen

Mit der folgenden Anforderung können Sie die Liste der Aufträge in Ihrer Anwendung abrufen:

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

Die Antwort auf diese Anforderung sieht wie das folgende Beispiel aus:

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

Mit der folgenden Anforderung können Sie einen einzelnen Auftrag anhand der ID abrufen:

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

Die Antwort auf diese Anforderung sieht wie das folgende Beispiel aus:

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

Mit der folgenden Anforderung können Sie die Details der Geräte in einem Auftrag abrufen:

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

Die Antwort auf diese Anforderung sieht wie das folgende Beispiel aus:

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

Erstellen eines Auftrags

Mit der folgenden Anforderung können Sie einen Auftrag erstellen:

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

Das Feld group im Anforderungstext identifiziert eine Gerätegruppe in Ihrer IoT Central-Anwendung. Ein Auftrag identifiziert mithilfe einer Gerätegruppe den Satz von Geräten, auf denen der Auftrag ausgeführt wird.

Wenn Sie noch keine geeignete Gerätegruppe haben, können Sie eine mit einem REST-API-Aufruf erstellen. Im folgenden Beispiel wird eine Gerätegruppe mit group1 als Gruppen-ID erstellt:

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

Beim Erstellen einer Gerätegruppe definieren Sie einen filter, der die Geräte auswählt, die in die Gruppe einbezogen werden sollen. Ein Filter identifiziert eine Gerätevorlage und alle Eigenschaften, die übereinstimmen sollen. Im folgenden Beispiel wird eine Gerätegruppe mit allen der Vorlage „dtmi:modelDefinition:dtdlv2“ zugeordneten Geräten erstellt, wobei die Eigenschaft provisioned den Wert true hat.

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

Die Antwort auf diese Anforderung sieht wie das folgende Beispiel aus:

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

Jetzt können Sie den Wert id aus der Antwort verwenden, um einen neuen Auftrag zu erstellen.

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

Die Antwort auf diese Anforderung sieht wie das folgende Beispiel aus. Der anfängliche Auftragsstatus lautet 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"
}

Beenden, Fortsetzen und erneutes Ausführen von Aufträgen

Mit der folgenden Anforderung können Sie einen zurzeit ausgeführten Auftrag beenden:

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

Wenn die Anforderung erfolgreich ist, wird eine 204 - No Content-Antwort zurückgegeben.

Mit der folgenden Anforderung können Sie einen beendeten Auftrag fortsetzen:

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

Wenn die Anforderung erfolgreich ist, wird eine 204 - No Content-Antwort zurückgegeben.

Mit dem folgenden Befehl können Sie einen vorhandenen Auftrag auf fehlerhaften Geräten erneut ausführen:

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

Erstellen eines geplanten Auftrags

Die Nutzlast für einen geplanten Auftrag ähnelt einem Standardauftrag, enthält aber die folgenden zusätzlichen Felder:

Feld Beschreibung
schedule/start Das Startdatum und die Startzeit für den Auftrag im ISO 8601-Format
schedule/recurrence Einer der folgenden Werte: daily, monthly, yearly |.
schedule/end Ein optionales Feld, das entweder die Anzahl von Vorkommen für den Auftrag oder ein Enddatum im ISO 8601-Format angibt 
PUT https://{your app subdomain}.azureiotcentral.com/api/scheduledJobs/scheduled-Job-001?api-version=2022-07-31

Das folgende Beispiel zeigt einen Anforderungstext zum Erstellen eines geplanten Auftrags:

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

Die Antwort auf diese Anforderung sieht wie das folgende Beispiel aus:

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

Abrufen eines geplanten Auftrags

Verwenden Sie die folgende Anforderung, um einen geplanten Auftrag abzurufen:

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

Die Antwort auf diese Anforderung sieht wie das folgende Beispiel aus:

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

Auflisten geplanter Aufträge

Verwenden Sie die folgende Anforderung, um eine Liste geplanter Aufträge abzurufen:

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

Die Antwort auf diese Anforderung sieht wie das folgende Beispiel aus:

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

Aktualisieren eines geplanten Auftrags

Verwenden Sie die folgende Anforderung, um einen geplanten Auftrag zu aktualisieren:

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

Das folgende Beispiel zeigt einen Anforderungstext zum Aktualisieren eines geplanten Auftrags:

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

Die Antwort auf diese Anforderung sieht wie das folgende Beispiel aus:

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

Löschen eines geplanten Auftrags

Verwenden Sie die folgende Anforderung, um einen geplanten Auftrag zu löschen:

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

Nächste Schritte

Nachdem Sie erfahren haben, wie Sie Aufträge mit der REST-API verwalten können, wird als nächster Schritt das Verwalten von IoT Central-Anwendungen mit der REST-API empfohlen.