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

Artikel
10/22/2024

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.

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 `deviceGroups`zum 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

Geplanten Auftrag erstellen

Die Nutzdaten für einen geplanten Auftrag ähneln denen eines Standardauftrags, enthalten aber zusätzlich folgende 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\""
}

Geplanten Auftrag löschen

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.

Freigeben über

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

Auftragsnutzlasten

Abrufen von Auftragsinformationen

Erstellen eines Auftrags

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

Geplanten Auftrag erstellen

Abrufen eines geplanten Auftrags

Auflisten geplanter Aufträge

Aktualisieren eines geplanten Auftrags

Geplanten Auftrag löschen

Nächste Schritte

Feedback

Zusätzliche Ressourcen