Verwenden der IoT Central-REST-API zum Verwalten von Geräten

Artikel
03/01/2024

Mit der IoT Central-REST-API können Sie Clientanwendungen entwickeln, die in IoT Central-Anwendungen integriert werden. Sie können die REST-API verwenden, um Geräte in Ihrer IoT Central-Anwendung zu verwalten.

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.

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.

Informationen zum Verwalten von Geräten mithilfe der IoT Central-Benutzeroberfläche finden Sie unter Verwalten einzelner Geräte in Ihrer Azure IoT Central-Anwendung.

REST-API für Device Messaging

Mit der IoT Central-REST-API können Sie folgende Aktionen ausführen:

Hinzufügen eines Geräts zu Ihrer Anwendung
Durchführen eines Updates für ein Gerät in Ihrer Anwendung
Abrufen einer Liste der Geräte in der Anwendung
Abrufen eines Geräts nach ID
Abrufen von Geräteanmeldeinformationen
Löschen eines Geräts in Ihrer Anwendung
Filtern der Liste der Geräte in der Anwendung

Hinzufügen eines Geräts

Verwenden Sie die folgende Anforderung, um ein neues Gerät zu erstellen.

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

Das folgende Beispiel zeigt einen Anforderungstext, der ein Gerät für eine Gerätevorlage hinzufügt. Die template-Details können Sie auf der Seite für Gerätevorlagen auf der Benutzeroberfläche der IoT Central-Anwendung abrufen.

{
  "displayName": "CheckoutThermostat",
  "template": "dtmi:contoso:Thermostat;1",
  "simulated": true,
  "enabled": true
}

Der Anforderungstext enthält einige erforderliche Felder:

@displayName: Dies ist der Anzeigename des Geräts.
@enabled: deklariert dieses Objekt als Schnittstelle
@etag: Dies ist das ETag, das verwendet wird, um Konflikte bei Geräteupdates zu verhindern.
simulated: Wird das Gerät simuliert?
template : Dies ist die Gerätevorlagendefinition für das Gerät.

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

{
    "id": "thermostat1",
    "etag": "eyJoZWFkZXIiOiJcIjI0MDAwYTdkLTAwMDAtMDMwMC0wMDAwLTYxYjgxZDIwMDAwMFwiIiwiZGF0YSI6IlwiMzMwMDQ1M2EtMDAwMC0wMzAwLTAwMDAtNjFiODFkMjAwMDAwXCIifQ",
    "displayName": "CheckoutThermostat",
    "simulated": true,
    "provisioned": false,
    "template": "dtmi:contoso:Thermostat;1",
    "enabled": true
}

Abrufen eines Geräts

Verwenden Sie die folgende Anforderung, um Details eines Geräts aus Ihrer Anwendung abzurufen:

GET https://{your app subdomain}/api/devices/{deviceId}?api-version=2022-07-31

Hinweis

Sie können die deviceId von der IoT Central-Anwendungsbenutzeroberfläche abrufen, indem Sie mit der Maus auf ein Gerät zeigen.

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

{
    "id": "5jcwskdwbm",
    "etag": "eyJoZWFkZXIiOiJcIjI0MDBlMDdjLTAwMDAtMDMwMC0wMDAwLTYxYjgxYmVlMDAwMFwiIn0",
    "displayName": "Thermostat - 5jcwskdwbm",
    "simulated": false,
    "provisioned": false,
    "template": "dtmi:contoso:Thermostat;1",
    "enabled": true
}

Die folgende Tabelle zeigt die Zuordnung zwischen dem Statuswert für ein Gerät in der Benutzeroberfläche und den Werten, die von der REST-API verwendet werden, um mit Geräten zu interagieren:

Gerätestatus in der Benutzeroberfläche	Hinweise	GET-Anforderung der REST-API
Warten auf Genehmigung	Die Option „Automatisch genehmigen“ ist in der Geräteverbindungsgruppe deaktiviert, und das Gerät wurde nicht über die Benutzeroberfläche hinzugefügt. Ein Benutzer muss das Gerät manuell über die Benutzeroberfläche genehmigen, bevor es verwendet werden kann.	`Provisioned: false` `Enabled: false`
Registriert	Ein Gerät wurde automatisch oder manuell genehmigt.	`Provisioned: false` `Enabled: true`
Bereitgestellt	Das Gerät wurde bereitgestellt und kann eine Verbindung mit Ihrer IoT Central-Anwendung herstellen.	`Provisioned: true` `Enabled: true`
Blockiert	Das Gerät kann keine Verbindung mit Ihrer IoT Central-Anwendung herstellen. Sie können Geräte blockieren, die einen der anderen Status aufweisen.	`Provisioned:` ist abhängig von `Waiting for approval`/`Registered`/`Provisioned status`. `Enabled: false`

