az iot device registration

  • Vista previa

Note

Esta referencia forma parte de la extensión azure-iot para el CLI de Azure (versión 2.73.0 o posterior). La extensión instalará automáticamente la primera vez que ejecute un comando az iot device registration. Obtenga más información sobre las extensiones.

Este grupo de comandos está en versión preliminar y en desarrollo. Niveles de referencia y soporte técnico: https://aka.ms/CLI_refstatus

Registre un dispositivo a través de Azure IoT Hub Device Provisioning Service (DPS).

Use create para una inscripción individual o de grupo y, a continuación, operation-status para seguir un registro aceptado. Autentique el dispositivo con su clave simétrica o un certificado X.509. Los registros de inscripción de servicio y la administración del estado de registro permanecen en az iot dps.

Comandos

Nombre Description Tipo Estado
az iot device registration create

Registre un dispositivo y, opcionalmente, emita su certificado operativo.

 Extension Preview
az iot device registration operation-status

Muestra el estado de una operación de registro de dispositivos DPS.

 Extension Preview

az iot device registration create

Vista previa

El grupo de comandos "iot device registration" está en versión preliminar y en desarrollo. Niveles de referencia y soporte técnico: https://aka.ms/CLI_refstatus

Registre un dispositivo y, opcionalmente, emita su certificado operativo.

Para una inscripción individual, proporcione su dispositivo --symmetric-key. Para una inscripción de grupo, proporcione la clave de grupo con --compute-key o proporcione una clave de dispositivo ya derivada sin --compute-key. Como alternativa, use --dps-name con el inicio de sesión --auth-type para detectar el ámbito o el punto de conexión de identificador y recuperar las claves de inscripción; agregue --group-id y --compute-key para una inscripción de grupo. Entra login autoriza esta búsqueda de arranque, no la solicitud de registro del dispositivo.

Use --id-scope con credenciales de dispositivo explícitas para omitir la detección de recursos de DPS. Establezca --host al usar un punto de conexión de aprovisionamiento no predeterminado. Para la autenticación X.509, proporcione --certificate-file-path y --key-file-path; agregue la frase de contraseña --passphrase solo si la clave privada está cifrada.

Agregue --csr (alias --csr-file-path) para solicitar un certificado operativo. Acepta PEM o BASE64 PKCS #10, insertado o desde un archivo. La firma CSR debe ser válida y su nombre común debe coincidir con --registration-id. Una CSR no reemplaza la clave simétrica del dispositivo ni la autenticación X.509.

El comando sondea los registros aceptados y respeta Retry-After. Si agota el tiempo de espera después de recibir un identificador de operación, use el estado de la operación con ese identificador y el mismo identificador de registro, ámbito de identificador, punto de conexión y autenticación del dispositivo. Un tiempo de espera no cancela la operación de back-end; no vuelva a ejecutar ciegamente la creación. --timeout aplica una fecha límite dura al mismo flujo de REST para el registro csr y no CSR, incluido el inicio de trabajo, los reintentos HTTP y el sondeo, después del ámbito de identificador preliminar y la detección de credenciales de arranque. Sin --timeout, se conserva el comportamiento de sondeo de cinco minutos limitado existente.

La salida JSON conserva issuedCertificateChain y connectionProfile cuando DPS los devuelve, además de registryDeviceExternalId para la correlación del dispositivo del Registro. El contrato RegisterDeviceAndIssueCertificate issuedCertificate 2026-11-02-preview describe issuedCertificateChain solo como una matriz de bytes y no define su orden de codificación o certificado de conexión. Por lo tanto, este comando conserva ese campo en la salida JSON, pero no ofrece una opción de salida de archivo de certificado; escribir una cadena adivinada podría producir un paquete no preparado para TLS o ordenado incorrectamente. --endorsement-key y --storage-root-key se conservan como campos avanzados de esquema de solicitud, pero la autenticación solo de TPM no se admite explícitamente porque este contrato no proporciona ningún protocolo de desafío de TPM de 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]

