az iot device registration

  • Pré-visualizar

Note

Esta referência faz parte da extensão azure-iot para a CLI do Azure (versão 2.73.0 ou superior). A extensão será instalada automaticamente na primeira vez que você executar um comando de registro de dispositivo az iot. Saiba mais sobre extensões.

Este grupo de comandos está em pré-visualização e em desenvolvimento. Níveis de referência e de apoio: https://aka.ms/CLI_refstatus

Registe um dispositivo através do Hub IoT do Azure Device Provisioning Service (DPS).

Use criar para uma inscrição individual ou de grupo, depois estado operacional para seguir um registo aceite. Autentique o dispositivo com a sua chave simétrica ou um certificado X.509. Os registos de inscrição no serviço e o registo-administração estadual permanecem sob az iot dps.

Comandos

Nome Descrição Tipo Estado
az iot device registration create

Registar um dispositivo e, opcionalmente, emitir o seu certificado operacional.

 Extension Preview
az iot device registration operation-status

Mostrar o estado de uma operação de registo de dispositivo DPS.

 Extension Preview

az iot device registration create

Pré-visualizar

O grupo de comandos 'iot device registration' está em pré-visualização e em desenvolvimento. Níveis de referência e de apoio: https://aka.ms/CLI_refstatus

Registar um dispositivo e, opcionalmente, emitir o seu certificado operacional.

Para uma inscrição individual, forneça o seu dispositivo --chave simétrica. Para uma inscrição de grupo, forneça à chave de grupo --compute-key, ou forneça uma chave de dispositivo já derivada sem --compute-key. Alternativamente, use --dps-name com --auth-type login para descobrir o escopo/endpoint de ID e recuperar as chaves de inscrição; adicionar --group-id e --compute-key para um registo de grupo. O login do Entra autoriza esta pesquisa de bootstrap, não o pedido de registo do dispositivo.

Use --id-scope com credenciais explícitas de dispositivo para evitar a descoberta de recursos DPS. Defina --host ao usar um endpoint de provisionamento não padrão. Para autenticação X.509, forneça --certificate-file-path e --key-file-path; adicione --passphrase apenas se a chave privada estiver encriptada.

Adicionar --csr (alias --csr-file-path) para solicitar um certificado operacional. Aceita PEM ou DER PKCS #10 em base64, em linha ou a partir de um ficheiro. A assinatura do CSR deve ser válida e o seu Nome Comum deve corresponder a --registration-id. Um CSR não substitui a chave simétrica do dispositivo nem a autenticação X.509.

As sondagens do comando aceitaram registos, honrando o Retry-After. Se expirar após receber um ID de operação, use o estado de operação com esse ID e o mesmo ID de registo, âmbito de ID, endpoint e autenticação do dispositivo. Um timeout não cancela a operação do backend; não execute cegamente o create. --timeout aplica um prazo rígido ao mesmo fluxo REST tanto para registo de CSR como não-CSR, incluindo arranque de trabalhadores, retentativas HTTP e polling, após o âmbito preliminar de identificação e a descoberta de credenciais bootstrap. Sem --timeout, mantém-se o comportamento de sondagem limitado de cinco minutos existente.

A saída JSON preserva o CertificateChain emitido e o connectionProfile quando o DPS os devolve, além do registryDeviceExternalId para correlação entre Dispositivos de Registo. O contrato de pré-visualização de 2026-11-02-02-RegisterDeviceAndIssueCertificate descreve a issuedCertificateChain apenas como um array de bytes e não define a sua codificação de fios ou a ordem dos certificados. Consequentemente, este comando preserva esse campo na saída JSON, mas não oferece uma opção de saída de ficheiro de certificado; escrever uma cadeia adivinhada pode produzir um conjunto não pronto para TLS ou mal ordenado. --chave de endosso e --chave-raiz de armazenamento são mantidas como campos avançados de esquema de pedido, mas a autenticação apenas TPM não é explicitamente suportada porque este contrato não prevê protocolo de desafio TPM do cliente.

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]