Abrufen der Geräteanmeldeinformationen

Verwenden Sie die folgende Anforderung, um die Anmeldeinformationen eines Geräts aus Ihrer Anwendung abzurufen:

GET https://{your app subdomain}/api/devices/{deviceId}/credentials?api-version=2022-07-31

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

{
    "idScope": "0ne003E64EF",
    "symmetricKey": {
        "primaryKey": "XUQvxGl6+Q1R0NKN5kOTmLOWsSKiuqs5N9unrjYCH4k=",
        "secondaryKey": "Qp/MTGHjn5MUTw4NVGhRfG+P+L1zh1gtAhO/KH8kn5c="
    }
}

Aktualisieren eines Geräts

PATCH https://{your app subdomain}/api/devices/{deviceId}?api-version=2022-07-31

Der folgende Beispielanforderungstext ändert das Feld enabled in false:

{
  "enabled": false
}

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

{
    "id": "thermostat1",
    "etag": "eyJoZWFkZXIiOiJcIjI0MDAwYTdkLTAwMDAtMDMwMC0wMDAwLTYxYjgxZDIwMDAwMFwiIiwiZGF0YSI6IlwiMzMwMDQ1M2EtMDAwMC0wMzAwLTAwMDAtNjFiODFkMjAwMDAwXCIifQ",
    "displayName": "CheckoutThermostat",
    "simulated": true,
    "provisioned": false,
    "template": "dtmi:contoso:Thermostat;1",
    "enabled": false
}

Löschen eines Mediums

Verwenden Sie die folgende Anforderung, um ein Gerät zu löschen:

DELETE https://{your app subdomain}/api/devices/{deviceId}?api-version=2022-07-31

Listen Sie die Geräte auf.

Verwenden Sie die folgende Anforderung, um eine Liste von Geräten aus Ihrer Anwendung abzurufen:

GET https://{your app subdomain}/api/devices?api-version=2022-07-31

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

{
    "value": [
        {
            "id": "5jcwskdwbm",
            "etag": "eyJoZWFkZXIiOiJcIjI0MDBlMDdjLTAwMDAtMDMwMC0wMDAwLTYxYjgxYmVlMDAwMFwiIn0",
            "displayName": "Thermostat - 5jcwskdwbm",
            "simulated": false,
            "provisioned": false,
            "template": "dtmi:contoso:Thermostat;1",
            "enabled": true
        },
        {
            "id": "ccc",
            "etag": "eyJoZWFkZXIiOiJcIjI0MDAwYjdkLTAwMDAtMDMwMC0wMDAwLTYxYjgxZDJjMDAwMFwiIn0",
            "displayName": "CheckoutThermostat",
            "simulated": true,
            "provisioned": true,
            "template": "dtmi:contoso:Thermostat;1",
            "enabled": true
        }
    ]
}

Zuweisen eines Bereitstellungsmanifests

Wenn Sie ein IoT Edge-Gerät hinzufügen, können Sie die API verwenden, um dem Gerät ein IoT Edge-Bereitstellungsmanifest zuzuweisen. Weitere Informationen finden Sie unter Zuweisen eines Bereitstellungsmanifests zu einem Gerät.

Verwenden von ODATA-Filtern

In der Vorschauversion der API (api-version=2022-10-31-preview) können Sie ODATA-Filter verwenden, um die von der API zum Auflisten von Geräten zurückgegebenen Ergebnisse zu filtern und zu sortieren.

maxpagesize

Verwenden Sie maxpagesize, um die Ergebnisgröße festzulegen. Die maximale Größe für zurückgegebene Ergebnisse beträgt 100, und die Standardgröße ist 25.

Verwenden Sie die folgende Anforderung, um eines der zehn wichtigsten Geräte aus Ihrer Anwendung abzurufen:

GET https://{your app subdomain}/api/devices?api-version=2022-10-31-preview&maxpagesize=10

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

