az iot device registration

  • Anteprima

Note

Questo riferimento fa parte dell'estensione azure-iot per il interfaccia della riga di comando di Azure (versione 2.73.0 o successiva). L'estensione installerà automaticamente la prima volta che si esegue un comando az iot device registration. Altre informazioni sulle estensioni.

Questo gruppo di comandi è in anteprima e in fase di sviluppo. Livelli di riferimento e supporto: https://aka.ms/CLI_refstatus

Registrare un dispositivo tramite hub IoT di Azure servizio Device Provisioning (DPS).

Usare create per una registrazione singola o di gruppo, quindi lo stato dell'operazione per seguire una registrazione accettata. Autenticare il dispositivo con la chiave simmetrica o un certificato X.509. I record di registrazione del servizio e l'amministrazione dello stato di registrazione rimangono in az iot dps.

Comandi

Nome Descrizione Tipo Status
az iot device registration create

Registrare un dispositivo e, facoltativamente, rilasciare il certificato operativo.

 Extension Preview
az iot device registration operation-status

Visualizzare lo stato di un'operazione di registrazione del dispositivo DPS.

 Extension Preview

az iot device registration create

Anteprima

Il gruppo di comandi 'iot device registration' è in anteprima e in fase di sviluppo. Livelli di riferimento e supporto: https://aka.ms/CLI_refstatus

Registrare un dispositivo e, facoltativamente, rilasciare il certificato operativo.

Per una registrazione singola, specificare il dispositivo --symmetric-key. Per una registrazione di gruppo, specificare la chiave di gruppo con --compute-key o fornire una chiave del dispositivo già derivata senza --compute-key. In alternativa, usare --dps-name con --auth-type login per individuare l'ambito ID/l'endpoint e recuperare le chiavi di registrazione; aggiungere --group-id e --compute-key per una registrazione di gruppo. Entra login autorizza questa ricerca bootstrap, non la richiesta di registrazione del dispositivo.

Usare --id-scope con credenziali esplicite del dispositivo per ignorare l'individuazione delle risorse dps. Impostare --host quando si usa un endpoint di provisioning non predefinito. Per l'autenticazione X.509, specificare --certificate-file-path e --key-file-path; add --passphrase solo se la chiave privata è crittografata.

Aggiungere --csr (alias --csr-file-path) per richiedere un certificato operativo. Accetta PEM o base64 DER PKCS #10, inline o da un file. La firma CSR deve essere valida e il nome comune deve corrispondere a --registration-id. Un csr non sostituisce la chiave simmetrica del dispositivo o l'autenticazione X.509.

Il comando esegue il polling delle registrazioni accettate, rispettando Retry-After. Se si verifica il timeout dopo aver ricevuto un ID operazione, usare lo stato dell'operazione con tale ID e lo stesso ID di registrazione, ambito ID, endpoint e autenticazione del dispositivo. Un timeout non annulla l'operazione back-end; non rieseguire cieco la creazione. --timeout applica una scadenza rigida allo stesso flusso REST sia per la registrazione CSR che per la registrazione non CSR, inclusi l'avvio del ruolo di lavoro, i tentativi HTTP e il polling, dopo l'individuazione preliminare dell'ambito ID e l'individuazione delle credenziali bootstrap. Senza --timeout, viene mantenuto il comportamento di polling di cinque minuti delimitato esistente.

L'output JSON mantiene rilasciatoCertificateChain e connectionProfile quando dps li restituisce, oltre a registryDeviceExternalId per la correlazione del dispositivo del Registro di sistema. Il contratto RegisterDeviceAndIssueCertificate 2026-11-02-preview descrive emessoCertificateChain solo come matrice di byte e non definisce la codifica wire o l'ordine dei certificati. Di conseguenza, questo comando mantiene tale campo nell'output JSON, ma non offre un'opzione di output del file di certificato; la scrittura di una catena indovina potrebbe produrre un bundle non pronto per TLS o ordinato in modo non corretto. --endorsement-key e --storage-root-key vengono mantenuti come campi avanzati dello schema di richiesta, ma l'autenticazione solo TPM non è supportata in modo esplicito perché questo contratto non fornisce alcun protocollo di verifica TPM client.

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]

