你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。

az iot device registration

Note

此参考是Azure CLI的 azure-iot 扩展的一部分(版本 2.73.0 或更高版本)。 该扩展将在首次运行 az iot device registration 命令时自动安装。 了解更多关于扩展的信息。

此命令组处于预览状态,正在开发中。 参考和支持级别:https://aka.ms/CLI_refstatus

通过Azure IoT 中心设备预配服务(DPS)注册设备。

对单个或组注册使用创建,然后按照接受的注册操作状态进行操作。 使用对称密钥或 X.509 证书对设备进行身份验证。 服务注册记录和注册状态管理仍在进行中 az iot dps。

命令

名称 说明 类型 Status
az iot device registration create

注册设备并选择性地颁发其操作证书。

Extension Preview
az iot device registration operation-status

显示 DPS 设备注册操作的状态。

Extension Preview

az iot device registration create

预览

命令组“iot 设备注册”处于预览状态,正在开发中。 参考和支持级别:https://aka.ms/CLI_refstatus

注册设备并选择性地颁发其操作证书。

对于单个注册,请提供其设备 --symmetric-key。 对于组注册,请使用 --compute-key 提供组密钥,或者提供已派生的设备密钥,而不提供 --compute-key。 或者,将 --dps-name 与 --auth-type 登录名配合使用来发现 ID 范围/终结点并检索注册密钥;为组注册添加 --group-id 和 --compute-key。 Entra 登录名授权此启动查找,而不是设备注册请求。

使用具有显式设备凭据的 --id-scope 跳过 DPS 资源发现。 使用非默认预配终结点时设置 --host。 对于 X.509 身份验证,请提供 --certificate-file-path 和 --key-file-path;仅当私钥已加密时,才添加 --passphrase。

添加 --csr (alias --csr-file-path)以请求操作证书。 它接受 PEM 或 base64 DER PKCS #10、内联或来自文件。 CSR 签名必须有效,其公用名必须与 --registration-id 匹配。CSR 不会替换设备的对称密钥或 X.509 身份验证。

该命令轮询接受的注册,并遵循重试后。 如果在收到操作 ID 后超时,请使用具有该 ID 的操作状态以及相同的注册 ID、ID 范围、终结点和设备身份验证。 超时不会取消后端操作;不要盲目重新运行创建。 --timeout 对 CSR 和非 CSR 注册(包括辅助角色启动、HTTP 重试和轮询)在初步 ID 范围和启动凭据发现之后的同一 REST 流应用硬截止时间。 如果没有 --timeout,则保留现有的有限五分钟轮询行为。

当 DPS 返回时,JSON 输出将保留 issuedCertificateChain 和 connectionProfile,以及注册表设备相关性的 registryDeviceExternalId。 2026-11-02-preview RegisterDeviceAndIssueCertificate 协定仅将 issuedCertificateChain 描述为字节数组,并且不定义其线路编码或证书顺序。 因此,此命令在 JSON 输出中保留该字段,但不提供证书文件输出选项;编写猜测的链可能会生成非 TLS 就绪或错误排序的捆绑包。 --endorsement-key 和 --storage-root-key 保留为高级请求架构字段,但明确不支持仅 TPM 身份验证,因为此协定不提供客户端 TPM 质询协议。

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]

示例

使用 Entra 授权的启动密钥查找注册单个注册

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

使用 Entra 授权的启动密钥查找注册组成员

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

使用设备密钥和已知 ID 范围注册,而无需启动查找

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

从注册组密钥派生设备密钥并注册

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

从 PEM CSR 注册和请求操作证书

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

使用 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

必需参数

--registration-id --rid

设备注册 ID 或单个注册 ID。

可选参数

以下参数是可选的,但根据上下文,命令可能需要一个或多个参数才能成功执行。

--acquire-policy-token

为此资源操作自动获取Azure Policy令牌。

属性 值
参数组: Global Policy Arguments
--auth-type

指示操作是否应自动派生策略密钥或使用当前Azure AD 会话。 如果身份验证类型为登录,并且提供资源主机名,则除非需要,否则将跳过资源查找。可以使用 < a0/a0> 配置默认值 az configure --defaults iothub-data-auth-type={auth-type-value}。