{
    "value": [
        {
            "id": "5jcwskdwbm",
            "etag": "eyJoZWFkZXIiOiJcIjI0MDBlMDdjLTAwMDAtMDMwMC0wMDAwLTYxYjgxYmVlMDAwMFwiIn0",
            "displayName": "Thermostat - 5jcwskdwbm",
            "simulated": false,
            "provisioned": false,
            "template": "dtmi:contoso:Thermostat;1",
            "enabled": true
        },
        {
            "id": "5jcwskdgdwbm",
            "etag": "eyJoZWdhhZXIiOiJcIjI0MDBlMDdjLTAwMDAtMDMwMC0wMDAwLTYxYjgxYmVlMDAwMFwiIn0",
            "displayName": "RS40 Occupancy Sensor - 5jcwskdgdwbm",
            "simulated": false,
            "provisioned": false,
            "template": "urn:modelDefinition:aqlyr1ulfku:tz5rut2pvx",
            "enabled": true
        },
        ...
    ],
    "nextLink": "https://{your app subdomain}.azureiotcentral.com/api/devices?api-version=2022-07-31&%24top=1&%24skiptoken=%257B%2522token%2522%253A%2522%252BRID%253A%7EJWYqAOis7THQbBQAAAAAAg%253D%253D%2523RT%253A1%2523TRC%253A1%2523ISV%253A2%2523IEO%253A65551%2523QCF%253A4%2522%252C%2522range%2522%253A%257B%2522min%2522%253A%2522%2522%252C%2522max%2522%253A%252205C1D7F7591D44%2522%257D%257D"
}

Die Antwort enthält einen nextLink-Wert, mit dem Sie die nächste Ergebnisseite abrufen können.

filter

Verwenden Sie filter, um Ausdrücke zum Filtern der Geräteliste zu erstellen. In der folgenden Tabelle sind die Vergleichsoperatoren aufgeführt, die Sie verwenden können:

Vergleichsoperator	Symbol	Beispiel
Equals	eq	`id eq 'device1' and scopes eq 'redmond'`
Not Equals	ne	`Enabled ne true`
Kleiner als oder gleich	le	`id le '26whl7mure6'`
Kleiner als	lt	`id lt '26whl7mure6'`
Größer als oder gleich	ge	`id ge '26whl7mure6'`
Größer als	gt	`id gt '26whl7mure6'`

In der folgenden Tabelle sind die logischen Operatoren aufgeführt, die Sie in filter-Ausdrücken verwenden können:

Logischer Operator	Symbol	Beispiel
UND	und	`id eq 'device1' and enabled eq true`
oder	oder	`id eq 'device1' or simulated eq false`

Aktuell funktioniert filter mit den folgenden Gerätefeldern:

FieldName	type	Beschreibung
`id`	string	Geräte-ID
`displayName`	Zeichenfolge	Anzeigename des Geräts
`enabled`	boolean	Aktivierungsstatus des Geräts
`provisioned`	boolean	Bereitstellungsstatus des Geräts
`simulated`	boolean	Simulationsstatus des Geräts
`template`	Zeichenfolge	Gerätevorlagen-ID
`scopes`	Zeichenfolge	Organisations-ID

Für „filter“ unterstützte Funktionen:

Aktuell ist die contains-Funktion die einzige unterstützte Filterfunktion für Gerätelisten:

filter=contains(displayName, 'device1')

Das folgende Beispiel zeigt, wie alle Geräte abgerufen werden, in denen die Zeichenfolge thermostat im Anzeigename enthalten ist:

GET https://{your app subdomain}/api/deviceTemplates?api-version=2022-10-31-preview&filter=contains(displayName, 'thermostat')

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

{
    "value": [
        {
            "id": "5jcwskdwbm",
            "etag": "eyJoZWFkZXIiOiJcIjI0MDBlMDdjLTAwMDAtMDMwMC0wMDAwLTYxYjgxYmVlMDAwMFwiIn0",
            "displayName": "thermostat1",
            "simulated": false,
            "provisioned": false,
            "template": "dtmi:contoso:Thermostat;1",
            "enabled": true
        },
        {
            "id": "ccc",
            "etag": "eyJoZWFkZXIiOiJcIjI0MDAwYjdkLTAwMDAtMDMwMC0wMDAwLTYxYjgxZDJjMDAwMFwiIn0",
            "displayName": "thermostat2",
            "simulated": true,
            "provisioned": true,
            "template": "dtmi:contoso:Thermostat;1",
            "enabled": true
        }
    ]
}

orderby

Verwenden Sie orderby, um die Ergebnisse zu sortieren. Derzeit ermöglicht orderby nur das Sortieren nach displayName. orderby sortiert standardmäßig in aufsteigender Reihenfolge. Mit desc können Sie in absteigender Reihenfolge sortieren. Beispiel:

orderby=displayName
orderby=displayName desc

Das folgende Beispiel zeigt, wie alle Gerätevorlagen abgerufen werden, in denen das Ergebnis nach displayName sortiert wird:

GET https://{your app subdomain}/api/devices?api-version=2022-10-31-preview&orderby=displayName

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

{
    "value": [
        {
            "id": "ccc",
            "etag": "eyJoZWFkZXIiOiJcIjI0MDAwYjdkLTAwMDAtMDMwMC0wMDAwLTYxYjgxZDJjMDAwMFwiIn0",
            "displayName": "CheckoutThermostat",
            "simulated": true,
            "provisioned": true,
            "template": "dtmi:contoso:Thermostat;1",
            "enabled": true
        },
        {
            "id": "5jcwskdwbm",
            "etag": "eyJoZWFkZXIiOiJcIjI0MDBlMDdjLTAwMDAtMDMwMC0wMDAwLTYxYjgxYmVlMDAwMFwiIn0",
            "displayName": "Thermostat - 5jcwskdwbm",
            "simulated": false,
            "provisioned": false,
            "template": "dtmi:contoso:Thermostat;1",
            "enabled": true
        }
    ]
}

Sie können auch zwei oder mehr Filter kombinieren.

Das folgende Beispiel zeigt, wie Sie die ersten drei Geräte abrufen, bei denen der Anzeigename die Zeichenfolge Thermostat enthält.

GET https://{your app subdomain}/api/deviceTemplates?api-version=2022-10-31-preview&filter=contains(displayName, 'Thermostat')&maxpagesize=3

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

{
  "value": [
    {
      "id": "1fpwlahp0zp",
      "displayName": "Thermostat - 1fpwlahp0zp",
      "simulated": false,
      "provisioned": false,
      "etag": "eyJwZ0luc3RhbmNlIjoiYTRjZGQyMjQtZjIxMi00MTI4LTkyMTMtZjcwMTBlZDhkOWQ0In0=",
      "template": "dtmi:contoso:mythermostattemplate;1",
      "enabled": true
    },
    {
      "id": "1yg0zvpz9un",
      "displayName": "Thermostat - 1yg0zvpz9un",
      "simulated": false,
      "provisioned": false,
      "etag": "eyJwZ0luc3RhbmNlIjoiZGQ1YTY4MDUtYzQxNS00ZTMxLTgxM2ItNTRiYjdiYWQ1MWQ2In0=",
      "template": "dtmi:contoso:mythermostattemplate;1",
      "enabled": true
    },
    {
      "id": "20cp9l96znn",
      "displayName": "Thermostat - 20cp9l96znn",
      "simulated": false,
      "provisioned": false,
      "etag": "eyJwZ0luc3RhbmNlIjoiNGUzNWM4OTItNDBmZi00OTcyLWExYjUtM2I4ZjU5NGZkODBmIn0=",
      "template": "dtmi:contoso:mythermostattemplate;1",
      "enabled": true
    }
  ],
  "nextLink": "https://{your app subdomain}.azureiotcentral.com/api/devices?api-version=2022-10-31-preview&filter=contains%28displayName%2C+%27Thermostat%27%29&maxpagesize=3&$skiptoken=aHR0cHM6Ly9pb3RjLXByb2QtbG4taW5ma3YteWRtLnZhdWx0LmF6dXJlLm5ldC9zZWNyZXRzL2FwaS1lbmMta2V5LzY0MzZkOTY2ZWRjMjRmMDQ5YWM1NmYzMzFhYzIyZjZi%3AgWMDkfdpzBF0eYiYCGRdGQ%3D%3D%3ATVTgi5YVv%2FBfCd7Oos6ayrCIy9CaSUVu2ULktGQoHZDlaN7uPUa1OIuW0MCqT3spVXlSRQ9wgNFXsvb6mXMT3WWapcDB4QPynkI%2FE1Z8k7s3OWiBW3EQpdtit3JTCbj8qRNFkA%3D%3D%3Aq63Js0HL7OCq%2BkTQ19veqA%3D%3D"
}

Gerätegruppen

Sie können Gerätegruppen in einer IoT Central-Anwendung erstellen, um aggregierte Daten zu überwachen, mit Aufträgen zu verwenden und den Zugriff zu verwalten. Gerätegruppen werden anhand eines Filters definiert, der die Geräte auswählt, die der Gruppe hinzugefügt werden sollen. Gerätegruppen können im IoT Central-Portal oder mithilfe der API erstellt werden.