Exemplos

Registe uma inscrição individual usando a pesquisa de chave bootstrap autorizada pela Entra

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

Registe um membro do grupo usando a pesquisa de chave bootstrap autorizada pela Entra.

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

Registar com uma chave de dispositivo e um escopo de ID conhecido, sem pesquisa bootstrap

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

Derive uma chave de dispositivo a partir de uma chave de grupo de registo e registo de inscrição

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

Registe-se e solicite um certificado operacional a um CSR PEM

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

Registe-se com um certificado de 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

Parâmetros Obrigatórios

--registration-id --rid

ID de registo do dispositivo ou ID de inscrição individual.

Parâmetros Opcionais

Os seguintes parâmetros são opcionais, mas dependendo do contexto, um ou mais podem tornar-se necessários para que o comando seja executado com êxito.

--acquire-policy-token

Aquisição automática de um token Azure Policy para esta operação de recurso.

Propriedade Valor
Grupo de parâmetros: Global Policy Arguments
--auth-type

Indica se a operação deve derivar automaticamente uma chave de política ou usar a sessão atual do Azure AD. Se o tipo de autenticação for login e o nome de host do recurso for fornecido, a pesquisa de recursos será ignorada, a menos que necessário. Você pode configurar o padrão usando az configure --defaults iothub-data-auth-type={auth-type-value}.

Propriedade Valor
Grupo de parâmetros: Access Control Arguments
Valor predefinido: key
Valores aceites: key, login
--certificate-file-path --cp

Caminho para o arquivo PEM do certificado. Necessário para registros x509.

Propriedade Valor
Grupo de parâmetros: x509 Authentication Arguments
--change-reference

O ID de referência de alteração relacionado para esta operação de recurso.

Propriedade Valor
Grupo de parâmetros: Global Policy Arguments
--ck --compute-key

Calcule a chave por dispositivo a partir de --simétrica-chave, ou a partir da chave do grupo de registo resolvida por --group-id com --dps-name/--login. Não pode ser combinado com entradas X.509.

Propriedade Valor
Grupo de parâmetros: Symmetric Key Authentication Arguments
Valor predefinido: False
--csr --csr-file-path

Inline PEM/base64 DER PKCS #10 CSR ou caminho para um ficheiro CSR. A sua assinatura deve ser válida e o Nome Comum deve corresponder ao ID de registo. O pedido envia DER base64 sem cabeçalhos PEM.

Propriedade Valor
Grupo de parâmetros: Certificate Issuance Arguments
--dps-name -n

Nome do Azure IoT Zoom Device Provisioning Service. Obrigatório se --login não for fornecido ou se os argumentos authenticaton e --id-scope não forem fornecidos.

Propriedade Valor
Grupo de parâmetros: DPS Identifier Arguments
--endorsement-key

Campo de pedido TPM avançado mantido pelo esquema de serviço. Deve ser usado com --storage-root-key. A autenticação do cliente apenas TPM não é suportada por este comando.

Propriedade Valor
Grupo de parâmetros: TPM Arguments
--enrollment-group-id --gid --group-id

ID do grupo de inscrição. Só é necessário recuperar argumentos de autenticação.

--host --provisioning-host

Endpoint do dispositivo DPS. Quando omitido, o endpoint é derivado do recurso DPS selecionado e depois regressa ao endpoint global.

--id-scope --scope

ID âmbito do Azure IoT Zoom Device Provisioning Service. O âmbito do ID não identifica o endpoint do dispositivo: --dps-name ou --login ainda é resolvido quando fornecido. Com apenas --id-scope e credenciais explícitas do dispositivo, utiliza-se a alternativa global de endpoint documentada.

Propriedade Valor
Grupo de parâmetros: DPS Identifier Arguments
--key --symmetric-key

A chave de acesso compartilhada simétrica para o registro do dispositivo.

Propriedade Valor
Grupo de parâmetros: Symmetric Key Authentication Arguments
--key-file-path --kp