Ejemplos

Registro de una inscripción individual mediante la búsqueda de claves de arranque autorizadas por Entra

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

Registro de un miembro del grupo mediante la búsqueda de claves de arranque autorizadas por Entra

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

Registro con una clave de dispositivo y un ámbito de identificador conocido, sin búsqueda de arranque

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

Derivar una clave de dispositivo de una clave de grupo de inscripción y registrarla

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

Registro y solicitud de un certificado operativo de un CSR de PEM

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

Registro con un 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 requeridos

--registration-id --rid

Identificador de registro de dispositivo o identificador de inscripción individual.

Parámetros opcionales

Los parámetros siguientes son opcionales, pero dependiendo del contexto, es posible que se requiera uno o varios para que el comando se ejecute correctamente.

--acquire-policy-token

Adquirir un token de Azure Policy automáticamente para esta operación de recursos.

Propiedad Valor
Grupo de parámetros: Global Policy Arguments
--auth-type

Indica si la operación debe derivar automáticamente una clave de directiva o usar la sesión de Azure AD actual. Si el tipo de autenticación es login y se proporciona el nombre de host del recurso, se omitirá la búsqueda de recursos a menos que sea necesario. Puede configurar el valor predeterminado mediante az configure --defaults iothub-data-auth-type={auth-type-value}.

Propiedad Valor
Grupo de parámetros: Access Control Arguments
Valor predeterminado: key
Valores aceptados: key, login
--certificate-file-path --cp

Ruta de acceso al archivo PEM de certificado. Necesario para los registros x509.

Propiedad Valor
Grupo de parámetros: x509 Authentication Arguments
--change-reference

Identificador de referencia de cambio relacionado para esta operación de recurso.

Propiedad Valor
Grupo de parámetros: Global Policy Arguments
--ck --compute-key

Calcule la clave por dispositivo desde --symmetric-key o desde la clave enrollment-group resuelta por --group-id con --dps-name/--login. No se puede combinar con entradas X.509.

Propiedad Valor
Grupo de parámetros: Symmetric Key Authentication Arguments
Valor predeterminado: False
--csr --csr-file-path

PEM/base64 DER PKCS #10 CSR insertado o ruta de acceso a un archivo CSR. Su firma debe ser válida y El nombre común debe coincidir con el identificador de registro. La solicitud envía DER base64 sin encabezados PEM.

Propiedad Valor
Grupo de parámetros: Certificate Issuance Arguments
--dps-name -n

Nombre del servicio Azure IoT Hub Device Provisioning. Obligatorio si --login no se proporciona o no se proporcionan argumentos authenticaton y no se proporciona el ámbito --id-scope.

Propiedad Valor
Grupo de parámetros: DPS Identifier Arguments
--endorsement-key

Campo de solicitud de TPM avanzado retenido por el esquema de servicio. Debe usarse con --storage-root-key. Este comando no admite la autenticación de cliente solo de TPM.

Propiedad Valor
Grupo de parámetros: TPM Arguments
--enrollment-group-id --gid --group-id

Identificador del grupo de inscripción. Solo es necesario para recuperar argumentos de autenticación.

--host --provisioning-host

Punto de conexión del dispositivo DPS. Cuando se omite, el punto de conexión se deriva del recurso de DPS seleccionado y, a continuación, vuelve al punto de conexión global.

--id-scope --scope

Ámbito de identificador del servicio Azure IoT Hub Device Provisioning. El ámbito de identificador no identifica un punto de conexión de dispositivo: --dps-name o --login todavía se resuelve cuando se proporciona. Con solo las credenciales de dispositivo --id-scope y explícitas, se usa la reserva del punto de conexión global documentado.

Propiedad Valor
Grupo de parámetros: DPS Identifier Arguments
--key --symmetric-key

Clave de acceso compartido simétrica para el registro del dispositivo.

Propiedad Valor
Grupo de parámetros: Symmetric Key Authentication Arguments
--key-file-path --kp

Ruta de acceso al archivo PEM de clave. Necesario para los registros x509.

