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

az iot hub device-identity

注意

此参考是 Azure CLI (2.32.0 或更高版本) 的 azure-iot 扩展的一部分。 首次运行 az iot hub device-identity 命令时,该扩展将自动安装。 详细了解扩展。

管理 IoT 设备。

命令

az iot hub device-identity children

管理 IoT 边缘设备的子设备关系。

az iot hub device-identity children add

将设备作为子级添加到目标边缘设备。

az iot hub device-identity children list

输出分配的子设备的集合。

az iot hub device-identity children remove

从目标边缘设备中删除子设备。

az iot hub device-identity connection-string

管理 IoT 设备的连接字符串。

az iot hub device-identity connection-string show

显示给定IoT 中心设备连接字符串。

az iot hub device-identity create

在IoT 中心中创建设备。

az iot hub device-identity delete

删除IoT 中心设备。

az iot hub device-identity export

将所有设备标识从IoT 中心导出到 Azure 存储 Blob 容器。

az iot hub device-identity import

将设备标识从存储容器 Blob 导入到IoT 中心。

az iot hub device-identity list

列出IoT 中心中的设备。

az iot hub device-identity parent

管理 IoT 设备的父设备关系。

az iot hub device-identity parent set

设置目标设备的父设备。

az iot hub device-identity parent show

获取目标设备的父设备。

az iot hub device-identity renew-key

使用 sas 身份验证续订IoT 中心设备的目标密钥。

az iot hub device-identity show

获取IoT 中心设备的详细信息。

az iot hub device-identity update

更新IoT 中心设备。

az iot hub device-identity create

在IoT 中心中创建设备。

使用shared_private_key (也称为对称密钥) 的身份验证方法时,如果未提供任何自定义密钥,服务将为设备生成它们。

如果为边缘设备提供了设备范围,则该值将自动转换为父范围。

az iot hub device-identity create --device-id
                                  [--am {shared_private_key, x509_ca, x509_thumbprint}]
                                  [--auth-type {key, login}]
                                  [--device-scope]
                                  [--edge-enabled {false, true}]
                                  [--hub-name]
                                  [--login]
                                  [--od]
                                  [--pk]
                                  [--primary-thumbprint]
                                  [--resource-group]
                                  [--secondary-key]
                                  [--secondary-thumbprint]
                                  [--sta {disabled, enabled}]
                                  [--star]
                                  [--valid-days]

示例

使用默认授权创建启用了边缘的 IoT 设备, (共享私钥) 。

az iot hub device-identity create -n {iothub_name} -d {device_id} --ee

创建具有自签名证书授权的 IoT 设备,生成有效期为 10 天的证书,然后使用其指纹。

az iot hub device-identity create -n {iothub_name} -d {device_id} --am x509_thumbprint --valid-days 10

创建具有自签名证书授权的 IoT 设备,生成默认过期 (365 天的证书,) 并输出到目标目录。

az iot hub device-identity create -n {iothub_name} -d {device_id} --am x509_thumbprint --output-dir /path/to/output

创建具有自签名证书授权的 IoT 设备,并显式提供主要和辅助指纹。

az iot hub device-identity create -n {iothub_name} -d {device_id} --am x509_thumbprint --ptp {thumbprint_1} --stp {thumbprint_2}

创建具有已禁用状态和原因的根 CA 授权的 IoT 设备。

az iot hub device-identity create -n {iothub_name} -d {device_id} --am x509_ca --status disabled --status-reason 'for reasons'

创建具有设备范围的 IoT 设备。

az iot hub device-identity create -n {iothub_name} -d {device_id} --device-scope 'ms-azure-iot-edge://edge0-123456789123456789'

必需参数

--device-id -d

目标设备 ID。

可选参数

--am --auth-method

用于创建实体的授权方法。

接受的值: shared_private_key, x509_ca, x509_thumbprint
默认值: shared_private_key
--auth-type

指示操作是应自动派生策略密钥还是应使用当前的 Azure AD 会话。 可以使用 配置默认值 az configure --defaults iothub-data-auth-type=<auth-type-value>

