Freigeben über

Verwenden von X.509-Zertifikaten über HTTPS ohne SDK

  • Artikel

In diesem Anleitungsartikel wird ein Gerät unter Verwendung von X.509-Zertifikaten über HTTPS ohne Verwendung eines Azure IoT DPS-Geräte-SDK bereitgestellt. Die meisten Sprachen bieten Bibliotheken zum Senden von HTTP-Anforderungen. In diesem Artikel wird allerdings das Befehlszeilentool cURL zum Senden und Empfangen über HTTPS verwendet, anstatt sich auf eine bestimmte Sprache zu konzentrieren.

Die Schritte in diesem Artikel können sowohl auf einem Linux-Computer als auch auf einem Windows-Computer ausgeführt werden. Bei Verwendung des Windows-Subsystems für Linux (WSL) oder auf einem Linux-Computer können Sie alle Befehle auf Ihrem lokalen System in eine Bash-Eingabeaufforderung eingeben. Geben Sie unter Windows alle Befehle auf Ihrem lokalen System in eine GitBash-Eingabeaufforderung ein.

In diesem Artikel gibt es mehrere Pfade, abhängig von der Art des verwendeten Registrierungseintrags und von den verwendeten X.509-Zertifikaten. Sehen Sie nach der Installation der erforderlichen Komponenten unbedingt zunächst die Übersicht an.

Voraussetzungen

  • Wenn Sie kein Azure-Abonnement besitzen, können Sie ein kostenloses Konto erstellen, bevor Sie beginnen.

  • Führen Sie die Schritte im Artikel Einrichten des IoT Hub Device Provisioning Service im Azure-Portal aus.

  • Stellen Sie sicher, dass auf Ihrem Computer mindestens Python 3.7 installiert ist. Durch Ausführen von python --version oder python3 --version können Sie überprüfen, über welche Python-Version Sie verfügen.

  • Installieren Sie unter Windows die neueste Version von Git. Stellen Sie sicher, dass Git den Umgebungsvariablen hinzugefügt wurde, auf die das Befehlsfenster Zugriff hat. Unter den Git-Clienttools von Software Freedom Conservancy finden Sie die neueste Version der zu installierenden git-Tools. Hierzu zählt auch die Befehlszeilen-App Git Bash, über die Sie mit Ihrem lokalen Git-Repository interagieren können. Unter Windows werden alle Befehle auf Ihrem lokalen System in eine GitBash-Eingabeaufforderung eingegeben.

  • Azure-Befehlszeilenschnittstelle. In diesem Artikel gibt es zwei Möglichkeiten zum Ausführen von Azure CLI-Befehlen:

    • Verwenden Sie Azure Cloud Shell. Dabei handelt es sich um eine interaktive Shell, mit der CLI-Befehle im Browser ausgeführt werden. Diese Option wird empfohlen, da Sie nichts installieren müssen. Wenn Sie Cloud Shell zum ersten Mal verwenden, melden Sie sich beim Azure-Portal an. Führen Sie in der Cloud Shell-Schnellstartanleitung die Schritte zum Starten von Cloud Shell und Auswählen der Bash-Umgebung aus.
    • Führen Sie optional die Azure CLI auf dem lokalen Computer aus. Wenn die Azure CLI bereits installiert ist, führen Sie az upgrade aus, um die CLI und die Erweiterungen auf die aktuelle Version zu aktualisieren. Informationen zur Installation der Azure CLI finden Sie unter Installieren der Azure CLI.

  • Öffnen Sie bei Verwendung einer Linux- oder WSL-Umgebung eine Bash-Eingabeaufforderung, um Befehle lokal auszuführen. In einer Windows-Umgebung können Sie eine GitBash-Eingabeaufforderung öffnen.

Übersicht

In diesem Artikel werden drei Szenarien mit jeweils unterschiedlichen ersten Schritten behandelt. Zweck:

Nachdem Sie die Schritte für das ausgewählte Szenario ausgeführt haben, können Sie mit dem Registrieren Ihres Geräts und dem Senden einer Telemetrienachricht fortfahren.

Erstellen eines Gerätezertifikats