Propiedad Valor
Grupo de parámetros: x509 Authentication Arguments
--login -l

Este comando admite una entidad cadena de conexión con derechos para realizar la acción. Use para evitar el inicio de sesión de sesión a través de "az login". Si se proporciona un cadena de conexión de entidad y un nombre, el cadena de conexión tiene prioridad. Obligatorio si no se proporcionan argumentos --dps-name o authenticaton y --id-scope no se proporcionan.

Propiedad Valor
Grupo de parámetros: DPS Identifier Arguments
--pass --passphrase

Frase de contraseña para la clave privada X.509. Válido solo con --certificate-file-path y --key-file-path.

Propiedad Valor
Grupo de parámetros: x509 Authentication Arguments
--payload

Carga de registro como un objeto JSON o ruta de acceso a un archivo JSON.

--resource-group -g

Nombre del grupo de recursos. Puede configurar el grupo predeterminado mediante az configure --defaults group=<name>.

--storage-root-key

Campo de solicitud de TPM avanzado retenido por el esquema de servicio. Debe usarse con --endorsement-key. Este comando no admite la autenticación de cliente solo de TPM.

Propiedad Valor
Grupo de parámetros: TPM Arguments
--timeout

Tiempo de espera de registro rest entero positivo en segundos, incluido el inicio del trabajo, HTTP y sondeo. Excluye el ámbito de identificador preliminar y la detección de credenciales de arranque.

Parámetros globales
--debug

Aumente el nivel de detalle del registro para mostrar todos los registros de depuración.

Propiedad Valor
Valor predeterminado: False
--help -h

Mostrar este mensaje de ayuda y salir.

--only-show-errors

Solo se muestran errores, suprimiendo advertencias.

Propiedad Valor
Valor predeterminado: False
--output -o

Formato de salida.

Propiedad Valor
Valor predeterminado: json
Valores aceptados: json, jsonc, none, table, tsv, yaml, yamlc
--query

Cadena de consulta JMESPath. Consulte http://jmespath.org/ para obtener más información y ejemplos.

--subscription

Nombre o identificador de la suscripción. Puede configurar la suscripción predeterminada mediante az account set -s NAME_OR_ID.

--verbose

Aumente el nivel de detalle del registro. Usa --debug para ver registros de depuración completos.

Propiedad Valor
Valor predeterminado: False

az iot device registration operation-status

Vista previa

El grupo de comandos "iot device registration" está en versión preliminar y en desarrollo. Niveles de referencia y soporte técnico: https://aka.ms/CLI_refstatus

Muestra el estado de una operación de registro de dispositivos DPS.

Proporcione el identificador de operación devuelto por DPS o notificado por la creación después de un tiempo de espera. Vuelva a usar el identificador de registro, el ámbito de identificador (o el nombre de DPS), el aprovisionamiento del host y la autenticación de dispositivos a partir de la creación. Se trata de una lectura de estado, no de un nuevo 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]

Ejemplos

Seguimiento de una inscripción individual con búsqueda de claves de arranque

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

Siga un miembro del grupo con la misma clave de grupo y el mismo host de aprovisionamiento.

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 una operación aceptada después de un tiempo de espera sin volver a enviar el registro

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

Parámetros requeridos

--operation-id

Identificador de operación de registro devuelto por create.

--registration-id --rid

Identificador de registro de dispositivo o identificador de inscripción individual.

Parámetros opcionales

Los parámetros siguientes son opcionales, pero dependiendo del contexto, es posible que se requiera uno o varios para que el comando se ejecute correctamente.

--acquire-policy-token

Adquirir un token de Azure Policy automáticamente para esta operación de recursos.

Propiedad Valor
Grupo de parámetros: Global Policy Arguments
--auth-type

Indica si la operación debe derivar automáticamente una clave de directiva o usar la sesión de Azure AD actual. Si el tipo de autenticación es login y se proporciona el nombre de host del recurso, se omitirá la búsqueda de recursos a menos que sea necesario. Puede configurar el valor predeterminado mediante az configure --defaults iothub-data-auth-type={auth-type-value}.