接受的值: key, login
默认值: key
--device-scope

设备的范围。 对于边缘设备,这是自动生成且不可变的。 对于叶设备,设置此项以创建子/父关系。

--edge-enabled --ee

指示边缘启用的标志。

接受的值: false, true
默认值: False
--hub-name -n

IoT 中心名称。 如果未提供 --login,则是必需的。

--login -l

此命令支持具有执行操作权限的实体连接字符串。 使用 可避免通过“az login”进行会话登录。 如果同时提供实体连接字符串和名称,则连接字符串优先。 如果未提供 --hub-name,则是必需的。

--od --output-dir

生成自签名证书并使用其指纹。 输出到指定目标目录。

--pk --primary-key

以 base64 格式存储的主对称共享访问密钥。

--primary-thumbprint --ptp

用于主要指纹的自签名证书指纹。

--resource-group -g

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

--secondary-key --sk

以 base64 格式存储的辅助对称共享访问密钥。

--secondary-thumbprint --stp

用于辅助指纹的自签名证书指纹。

--sta --status

创建时设置设备状态。

接受的值: disabled, enabled
默认值: enabled
--star --status-reason

设备状态的说明。

--valid-days --vd

生成自签名证书并使用其指纹。 在指定的天数内有效。 默认值:365。

az iot hub device-identity delete

删除IoT 中心设备。

az iot hub device-identity delete --device-id
                                  [--auth-type {key, login}]
                                  [--etag]
                                  [--hub-name]
                                  [--login]
                                  [--resource-group]

必需参数

--device-id -d

目标设备 ID。

可选参数

--auth-type

指示操作是应自动派生策略密钥还是应使用当前的 Azure AD 会话。 可以使用 配置默认值 az configure --defaults iothub-data-auth-type=<auth-type-value>

接受的值: key, login
默认值: key
--etag -e

对应于资源最后一个状态的 Etag 或实体标记。 如果未提供 etag,则使用值“*”。

--hub-name -n

IoT 中心名称。 如果未提供 --login,则为必需。

--login -l

此命令支持具有执行操作权限的实体连接字符串。 使用 避免通过“az login”进行会话登录。 如果同时提供了实体连接字符串和名称,则连接字符串优先。 如果未提供 --hub-name,则是必需的。

--resource-group -g

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

az iot hub device-identity export

将所有设备标识从IoT 中心导出到 Azure 存储 Blob 容器。

包含设备标识的输出 Blob 是名为“devices.txt”的文本文件。

所需权限 - IoT 中心支持“注册表读取&注册表写入”的共享访问策略,或者在IoT 中心上具有“IoT 中心数据参与者”角色的主体。

仅当存储帐户与输入IoT 中心位于同一订阅中时,才能使用存储帐户名称和 Blob 容器名称参数。 对于内联 Blob 容器 SAS URI 输入,请查看环境的输入规则。

有关详细信息,请参阅 https://aka.ms/iothub-device-exportimport

az iot hub device-identity export [--auth-type {key, login}]
                                  [--bc]
                                  [--bcu]
                                  [--hub-name]
                                  [--identity]
                                  [--ik {false, true}]
                                  [--login]
                                  [--resource-group]
                                  [--sa]

示例

将所有设备标识导出到配置的 Blob 容器,并包括设备密钥。 Blob 容器名称和存储帐户名称作为命令的参数提供。

az iot hub device-identity export -n {iothub_name} --ik --bc {blob_container_name} --sa {storage_account_name}

将所有设备标识导出到配置的 Blob 容器,并包括设备密钥。 使用内联 SAS URI 示例。

az iot hub device-identity export -n {iothub_name} --ik --bcu 'https://mystorageaccount.blob.core.windows.net/devices?sv=2019-02-02&st=2020-08-23T22%3A35%3A00Z&se=2020-08-24T22%3A35%3A00Z&sr=c&sp=rwd&sig=VrmJ5sQtW3kLzYg10VqmALGCp4vtYKSLNjZDDJBSh9s%3D'

