使用 Azure CLI 配置 IoT 中心文件上传

项目
10/28/2024

本文介绍如何使用 Azure CLI 在 IoT 中心配置文件上传。

若要使用 IoT 中心的文件上传功能，必须先将 Azure 存储帐户和 Blob 容器与 IoT 中心关联。 IoT 中心会自动生成对此 Blob 容器具有写入权限的 SAS URI，以供设备上传文件时使用。除了存储帐户和 Blob 容器，还可以设置 SAS URI 的生存时间和 IoT 中心用于 Azure 存储的身份验证类型。还可以为 IoT 中心可以传送给后端服务的可选文件上传通知配置设置。

先决条件

有效的 Azure 帐户。如果没有帐户，可以创建一个试用版订阅，只需几分钟即可完成。
Azure 订阅中的 IoT 中心。如果还没有中心，则可以按照创建 IoT 中心中的步骤进行操作。
一个 Azure 存储帐户。如果没有 Azure 存储帐户，可以使用 Azure CLI 创建一个。有关详细信息，请参阅创建存储帐户。

可以使用本地 Azure CLI。

如果需要，请安装 Azure CLI 来运行 CLI 参考命令。
本地 Azure CLI，请了解如何安装 Azure CLI。如果在 Windows 或 macOS 上运行，请考虑在 Docker 容器中运行 Azure CLI。有关详细信息，请参阅如何在 Docker 容器中运行 Azure CLI。
- 通过使用 az login 命令登录到 Azure CLI。若要完成身份验证过程，请遵循终端中显示的步骤。有关其他登录选项，请参阅使用 Azure CLI 登录。
- 出现提示时，请在首次使用时安装 Azure CLI 扩展。有关扩展详细信息，请参阅使用 Azure CLI 的扩展。
- 运行 az version 以查找安装的版本和依赖库。若要升级到最新版本，请运行 az upgrade。

注意

本文使用最新版本的 Azure IoT 扩展（称为 azure-iot）。旧版本称为 azure-cli-iot-ext。只应同时安装有一个版本。可以使用命令 az extension list 来验证当前安装的扩展。

使用 az extension remove --name azure-cli-iot-ext 可删除扩展的旧版本。

使用 az extension add --name azure-iot 可添加扩展的新版本。

若要查看已安装了哪些扩展，请使用 az extension list。

登录到 Azure 帐户，并选择订阅。

在命令提示符中，运行 login 命令：
```
az login
```
按照说明使用代码进行身份验证，并通过 Web 浏览器登录 Azure 帐户。
如果有多个 Azure 订阅，登录 Azure 可获得与凭据关联的所有 Azure 帐户的访问权限。使用以下命令列出可供使用的 Azure 帐户：
```
az account list
```
使用以下命令，选择想要用于运行命令以创建 IoT 中心的订阅。可使用上一命令输出中的订阅名称或 ID：
```
az account set --subscription {your subscription name or id}
```

检索存储帐户详细信息

以下步骤假设已使用 Resource Manager 部署模型而不经典部署模型创建了存储帐户。

若要从设备配置文件上传，需要 Azure 存储帐户的连接字符串。存储帐户必须与 IoT 中心位于同一订阅中。还需要存储帐户中 Blob 容器的名称。使用以下命令检索存储帐户密钥：

az storage account show-connection-string --name {your storage account name} \
  --resource-group {your storage account resource group}

连接字符串将类似于以下输出：

{
  "connectionString": "DefaultEndpointsProtocol=https;EndpointSuffix=core.chinacloudapi.cn;AccountName={your storage account name};AccountKey={your storage account key}"
}

记下 connectionString 值。在后续步骤中需要用到它。

可将现有的 Blob 容器用于文件上传，或新建一个容器：

若要列出存储帐户中的现有 Blob 容器，请使用以下命令：

az storage container list --connection-string "{your storage account connection string}"

若要在存储帐户中创建 Blob 容器，请使用以下命令：

az storage container create --name {container name} \
  --connection-string "{your storage account connection string}"

配置 IoT 中心

现在可以使用存储帐户详细信息配置 IoT 中心以将文件上传到 IoT 中心。

配置需要以下值：

存储容器：当前 Azure 订阅中要与 IoT 中心关联的 Azure 存储帐户中的 Blob 容器。检索在上一部分中必要的存储帐户信息。 IoT 中心会自动生成对此 Blob 容器具有写入权限的 SAS URI，以供设备上传文件时使用。
接收已上传文件的通知：启用或禁用文件上传通知。
SAS TTL：此设置是 IoT 中心返回给设备的 SAS URI 生存时间。默认设置为一小时。
文件通知设置默认 TTL：文件上传通知到期前的生存时间。默认设置为一天。
文件通知最大传送数：IoT 中心将尝试传送文件上传通知的次数。默认设置为 10。
文件通知锁定持续时间：文件通知队列的锁定持续时间。默认设置为 60 秒。
身份验证类型：IoT 中心与 Azure 存储一起使用的身份验证类型。此设置确定 IoT 中心如何对 Azure 存储进行身份验证和授权。默认值为基于密钥的身份验证；但是，系统分配和用户分配的托管标识也可使用。托管标识在 Microsoft Entra ID 中以安全方式为 Azure 服务提供了一个自动托管标识。若要了解如何在 IoT 中心和 Azure 存储帐户上配置托管标识，请参阅 IoT 中心对托管标识的支持。配置完成后，可以设置一个托管标识以通过 Azure 存储进行身份验证。