Esempio

Registrare una registrazione singola usando la ricerca della chiave di bootstrap autorizzata da Entra

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

Registrare un membro del gruppo usando la ricerca della chiave bootstrap autorizzata da Entra

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

Eseguire la registrazione con una chiave del dispositivo e un ambito ID noto, senza ricerca bootstrap

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

Derivare una chiave del dispositivo da una chiave del gruppo di registrazione e registrare

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

Registrare e richiedere un certificato operativo da un file PEM CSR

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

Eseguire la registrazione con un certificato del dispositivo X.509

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

Parametri necessari

--registration-id --rid

ID registrazione dispositivo o ID registrazione singola.

Parametri facoltativi

I seguenti parametri sono facoltativi, ma a seconda del contesto, uno o più di questi potrebbero diventare necessari per l'esecuzione corretta del comando.

--acquire-policy-token

Acquisizione automatica di un token Criteri di Azure per questa operazione di risorsa.

Proprietà Valore
Gruppo di parametri: Global Policy Arguments
--auth-type

Indica se l'operazione deve derivare automaticamente una chiave dei criteri o usare la sessione corrente di Azure AD. Se il tipo di autenticazione è login e viene specificato il nome host della risorsa, la ricerca della risorsa verrà ignorata a meno che non sia necessario. È possibile configurare l'impostazione predefinita usando az configure --defaults iothub-data-auth-type={auth-type-value}.

Proprietà Valore
Gruppo di parametri: Access Control Arguments
Valore predefinito: key
Valori accettati: key, login
--certificate-file-path --cp

Percorso del file PEM del certificato. Obbligatorio per le registrazioni x509.

Proprietà Valore
Gruppo di parametri: x509 Authentication Arguments
--change-reference

ID riferimento di modifica correlato per questa operazione di risorsa.

Proprietà Valore
Gruppo di parametri: Global Policy Arguments
--ck --compute-key

Calcolare la chiave per dispositivo da --symmetric-key o dalla chiave enrollment-group risolta da --group-id con --dps-name/--login. Impossibile combinare gli input X.509.

Proprietà Valore
Gruppo di parametri: Symmetric Key Authentication Arguments
Valore predefinito: False
--csr --csr-file-path

PEM/base64 DER PKCS #10 CSR inline o percorso di un file CSR. La firma deve essere valida e Common Name deve corrispondere all'ID di registrazione. La richiesta invia der base64 senza intestazioni PEM.

Proprietà Valore
Gruppo di parametri: Certificate Issuance Arguments
--dps-name -n

Nome del servizio Device Provisioning hub IoT di Azure. Obbligatorio se non vengono specificati argomenti --login o authenticaton e --id-scope non vengono forniti.

Proprietà Valore
Gruppo di parametri: DPS Identifier Arguments
--endorsement-key

Campo della richiesta TPM avanzato mantenuto dallo schema del servizio. Deve essere usato con --storage-root-key. L'autenticazione client solo TPM non è supportata da questo comando.

Proprietà Valore
Gruppo di parametri: TPM Arguments
--enrollment-group-id --gid --group-id

ID gruppo di registrazione. Solo necessario per recuperare gli argomenti di autenticazione.

--host --provisioning-host

Endpoint del dispositivo DPS. Se omesso, l'endpoint viene derivato dalla risorsa dps selezionata, quindi esegue il fallback all'endpoint globale.

--id-scope --scope

Ambito ID del servizio Device Provisioning hub IoT di Azure. L'ambito ID non identifica un endpoint del dispositivo: --dps-name o --login viene comunque risolto quando specificato. Con solo --id-scope e credenziali esplicite del dispositivo, viene usato il fallback dell'endpoint globale documentato.

Proprietà Valore
Gruppo di parametri: DPS Identifier Arguments
--key --symmetric-key

Chiave di accesso condiviso simmetrica per la registrazione del dispositivo.