使用包含 SAS URI 的文件路径将所有设备标识导出到配置的 Blob 容器。

az iot hub device-identity export -n {iothub_name} --bcu {sas_uri_filepath}

将所有设备标识导出到配置的 Blob 容器,并包括设备密钥。 使用系统分配的标识,该标识具有存储帐户的存储 Blob 数据参与者角色。 Blob 容器名称和存储帐户名称作为命令的参数提供。

az iot hub device-identity export -n {iothub_name} --ik --bc {blob_container_name} --sa {storage_account_name} --identity [system]

将所有设备标识导出到配置的 Blob 容器,并包括设备密钥。 使用系统分配的标识,该标识具有存储帐户的存储 Blob 数据参与者角色。 Blob 容器 URI 不需要 Blob SAS 令牌。

az iot hub device-identity export -n {iothub_name} --ik --bcu 'https://mystorageaccount.blob.core.windows.net/devices' --identity [system]

将所有设备标识导出到配置的 Blob 容器,并包括设备密钥。 使用用户分配的托管标识,该标识具有存储帐户的存储 Blob 数据参与者角色。 Blob 容器名称和存储帐户名称作为命令的参数提供。

az iot hub device-identity export -n {iothub_name} --ik --bc {blob_container_name} --sa {storage_account_name} --identity {managed_identity_resource_id}

将所有设备标识导出到配置的 Blob 容器,并包括设备密钥。 使用用户分配的托管标识,该标识具有存储帐户的存储 Blob 数据参与者角色。 Blob 容器 URI 不需要 Blob SAS 令牌。

az iot hub device-identity export -n {iothub_name} --ik --bcu 'https://mystorageaccount.blob.core.windows.net/devices' --identity {managed_identity_resource_id}

可选参数

--auth-type

指示操作是应自动派生策略密钥还是使用当前的 Azure AD 会话。 可以使用 配置默认值 az configure --defaults iothub-data-auth-type=<auth-type-value>

接受的值: key, login
默认值: key
--bc --blob-container

此 Blob 容器用于输出设备标识导入作业的状态和结果。 提供blob_container_uri时,将忽略参数。 此 Blob 容器需要写入、读取和删除访问权限。

--bcu --blob-container-uri

具有对 Blob 容器的写入、读取和删除访问权限的 Blob 共享访问签名 URI。 这用于输出作业的状态和结果。 注意:使用基于标识的身份验证时,仍需要 https:// URI,但不需要 SAS 令牌。 此参数的输入可以是内联输入,也可以来自文件路径。

--hub-name -n

IoT 中心名称。 如果未提供 --login,则为必需。

--identity

托管标识类型,用于确定是否使用系统分配的托管标识或用户分配的托管标识。 对于系统分配的托管标识,请使用 [system]。 对于用户分配的托管标识,请提供用户分配的托管标识资源 ID。此标识需要存储帐户的存储 Blob 数据参与者角色。

--ik --include-keys

如果设置,则正常导出密钥。 否则,密钥在导出输出中设置为 null。

接受的值: false, true
默认值: False
--login -l

此命令支持具有执行操作权限的实体连接字符串。 使用 避免通过“az login”进行会话登录。 如果同时提供了实体连接字符串和名称,则连接字符串优先。 如果未提供 --hub-name,则是必需的。

--resource-group -g

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

--sa --storage-account

包含输出 Blob 容器的 Azure 存储帐户的名称。提供blob_container_uri时,将忽略参数。 需要写入、读取和删除访问权限。

az iot hub device-identity import

将设备标识从存储容器 Blob 导入到IoT 中心。

包含设备标识的预期输入文件应命名为“devices.txt”。 导入成功时,输出日志文件“importErrors.log”为空,并在导入失败时包含错误日志。

所需权限 - IoT 中心支持“注册表读取&注册表写入”的共享访问策略,或者在IoT 中心上具有“IoT 中心数据参与者”角色的主体。

