az iot device registration

  • Vorschau

Note

Diese Referenz ist Teil der Azure-iot-Erweiterung für die Azure CLI (Version 2.73.0 oder höher). Die Erweiterung wird automatisch installiert, wenn Sie zum ersten Mal eine az iot-Geräteregistrierung Befehl ausführen. Erfahren Sie mehr über Erweiterungen.

Diese Befehlsgruppe befindet sich in der Vorschau und in der Entwicklung. Referenz- und Supportebenen: https://aka.ms/CLI_refstatus

Registrieren Eines Geräts über Azure IoT Hub Device Provisioning Service (DPS).

Verwenden Sie create for an individual or group enrollment, then operation-status to follow an accepted registration. Authentifizieren Sie das Gerät mit seinem symmetrischen Schlüssel oder einem X.509-Zertifikat. Dienstregistrierungsdatensätze und Registrierungsstatusverwaltung verbleiben unter az iot dps.

Befehle

Name Beschreibung Typ Status
az iot device registration create

Registrieren Sie ein Gerät, und stellen Sie optional das Betriebszertifikat aus.

 Extension Preview
az iot device registration operation-status

Zeigt den Status eines DPS-Geräteregistrierungsvorgangs an.

 Extension Preview

az iot device registration create

Vorschau

Die Befehlsgruppe "iot-Geräteregistrierung" befindet sich in der Vorschau und in der Entwicklung. Referenz- und Supportebenen: https://aka.ms/CLI_refstatus

Registrieren Sie ein Gerät, und stellen Sie optional das Betriebszertifikat aus.

Geben Sie für eine einzelne Registrierung ihr Gerät --symmetric-key an. Geben Sie für eine Gruppenregistrierung den Gruppenschlüssel mit --compute-key an, oder geben Sie einen bereits abgeleiteten Geräteschlüssel ohne --compute-key an. Alternativ können Sie "--dps-name" mit "--auth-type"-Anmeldung verwenden, um den ID-Bereich/Endpunkt zu ermitteln und Registrierungsschlüssel abzurufen; add --group-id and --compute-key for a group enrollment. Die Entra-Anmeldung autorisiert diesen Bootstrap-Nachschlagevorgang, nicht die Geräteregistrierungsanforderung.

Verwenden Sie "--id-scope" mit expliziten Geräteanmeldeinformationen, um die DPS-Ressourcenermittlung zu überspringen. Legen Sie "-host" fest, wenn Sie einen nicht standardmäßigen Bereitstellungsendpunkt verwenden. Geben Sie für die X.509-Authentifizierung --certificate-file-path und --key-file-path an; add --passphrase only if the private key is encrypted.

Fügen Sie "--csr" (Alias --csr-file-path) hinzu, um ein Betriebszertifikat anzufordern. Sie akzeptiert PEM oder base64 DER PKCS #10, inline oder aus einer Datei. Die CSR-Signatur muss gültig sein, und der gemeinsame Name muss mit "-registration-id" übereinstimmen. Eine CSR ersetzt nicht die symmetrische oder X.509-Authentifizierung des Geräts.

Mit dem Befehl werden akzeptierte Registrierungen abgerufen, wobei "Wiederholen nach" berücksichtigt wird.The command polls accepted registrations, honoring Retry-After. Wenn nach Erhalt einer Vorgangs-ID ein Zeitüberschreitung auftritt, verwenden Sie den Vorgangsstatus mit dieser ID und derselben Registrierungs-ID, dem ID-Bereich, dem Endpunkt und der Geräteauthentifizierung. Ein Timeout bricht den Back-End-Vorgang nicht ab; Erstellen Sie nicht blind erneut. --timeout wendet einen harten Stichtag auf denselben REST-Fluss sowohl für CSR- als auch für Nicht-CSR-Registrierung an, einschließlich Mitarbeiterstart, HTTP-Wiederholungen und Abfragen, nach vorläufigem ID-Bereich und Bootstrap-Anmeldeinformationenermittlung. Ohne --Timeout wird das vorhandene gebundene fünfminütige Abrufverhalten beibehalten.

