az iot device registration

  • Versão Prévia

Note

Essa referência faz parte da extensão azure-iot para o CLI do Azure (versão 2.73.0 ou superior). A extensão instalará automaticamente na primeira vez que você executar um comando az iot device registration. Saiba mais sobre extensões.

Esse grupo de comandos está em versão prévia e em desenvolvimento. Níveis de referência e suporte: https://aka.ms/CLI_refstatus

Registre um dispositivo por meio do DPS (Serviço de Provisionamento de Dispositivos) Hub IoT do Azure.

Use criar para um registro individual ou de grupo e, em seguida, o status da operação para seguir um registro aceito. Autentique o dispositivo com sua chave simétrica ou um certificado X.509. Os registros de registro de serviço e a administração de estado de registro permanecem sob az iot dps.

Comandos

Nome Description Tipo Status
az iot device registration create

Registre um dispositivo e, opcionalmente, emita seu certificado operacional.

 Extension Preview
az iot device registration operation-status

Mostrar o status de uma operação de registro de dispositivo DPS.

 Extension Preview

az iot device registration create

Versão Prévia

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

Registre um dispositivo e, opcionalmente, emita seu certificado operacional.

Para um registro individual, forneça seu dispositivo --symmetric-key. Para um registro em grupo, forneça a chave de grupo com --compute-key ou forneça uma chave de dispositivo já derivada sem --compute-key. Como alternativa, use --dps-name com logon do tipo --auth para descobrir o escopo/ponto de extremidade da ID e recuperar chaves de registro; add --group-id and --compute-key for a group enrollment. O logon do Entra autoriza essa pesquisa de inicialização, não a solicitação de registro do dispositivo.

Use o escopo --id com credenciais de dispositivo explícitas para ignorar a descoberta de recursos do DPS. Defina --host ao usar um ponto de extremidade de provisionamento não padrão. Para autenticação X.509, forneça --certificate-file-path e --key-file-path; adicione --passphrase somente se a chave privada for criptografada.

Adicione --csr (alias --csr-file-path) para solicitar um certificado operacional. Ele aceita PEM ou base64 DER PKCS nº 10, embutido ou de um arquivo. A assinatura CSR deve ser válida e seu Nome Comum deve corresponder a --registration-id. Uma CSR não substitui a chave simétrica do dispositivo ou a autenticação X.509.

As pesquisas de comando aceitaram registros, respeitando Retry-After. Se ele atingir o tempo limite após receber uma ID de operação, use o status da operação com essa ID e a mesma ID de registro, escopo de ID, ponto de extremidade e autenticação de dispositivo. Um tempo limite não cancela a operação de back-end; não execute novamente a criação às cegas. --timeout aplica um prazo rígido ao mesmo fluxo REST para registro CSR e não CSR, incluindo inicialização de trabalho, repetições HTTP e sondagem, após a descoberta preliminar do escopo da ID e da credencial de inicialização. Sem --tempo limite, o comportamento de sondagem limitado existente de cinco minutos é mantido.

A saída JSON preserva issuedCertificateChain e connectionProfile quando o DPS os retorna, além de RegistryDeviceExternalId para correlação de dispositivo do Registro. O contrato RegisterDeviceAndIssueCertificate 2026-11-02-preview descreve issuedCertificateChain apenas como uma matriz de bytes e não define sua codificação de fio ou ordem de certificado. Consequentemente, esse comando preserva esse campo na saída JSON, mas não oferece uma opção de saída de arquivo de certificado; escrever uma cadeia adivinhada pode produzir um pacote não pronto para TLS ou ordenado incorretamente. --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]

Exemplos

Registrar um registro individual usando a pesquisa de chave de inicialização autorizada por Entra

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

Registrar um membro do grupo usando a pesquisa de chave de inicialização autorizada pelo Entra

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

Registrar-se com uma chave de dispositivo e um escopo de ID conhecido, sem pesquisa de inicialização

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

Derivar uma chave do dispositivo de uma chave de grupo de registro e registrar

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

Registrar e solicitar um certificado operacional de uma CSR PEM

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

Registrar-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 registro do dispositivo ou ID de registro individual.

Parâmetros Opcionais

Os seguintes parâmetros são opcionais, mas dependendo do contexto, um ou mais podem se tornar obrigatórios para que o comando seja executado com sucesso.

--acquire-policy-token

Adquirir um token Azure Policy automaticamente para essa 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 AD Azure. Se o tipo de autenticação for logon e o nome do host do recurso for fornecido, a pesquisa de recursos será ignorada, a menos que seja 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 padrão: key
Valores aceitos: 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

A ID de referência de alteração relacionada para esta operação de recurso.

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

Compute a chave por dispositivo de --symmetric-key ou da chave de grupo de registro resolvida por --group-id com --dps-name/--login. Não é possível combinar com entradas X.509.

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

PEM embutido/base64 DER PKCS #10 CSR ou caminho para um arquivo CSR. Sua assinatura deve ser válida e o Nome Comum deve corresponder à ID de registro. A solicitação envia o DER base64 sem cabeçalhos PEM.

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

Nome do serviço de provisionamento de dispositivo Hub IoT do Azure. Necessário se --login não for fornecido ou argumentos authenticaton e --id-scope não forem fornecidos.

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

Campo de solicitação TPM avançado retido pelo esquema de serviço. Deve ser usado com --storage-root-key. A autenticação de cliente somente TPM não tem suporte neste comando.

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