仅当存储帐户与输入IoT 中心位于同一订阅中时,才能使用存储帐户名称和 Blob 容器名称参数。 对于内联 Blob 容器 SAS URI 输入,请查看环境的输入规则。

有关详细信息,请参阅 https://aka.ms/iothub-device-exportimport

az iot hub device-identity import [--auth-type {key, login}]
                                  [--hub-name]
                                  [--ibc]
                                  [--ibcu]
                                  [--identity]
                                  [--input-storage-account]
                                  [--login]
                                  [--obc]
                                  [--obcu]
                                  [--osa]
                                  [--resource-group]

示例

通过为输入 Blob 容器和存储帐户以及输出 Blob 容器和存储帐户提供命令参数,从 Blob 导入所有设备标识。

az iot hub device-identity import -n {iothub_name} --ibc {input_blob_container_name} --isa {input_storage_account_name} --obc {output_blob_container_name} --osa {output_storage_account_name}

使用内联 SAS URI 从 Blob 导入所有设备标识。

az iot hub device-identity import -n {iothub_name} --ibcu {input_sas_uri} --obcu {output_sas_uri}

使用包含 SAS URI 的文件路径从 Blob 导入所有设备标识。

az iot hub device-identity import -n {iothub_name} --ibcu {input_sas_uri_filepath} --obcu {output_sas_uri_filepath}

使用系统分配的标识从 Blob 导入所有设备标识,该标识具有两个存储帐户的存储 Blob 数据参与者角色。 输入 Blob 容器和存储帐户以及输出 Blob 容器和存储帐户作为命令的参数提供

az iot hub device-identity import -n {iothub_name} --ibc {input_blob_container_name} --isa {input_storage_account_name} --obc {output_blob_container_name} --osa {output_storage_account_name} --identity [system]

使用系统分配的标识从 Blob 导入所有设备标识,该标识具有两个存储帐户的存储 Blob 数据参与者角色。 Blob 容器 URI 不需要 Blob SAS 令牌。

az iot hub device-identity import -n {iothub_name} --ibcu {input_sas_uri} --obcu {output_sas_uri} --identity [system]

使用用户分配的托管标识从 Blob 导入所有设备标识,该标识具有两个存储帐户的存储 Blob 数据参与者角色。 输入 Blob 容器和存储帐户以及输出 Blob 容器和存储帐户作为命令的参数提供

az iot hub device-identity import -n {iothub_name} --ibc {input_blob_container_name} --isa {input_storage_account_name} --obc {output_blob_container_name} --osa {output_storage_account_name} --identity {managed_identity_resource_id}

使用用户分配的托管标识从 Blob 导入所有设备标识,该标识具有两个存储帐户的存储 Blob 数据参与者角色。 Blob 容器 URI 不需要 Blob SAS 令牌。

az iot hub device-identity import -n {iothub_name} --ibcu {input_sas_uri} --obcu {output_sas_uri} --identity {managed_identity_resource_id}

可选参数

--auth-type

指示操作是应自动派生策略密钥还是使用当前的 Azure AD 会话。 可以使用 配置默认值 az configure --defaults iothub-data-auth-type=<auth-type-value>

接受的值: key, login
默认值: key
--hub-name -n

IoT 中心名称。 如果未提供 --login,则为必需。

--ibc --input-blob-container

此 Blob 容器存储文件,该文件定义要对标识注册表执行的操作。 提供input_blob_container_uri时,将忽略参数。 此 Blob 容器需要读取访问权限。

--ibcu --input-blob-container-uri

对 Blob 容器具有读取访问权限的 Blob 共享访问签名 URI。 此 Blob 包含要对标识注册表执行的操作。 注意:使用基于标识的身份验证时,仍需要 https:// URI,但不需要 SAS 令牌。 此参数的输入可以是内联输入,也可以来自文件路径。

--identity

托管标识类型,用于确定是否使用系统分配的托管标识或用户分配的托管标识。 对于系统分配的托管标识,请使用 [system]。 对于用户分配的托管标识,请提供用户分配的托管标识资源 ID。此标识需要目标存储帐户的存储 Blob 数据参与者角色和IoT 中心的参与者角色。