Die JSON-Ausgabe behält "issuedCertificateChain" und "connectionProfile" bei, wenn DPS sie zurückgibt, plus registryDeviceExternalId für die Korrelation des Registrierungsgeräts. Der Vertrag 2026-11-02-preview RegisterDeviceAndIssueCertificate beschreibt ausgestellteCertificateChain nur als Array von Bytes und definiert seine Drahtcodierung oder Zertifikatreihenfolge nicht. Daher behält dieser Befehl dieses Feld in der JSON-Ausgabe bei, bietet jedoch keine Ausgabeoption für Zertifikatdateien; Das Schreiben einer erratenen Kette könnte ein nicht TLS-fähiges oder falsch sortiertes Bündel erzeugen. --endorsement-key and --storage-root-key are retained as advanced request-schema fields, but TPM-only authentication is explicitly unsupported because this contract provides no client TPM challenge protocol.

az iot device registration create --registration-id --rid
                                  [--acquire-policy-token]
                                  [--auth-type {key, login}]
                                  [--certificate-file-path --cp]
                                  [--change-reference]
                                  [--ck --compute-key]
                                  [--csr --csr-file-path]
                                  [--dps-name]
                                  [--endorsement-key]
                                  [--enrollment-group-id --gid --group-id]
                                  [--host --provisioning-host]
                                  [--id-scope --scope]
                                  [--key --symmetric-key]
                                  [--key-file-path --kp]
                                  [--login]
                                  [--pass --passphrase]
                                  [--payload]
                                  [--resource-group]
                                  [--storage-root-key]
                                  [--timeout]

Beispiele

Registrieren einer einzelnen Registrierung mithilfe der Entra-autorisierten Bootstrap-Schlüsselsuche

az iot device registration create --dps-name MyDps --resource-group MyResourceGroup \
  --registration-id device-01 --auth-type login

Registrieren eines Gruppenmitglieds mithilfe der Entra-autorisierten Bootstrap-Schlüsselsuche

az iot device registration create --dps-name MyDps --registration-id device-01 \
  --group-id MyEnrollmentGroup --compute-key --auth-type login

Registrieren mit einem Geräteschlüssel und einem bekannten ID-Bereich ohne Bootstrap-Nachschlagevorgang

az iot device registration create --id-scope 0ne00000000 \
  --registration-id device-01 --symmetric-key DEVICE_KEY

Ableiten eines Geräteschlüssels von einem Registrierungsgruppenschlüssel und Registrieren

az iot device registration create --id-scope 0ne00000000 \
  --registration-id device-01 --symmetric-key GROUP_KEY --compute-key

Registrieren und Anfordern eines Betriebszertifikats von einer PEM CSR

az iot device registration create --id-scope 0ne00000000 --registration-id device-01 \
  --symmetric-key DEVICE_KEY --csr ./device-01.csr --timeout 120

Registrieren mit einem X.509-Gerätezertifikat

az iot device registration create --id-scope 0ne00000000 \
  --registration-id device-01 --certificate-file-path ./device.pem \
  --key-file-path ./device-key.pem

Erforderliche Parameter

--registration-id --rid

Geräteregistrierungs-ID oder einzelne Registrierungs-ID.

Optionale Parameter

Die folgenden Parameter sind optional, aber je nach Kontext kann mindestens ein Parameter erforderlich sein, damit der Befehl erfolgreich ausgeführt werden kann.

--acquire-policy-token

Automatisches Abrufen eines Azure Policy Tokens für diesen Ressourcenvorgang.

Eigenschaft Wert
Parametergruppe: Global Policy Arguments
--auth-type

Gibt an, ob der Vorgang einen Richtlinienschlüssel automatisch ableiten oder die aktuelle Azure AD-Sitzung verwenden soll. Wenn der Authentifizierungstyp login ist und der Ressourcenhost bereitgestellt wird, wird die Ressourcensuche übersprungen, es sei denn, dies ist erforderlich. Sie können die Standardeinstellung mithilfe von az configure --defaults iothub-data-auth-type={auth-type-value}.

Eigenschaft Wert
Parametergruppe: Access Control Arguments
Standardwert: key
Zulässige Werte: key, login
--certificate-file-path --cp

Pfad zur PEM-Zertifikatdatei. Erforderlich für x509-Registrierungen.

Eigenschaft Wert
Parametergruppe: x509 Authentication Arguments
--change-reference

Die zugehörige Änderungsreferenz-ID für diesen Ressourcenvorgang.

Eigenschaft Wert
Parametergruppe: Global Policy Arguments
--ck --compute-key