Caminho para o arquivo PEM chave. Necessário para registros x509.

Propriedade Valor
Grupo de parâmetros: x509 Authentication Arguments
--login -l

Este comando suporta uma cadeia de ligação de entidade com direitos para executar ações. Use para evitar login de sessão via "az login". Se forem fornecidos tanto uma entidade, cadeia de ligação como o nome, a cadeia de ligação tem prioridade. Obrigatório se --dps-name não for fornecido ou se os argumentos authenticaton e --id-scope não forem fornecidos.

Propriedade Valor
Grupo de parâmetros: DPS Identifier Arguments
--pass --passphrase

Frase de acesso para a chave privada X.509. Válido apenas com --certificate-file-path e --key-file-path.

Propriedade Valor
Grupo de parâmetros: x509 Authentication Arguments
--payload

Payload de registo como objeto JSON ou caminho para um ficheiro JSON.

--resource-group -g

Nome do grupo de recursos. Você pode configurar o grupo padrão usando az configure --defaults group=<name>.

--storage-root-key

Campo de pedido TPM avançado mantido pelo esquema de serviço. Deve ser usado com --chave-endosso. A autenticação do cliente apenas TPM não é suportada por este comando.

Propriedade Valor
Grupo de parâmetros: TPM Arguments
--timeout

Tempo de espera positivo para o registo REST duro inteiro em segundos, incluindo arranque do trabalhador, HTTP e polling. Exclui o âmbito preliminar de identificação e a descoberta de credenciais bootstrap.

Parâmetros de Globais
--debug

Aumente a verbosidade do log para mostrar todos os logs de depuração.

Propriedade Valor
Valor predefinido: False
--help -h

Mostrar esta mensagem de ajuda e sair.

--only-show-errors

Mostrar apenas erros, suprimindo avisos.

Propriedade Valor
Valor predefinido: False
--output -o

Formato de saída.

Propriedade Valor
Valor predefinido: json
Valores aceites: json, jsonc, none, table, tsv, yaml, yamlc
--query

Cadeia de caracteres de consulta JMESPath. Consulte http://jmespath.org/ para obter mais informações e exemplos.

--subscription

Nome ou ID da subscrição. Você pode configurar a assinatura padrão usando az account set -s NAME_OR_ID.

--verbose

Aumente a verbosidade do registro. Use --debug para logs de depuração completos.

Propriedade Valor
Valor predefinido: False

az iot device registration operation-status

Pré-visualizar

O grupo de comandos 'iot device registration' está em pré-visualização e em desenvolvimento. Níveis de referência e de apoio: https://aka.ms/CLI_refstatus

Mostrar o estado de uma operação de registo de dispositivo DPS.

Fornece o ID da operação devolvido pelo DPS ou reportado por criar após um timeout. Reutilizar o ID de registo, o âmbito do ID (ou nome DPS), provisionando a autenticação do host e do dispositivo a partir da criação. Isto é um estado lido, não um novo registo.

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]

Exemplos

Siga uma inscrição individual com pesquisa de chave bootstrap

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

Siga um membro do grupo com a mesma chave de grupo e anfitrião de provisionamento

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

Siga uma operação aceite após um período de pausa sem submeter novamente o registo

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

Parâmetros Obrigatórios

--operation-id

Identificador de operação de registo devolvido por create.

--registration-id --rid

ID de registo do dispositivo ou ID de inscrição individual.

Parâmetros Opcionais

Os seguintes parâmetros são opcionais, mas dependendo do contexto, um ou mais podem tornar-se necessários para que o comando seja executado com êxito.

--acquire-policy-token

Aquisição automática de um token Azure Policy para esta operação de recurso.

Propriedade Valor
Grupo de parâmetros: Global Policy Arguments
--auth-type

Indica se a operação deve derivar automaticamente uma chave de política ou usar a sessão atual do Azure AD. Se o tipo de autenticação for login e o nome de host do recurso for fornecido, a pesquisa de recursos será ignorada, a menos que necessário. Você pode configurar o padrão usando az configure --defaults iothub-data-auth-type={auth-type-value}.