--input-storage-account --isa

包含输入 Blob 容器的 Azure 存储帐户的名称。仅当未提供input_blob_container_uri时才需要。 需要读取访问权限。

--login -l

此命令支持具有执行操作权限的实体连接字符串。 使用 避免通过“az login”进行会话登录。 如果同时提供了实体连接字符串和名称,则连接字符串优先。 如果未提供 --hub-name,则是必需的。

--obc --output-blob-container

此 Blob 容器用于输出设备标识导入作业的状态和结果。 仅当未提供input_blob_container_uri时才需要。 此 Blob 容器需要写入访问权限。

--obcu --output-blob-container-uri

对 Blob 容器具有写入访问权限的 Blob 共享访问签名 URI。 这用于输出作业的状态和结果。 注意:使用基于标识的身份验证时,仍然需要没有 SAS 令牌的 https:// URI。 此参数的输入可以是内联输入,也可以来自文件路径。

--osa --output-storage-account

包含输出 Blob 容器的 Azure 存储帐户的名称。提供output_blob_container_uri时,将忽略参数。 需要写入访问权限。

--resource-group -g

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

az iot hub device-identity list

列出IoT 中心中的设备。

此命令是 的 az iot hub device-twin list别名,强烈建议使用此命令。 将来,此命令 az iot hub device-identity list 可能会更改或弃用。

az iot hub device-identity list [--auth-type {key, login}]
                                [--edge-enabled {false, true}]
                                [--hub-name]
                                [--login]
                                [--resource-group]
                                [--top]

可选参数

--auth-type

指示操作是应自动派生策略密钥还是使用当前的 Azure AD 会话。 可以使用 配置默认值 az configure --defaults iothub-data-auth-type=<auth-type-value>

接受的值: key, login
默认值: key
--edge-enabled --ee

指示边缘启用的标志。

接受的值: false, true
默认值: False
--hub-name -n

IoT 中心名称。 如果未提供 --login,则为必需。

--login -l

此命令支持具有执行操作权限的实体连接字符串。 使用 避免通过“az login”进行会话登录。 如果同时提供了实体连接字符串和名称,则连接字符串优先。 如果未提供 --hub-name,则是必需的。

--resource-group -g

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

--top

要返回的最大元素数。 将 -1 用于无限制。

默认值: 1000

az iot hub device-identity renew-key

使用 sas 身份验证续订IoT 中心设备的目标密钥。

az iot hub device-identity renew-key --device-id
                                     --hub-name
                                     --key-type {primary, secondary, swap}
                                     [--auth-type {key, login}]
                                     [--etag]
                                     [--login]
                                     [--resource-group]

示例

续订主密钥。

az iot hub device-identity renew-key -d {device_id} -n {iothub_name} --kt primary

交换主密钥和辅助密钥。

az iot hub device-identity renew-key -d {device_id} -n {iothub_name} --kt swap

必需参数

--device-id -d

目标设备 ID。

--hub-name -n

IoT 中心名称。 如果未提供 --login,则为必需。

--key-type --kt

要重新生成的目标密钥类型。

接受的值: primary, secondary, swap

可选参数

--auth-type

指示操作是应自动派生策略密钥还是使用当前的 Azure AD 会话。 可以使用 配置默认值 az configure --defaults iothub-data-auth-type=<auth-type-value>

接受的值: key, login
默认值: key
--etag -e

对应于资源最后一个状态的 Etag 或实体标记。 如果未提供 etag,则使用值“*”。

--login -l

此命令支持具有执行操作权限的实体连接字符串。 使用 避免通过“az login”进行会话登录。 如果同时提供了实体连接字符串和名称,则连接字符串优先。 如果未提供 --hub-name,则是必需的。

--resource-group -g

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

az iot hub device-identity show

获取IoT 中心设备的详细信息。