Berechnen Sie den Schlüssel pro Gerät von --symmetric-key oder aus dem Registrierungsgruppenschlüssel, der durch --group-id mit --dps-name/--login aufgelöst wurde. Kann nicht mit X.509-Eingaben kombiniert werden.

Eigenschaft Wert
Parametergruppe: Symmetric Key Authentication Arguments
Standardwert: False
--csr --csr-file-path

Inline PEM/base64 DER PKCS #10 CSR oder Pfad zu einer CSR-Datei. Die Signatur muss gültig sein, und der gemeinsame Name muss mit der Registrierungs-ID übereinstimmen. Die Anforderung sendet base64 DER ohne PEM-Header.

Eigenschaft Wert
Parametergruppe: Certificate Issuance Arguments
--dps-name -n

Name des Azure IoT Hub Gerätebereitstellungsdiensts. Erforderlich, wenn --login nicht angegeben oder authenticaton-Argumente und --id-scope nicht bereitgestellt werden.

Eigenschaft Wert
Parametergruppe: DPS Identifier Arguments
--endorsement-key

Erweitertes TPM-Anforderungsfeld, das vom Dienstschema aufbewahrt wird. Muss mit --storage-root-key verwendet werden. Die nur TPM-Clientauthentifizierung wird von diesem Befehl nicht unterstützt.

Eigenschaft Wert
Parametergruppe: TPM Arguments
--enrollment-group-id --gid --group-id

Registrierungsgruppen-ID. Nur zum Abrufen von Authentifizierungsargumenten erforderlich.

--host --provisioning-host

DPS-Geräteendpunkt. Wenn sie weggelassen wird, wird der Endpunkt von der ausgewählten DPS-Ressource abgeleitet und greift dann auf den globalen Endpunkt zurück.

--id-scope --scope

ID-Bereich des Azure IoT Hub Gerätebereitstellungsdiensts. Der ID-Bereich identifiziert keinen Geräteendpunkt: --dps-name oder --login wird weiterhin aufgelöst, wenn angegeben. Bei nur --id-bereichs- und expliziten Geräteanmeldeinformationen wird der dokumentierte globale Endpunkt-Fallback verwendet.

Eigenschaft Wert
Parametergruppe: DPS Identifier Arguments
--key --symmetric-key

Der symmetrische gemeinsam genutzte Zugriffsschlüssel für die Geräteregistrierung.

Eigenschaft Wert
Parametergruppe: Symmetric Key Authentication Arguments
--key-file-path --kp

Pfad zur PEM-Schlüsseldatei. Erforderlich für x509-Registrierungen.

Eigenschaft Wert
Parametergruppe: x509 Authentication Arguments
--login -l

Dieser Befehl unterstützt eine Entität Verbindungszeichenfolge mit Rechten zum Ausführen von Aktionen. Wird verwendet, um die Sitzungsanmeldung über "az login" zu vermeiden. Wenn sowohl eine Entität Verbindungszeichenfolge als auch ein Name angegeben werden, hat die Verbindungszeichenfolge Vorrang. Erforderlich, wenn --dps-name nicht angegeben oder authenticaton-Argumente und --id-scope nicht bereitgestellt werden.

Eigenschaft Wert
Parametergruppe: DPS Identifier Arguments
--pass --passphrase

Passphrase für den privaten X.509-Schlüssel. Nur gültig mit --certificate-file-path und --key-file-path.

Eigenschaft Wert
Parametergruppe: x509 Authentication Arguments
--payload

Registrierungsnutzlast als JSON-Objekt oder Pfad zu einer JSON-Datei.

--resource-group -g

Name der Ressourcengruppe. Sie können die Standardgruppe mit az configure --defaults group=<name>konfigurieren.

--storage-root-key

Erweitertes TPM-Anforderungsfeld, das vom Dienstschema aufbewahrt wird. Muss mit ---endorsement-key verwendet werden. Die nur TPM-Clientauthentifizierung wird von diesem Befehl nicht unterstützt.

Eigenschaft Wert
Parametergruppe: TPM Arguments
--timeout

Positiver ganzzahliger harter REST-Registrierungstimeout in Sekunden, einschließlich Start des Mitarbeiters, HTTP und Abruf. Schließt den vorläufigen ID-Bereich und die Bootstrap-Erkennung von Anmeldeinformationen aus.