属性 值
参数组: Access Control Arguments
默认值: key
接受的值: key, login
--certificate-file-path --cp

证书 PEM 文件的路径。 x509 注册所必需的。

属性 值
参数组: x509 Authentication Arguments
--change-reference

此资源操作的相关更改引用 ID。

属性 值
参数组: Global Policy Arguments
--ck --compute-key

通过 --symmetric-key 或通过 --dps-name/--login 解析的注册组密钥计算每设备密钥。 不能与 X.509 输入组合。

属性 值
参数组: Symmetric Key Authentication Arguments
默认值: False
--csr --csr-file-path

内联 PEM/base64 DER PKCS #10 CSR 或 CSR 文件的路径。 其签名必须有效,公用名必须与注册 ID 匹配。 请求发送没有 PEM 标头的 base64 DER。

属性 值
参数组: Certificate Issuance Arguments
--dps-name -n

Azure IoT 中心设备预配服务的名称。 如果未提供 --login 或 authenticaton 参数且未提供 --id-scope,则是必需的。

属性 值
参数组: DPS Identifier Arguments
--endorsement-key

服务架构保留的高级 TPM 请求字段。 必须与 --storage-root-key 一起使用。 此命令不支持仅 TPM 客户端身份验证。

属性 值
参数组: TPM Arguments
--enrollment-group-id --gid --group-id

注册组 ID。 仅需要检索身份验证参数。

--host --provisioning-host

DPS 设备终结点。 省略时,终结点派生自所选 DPS 资源,然后回退到全局终结点。

--id-scope --scope

Azure IoT 中心设备预配服务的 ID 范围。 ID 范围不标识设备终结点:提供时仍会解析 --dps-name 或 --login。 仅使用 --id 范围和显式设备凭据,将使用记录的全局终结点回退。

属性 值
参数组: DPS Identifier Arguments
--key --symmetric-key

用于设备注册的对称共享访问密钥。

属性 值
参数组: Symmetric Key Authentication Arguments
--key-file-path --kp

密钥 PEM 文件的路径。 x509 注册所必需的。

属性 值
参数组: x509 Authentication Arguments
--login -l

此命令支持具有执行操作权限的实体连接字符串。 用于避免通过“az login”进行会话登录。 如果提供了实体连接字符串和名称,则连接字符串优先。 如果未提供 --dps-name 或 authenticaton 参数,并且未提供 --id-scope,则是必需的。

属性 值
参数组: DPS Identifier Arguments
--pass --passphrase

X.509 私钥的通行短语。 仅对 --certificate-file-path 和 --key-file-path 有效。

属性 值
参数组: x509 Authentication Arguments
--payload

将有效负载注册为 JSON 对象或 JSON 文件的路径。

--resource-group -g

资源组的名称。 可以使用 az configure --defaults group=<name>配置默认组。

--storage-root-key

服务架构保留的高级 TPM 请求字段。 必须与 --endorsement-key 一起使用。 此命令不支持仅 TPM 客户端身份验证。

属性 值
参数组: TPM Arguments
--timeout

正整数硬 REST 注册超时(以秒为单位,包括辅助角色启动、HTTP 和轮询)。 排除初步 ID 范围和启动凭据发现。

全局参数
--debug

提高日志记录详细程度以显示所有调试日志。

属性 值
默认值: False
--help -h

显示此帮助消息并退出。

--only-show-errors

仅显示错误,禁止显示警告。

属性 值
默认值: False
--output -o

输出格式。

属性 值
默认值: json
接受的值: json, jsonc, none, table, tsv, yaml, yamlc
--query

JMESPath 查询字符串。 有关更多信息和示例,请参阅 http://jmespath.org/。

--subscription

订阅的名称或 ID。 可以使用 az account set -s NAME_OR_ID 配置默认订阅。

--verbose

增加日志记录详细程度。 使用 --debug 获取完整的调试日志。

属性 值
默认值: False

az iot device registration operation-status

预览

命令组“iot 设备注册”处于预览状态,正在开发中。 参考和支持级别:https://aka.ms/CLI_refstatus