Propriedade Valor
Grupo de parâmetros: Access Control Arguments
Valor predefinido: key
Valores aceites: key, login
--certificate-file-path --cp

Caminho para o arquivo PEM do certificado. Necessário para registros x509.

Propriedade Valor
Grupo de parâmetros: x509 Authentication Arguments
--change-reference

O ID de referência de alteração relacionado para esta operação de recurso.

Propriedade Valor
Grupo de parâmetros: Global Policy Arguments
--ck --compute-key

Calcule a chave por dispositivo a partir de --simétrica-chave, ou a partir da chave do grupo de registo resolvida por --group-id com --dps-name/--login. Não pode ser combinado com entradas X.509.

Propriedade Valor
Grupo de parâmetros: Symmetric Key Authentication Arguments
Valor predefinido: False
--dps-name -n

Nome do Azure IoT Zoom Device Provisioning Service. Obrigatório se --login não for fornecido ou se os argumentos authenticaton e --id-scope não forem fornecidos.

Propriedade Valor
Grupo de parâmetros: DPS Identifier Arguments
--enrollment-group-id --gid --group-id

ID do grupo de inscrição. Só é necessário recuperar argumentos de autenticação.

--host --provisioning-host

Endpoint do dispositivo DPS. Quando omitido, o endpoint é derivado do recurso DPS selecionado e depois regressa ao endpoint global.

--id-scope --scope

ID âmbito do Azure IoT Zoom Device Provisioning Service. O âmbito do ID não identifica o endpoint do dispositivo: --dps-name ou --login ainda é resolvido quando fornecido. Com apenas --id-scope e credenciais explícitas do dispositivo, utiliza-se a alternativa global de endpoint documentada.

Propriedade Valor
Grupo de parâmetros: DPS Identifier Arguments
--key --symmetric-key

A chave de acesso compartilhada simétrica para o registro do dispositivo.

Propriedade Valor
Grupo de parâmetros: Symmetric Key Authentication Arguments
--key-file-path --kp

Caminho para o arquivo PEM chave. Necessário para registros x509.

Propriedade Valor
Grupo de parâmetros: x509 Authentication Arguments
--login -l

Este comando suporta uma cadeia de ligação de entidade com direitos para executar ações. Use para evitar login de sessão via "az login". Se forem fornecidos tanto uma entidade, cadeia de ligação como o nome, a cadeia de ligação tem prioridade. Obrigatório se --dps-name não for fornecido ou se os argumentos authenticaton e --id-scope não forem fornecidos.

Propriedade Valor
Grupo de parâmetros: DPS Identifier Arguments
--pass --passphrase

Frase de acesso para a chave privada X.509. Válido apenas com --certificate-file-path e --key-file-path.

Propriedade Valor
Grupo de parâmetros: x509 Authentication Arguments
--resource-group -g

Nome do grupo de recursos. Você pode configurar o grupo padrão usando az configure --defaults group=<name>.

Parâmetros de Globais
--debug

Aumente a verbosidade do log para mostrar todos os logs de depuração.

Propriedade Valor
Valor predefinido: False
--help -h

Mostrar esta mensagem de ajuda e sair.

--only-show-errors

Mostrar apenas erros, suprimindo avisos.

Propriedade Valor
Valor predefinido: False
--output -o

Formato de saída.

Propriedade Valor
Valor predefinido: json
Valores aceites: json, jsonc, none, table, tsv, yaml, yamlc
--query

Cadeia de caracteres de consulta JMESPath. Consulte http://jmespath.org/ para obter mais informações e exemplos.

--subscription

Nome ou ID da subscrição. Você pode configurar a assinatura padrão usando az account set -s NAME_OR_ID.

--verbose

Aumente a verbosidade do registro. Use --debug para logs de depuração completos.

Propriedade Valor
Valor predefinido: False