注意

身份验证类型设置配置 IoT 中心如何向 Azure 存储帐户进行身份验证。设备始终使用从 IoT 中心获取的 SAS URI 通过 Azure 存储进行身份验证。

以下命令显示如何在 IoT 中心配置文件上传设置。为清楚起见，这些命令会单独显示，但通常情况下，你会发出包含方案所需全部参数的单个命令。包括在命令行中显示的引号。不要包含大括号。有关每个参数的更多详细信息，请参阅 az iot hub update 命令的 Azure CLI 文档。

以下命令可配置存储帐户和 Blob 容器。

az iot hub update --name {your iot hub name} \
    --fileupload-storage-connectionstring "{your storage account connection string}" \
    --fileupload-storage-container-name "{your container name}"

以下命令可将 SAS URI 生存时间设置为默认值（一小时）。

az iot hub update --name {your iot hub name} \
    --fileupload-sas-ttl 1

以下命令启用文件通知，将文件通知属性设置为默认值。（文件上传通知的生存时间设为一小时，锁定持续时间设为 60 秒。）

az iot hub update --name {your iot hub name} \
    --fileupload-notifications true  \
    --fileupload-notification-max-delivery-count 10 \
    --fileupload-notification-ttl 1 \
    --fileupload-notification-lock-duration 60

以下命令可配置基于密钥的身份验证：

az iot hub update --name {your iot hub name} \
    --fileupload-storage-auth-type keyBased

以下命令使用 IoT 中心的系统分配的托管标识来配置身份验证。运行此命令之前，需要为 IoT 中心启用系统分配的托管标识，并在 Azure 存储帐户上为其授予正确的 RBAC 角色。若要了解如何操作，请参阅托管标识的 IoT 中心支持。

az iot hub update --name {your iot hub name} \
    --fileupload-storage-auth-type identityBased \
    --fileupload-storage-identity [system]

以下命令可检索在 IoT 中心配置的用户分配的托管标识，并可使用其中一个标识来配置身份验证。在使用用户分配的托管标识进行身份验证之前，必须先在 IoT 中心配置它并在 Azure 存储帐户上授予其适当的 RBAC 角色。若要了解详细信息和步骤，请参阅 IoT 中心对托管标识的支持。

若要在 IoT 中心查询用户分配的托管标识，请使用 az iot hub identity show 命令。

az iot hub identity show --name {your iot hub name} --query userAssignedIdentities

该命令将返回在 IoT 中心配置的用户分配的托管标识的集合。以下输出显示了包含单个用户分配的托管标识的集合。

{
  "/subscriptions/{your subscription ID}/resourcegroups/{your resource group}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{your user-assigned managed identity name}": 
  {
    "clientId": "<client ID GUID>",
    "principalId": "<principal ID GUID>"
  }
}

以下命令将身份验证配置为使用上述的用户分配的标识。

az iot hub update --name {your iot hub name} \
    --fileupload-storage-auth-type identityBased \
    --fileupload-storage-identity  "/subscriptions/{your subscription ID}/resourcegroups/{your resource group}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{your user-assigned managed identity name}"

可以使用以下命令查看 IoT 中心上的设置：

az iot hub show --name {your iot hub name}

若仅查看文件上传设置，请使用以下命令：

az iot hub show --name {your iot hub name}
    --query '[properties.storageEndpoints, properties.enableFileUploadNotifications, properties.messagingEndpoints.fileNotifications]'

大多数情况下，在 Azure CLI 命令中使用命名参数是最简单的方法；但是，也可以使用 --set 参数配置文件上传设置。以下命令有助于了解如何操作。

az iot hub update --name {your iot hub name} \
  --set properties.storageEndpoints.'$default'.connectionString="{your storage account connection string}"

az iot hub update --name {your iot hub name} \
  --set properties.storageEndpoints.'$default'.containerName="{your storage container name}"

az iot hub update --name {your iot hub name} \
  --set properties.storageEndpoints.'$default'.sasTtlAsIso8601=PT1H0M0S

az iot hub update --name {your iot hub name} \
  --set properties.enableFileUploadNotifications=true

az iot hub update --name {your iot hub name} \
  --set properties.messagingEndpoints.fileNotifications.maxDeliveryCount=10

az iot hub update --name {your iot hub name} \
  --set properties.messagingEndpoints.fileNotifications.ttlAsIso8601=PT1H0M0S

后续步骤

从设备上传文件概述
IoT 中心对托管标识的支持
文件上传操作指南
Azure CLI az iot hub update、az iot hub identity show 和 az iot hub create 命令

通过

使用 Azure CLI 配置 IoT 中心文件上传

先决条件

登录并设置 Azure 帐户

检索存储帐户详细信息

配置 IoT 中心

后续步骤

其他资源