Hinzufügen einer Gerätegruppe

Verwenden Sie die folgende Anforderung, um eine neue Gerätegruppe zu erstellen.

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

Wenn Sie eine Gerätegruppe erstellen, definieren Sie einen filter, der die Geräte auswählt, die der Gruppe hinzugefügt werden sollen. Eine filter identifiziert eine Gerätevorlage und alle Eigenschaften, die übereinstimmen sollen. Im folgenden Beispiel wird eine Gerätegruppe erstellt, die alle der Vorlage „dtmi:modelDefinition:dtdlv2“ zugeordneten Geräte enthält, deren provisioned-Eigenschaft auf true festgelegt ist.

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

Der Anforderungstext enthält einige erforderliche Felder:

@displayName: Anzeigename der Gerätegruppe.
@filter: Abfrage, die definiert, welche Geräte in dieser Gruppe enthalten sein sollen.
@etag: Dies ist das ETag, das verwendet wird, um Konflikte bei Geräteupdates zu verhindern.
description: Kurze Zusammenfassung der Gerätegruppe.

Das Feld „Organisationen“ wird nur verwendet, wenn für eine Anwendung eine Organisationshierarchie definiert ist. Weitere Informationen zu Organisationen finden Sie unter Verwalten von IoT Central-Organisationen.

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",
  "organizations": [
    "seattle"
  ]
}

Abrufen einer Gerätegruppe

Verwenden Sie die folgende Anforderung, um Details einer Gerätegruppe aus Ihrer Anwendung abzurufen:

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

deviceGroupId – Eindeutige ID für die Gerätegruppe.

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

{
  "id": "475cad48-b7ff-4a09-b51e-1a9021385453",
  "displayName": "DeviceGroupEntry1",
  "description": "This is a default device group containing all the devices for this particular Device Template.",
  "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
  "organizations": [
    "seattle"
  ]
}

Aktualisieren einer Gerätegruppe

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

Der Beispielanforderungstext sieht wie im folgenden Beispiel aus, in dem displayName der Gerätegruppe aktualisiert wird:

{
  "displayName": "New group name"
}

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

{
  "id": "group1",
  "displayName": "New group name",
  "description": "Custom device group.",
  "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
  "organizations": [
    "seattle"
  ]
}

Löschen einer Gerätegruppe

Verwenden Sie die folgende Anforderung, um eine Gerätegruppe zu löschen:

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

Auflisten von Gerätegruppen

Verwenden Sie die folgende Anforderung, um eine Liste von Gerätegruppen aus Ihrer Anwendung abzurufen:

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

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

{
  "value": [
    {
      "id": "475cad48-b7ff-4a09-b51e-1a9021385453",
      "displayName": "DeviceGroupEntry1",
      "description": "This is a default device group containing all the devices for this particular Device Template.",
      "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
      "organizations": [
        "seattle"
      ]
    },
    {
      "id": "c2d5ae1d-2cb7-4f58-bf44-5e816aba0a0e",
      "displayName": "DeviceGroupEntry2",
      "description": "This is a default device group containing all the devices for this particular Device Template.",
      "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:model1\"",
      "organizations": [
        "redmond"
      ]
    },
    {
      "id": "241ad72b-32aa-4216-aabe-91b240582c8d",
      "displayName": "DeviceGroupEntry3",
      "description": "This is a default device group containing all the devices for this particular Device Template.",
      "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:model2\" AND $simulated = true"
    },
    {
      "id": "group4",
      "displayName": "DeviceGroupEntry4",
      "description": "This is a default device group containing all the devices for this particular Device Template.",
      "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:model3\""
    }
  ]
}

Registrierungsgruppen

Registrierungsgruppen werden zum Verwalten der Geräteauthentifizierungsoptionen in Ihrer IoT Central-Anwendung verwendet. Weitere Informationen finden Sie unter Geräteauthentifizierungskonzepte in IoT Central.

Informationen zum Erstellen und Verwalten von Registrierungsgruppen über die Benutzeroberfläche finden Sie unter Verbinden von Geräten mit X.509-Zertifikaten mit einer IoT Central-Anwendung.

Wenn Sie eine Registrierungsgruppe für Geräte erstellen, die X.509-Zertifikate verwenden, müssen Sie zuerst das Stamm- oder Zwischenzertifikat in Ihre IoT Central-Anwendung hochladen.

Generieren von Stamm- und Gerätezertifikaten

In diesem Abschnitt generieren Sie die X.509-Zertifikate, die Sie zum Verbinden eines Geräts mit IoT Central benötigen.