ID do grupo de registro. Necessário apenas para recuperar argumentos de autenticação.

--host --provisioning-host

Ponto de extremidade do dispositivo DPS. Quando omitido, o ponto de extremidade é derivado do recurso DPS selecionado e, em seguida, volta para o ponto de extremidade global.

--id-scope --scope

Escopo de ID do Serviço de Provisionamento de Dispositivos Hub IoT do Azure. O escopo da ID não identifica um ponto de extremidade do dispositivo: --dps-name ou --login ainda é resolvido quando fornecido. Com apenas o escopo da ID e as credenciais explícitas do dispositivo, o fallback do ponto de extremidade global documentado é usado.

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

A chave de acesso compartilhado 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 de chave. Necessário para registros x509.

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

Esse comando dá suporte a uma entidade cadeia de conexão com direitos para executar a ação. Use para evitar o logon da sessão por meio de "az login". Se uma entidade cadeia de conexão e um nome forem fornecidos, o cadeia de conexão será priorizado. Necessário se --dps-name não for fornecido ou argumentos authenticaton e --id-scope não forem fornecidos.

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

Frase secreta para a chave privada X.509. Válido somente com --certificate-file-path e --key-file-path.

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

Conteúdo de registro como um objeto JSON ou caminho para um arquivo 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 solicitação TPM avançado retido pelo esquema de serviço. Deve ser usado com --endorsement-key. A autenticação de cliente somente TPM não tem suporte neste comando.

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

Tempo limite de registro REST inteiro positivo em segundos, incluindo inicialização de trabalho, HTTP e sondagem. Exclui o escopo preliminar da ID e a descoberta de credenciais de inicialização.

Parâmetros Globais
--debug

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

Propriedade Valor
Valor padrão: False
--help -h

Mostre esta mensagem de ajuda e saia.

--only-show-errors

Mostrar apenas erros, suprimindo avisos.

Propriedade Valor
Valor padrão: False
--output -o

Formato de saída.

Propriedade Valor
Valor padrão: json
Valores aceitos: 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 assinatura. Você pode configurar a assinatura padrão usando az account set -s NAME_OR_ID.

--verbose

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

Propriedade Valor
Valor padrão: False

az iot device registration operation-status

Versão Prévia

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

Mostrar o status de uma operação de registro de dispositivo DPS.

Forneça a ID da operação retornada pelo DPS ou relatada pela criação após um tempo limite. Reutilize a ID de registro, o escopo da ID (ou o nome DPS), o host de provisionamento e a autenticação do dispositivo da criação. Este é um status lido, não um novo registro.

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

Seguir um registro individual com pesquisa de chave de inicialização

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 host 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 aceita após um tempo limite sem reenviar o registro

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 registro retornado pela criação.

--registration-id --rid

ID de registro do dispositivo ou ID de registro individual.

Parâmetros Opcionais

Os seguintes parâmetros são opcionais, mas dependendo do contexto, um ou mais podem se tornar obrigatórios para que o comando seja executado com sucesso.

--acquire-policy-token

Adquirir um token Azure Policy automaticamente para essa 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 AD Azure. Se o tipo de autenticação for logon e o nome do host do recurso for fornecido, a pesquisa de recursos será ignorada, a menos que seja 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 padrão: key
Valores aceitos: 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

A ID de referência de alteração relacionada para esta operação de recurso.

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

Compute a chave por dispositivo de --symmetric-key ou da chave de grupo de registro resolvida por --group-id com --dps-name/--login. Não é possível combinar com entradas X.509.

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

Nome do serviço de provisionamento de dispositivo Hub IoT do Azure. Necessário se --login não for fornecido ou 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 registro. Necessário apenas para recuperar argumentos de autenticação.

--host --provisioning-host

Ponto de extremidade do dispositivo DPS. Quando omitido, o ponto de extremidade é derivado do recurso DPS selecionado e, em seguida, volta para o ponto de extremidade global.

--id-scope --scope

Escopo de ID do Serviço de Provisionamento de Dispositivos Hub IoT do Azure. O escopo da ID não identifica um ponto de extremidade do dispositivo: --dps-name ou --login ainda é resolvido quando fornecido. Com apenas o escopo da ID e as credenciais explícitas do dispositivo, o fallback do ponto de extremidade global documentado é usado.

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

A chave de acesso compartilhado 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 de chave. Necessário para registros x509.

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

Esse comando dá suporte a uma entidade cadeia de conexão com direitos para executar a ação. Use para evitar o logon da sessão por meio de "az login". Se uma entidade cadeia de conexão e um nome forem fornecidos, o cadeia de conexão será priorizado. Necessário se --dps-name não for fornecido ou argumentos authenticaton e --id-scope não forem fornecidos.

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

Frase secreta para a chave privada X.509. Válido somente 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 Globais
--debug

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

Propriedade Valor
Valor padrão: False
--help -h

Mostre esta mensagem de ajuda e saia.

--only-show-errors

Mostrar apenas erros, suprimindo avisos.

Propriedade Valor
Valor padrão: False
--output -o

Formato de saída.

Propriedade Valor
Valor padrão: json
Valores aceitos: 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 assinatura. Você pode configurar a assinatura padrão usando az account set -s NAME_OR_ID.

--verbose

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

Propriedade Valor
Valor padrão: False