Proprietà Valore
Gruppo di parametri: Symmetric Key Authentication Arguments
--key-file-path --kp

Percorso del file PEM della chiave. Obbligatorio per le registrazioni x509.

Proprietà Valore
Gruppo di parametri: x509 Authentication Arguments
--login -l

Questo comando supporta un'entità stringa di connessione con diritti per eseguire l'azione. Usare per evitare l'accesso di sessione tramite "az login". Se vengono forniti sia un stringa di connessione di entità che un nome, il stringa di connessione ha la priorità. Obbligatorio se non vengono specificati argomenti --dps-name o authenticaton e --id-scope non vengono forniti.

Proprietà Valore
Gruppo di parametri: DPS Identifier Arguments
--pass --passphrase

Passphrase per la chiave privata X.509. Valido solo con --certificate-file-path e --key-file-path.

Proprietà Valore
Gruppo di parametri: x509 Authentication Arguments
--payload

Payload di registrazione come oggetto JSON o percorso di un file JSON.

--resource-group -g

Nome del gruppo di risorse. È possibile configurare il gruppo predefinito usando az configure --defaults group=<name>.

--storage-root-key

Campo della richiesta TPM avanzato mantenuto dallo schema del servizio. Deve essere usato con --endorsement-key. L'autenticazione client solo TPM non è supportata da questo comando.

Proprietà Valore
Gruppo di parametri: TPM Arguments
--timeout

Timeout positivo della registrazione REST con numero intero in secondi, tra cui avvio del ruolo di lavoro, HTTP e polling. Esclude l'ambito id preliminare e l'individuazione delle credenziali bootstrap.

Parametri globali
--debug

Aumentare la verbosità dei log per visualizzare tutti i log di debug.

Proprietà Valore
Valore predefinito: False
--help -h

Mostra questo messaggio Guida, esci.

--only-show-errors

Mostra solo gli errori, eliminando gli avvisi.

Proprietà Valore
Valore predefinito: False
--output -o

Formato dell'output.

Proprietà Valore
Valore predefinito: json
Valori accettati: json, jsonc, none, table, tsv, yaml, yamlc
--query

Stringa di query JMESPath. Per altre informazioni ed esempi, vedere http://jmespath.org/.

--subscription

Nome o ID della sottoscrizione. È possibile configurare la posizione predefinito usando az account set -s NAME_OR_ID.

--verbose

Aumentare il livello di dettaglio della registrazione. Usare --debug per log di debug completi.

Proprietà Valore
Valore predefinito: False

az iot device registration operation-status

Anteprima

Il gruppo di comandi 'iot device registration' è in anteprima e in fase di sviluppo. Livelli di riferimento e supporto: https://aka.ms/CLI_refstatus

Visualizzare lo stato di un'operazione di registrazione del dispositivo DPS.

Specificare l'ID operazione restituito dal servizio Device Provisioning o segnalato da crea dopo un timeout. Riutilizzare l'ID di registrazione, l'ambito ID (o il nome dps), l'host di provisioning e l'autenticazione del dispositivo da creare. Questo è uno stato letto, non una nuova registrazione.

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]

Esempio

Seguire una registrazione singola con la ricerca della chiave bootstrap

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

Seguire un membro del gruppo con la stessa chiave di gruppo e la stessa host di provisioning

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

Seguire un'operazione accettata dopo un timeout senza inviare nuovamente la registrazione

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

Parametri necessari

--operation-id

Identificatore dell'operazione di registrazione restituito da create.

--registration-id --rid

ID registrazione dispositivo o ID registrazione singola.

Parametri facoltativi

I seguenti parametri sono facoltativi, ma a seconda del contesto, uno o più di questi potrebbero diventare necessari per l'esecuzione corretta del comando.

--acquire-policy-token

Acquisizione automatica di un token Criteri di Azure per questa operazione di risorsa.

Proprietà Valore
Gruppo di parametri: Global Policy Arguments
--auth-type