Warnung

Diese Methode zum Erstellen von X.509-Zertifikaten dient nur zu Testzwecken. Für eine Produktionsumgebung sollten Sie Ihren offiziellen, sicheren Mechanismus für Zertifikatgenerierung verwenden.

Navigieren Sie zum Zertifikatgeneratorskript im Microsoft Azure IoT SDK für Node.js, das Sie heruntergeladen haben. Installieren Sie die erforderlichen Pakete:
```
cd azure-iot-sdk-node/provisioning/tools
npm install
```
Erstellen Sie ein Stammzertifikat, und leiten Sie dann ein Gerätezertifikat durch Ausführen des Skripts ab:
```
node create_test_cert.js root mytestrootcert
node create_test_cert.js device sample-device-01 mytestrootcert
```
Tipp

Eine Geräte-ID kann Buchstaben, Ziffern und das Zeichen - enthalten.

Diese Befehle erzeugen das folgende Stammzertifikat und das Gerätezertifikat:

filename	contents
mytestrootcert_cert.pem	Der öffentliche Teil des X.509-Stammzertifikats
mytestrootcert_key.pem	Der private Schlüssel für das X.509-Stammzertifikat
mytestrootcert_fullchain.pem	Die gesamte Keychain (Schlüsselbund) für das X.509-Stammzertifikat
mytestrootcert.pfx	Die PFX-Datei für das X.509-Stammzertifikat
sampleDevice01_cert.pem	Der öffentliche Teil des X.509-Gerätezertifikats
sampleDevice01_key.pem	Der private Schlüssel für das X.509-Gerätezertifikat
sampleDevice01_fullchain.pem	Die gesamte Keychain (Schlüsselbund) für das X.509-Gerätezertifikat
sampleDevice01.pfx	Die PFX-Datei für das X.509-Gerätezertifikat

Notieren Sie sich den Speicherort dieser Dateien. Sie benötigen ihn später.

Generieren der Base64-codierten Version des Stammzertifikats

Erstellen Sie in dem Ordner auf Ihrem lokalen Computer, der die von Ihnen generierten Zertifikate enthält, eine Datei namens „convert.js“, und fügen Sie den folgenden JavaScript-Inhalt hinzu:

const fs = require('fs')
const fileContents = fs.readFileSync(process.argv[2]).toString('base64');
console.log(fileContents);

Führen Sie den folgenden Befehl zum Generieren einer Base64-codierten Version des Zertifikats aus:

node convert.js mytestrootcert_cert.pem

Notieren Sie sich die Base64-codierte Version des Zertifikats. Sie benötigen ihn später.

Hinzufügen einer X.509-Registrierungsgruppe

Verwenden Sie die folgende Anforderung zum Erstellen einer neuen Registrierungsgruppe mit der ID myx509eg:

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

Das folgende Beispiel zeigt einen Anforderungstext, der eine neue X.509-Registrierungsgruppe hinzufügt:

{
  "displayName": "My group",
  "enabled": true,
  "type": "iot",
  "attestation": {
    "type": "x509"
  }
}

Der Anforderungstext enthält einige erforderliche Felder:

@displayName: Anzeigename der Registrierungsgruppe.
@enabled: Gibt an, ob die Geräte, die die Gruppe verwenden, eine Verbindung mit IoT Central herstellen dürfen.
@type: Typ der Geräte, die eine Verbindung über die Gruppe herstellen – entweder iot oder iotEdge.
attestation: Der Nachweismechanismus für die Registrierungsgruppe – entweder symmetricKeyoder x509.

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

{
    "id": "myEnrollmentGroupId",
    "displayName": "My group",
    "enabled": true,
    "type": "iot",
    "attestation": {
        "type": "x509",
        "x509": {
            "signingCertificates": {}
        }
    },
    "etag": "IjdiMDcxZWQ5LTAwMDAtMDcwMC0wMDAwLTYzMWI3MWQ4MDAwMCI="
}

Hinzufügen eines X.509-Zertifikats zu einer Registrierungsgruppe

Verwenden Sie die folgende Anforderung, um das primäre X.509-Zertifikat der Registrierungsgruppe „myx509eg“ festzulegen:

PUT https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/myx509eg/certificates/primary?api-version=2022-07-31

Verwenden Sie diese Anforderung, um der Registrierungsgruppe ein primäres oder sekundäres X.509-Zertifikat hinzuzufügen.

Das folgende Beispiel zeigt einen Anforderungstext, der einer Registrierungsgruppe ein X.509-Zertifikat hinzufügt:

{
  "verified": false,
  "certificate": "<base64-certificate>"
}

certificate – Die Base64-Version des Zertifikats, die Sie sich zuvor notiert haben.
verified (überprüft) – true wenn Sie bestätigen, dass das Zertifikat gültig ist; false wenn Sie die Gültigkeit des Zertifikats nachweisen müssen.

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

{
  "verified": false,
  "info": {
    "sha1Thumbprint": "644543467786B60C14DFE6B7C968A1990CF63EAC"
  },
  "etag": "IjE3MDAwODNhLTAwMDAtMDcwMC0wMDAwLTYyNjFmNzk0MDAwMCI="
}

Generieren von Überprüfungscode für ein X.509-Zertifikat

Verwenden Sie die folgende Anforderung zum Generieren eines Überprüfungscodes für das primäre oder sekundäre X.509-Zertifikat einer Registrierungsgruppe.

Wenn Sie in der vorherigen Anforderung verified auf false festgelegt haben, verwenden Sie die folgende Anforderung zum Generieren eines Überprüfungscodes für das primäre X.509-Zertifikat in der Registrierungsgruppe myx509eg:

POST https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/myx509eg/certificates/primary/generateVerificationCode?api-version=2022-07-31

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

{
  "verificationCode": "<certificate-verification-code>"
}

Notieren Sie sich den Überprüfungscode. Sie benötigen ihn im nächsten Schritt.

Generieren des Verifizierungszertifikats

Verwenden Sie den folgenden Befehl zum Generieren eines Überprüfungszertifikats aus dem Überprüfungscode im vorherigen Schritt:

node create_test_cert.js verification --ca mytestrootcert_cert.pem --key mytestrootcert_key.pem --nonce  {verification-code}

Führen Sie den folgenden Befehl zum Generieren einer Base64-codierten Version des Zertifikats aus:

node convert.js verification_cert.pem

Notieren Sie sich die Base64-codierte Version des Zertifikats. Sie benötigen ihn später.

Überprüfen des X.509-Zertifikats einer Registrierungsgruppe

Verwenden Sie die folgende Anforderung zum Überprüfen des primären X.509-Zertifikats der Registrierungsgruppe myx509eg, indem Sie das Zertifikat mit dem signierten Überprüfungscode angeben:

POST PUT https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/myx509eg/certificates/primary/verify?api-version=2022-07-31

Das folgende Beispiel zeigt einen Anforderungstext, der ein X.509-Zertifikat überprüft:

{
  "certificate": "base64-verification-certificate"
}

Abrufen eines X.509-Zertifikats einer Registrierungsgruppe

Verwenden Sie die folgende Anforderung zum Abrufen von Details des X.509-Zertifikats einer Registrierungsgruppe aus Ihrer Anwendung:

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

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

{
  "verified": true,
  "info": {
    "sha1Thumbprint": "644543467786B60C14DFE6B7C968A1990CF63EAC"
  },
  "etag": "IjE3MDAwODNhLTAwMDAtMDcwMC0wMDAwLTYyNjFmNzk0MDAwMCI="
}

Löschen eines X.509-Zertifikats aus einer Registrierungsgruppe

Verwenden Sie die folgende Anforderung zum Löschen des primären X.509-Zertifikat aus einer Registrierungsgruppe mit der ID myx509eg:

DELETE https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/myx509eg/certificates/primary?api-version=2022-07-31

Hinzufügen einer Registrierungsgruppe mit symmetrischem Schlüssel

Verwenden Sie die folgende Anforderung zum Erstellen einer neuen Registrierungsgruppe mit der ID mysymmetric:

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

Das folgende Beispiel zeigt einen Anforderungstext, der eine neue Registrierungsgruppe hinzufügt:

{
  "displayName": "My group",
  "enabled": true,
  "type": "iot",
  "attestation": {
    "type": "symmetricKey"
  }
}

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

{
  "id": "mysymmetric",
  "displayName": "My group",
  "enabled": true,
  "type": "iot",
  "attestation": {
    "type": "symmetricKey",
    "symmetricKey": {
      "primaryKey": "<primary-symmetric-key>",
      "secondaryKey": "<secondary-symmetric-key>"
    }
  },
  "etag": "IjA4MDUwMTJiLTAwMDAtMDcwMC0wMDAwLTYyODJhOWVjMDAwMCI="
}

IoT Central generiert die primären und sekundären symmetrischen Schlüssel, wenn Sie diesen API-Aufruf durchführen.