Globale Parameter
--debug

Erhöhen Sie die Ausführlichkeit der Protokollierung, um alle Debugprotokolle anzuzeigen.

Eigenschaft Wert
Standardwert: False
--help -h

Diese Hilfemeldung anzeigen und schließen.

--only-show-errors

Nur Fehler anzeigen, Warnungen unterdrücken.

Eigenschaft Wert
Standardwert: False
--output -o

Ausgabeformat.

Eigenschaft Wert
Standardwert: json
Zulässige Werte: json, jsonc, none, table, tsv, yaml, yamlc
--query

JMESPath-Abfragezeichenfolge. Weitere Informationen und Beispiele finden Sie unter http://jmespath.org/.

--subscription

Name oder ID des Abonnements. Sie können das Standardabonnement mithilfe von az account set -s NAME_OR_IDkonfigurieren.

--verbose

Erhöhen Sie die Ausführlichkeit der Protokollierung. Verwenden Sie "-debug" für vollständige Debugprotokolle.

Eigenschaft Wert
Standardwert: False

az iot device registration operation-status

Vorschau

Die Befehlsgruppe "iot-Geräteregistrierung" befindet sich in der Vorschau und in der Entwicklung. Referenz- und Supportebenen: https://aka.ms/CLI_refstatus

Zeigt den Status eines DPS-Geräteregistrierungsvorgangs an.

Geben Sie die von DPS zurückgegebene Vorgangs-ID an oder geben Sie sie nach einem Timeout an. Verwenden Sie die Registrierungs-ID, den ID-Bereich (oder DEN DPS-Namen), die Host- und Geräteauthentifizierung aus der Erstellung wieder. Dies ist ein Status, der gelesen wird, keine neue Registrierung.

az iot device registration operation-status --operation-id
                                            --registration-id --rid
                                            [--acquire-policy-token]
                                            [--auth-type {key, login}]
                                            [--certificate-file-path --cp]
                                            [--change-reference]
                                            [--ck --compute-key]
                                            [--dps-name]
                                            [--enrollment-group-id --gid --group-id]
                                            [--host --provisioning-host]
                                            [--id-scope --scope]
                                            [--key --symmetric-key]
                                            [--key-file-path --kp]
                                            [--login]
                                            [--pass --passphrase]
                                            [--resource-group]

Beispiele

Folgen einer einzelnen Registrierung mit Bootstrap-Schlüsselsuche

az iot device registration operation-status --dps-name MyDps \
  --registration-id device-01 --operation-id OPERATION_ID --auth-type login

Folgen eines Gruppenmitglieds mit demselben Gruppenschlüssel und Bereitstellungshost

az iot device registration operation-status --id-scope 0ne00000000 \
  --registration-id device-01 --operation-id OPERATION_ID \
  --symmetric-key GROUP_KEY --compute-key --host MyProvisioningHost

Folgen eines akzeptierten Vorgangs nach einem Timeout ohne erneute Übermittlung der Registrierung

az iot device registration operation-status --id-scope 0ne00000000 \
  --registration-id device-01 --operation-id OPERATION_ID --symmetric-key DEVICE_KEY

Erforderliche Parameter

--operation-id

Registrierungsvorgangsbezeichner, der von create zurückgegeben wird.

--registration-id --rid

Geräteregistrierungs-ID oder einzelne Registrierungs-ID.

Optionale Parameter

Die folgenden Parameter sind optional, aber je nach Kontext kann mindestens ein Parameter erforderlich sein, damit der Befehl erfolgreich ausgeführt werden kann.

--acquire-policy-token

Automatisches Abrufen eines Azure Policy Tokens für diesen Ressourcenvorgang.

Eigenschaft Wert
Parametergruppe: Global Policy Arguments
--auth-type

Gibt an, ob der Vorgang einen Richtlinienschlüssel automatisch ableiten oder die aktuelle Azure AD-Sitzung verwenden soll. Wenn der Authentifizierungstyp login ist und der Ressourcenhost bereitgestellt wird, wird die Ressourcensuche übersprungen, es sei denn, dies ist erforderlich. Sie können die Standardeinstellung mithilfe von az configure --defaults iothub-data-auth-type={auth-type-value}.

Eigenschaft Wert
Parametergruppe: Access Control Arguments
Standardwert: key
Zulässige Werte: key, login
--certificate-file-path --cp