Propiedad Valor
Grupo de parámetros: Access Control Arguments
Valor predeterminado: key
Valores aceptados: key, login
--certificate-file-path --cp

Ruta de acceso al archivo PEM de certificado. Necesario para los registros x509.

Propiedad Valor
Grupo de parámetros: x509 Authentication Arguments
--change-reference

Identificador de referencia de cambio relacionado para esta operación de recurso.

Propiedad Valor
Grupo de parámetros: Global Policy Arguments
--ck --compute-key

Calcule la clave por dispositivo desde --symmetric-key o desde la clave enrollment-group resuelta por --group-id con --dps-name/--login. No se puede combinar con entradas X.509.

Propiedad Valor
Grupo de parámetros: Symmetric Key Authentication Arguments
Valor predeterminado: False
--dps-name -n

Nombre del servicio Azure IoT Hub Device Provisioning. Obligatorio si --login no se proporciona o no se proporcionan argumentos authenticaton y no se proporciona el ámbito --id-scope.

Propiedad Valor
Grupo de parámetros: DPS Identifier Arguments
--enrollment-group-id --gid --group-id

Identificador del grupo de inscripción. Solo es necesario para recuperar argumentos de autenticación.

--host --provisioning-host

Punto de conexión del dispositivo DPS. Cuando se omite, el punto de conexión se deriva del recurso de DPS seleccionado y, a continuación, vuelve al punto de conexión global.

--id-scope --scope

Ámbito de identificador del servicio Azure IoT Hub Device Provisioning. El ámbito de identificador no identifica un punto de conexión de dispositivo: --dps-name o --login todavía se resuelve cuando se proporciona. Con solo las credenciales de dispositivo --id-scope y explícitas, se usa la reserva del punto de conexión global documentado.

Propiedad Valor
Grupo de parámetros: DPS Identifier Arguments
--key --symmetric-key

Clave de acceso compartido simétrica para el registro del dispositivo.

Propiedad Valor
Grupo de parámetros: Symmetric Key Authentication Arguments
--key-file-path --kp

Ruta de acceso al archivo PEM de clave. Necesario para los registros x509.

Propiedad Valor
Grupo de parámetros: x509 Authentication Arguments
--login -l

Este comando admite una entidad cadena de conexión con derechos para realizar la acción. Use para evitar el inicio de sesión de sesión a través de "az login". Si se proporciona un cadena de conexión de entidad y un nombre, el cadena de conexión tiene prioridad. Obligatorio si no se proporcionan argumentos --dps-name o authenticaton y --id-scope no se proporcionan.

Propiedad Valor
Grupo de parámetros: DPS Identifier Arguments
--pass --passphrase

Frase de contraseña para la clave privada X.509. Válido solo con --certificate-file-path y --key-file-path.

Propiedad Valor
Grupo de parámetros: x509 Authentication Arguments
--resource-group -g

Nombre del grupo de recursos. Puede configurar el grupo predeterminado mediante az configure --defaults group=<name>.

Parámetros globales
--debug

Aumente el nivel de detalle del registro para mostrar todos los registros de depuración.

Propiedad Valor
Valor predeterminado: False
--help -h

Mostrar este mensaje de ayuda y salir.

--only-show-errors

Solo se muestran errores, suprimiendo advertencias.

Propiedad Valor
Valor predeterminado: False
--output -o

Formato de salida.

Propiedad Valor
Valor predeterminado: json
Valores aceptados: json, jsonc, none, table, tsv, yaml, yamlc
--query

Cadena de consulta JMESPath. Consulte http://jmespath.org/ para obtener más información y ejemplos.

--subscription

Nombre o identificador de la suscripción. Puede configurar la suscripción predeterminada mediante az account set -s NAME_OR_ID.

--verbose

Aumente el nivel de detalle del registro. Usa --debug para ver registros de depuración completos.

Propiedad Valor
Valor predeterminado: False