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
必需参数
设备注册 ID 或单个注册 ID。
可选参数
以下参数是可选的,但根据上下文,命令可能需要一个或多个参数才能成功执行。
为此资源操作自动获取Azure Policy令牌。
| 属性 | 值 |
|---|---|
| 参数组: | Global Policy Arguments |
指示操作是否应自动派生策略密钥或使用当前Azure AD 会话。 如果身份验证类型为登录,并且提供资源主机名,则除非需要,否则将跳过资源查找。可以使用 < a0/a0> 配置默认值 az configure --defaults iothub-data-auth-type={auth-type-value}。
| 属性 | 值 |
|---|---|
| 参数组: | Access Control Arguments |
| 默认值: | key |
| 接受的值: | key, login |
证书 PEM 文件的路径。 x509 注册所必需的。
| 属性 | 值 |
|---|---|
| 参数组: | x509 Authentication Arguments |
此资源操作的相关更改引用 ID。
| 属性 | 值 |
|---|---|
| 参数组: | Global Policy Arguments |
通过 --symmetric-key 或通过 --dps-name/--login 解析的注册组密钥计算每设备密钥。 不能与 X.509 输入组合。
| 属性 | 值 |
|---|---|
| 参数组: | Symmetric Key Authentication Arguments |
| 默认值: | False |
内联 PEM/base64 DER PKCS #10 CSR 或 CSR 文件的路径。 其签名必须有效,公用名必须与注册 ID 匹配。 请求发送没有 PEM 标头的 base64 DER。
| 属性 | 值 |
|---|---|
| 参数组: | Certificate Issuance Arguments |
Azure IoT 中心设备预配服务的名称。 如果未提供 --login 或 authenticaton 参数且未提供 --id-scope,则是必需的。
| 属性 | 值 |
|---|---|
| 参数组: | DPS Identifier Arguments |
服务架构保留的高级 TPM 请求字段。 必须与 --storage-root-key 一起使用。 此命令不支持仅 TPM 客户端身份验证。
| 属性 | 值 |
|---|---|
| 参数组: | TPM Arguments |
注册组 ID。 仅需要检索身份验证参数。
DPS 设备终结点。 省略时,终结点派生自所选 DPS 资源,然后回退到全局终结点。
Azure IoT 中心设备预配服务的 ID 范围。 ID 范围不标识设备终结点:提供时仍会解析 --dps-name 或 --login。 仅使用 --id 范围和显式设备凭据,将使用记录的全局终结点回退。
| 属性 | 值 |
|---|---|
| 参数组: | DPS Identifier Arguments |
用于设备注册的对称共享访问密钥。
| 属性 | 值 |
|---|---|
| 参数组: | Symmetric Key Authentication Arguments |
密钥 PEM 文件的路径。 x509 注册所必需的。
| 属性 | 值 |
|---|---|
| 参数组: | x509 Authentication Arguments |
此命令支持具有执行操作权限的实体连接字符串。 用于避免通过“az login”进行会话登录。 如果提供了实体连接字符串和名称,则连接字符串优先。 如果未提供 --dps-name 或 authenticaton 参数,并且未提供 --id-scope,则是必需的。
| 属性 | 值 |
|---|---|
| 参数组: | DPS Identifier Arguments |
X.509 私钥的通行短语。 仅对 --certificate-file-path 和 --key-file-path 有效。
| 属性 | 值 |
|---|---|
| 参数组: | x509 Authentication Arguments |
将有效负载注册为 JSON 对象或 JSON 文件的路径。
资源组的名称。 可以使用 az configure --defaults group=<name>配置默认组。
服务架构保留的高级 TPM 请求字段。 必须与 --endorsement-key 一起使用。 此命令不支持仅 TPM 客户端身份验证。
| 属性 | 值 |
|---|---|
| 参数组: | TPM Arguments |
正整数硬 REST 注册超时(以秒为单位,包括辅助角色启动、HTTP 和轮询)。 排除初步 ID 范围和启动凭据发现。
全局参数
提高日志记录详细程度以显示所有调试日志。
| 属性 | 值 |
|---|---|
| 默认值: | False |
显示此帮助消息并退出。
仅显示错误,禁止显示警告。
| 属性 | 值 |
|---|---|
| 默认值: | False |
输出格式。
| 属性 | 值 |
|---|---|
| 默认值: | json |
| 接受的值: | json, jsonc, none, table, tsv, yaml, yamlc |
JMESPath 查询字符串。 有关更多信息和示例,请参阅 http://jmespath.org/。
订阅的名称或 ID。 可以使用 az account set -s NAME_OR_ID 配置默认订阅。
增加日志记录详细程度。 使用 --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
必需参数
创建返回的注册操作标识符。
设备注册 ID 或单个注册 ID。
可选参数
以下参数是可选的,但根据上下文,命令可能需要一个或多个参数才能成功执行。
为此资源操作自动获取Azure Policy令牌。
| 属性 | 值 |
|---|---|
| 参数组: | Global Policy Arguments |
指示操作是否应自动派生策略密钥或使用当前Azure AD 会话。 如果身份验证类型为登录,并且提供资源主机名,则除非需要,否则将跳过资源查找。可以使用 < a0/a0> 配置默认值 az configure --defaults iothub-data-auth-type={auth-type-value}。
| 属性 | 值 |
|---|---|
| 参数组: | Access Control Arguments |
| 默认值: | key |
| 接受的值: | key, login |
证书 PEM 文件的路径。 x509 注册所必需的。
| 属性 | 值 |
|---|---|
| 参数组: | x509 Authentication Arguments |
此资源操作的相关更改引用 ID。
| 属性 | 值 |
|---|---|
| 参数组: | Global Policy Arguments |
通过 --symmetric-key 或通过 --dps-name/--login 解析的注册组密钥计算每设备密钥。 不能与 X.509 输入组合。
| 属性 | 值 |
|---|---|
| 参数组: | Symmetric Key Authentication Arguments |
| 默认值: | False |
Azure IoT 中心设备预配服务的名称。 如果未提供 --login 或 authenticaton 参数且未提供 --id-scope,则是必需的。
| 属性 | 值 |
|---|---|
| 参数组: | DPS Identifier Arguments |
注册组 ID。 仅需要检索身份验证参数。
DPS 设备终结点。 省略时,终结点派生自所选 DPS 资源,然后回退到全局终结点。
Azure IoT 中心设备预配服务的 ID 范围。 ID 范围不标识设备终结点:提供时仍会解析 --dps-name 或 --login。 仅使用 --id 范围和显式设备凭据,将使用记录的全局终结点回退。
| 属性 | 值 |
|---|---|
| 参数组: | DPS Identifier Arguments |
用于设备注册的对称共享访问密钥。
| 属性 | 值 |
|---|---|
| 参数组: | Symmetric Key Authentication Arguments |
密钥 PEM 文件的路径。 x509 注册所必需的。
| 属性 | 值 |
|---|---|
| 参数组: | x509 Authentication Arguments |
此命令支持具有执行操作权限的实体连接字符串。 用于避免通过“az login”进行会话登录。 如果提供了实体连接字符串和名称,则连接字符串优先。 如果未提供 --dps-name 或 authenticaton 参数,并且未提供 --id-scope,则是必需的。
| 属性 | 值 |
|---|---|
| 参数组: | DPS Identifier Arguments |
X.509 私钥的通行短语。 仅对 --certificate-file-path 和 --key-file-path 有效。
| 属性 | 值 |
|---|---|
| 参数组: | x509 Authentication Arguments |
资源组的名称。 可以使用 az configure --defaults group=<name>配置默认组。
全局参数
提高日志记录详细程度以显示所有调试日志。
| 属性 | 值 |
|---|---|
| 默认值: | False |
显示此帮助消息并退出。
仅显示错误,禁止显示警告。
| 属性 | 值 |
|---|---|
| 默认值: | False |
输出格式。
| 属性 | 值 |
|---|---|
| 默认值: | json |
| 接受的值: | json, jsonc, none, table, tsv, yaml, yamlc |
JMESPath 查询字符串。 有关更多信息和示例,请参阅 http://jmespath.org/。
订阅的名称或 ID。 可以使用 az account set -s NAME_OR_ID 配置默认订阅。
增加日志记录详细程度。 使用 --debug 获取完整的调试日志。
| 属性 | 值 |
|---|---|
| 默认值: | False |