Indica se l'operazione deve derivare automaticamente una chiave dei criteri o usare la sessione corrente di Azure AD. Se il tipo di autenticazione è login e viene specificato il nome host della risorsa, la ricerca della risorsa verrà ignorata a meno che non sia necessario. È possibile configurare l'impostazione predefinita usando az configure --defaults iothub-data-auth-type={auth-type-value}.

Proprietà Valore
Gruppo di parametri: Access Control Arguments
Valore predefinito: key
Valori accettati: key, login
--certificate-file-path --cp

Percorso del file PEM del certificato. Obbligatorio per le registrazioni x509.

Proprietà Valore
Gruppo di parametri: x509 Authentication Arguments
--change-reference

ID riferimento di modifica correlato per questa operazione di risorsa.

Proprietà Valore
Gruppo di parametri: Global Policy Arguments
--ck --compute-key

Calcolare la chiave per dispositivo da --symmetric-key o dalla chiave enrollment-group risolta da --group-id con --dps-name/--login. Impossibile combinare gli input X.509.

Proprietà Valore
Gruppo di parametri: Symmetric Key Authentication Arguments
Valore predefinito: False
--dps-name -n

Nome del servizio Device Provisioning hub IoT di Azure. Obbligatorio se non vengono specificati argomenti --login o authenticaton e --id-scope non vengono forniti.

Proprietà Valore
Gruppo di parametri: DPS Identifier Arguments
--enrollment-group-id --gid --group-id

ID gruppo di registrazione. Solo necessario per recuperare gli argomenti di autenticazione.

--host --provisioning-host

Endpoint del dispositivo DPS. Se omesso, l'endpoint viene derivato dalla risorsa dps selezionata, quindi esegue il fallback all'endpoint globale.

--id-scope --scope

Ambito ID del servizio Device Provisioning hub IoT di Azure. L'ambito ID non identifica un endpoint del dispositivo: --dps-name o --login viene comunque risolto quando specificato. Con solo --id-scope e credenziali esplicite del dispositivo, viene usato il fallback dell'endpoint globale documentato.

Proprietà Valore
Gruppo di parametri: DPS Identifier Arguments
--key --symmetric-key

Chiave di accesso condiviso simmetrica per la registrazione del dispositivo.

Proprietà Valore
Gruppo di parametri: Symmetric Key Authentication Arguments
--key-file-path --kp

Percorso del file PEM della chiave. Obbligatorio per le registrazioni x509.

Proprietà Valore
Gruppo di parametri: x509 Authentication Arguments
--login -l

Questo comando supporta un'entità stringa di connessione con diritti per eseguire l'azione. Usare per evitare l'accesso di sessione tramite "az login". Se vengono forniti sia un stringa di connessione di entità che un nome, il stringa di connessione ha la priorità. Obbligatorio se non vengono specificati argomenti --dps-name o authenticaton e --id-scope non vengono forniti.

Proprietà Valore
Gruppo di parametri: DPS Identifier Arguments
--pass --passphrase

Passphrase per la chiave privata X.509. Valido solo con --certificate-file-path e --key-file-path.

Proprietà Valore
Gruppo di parametri: x509 Authentication Arguments
--resource-group -g

Nome del gruppo di risorse. È possibile configurare il gruppo predefinito usando az configure --defaults group=<name>.

Parametri globali
--debug

Aumentare la verbosità dei log per visualizzare tutti i log di debug.

Proprietà Valore
Valore predefinito: False
--help -h

Mostra questo messaggio Guida, esci.

--only-show-errors

Mostra solo gli errori, eliminando gli avvisi.

Proprietà Valore
Valore predefinito: False
--output -o

Formato dell'output.

Proprietà Valore
Valore predefinito: json
Valori accettati: json, jsonc, none, table, tsv, yaml, yamlc
--query

Stringa di query JMESPath. Per altre informazioni ed esempi, vedere http://jmespath.org/.

--subscription

Nome o ID della sottoscrizione. È possibile configurare la posizione predefinito usando az account set -s NAME_OR_ID.

--verbose

Aumentare il livello di dettaglio della registrazione. Usare --debug per log di debug completi.

Proprietà Valore
Valore predefinito: False