Pfad zur PEM-Zertifikatdatei. Erforderlich für x509-Registrierungen.

Eigenschaft Wert
Parametergruppe: x509 Authentication Arguments
--change-reference

Die zugehörige Änderungsreferenz-ID für diesen Ressourcenvorgang.

Eigenschaft Wert
Parametergruppe: Global Policy Arguments
--ck --compute-key

Berechnen Sie den Schlüssel pro Gerät von --symmetric-key oder aus dem Registrierungsgruppenschlüssel, der durch --group-id mit --dps-name/--login aufgelöst wurde. Kann nicht mit X.509-Eingaben kombiniert werden.

Eigenschaft Wert
Parametergruppe: Symmetric Key Authentication Arguments
Standardwert: False
--dps-name -n

Name des Azure IoT Hub Gerätebereitstellungsdiensts. Erforderlich, wenn --login nicht angegeben oder authenticaton-Argumente und --id-scope nicht bereitgestellt werden.

Eigenschaft Wert
Parametergruppe: DPS Identifier Arguments
--enrollment-group-id --gid --group-id

Registrierungsgruppen-ID. Nur zum Abrufen von Authentifizierungsargumenten erforderlich.

--host --provisioning-host

DPS-Geräteendpunkt. Wenn sie weggelassen wird, wird der Endpunkt von der ausgewählten DPS-Ressource abgeleitet und greift dann auf den globalen Endpunkt zurück.

--id-scope --scope

ID-Bereich des Azure IoT Hub Gerätebereitstellungsdiensts. Der ID-Bereich identifiziert keinen Geräteendpunkt: --dps-name oder --login wird weiterhin aufgelöst, wenn angegeben. Bei nur --id-bereichs- und expliziten Geräteanmeldeinformationen wird der dokumentierte globale Endpunkt-Fallback verwendet.

Eigenschaft Wert
Parametergruppe: DPS Identifier Arguments
--key --symmetric-key

Der symmetrische gemeinsam genutzte Zugriffsschlüssel für die Geräteregistrierung.

Eigenschaft Wert
Parametergruppe: Symmetric Key Authentication Arguments
--key-file-path --kp

Pfad zur PEM-Schlüsseldatei. Erforderlich für x509-Registrierungen.

Eigenschaft Wert
Parametergruppe: x509 Authentication Arguments
--login -l

Dieser Befehl unterstützt eine Entität Verbindungszeichenfolge mit Rechten zum Ausführen von Aktionen. Wird verwendet, um die Sitzungsanmeldung über "az login" zu vermeiden. Wenn sowohl eine Entität Verbindungszeichenfolge als auch ein Name angegeben werden, hat die Verbindungszeichenfolge Vorrang. Erforderlich, wenn --dps-name nicht angegeben oder authenticaton-Argumente und --id-scope nicht bereitgestellt werden.

Eigenschaft Wert
Parametergruppe: DPS Identifier Arguments
--pass --passphrase

Passphrase für den privaten X.509-Schlüssel. Nur gültig mit --certificate-file-path und --key-file-path.

Eigenschaft Wert
Parametergruppe: x509 Authentication Arguments
--resource-group -g

Name der Ressourcengruppe. Sie können die Standardgruppe mit az configure --defaults group=<name>konfigurieren.

Globale Parameter
--debug

Erhöhen Sie die Ausführlichkeit der Protokollierung, um alle Debugprotokolle anzuzeigen.

Eigenschaft Wert
Standardwert: False
--help -h

Diese Hilfemeldung anzeigen und schließen.

--only-show-errors

Nur Fehler anzeigen, Warnungen unterdrücken.

Eigenschaft Wert
Standardwert: False
--output -o

Ausgabeformat.

Eigenschaft Wert
Standardwert: json
Zulässige Werte: json, jsonc, none, table, tsv, yaml, yamlc
--query

JMESPath-Abfragezeichenfolge. Weitere Informationen und Beispiele finden Sie unter http://jmespath.org/.

--subscription

Name oder ID des Abonnements. Sie können das Standardabonnement mithilfe von az account set -s NAME_OR_IDkonfigurieren.

--verbose

Erhöhen Sie die Ausführlichkeit der Protokollierung. Verwenden Sie "-debug" für vollständige Debugprotokolle.

Eigenschaft Wert
Standardwert: False