In diesem Artikel wird ein X.509-Zertifikat für die Authentifizierung bei DPS unter Verwendung einer individuellen Registrierung oder einer Registrierungsgruppe verwendet.

Bei Verwendung einer individuellen Registrierung können Sie ein selbstsigniertes X.509-Zertifikat oder eine Zertifikatkette verwenden, die aus dem Gerätezertifikat und mindestens einem Signaturzertifikat besteht. Bei Verwendung einer Registrierungsgruppe muss eine Zertifikatkette verwendet werden.

Wichtig

Für die X.509-Registrierungsauthentifizierung wird der allgemeine Name des Antragstellers (Subject Common Name, CN) des Gerätezertifikats als Registrierungs-ID für das Gerät verwendet. Die Registrierungs-ID ist eine von der Groß- und Kleinschreibung unabhängige Zeichenfolge aus alphanumerischen Zeichen und Sonderzeichen: '-', '.', '_', ':'. Das letzte Zeichen muss alphanumerisch oder ein Bindestrich ('-') sein. DPS unterstützt Registrierungs-IDs mit einer Länge von bis zu 128 Zeichen. Die Länge des allgemeinen Namens des Antragstellers in einem X.509-Zertifikat ist jedoch auf 64 Zeichen begrenzt. Wenn Sie in den folgenden Schritten den allgemeinen Namen des Antragstellers für Ihr Gerätezertifikat ändern, achten Sie darauf, dass er diesem Format entspricht.

Verwenden eines selbstsignierten Zertifikats