az iot hub device-identity show --device-id
                                [--auth-type {key, login}]
                                [--hub-name]
                                [--login]
                                [--resource-group]

必需参数

--device-id -d

目标设备 ID。

可选参数

--auth-type

指示操作是应自动派生策略密钥还是使用当前的 Azure AD 会话。 可以使用 配置默认值 az configure --defaults iothub-data-auth-type=<auth-type-value>

接受的值: key, login
默认值: key
--hub-name -n

IoT 中心名称。 如果未提供 --login,则为必需。

--login -l

此命令支持具有执行操作权限的实体连接字符串。 使用 避免通过“az login”进行会话登录。 如果同时提供了实体连接字符串和名称,则连接字符串优先。 如果未提供 --hub-name,则是必需的。

--resource-group -g

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

az iot hub device-identity update

更新IoT 中心设备。

使用 --set,后跟属性分配来更新设备。 利用从“iot 中心设备标识显示”返回的参数。

az iot hub device-identity update --device-id
                                  [--add]
                                  [--am {shared_private_key, x509_ca, x509_thumbprint}]
                                  [--auth-type {key, login}]
                                  [--edge-enabled {false, true}]
                                  [--etag]
                                  [--force-string]
                                  [--hub-name]
                                  [--login]
                                  [--pk]
                                  [--primary-thumbprint]
                                  [--remove]
                                  [--resource-group]
                                  [--secondary-key]
                                  [--secondary-thumbprint]
                                  [--set]
                                  [--sta {disabled, enabled}]
                                  [--star]

示例

为设备启用边缘功能

az iot hub device-identity update -d {device_id} -n {iothub_name} --set capabilities.iotEdge=true

使用便捷参数为设备启用边缘功能。

az iot hub device-identity update -d {device_id} -n {iothub_name} --ee

禁用设备状态

az iot hub device-identity update -d {device_id} -n {iothub_name} --set status=disabled

使用便捷参数禁用设备状态。

az iot hub device-identity update -d {device_id} -n {iothub_name} --status disabled

在一个命令中

az iot hub device-identity update -d {device_id} -n {iothub_name} --set status=disabled capabilities.iotEdge=true

必需参数

--device-id -d

目标设备 ID。

可选参数

--add

通过指定路径和键值对,将对象添加到对象列表。 示例:--add property.listProperty <key=value、string 或 JSON string>。

默认值: []
--am --auth-method

用于创建实体的授权方法。

接受的值: shared_private_key, x509_ca, x509_thumbprint
--auth-type

指示操作是应自动派生策略密钥还是使用当前的 Azure AD 会话。 可以使用 配置默认值 az configure --defaults iothub-data-auth-type=<auth-type-value>

接受的值: key, login
默认值: key
--edge-enabled --ee

指示边缘启用的标志。

接受的值: false, true
--etag -e

对应于资源最后一个状态的 Etag 或实体标记。 如果未提供 etag,则使用值“*”。

--force-string

使用“set”或“add”时,请保留字符串文本,而不是尝试转换为 JSON。

默认值: False
--hub-name -n

IoT 中心名称。 如果未提供 --login,则为必需。

--login -l

此命令支持具有执行操作权限的实体连接字符串。 使用 避免通过“az login”进行会话登录。 如果同时提供了实体连接字符串和名称,则连接字符串优先。 如果未提供 --hub-name,则是必需的。

--pk --primary-key

以 base64 格式存储的主对称共享访问密钥。

--primary-thumbprint --ptp

用于主指纹的自签名证书指纹。

--remove

从列表中删除属性或元素。 示例:--remove property.list 或 --remove propertyToRemove。

默认值: []
--resource-group -g

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

--secondary-key --sk

以 base64 格式存储的辅助对称共享访问密钥。

--secondary-thumbprint --stp

用于辅助指纹的自签名证书指纹。

--set

通过指定要设置的属性路径和值来更新对象。 示例:--set property1.property2=。

默认值: []
--sta --status

创建时设置设备状态。

接受的值: disabled, enabled
--star --status-reason

设备状态的说明。