Abrufen einer Registrierungsgruppe

Verwenden Sie die folgende Anforderung zum Abrufen von Details einer Registrierungsgruppe mit der ID mysymmetric:

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

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

{
  "id": "mysymmetric",
  "displayName": "My group",
  "enabled": true,
  "type": "iot",
  "attestation": {
    "type": "symmetricKey",
    "symmetricKey": {
      "primaryKey": "<primary-symmetric-key>",
      "secondaryKey": "<secondary-symmetric-key>"
    }
  },
  "etag": "IjA4MDUwMTJiLTAwMDAtMDcwMC0wMDAwLTYyODJhOWVjMDAwMCI="
}

Aktualisieren einer Registrierungsgruppe

Verwenden Sie die folgende Anforderung zum Aktualisieren einer Registrierungsgruppe.

PATCH https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/myx509eg?api-version=2022-07-31

Das folgende Beispiel zeigt einen Anforderungstext, in dem der Anzeigename einer Registrierungsgruppe aktualisiert wird:

{
  "displayName": "My new group name",
}

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

{
  "id": "myEnrollmentGroupId",
  "displayName": "My new group name",
  "enabled": true,
  "type": "iot",
  "attestation": {
    "type": "symmetricKey",
    "symmetricKey": {
      "primaryKey": "<primary-symmetric-key>",
      "secondaryKey": "<secondary-symmetric-key>"
    }
  },
  "etag": "IjA4MDUwMTJiLTAwMDAtMDcwMC0wMDAwLTYyODJhOWVjMDAwMCI="
}

Löschen einer Registrierungsgruppe

Verwenden Sie die folgende Anforderung zum Löschen einer Registrierungsgruppe mit der ID myx509eg:

DELETE https://{your app subdomain}.azureiotcentral.com/api/enrollmentGroups/myx509eg?api-version=2022-07-31

Auflisten von Registrierungsgruppen

Verwenden Sie die folgende Anforderung zum Abrufen einer Liste von Registrierungsgruppen aus Ihrer Anwendung:

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

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

{
    "value": [
        {
            "id": "myEnrollmentGroupId",
            "displayName": "My group",
            "enabled": true,
            "type": "iot",
            "attestation": {
                "type": "symmetricKey",
                "symmetricKey": {
                    "primaryKey": "primaryKey",
                    "secondaryKey": "secondarykey"
                }
            },
            "etag": "IjZkMDc1YTgzLTAwMDAtMDcwMC0wMDAwLTYzMTc5ZjA4MDAwMCI="
        },
        {
            "id": "enrollmentGroupId2",
            "displayName": "My group",
            "enabled": true,
            "type": "iot",
            "attestation": {
                "type": "x509",
                "x509": {
                    "signingCertificates": {}
                }
            },
            "etag": "IjZkMDdjNjkyLTAwMDAtMDcwMC0wMDAwLTYzMTdhMDY1MDAwMCI="
        }
    ]
}

Verwenden der IoT Central-REST-API zum Verwalten von Geräten

REST-API für Device Messaging

Hinzufügen eines Geräts

Abrufen eines Geräts

Abrufen der Geräteanmeldeinformationen

Aktualisieren eines Geräts

Löschen eines Mediums

Listen Sie die Geräte auf.

Zuweisen eines Bereitstellungsmanifests

Verwenden von ODATA-Filtern

maxpagesize

filter

orderby

Gerätegruppen

Hinzufügen einer Gerätegruppe

Abrufen einer Gerätegruppe

Aktualisieren einer Gerätegruppe

Löschen einer Gerätegruppe

Auflisten von Gerätegruppen

Registrierungsgruppen

Erstellen einer Registrierungsgruppe

Generieren von Stamm- und Gerätezertifikaten

Generieren der Base64-codierten Version des Stammzertifikats

Hinzufügen einer X.509-Registrierungsgruppe

Hinzufügen eines X.509-Zertifikats zu einer Registrierungsgruppe

Generieren von Überprüfungscode für ein X.509-Zertifikat

Generieren des Verifizierungszertifikats

Überprüfen des X.509-Zertifikats einer Registrierungsgruppe

Abrufen eines X.509-Zertifikats einer Registrierungsgruppe

Löschen eines X.509-Zertifikats aus einer Registrierungsgruppe

Abrufen einer Registrierungsgruppe

Aktualisieren einer Registrierungsgruppe

Löschen einer Registrierungsgruppe

Auflisten von Registrierungsgruppen

Zusätzliche Ressourcen