Navigieren Sie zum Erstellen eines selbstsignierten Zertifikats für die Verwendung mit einer individuellen Registrierung zu einem Verzeichnis, in dem Sie Ihr Zertifikat erstellen möchten, und gehen Sie wie folgt vor:

  1. Führen Sie den folgenden Befehl aus:

    winpty openssl req -outform PEM -x509 -sha256 -newkey rsa:4096 -keyout device-key.pem -out device-cert.pem -days 30 -extensions usr_cert -addext extendedKeyUsage=clientAuth -subj "//CN=my-x509-device"

    Wichtig

    Der zusätzliche Schrägstrich für den Antragstellernamen (//CN=my-x509-device) ist nur erforderlich, um die Zeichenfolge für Git auf Windows-Plattformen mit einem Escapezeichen zu versehen.

  2. Wenn die Aufforderung PEM-Passphrase eingeben: angezeigt wird, verwenden Sie die Passphrase 1234.

  3. Wenn Sie zum Bestätigen der PEM-Passphrase aufgefordert werden, geben Sie die Passphrase 1234 erneut ein.

    Eine Datei für das öffentliche Schlüsselzertifikat (device-cert.pem) und eine Datei für den privaten Schlüssel (device-key.pem) sollten jetzt in dem Verzeichnis generiert werden, in dem Sie den Befehl openssl ausgeführt haben.

    Für die Zertifikatdatei ist der CN des Antragstellers auf my-x509-device festgelegt.

    Die Datei für den privaten Schlüssel ist durch eine Passphrase geschützt: 1234.

  4. Die Zertifikatdatei ist Base64-codiert. Wenn Sie den allgemeinen Namen (Common Name, CN) des Antragstellers und andere Eigenschaften der Zertifikatdatei anzeigen möchten, geben Sie den folgenden Befehl ein:

    winpty openssl x509 -in device-cert.pem -text -noout

    Certificate:
Data:
    Version: 3 (0x2)
    Serial Number:
        77:3e:1d:e4:7e:c8:40:14:08:c6:09:75:50:9c:1a:35:6e:19:52:e2
    Signature Algorithm: sha256WithRSAEncryption
    Issuer: CN = my-x509-device
    Validity
        Not Before: May  5 21:41:42 2022 GMT
        Not After : Jun  4 21:41:42 2022 GMT
    Subject: CN = my-x509-device
    Subject Public Key Info:
        Public Key Algorithm: rsaEncryption
            RSA Public-Key: (4096 bit)
            Modulus:
                00:d2:94:37:d6:1b:f7:43:b4:21:c6:08:1a:d6:d7:
                e6:40:44:4e:4d:24:41:6c:3e:8c:b2:2c:b0:23:29:
                ...
                23:6e:58:76:45:18:03:dc:2e:9d:3f:ac:a3:5c:1f:
                9f:66:b0:05:d5:1c:fe:69:de:a9:09:13:28:c6:85:
                0e:cd:53
            Exponent: 65537 (0x10001)
    X509v3 extensions:
        X509v3 Basic Constraints:
            CA:FALSE
        Netscape Comment:
            OpenSSL Generated Certificate
        X509v3 Subject Key Identifier:
            63:C0:B5:93:BF:29:F8:57:F8:F9:26:44:70:6F:9B:A4:C7:E3:75:18
        X509v3 Authority Key Identifier:
            keyid:63:C0:B5:93:BF:29:F8:57:F8:F9:26:44:70:6F:9B:A4:C7:E3:75:18

        X509v3 Extended Key Usage:
            TLS Web Client Authentication
Signature Algorithm: sha256WithRSAEncryption
     82:8a:98:f8:47:00:85:be:21:15:64:b9:22:b0:13:cc:9e:9a:
     ed:f5:93:b9:4b:57:0f:79:85:9d:89:47:69:95:65:5e:b3:b1:
     ...
     cc:b2:20:9a:b7:f2:5e:6b:81:a1:04:93:e9:2b:92:62:e0:1c:
     ac:d2:49:b9:36:d2:b0:21

Verwenden einer Zertifikatkette

Bei Verwendung einer Registrierungsgruppe muss für die Authentifizierung eine Zertifikatkette verwendet werden. Bei einer individuellen Registrierung können Sie eine Zertifikatkette oder ein selbstsigniertes Zertifikat verwenden.

Eine Anleitung zum Erstellen einer Zertifikatkette finden Sie unter Erstellen einer X.509-Zertifikatkette. Da für diesen Artikel nur ein einzelnes Gerät benötigt wird, können Sie den Vorgang nach dem Erstellen des privaten Schlüssels und der Zertifikatkette für das erste Gerät beenden.

Am Ende des Vorgangs sollten Sie über folgende Dateien verfügen:

Zertifikat Datei BESCHREIBUNG
Zertifikat der Stammzertifizierungsstelle. certs/azure-iot-test-only.root.ca.cert.pem Wird in DPS hochgeladen und überprüft.
Zertifikat der Zwischenzertifizierungsstelle certs/azure-iot-test-only.intermediate.cert.pem Wird verwendet, um eine Registrierungsgruppe in DPS zu erstellen.
Privater Schlüssel device-01 private/device-01.key.pem Wird vom Gerät verwendet, um den Besitz des Gerätezertifikats während der Authentifizierung mit DPS zu überprüfen.
Zertifikat „device-01“ certs/device-01.cert.pem Wird verwendet, um einen individuellen Registrierungseintrag mit DPS zu erstellen.
Vollständiges Kettenzertifikat device-01 certs/device-01-full-chain.cert.pem Wird vom Gerät angegeben, um sich mit DPS zu authentifizieren und zu registrieren.

Verwenden einer individuellen Registrierung

Verwenden Sie den Befehl az iot dps enrollment create, um eine individuelle Registrierung für diesen Artikel zu erstellen.

Der folgende Befehl erstellt einen individuellen Registrierungseintrag mit der Standardzuweisungsrichtlinie für Ihre DPS-Instanz unter Verwendung des von Ihnen angegebenen Gerätezertifikats:

az iot dps enrollment create -g {resource_group_name} --dps-name {dps_name} --enrollment-id {enrollment_id} --attestation-type x509 --certificate-path {path to your certificate}

  • Ersetzen Sie den Namen Ihrer Ressourcengruppe und Ihrer DPS-Instanz.

  • Die Registrierungs-ID ist die Registrierungs-ID für Ihr Gerät und muss bei X.509-Registrierungen dem allgemeinen Namen (Common Name, CN) des Antragstellers aus dem Gerätezertifikat entsprechen.

  • Der Zertifikatpfad ist der Pfad zu Ihrem Gerätezertifikat.

Hinweis

Wenn Sie Azure CLI-Befehle über Cloud Shell ausführen, können Sie vor dem Ausführen des Befehls die Uploadschaltfläche verwenden, um Ihre Zertifikatdatei in Ihr Cloudlaufwerk hochzuladen.

Screenshot: Schaltfläche für Dateiupload in Azure Cloud Shell

Verwenden einer Registrierungsgruppe

Verwenden Sie den Befehl az iot dps enrollment-group create, um eine Registrierungsgruppe für diesen Artikel zu erstellen.

Der folgende Befehl erstellt einen Registrierungsgruppeneintrag mit der Standardzuweisungsrichtlinie für Ihre DPS-Instanz unter Verwendung Zertifikats der Zwischenzertifizierungsstelle:

az iot dps enrollment-group create -g {resource_group_name} --dps-name {dps_name} --enrollment-id {enrollment_id} --certificate-path {path_to_your_certificate}

  • Ersetzen Sie den Namen Ihrer Ressourcengruppe und Ihrer DPS-Instanz.

  • Die Registrierungs-ID ist eine von der Groß- und Kleinschreibung unabhängige Zeichenfolge, die alphanumerische Zeichen und folgende Sonderzeichen enthalten kann: '-', '.', '_', ':'. Das letzte Zeichen muss alphanumerisch oder ein Bindestrich ('-') sein. Dabei kann es sich um einen beliebigen Namen handeln, den Sie für die Registrierungsgruppe verwenden möchten.

  • Der Zertifikatpfad ist der Pfad zu Ihrem Zwischenzertifikat. Wenn Sie die Anweisungen unter Verwenden einer Zertifikatkette befolgt haben, lautet der Dateiname certs/azure-iot-test-only.intermediate.cert.pem.

Hinweis

Wenn Sie Azure CLI-Befehle über Cloud Shell ausführen, können Sie vor dem Ausführen des Befehls die Uploadschaltfläche verwenden, um Ihre Zertifikatdatei in Ihr Cloudlaufwerk hochzuladen.

Screenshot: Schaltfläche für Dateiupload in Azure Cloud Shell

Hinweis

Falls gewünscht, können Sie eine Registrierungsgruppe basierend auf einem Signaturzertifikat erstellen, das zuvor hochgeladen und mit DPS überprüft wurde (siehe nächster Abschnitt). Geben Sie dazu den Zertifikatnamen mit --ca-name an, und lassen Sie im Befehl az iot dps enrollment-group create den Parameter --certificate-path weg.

Hochladen und Überprüfen eines Signaturzertifikats

Wenn Sie eine Zertifikatkette für eine individuelle Registrierung oder für eine Registrierungsgruppe verwenden, müssen Sie mindestens ein Zertifikat in der Signaturkette des Gerätezertifikats in DPS hochladen und überprüfen.

  • Bei einer individuellen Registrierung kann das ein beliebiges Signaturzertifikat in der Zertifikatkette des Geräts sein.

  • Bei einer Registrierungsgruppe kann dies das Zertifikat sein, das für die Registrierungsgruppe festgelegt ist, oder ein beliebiges Zertifikat in der Registrierungskette bis hin zum Zertifikat der Stammzertifizierungsstelle (einschließlich).

Verwenden Sie den Befehl az iot dps certificate create, um Ihr Zertifikat hochzuladen und zu überprüfen:

az iot dps certificate create -g {resource_group_name} --dps-name {dps_name} --certificate-name {friendly_name_for_your_certificate} --path {path_to_your_certificate} --verified true

  • Ersetzen Sie den Namen Ihrer Ressourcengruppe und Ihrer DPS-Instanz.

  • Der Zertifikatpfad ist der Pfad zu Ihrem Signaturzertifikat. Für diesen Artikel wird empfohlen, das Zertifikat der Stammzertifizierungsstelle hochzuladen. Wenn Sie die Anweisungen unter Verwenden einer Zertifikatkette befolgt haben, lautet der Dateiname certs/azure-iot-test-only.root.ca.cert.pem.

  • Der Zertifikatname darf nur alphanumerische Zeichen oder folgende Sonderzeichen enthalten: -._. Leerzeichen sind nicht zulässig. Beispiel: azure-iot-test-only-root.

Hinweis

Wenn Sie Azure CLI-Befehle über Cloud Shell ausführen, können Sie vor dem Ausführen des Befehls die Uploadschaltfläche verwenden, um Ihre Zertifikatdatei in Ihr Cloudlaufwerk hochzuladen.

Screenshot: Schaltfläche für Dateiupload in Azure Cloud Shell

Hinweis

Im Zuge der Schritte in diesem Abschnitt wurde das Zertifikat beim Hochladen automatisch überprüft. Sie können das Zertifikat aber auch manuell überprüfen. Weitere Informationen finden Sie unter Manuelle Überprüfung der Zwischen- oder Stammzertifizierungsstelle.

Registrieren Ihres Geräts

Rufen Sie die REST-API für die Geräteregistrierung auf, um Ihr Gerät über DPS bereitzustellen.

Verwenden Sie den folgenden cURL-Befehl:

curl -L -i -X PUT --cert [path_to_your_device_cert] --key [path_to_your_device_private_key] -H 'Content-Type: application/json' -H 'Content-Encoding:  utf-8' -d '{"registrationId": "[registration_id]"}' https://global.azure-devices-provisioning.net/[dps_id_scope]/registrations/[registration_id]/register?api-version=2019-03-31

Hierbei gilt:

  • -L weist cURL an, HTTP-Umleitungen zu folgen.

  • –i weist cURL an, Protokollheader in die Ausgabe einzuschließen. Diese Header sind nicht zwingend erforderlich, können aber hilfreich sein.

  • -X PUT teilt cURL mit, dass es sich um einen HTTP PUT-Befehl handelt. Erforderlich für diesen API-Aufruf.

  • --cert [path_to_your_device_cert] teilt cURL mit, wo sich das X.509-Zertifikat Ihres Geräts befindet. Wenn der private Schlüssel Ihres Geräts durch eine Passphrase geschützt ist, können Sie nach dem Zertifikatpfad die Passphrase mit einem vorangestellten Doppelpunkt hinzufügen (Beispiel: --cert my-device.pem:1234).

    • Bei Verwendung eines selbstsignierten Zertifikats enthält Ihre Gerätezertifikatdatei nur ein einzelnes X.509-Zertifikat. Wenn Sie die Anweisungen unter Verwenden eines selbstsignierten Zertifikats befolgt haben, lautet der Dateiname device-cert.pem, und die Passphrase des privaten Schlüssels lautet 1234. Verwenden Sie also --cert device-cert.pem:1234.

    • Wenn Sie eine Zertifikatkette verwenden (etwa bei der Authentifizierung über eine Registrierungsgruppe), muss Ihre Gerätezertifikatdatei eine gültige Zertifikatkette enthalten. Die Zertifikatkette muss das Gerätezertifikat und alle Signaturzertifikate bis zu einem verifizierten Zertifikat (einschließlich) enthalten. Wenn Sie die Anweisungen unter Verwenden einer Zertifikatkette befolgt haben, um die Zertifikatkette zu erstellen, lautet der Dateipfad certs/device-01-full-chain.cert.pem. Verwenden Sie also --cert certs/device-01-full-chain.cert.pem.

  • --key [path_to_your_device_private_key] teilt cURL mit, wo sich der private Schlüssel Ihres Geräts befindet.

    • Wenn Sie die Anweisungen unter Verwenden eines selbstsignierten Zertifikats befolgt haben, lautet der Dateiname device-key.pem. Verwenden Sie also --key device-cert.pem:1234.

    • Wenn Sie die Anweisungen unter Verwenden einer Zertifikatkette befolgt haben, lautet der Schlüsselpfad certs/device-01-full-chain.cert.pem. Verwenden Sie also --cert certs/device-01-full-chain.cert.pem.

  • -H 'Content-Type: application/json' teilt DPS mit, dass JSON-Inhalte veröffentlicht werden, und muss „application/json“ sein.

  • -H 'Content-Encoding: utf-8' teilt DPS die für den Nachrichtentext verwendete Codierung mit. Verwenden Sie den entsprechenden Code für Ihr Betriebssystem bzw. Ihren Client. Das ist üblicherweise utf-8.

  • -d '{"registrationId": "[registration_id]"}': Bei dem Parameter –d handelt es sich um die Daten oder um den Text der veröffentlichten Nachricht. Hierbei muss es sich um JSON-Code im folgenden Format handeln: '{"registrationId":"[registration_id"}'. Beachten Sie, dass der Code für cURL in einfache Anführungszeichen eingeschlossen wird. Andernfalls müssen die doppelten Anführungszeichen im JSON-Code mit Escapezeichen versehen werden. Bei der X.509-Registrierung ist die Registrierungs-ID der allgemeine Name (Common Name, CN) des Antragstellers aus Ihrem Gerätezertifikat.

  • Der letzte Parameter ist die URL für die Veröffentlichung. Bei einer regulären (nicht lokalen) DPS-Instanz wird der globale DPS-Endpunkt global.azure-devices-provisioning.net verwendet: https://global.azure-devices-provisioning.net/[dps_id_scope]/registrations/[registration_id]/register?api-version=2019-03-31. Beachten Sie, dass [dps_scope_id] und [registration_id] durch die entsprechenden Werte ersetzt werden müssen.

Zum Beispiel:

  • Wenn Sie die Anweisungen unter Verwenden eines selbstsignierten Zertifikats befolgt haben:

    curl -L -i -X PUT --cert device-cert.pem:1234 --key device-key.pem -H 'Content-Type: application/json' -H 'Content-Encoding:  utf-8' -d '{"registrationId": "my-x509-device"}' https://global.azure-devices-provisioning.net/0ne00111111/registrations/my-x509-device/register?api-version=2021-06-01

  • Wenn Sie die Anweisungen unter Verwenden einer Zertifikatkette befolgt haben:

    curl -L -i -X PUT --cert certs/device-01-full-chain.cert.pem --key private/device-01.key.pem -H 'Content-Type: application/json' -H 'Content-Encoding:  utf-8' -d '{"registrationId": "device-01"}' https://global.azure-devices-provisioning.net/0ne00111111/registrations/device-01/register?api-version=2021-06-01

Bei einem erfolgreichen Anruf wird eine Antwort wie die folgende angezeigt:

HTTP/1.1 202 Accepted
Date: Sat, 27 Aug 2022 17:53:18 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Location: https://global.azure-devices-provisioning.net/0ne00111111/registrations/my-x509-device/register
Retry-After: 3
x-ms-request-id: 05cdec07-c0c7-48f3-b3cd-30cfe27cbe57
Strict-Transport-Security: max-age=31536000; includeSubDomains

{"operationId":"5.506603669bd3e2bf.b3602f8f-76fe-4341-9214-bb6cfb891b8a","status":"assigning"}

Die Antwort enthält eine Vorgangs-ID und einen Status. In diesem Fall lautet der Status assigning. Die DPS-Registrierung ist unter Umständen ein zeitintensiver Vorgang und wird daher asynchron ausgeführt. In der Regel wird der Status mithilfe der REST-API zum Ermitteln des Vorgangsstatus abgefragt, um zu bestimmen, wann Ihr Gerät zugewiesen wurde oder ob ein Fehler aufgetreten ist.

Gültige Statuswerte für DPS sind:

  • assigned: Der Rückgabewert aus dem Statusaufruf gibt an, welchem IoT-Hub das Gerät zugewiesen wurde.

  • assigning: Der Vorgang wird noch ausgeführt.

  • disabled: Der Registrierungsdatensatz ist in DPS deaktiviert. Das Gerät kann somit nicht zugewiesen werden.

  • failed: Die Zuweisung war nicht erfolgreich. In der Antwort werden in einem Datensatz vom Typ registrationState ein Fehlercode (errorCode) und eine Fehlermeldung (errorMessage) zurückgegeben, die Aufschluss über den Fehler geben.

  • unassigned

Verwenden Sie den folgenden cURL-Befehl, um die API zum Ermitteln des Vorgangsstatus aufzurufen:

curl -L -i -X GET --cert [path_to_your_device_cert] --key [path_to_your_device_private_key] -H 'Content-Type: application/json' -H 'Content-Encoding:  utf-8' https://global.azure-devices-provisioning.net/[dps_id_scope]/registrations/[registration_id]/operations/[operation_id]?api-version=2019-03-31

Sie verwenden den gleichen ID-Bereich, die gleiche Registrierungs-ID sowie das gleiche Zertifikat und den gleichen Schlüssel wie bei der Anforderung Gerät registrieren. Verwenden Sie die Vorgangs-ID, die in der Antwort von Gerät registrieren zurückgegeben wurde.

Der folgende Befehl gilt beispielsweise für das selbstsignierte Zertifikat, das unter Verwenden eines selbstsignierten Zertifikats erstellt wurde. (ID-Bereich und Vorgangs-ID müssen geändert werden.)

curl -L -i -X GET --cert ./device-certPUT --cert device-cert.pem:1234 --key device-key.pem -H 'Content-Type: application/json' -H 'Content-Encoding:  utf-8' https://global.azure-devices-provisioning.net/0ne00111111/registrations/my-x509-device/operations/5.506603669bd3e2bf.b3602f8f-76fe-4341-9214-bb6cfb891b8a?api-version=2021-06-01

Die folgende Ausgabe zeigt die Antwort für ein erfolgreich zugewiesenes Gerät. Beachten Sie, dass die Eigenschaft status den Wert assigned hat und dass die Eigenschaft registrationState.assignedHub auf den IoT-Hub festgelegt ist, für den das Gerät bereitgestellt wurde.

HTTP/1.1 200 OK
Date: Sat, 27 Aug 2022 18:10:49 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
x-ms-request-id: 8f211bc5-3ed8-4c8b-9a79-e003e756e9e4
Strict-Transport-Security: max-age=31536000; includeSubDomains

{
   "operationId":"5.506603669bd3e2bf.b3602f8f-76fe-4341-9214-bb6cfb891b8a",
   "status":"assigned",
   "registrationState":{
      "x509":{
         
      },
      "registrationId":"my-x509-device",
      "createdDateTimeUtc":"2022-08-27T17:53:19.5143497Z",
      "assignedHub":"MyExampleHub.azure-devices.net",
      "deviceId":"my-x509-device",
      "status":"assigned",
      "substatus":"initialAssignment",
      "lastUpdatedDateTimeUtc":"2022-08-27T17:53:19.7519141Z",
      "etag":"IjEyMDA4NmYyLTAwMDAtMDMwMC0wMDAwLTYzMGE1YTBmMDAwMCI="
   }
}

Notieren Sie sich die Geräte-ID und den zugewiesenen IoT-Hub. Sie werden nächsten Abschnitt verwendet, um eine Telemetrienachricht zu senden.

Senden einer Telemetrienachricht

Rufen Sie die REST-API zum Senden von Geräteereignissen von IoT Hub auf, um Telemetriedaten an das Gerät zu senden.

Verwenden Sie den folgenden cURL-Befehl:

curl -L -i -X POST --cert [path_to_your_device_cert] --key [path_to_your_device_private_key] -H 'Content-Type: application/json' -H 'Content-Encoding:  utf-8' -d '{"temperature": 30}' https://[assigned_iot_hub_name].azure-devices.net/devices/[device_id]/messages/events?api-version=2020-03-13

Hierbei gilt:

  • -X POST teilt cURL mit, dass es sich um einen HTTP POST-Befehl handelt. Erforderlich für diesen API-Aufruf.

  • --cert [path_to_your_device_cert] teilt cURL mit, wo sich das X.509-Zertifikat Ihres Geräts befindet. Wenn der private Schlüssel Ihres Geräts durch eine Passphrase geschützt ist, können Sie nach dem Zertifikatpfad die Passphrase mit einem vorangestellten Doppelpunkt hinzufügen (Beispiel: --cert my-device.pem:1234).

    • Bei Verwendung eines selbstsignierten Zertifikats enthält Ihre Gerätezertifikatdatei nur ein einzelnes X.509-Zertifikat. Wenn Sie die Anweisungen unter Verwenden eines selbstsignierten Zertifikats befolgt haben, lautet der Dateiname device-cert.pem, und die Passphrase des privaten Schlüssels lautet 1234. Verwenden Sie also --cert device-cert.pem:1234.

    • Wenn Sie eine Zertifikatkette verwenden, muss Ihre Gerätezertifikatdatei eine gültige Zertifikatkette enthalten. Wenn Sie die Anweisungen unter Verwenden einer Zertifikatkette befolgt haben, um die Zertifikatkette zu erstellen, lautet der Dateipfad certs/device-01-full-chain.cert.pem. Verwenden Sie also --cert certs/device-01-full-chain.cert.pem.

  • --key [path_to_your_device_private_key] teilt cURL mit, wo sich der private Schlüssel Ihres Geräts befindet.

    • Wenn Sie die Anweisungen unter Verwenden eines selbstsignierten Zertifikats befolgt haben, lautet der Dateiname device-key.pem. Verwenden Sie also --key device-cert.pem:1234.

    • Wenn Sie die Anweisungen unter Verwenden einer Zertifikatkette befolgt haben, lautet der Schlüsselpfad certs/device-01-full-chain.cert.pem. Verwenden Sie also --cert certs/device-01-full-chain.cert.pem.

  • -H 'Content-Type: application/json' teilt IoT Hub mit, dass JSON-Inhalte veröffentlicht werden, und muss „application/json“ sein.

  • -H 'Content-Encoding: utf-8' teilt IoT Hub die für den Nachrichtentext verwendete Codierung mit. Verwenden Sie den entsprechenden Code für Ihr Betriebssystem bzw. Ihren Client. Das ist üblicherweise utf-8.

  • -d '{"temperature": 30}': Bei dem Parameter –d handelt es sich um die Daten oder um den Text der veröffentlichten Nachricht. Für diesen Artikel wird ein einzelner Temperaturdatenpunkt veröffentlicht. Der Inhaltstyp wurde als „application/json“ angegeben. Der Text für diese Anforderung ist also JSON-Code. Beachten Sie, dass der Code für cURL in einfache Anführungszeichen eingeschlossen wird. Andernfalls müssen die doppelten Anführungszeichen im JSON-Code mit Escapezeichen versehen werden.

  • Der letzte Parameter ist die URL für die Veröffentlichung. Für die API zum Senden von Geräteereignissen lautet die URL https://[assigned_iot_hub_name].azure-devices.net/devices/[device_id]/messages/events?api-version=2020-03-13.

    • Ersetzen Sie [assigned_iot_hub_name] durch den Namen des IoT-Hubs, dem Ihr Gerät zugewiesen wurde.

    • Ersetzen Sie [device_id] durch die Geräte-ID, die bei der Registrierung Ihres Geräts zugewiesen wurde. Bei Geräten mit Bereitstellung über Registrierungsgruppen ist die Geräte-ID die Registrierungs-ID. Bei individuellen Registrierungen können Sie optional eine Geräte-ID angeben, die sich von der Registrierungs-ID im Registrierungseintrag unterscheidet.

Zum Beispiel:

  • Wenn Sie die Anweisungen unter Verwenden eines selbstsignierten Zertifikats befolgt haben:

    curl -L -i -X POST --cert device-cert.pem:1234 --key device-key.pem -H 'Content-Type: application/json' -H 'Content-Encoding:  utf-8' -d '{"temperature": 30}' https://MyExampleHub.azure-devices.net/devices/my-x509-device/messages/events?api-version=2020-03-13

  • Wenn Sie die Anweisungen unter Verwenden einer Zertifikatkette befolgt haben:

    curl -L -i -X POST --cert certs/device-01-full-chain.cert.pem --key private/device-01.key.pem -H 'Content-Type: application/json' -H 'Content-Encoding:  utf-8' -d '{"temperature": 30}' https://MyExampleHub.azure-devices.net/devices/my-x509-device/messages/events?api-version=2020-03-13

Bei einem erfolgreichen Anruf wird eine Antwort wie die folgende angezeigt:

HTTP/1.1 204 No Content
Content-Length: 0
Vary: Origin
Server: Microsoft-HTTPAPI/2.0
x-ms-request-id: aa58c075-20d9-4565-8058-de6dc8524f14
Date: Wed, 31 Aug 2022 18:34:44 GMT

Nächste Schritte