显示 DPS 设备注册操作的状态。

提供 DPS 返回的操作 ID,或在超时后创建报告。 重复使用注册 ID、ID 范围(或 DPS 名称),从创建中预配主机和设备身份验证。 这是已读状态,而不是新注册。

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]

示例

使用启动密钥查找跟踪单个注册

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

遵循具有相同组密钥和预配主机的组成员

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

在超时后遵循接受的操作,无需重新提交注册

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

必需参数

--operation-id

创建返回的注册操作标识符。

--registration-id --rid

设备注册 ID 或单个注册 ID。

可选参数

以下参数是可选的,但根据上下文,命令可能需要一个或多个参数才能成功执行。

--acquire-policy-token

为此资源操作自动获取Azure Policy令牌。

属性 值
参数组: Global Policy Arguments
--auth-type

指示操作是否应自动派生策略密钥或使用当前Azure AD 会话。 如果身份验证类型为登录,并且提供资源主机名,则除非需要,否则将跳过资源查找。可以使用 < a0/a0> 配置默认值 az configure --defaults iothub-data-auth-type={auth-type-value}。

属性 值
参数组: Access Control Arguments
默认值: key
接受的值: key, login
--certificate-file-path --cp

证书 PEM 文件的路径。 x509 注册所必需的。

属性 值
参数组: x509 Authentication Arguments
--change-reference

此资源操作的相关更改引用 ID。

属性 值
参数组: Global Policy Arguments
--ck --compute-key

通过 --symmetric-key 或通过 --dps-name/--login 解析的注册组密钥计算每设备密钥。 不能与 X.509 输入组合。

属性 值
参数组: Symmetric Key Authentication Arguments
默认值: False
--dps-name -n

Azure IoT 中心设备预配服务的名称。 如果未提供 --login 或 authenticaton 参数且未提供 --id-scope,则是必需的。

属性 值
参数组: DPS Identifier Arguments
--enrollment-group-id --gid --group-id

注册组 ID。 仅需要检索身份验证参数。

--host --provisioning-host

DPS 设备终结点。 省略时,终结点派生自所选 DPS 资源,然后回退到全局终结点。

--id-scope --scope

Azure IoT 中心设备预配服务的 ID 范围。 ID 范围不标识设备终结点:提供时仍会解析 --dps-name 或 --login。 仅使用 --id 范围和显式设备凭据,将使用记录的全局终结点回退。

属性 值
参数组: DPS Identifier Arguments
--key --symmetric-key

用于设备注册的对称共享访问密钥。

属性 值
参数组: Symmetric Key Authentication Arguments
--key-file-path --kp

密钥 PEM 文件的路径。 x509 注册所必需的。

属性 值
参数组: x509 Authentication Arguments
--login -l

此命令支持具有执行操作权限的实体连接字符串。 用于避免通过“az login”进行会话登录。 如果提供了实体连接字符串和名称,则连接字符串优先。 如果未提供 --dps-name 或 authenticaton 参数,并且未提供 --id-scope,则是必需的。

属性 值
参数组: DPS Identifier Arguments
--pass --passphrase

X.509 私钥的通行短语。 仅对 --certificate-file-path 和 --key-file-path 有效。

属性 值
参数组: x509 Authentication Arguments
--resource-group -g

资源组的名称。 可以使用 az configure --defaults group=<name>配置默认组。

全局参数
--debug

提高日志记录详细程度以显示所有调试日志。

属性 值
默认值: False
--help -h

显示此帮助消息并退出。

--only-show-errors

仅显示错误,禁止显示警告。

属性 值
默认值: False
--output -o

输出格式。

属性 值
默认值: json
接受的值: json, jsonc, none, table, tsv, yaml, yamlc
--query

JMESPath 查询字符串。 有关更多信息和示例,请参阅 http://jmespath.org/。

--subscription

订阅的名称或 ID。 可以使用 az account set -s NAME_OR_ID 配置默认订阅。

--verbose

增加日志记录详细程度。 使用 --debug 获取完整的调试日志。

属性 值
默认值: False