通过

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

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

  • 项目

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

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

先决条件

  • 有效的 Azure 帐户。 如果没有帐户，只需花费几分钟就能创建一个免费帐户。

  • Azure 订阅中的 IoT 中心。 如果还没有中心，则可以按照创建 IoT 中心中的步骤进行操作。

  • 一个带有 Blob 容器的 Azure 存储帐户。 如果没有 Azure 存储帐户，可以使用 Azure CLI 创建一个。 有关详细信息，请参阅创建存储帐户。

注意

本文使用最新版本的 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 帐户

登录到 Azure 帐户，并选择订阅。 如果你使用的是 Azure Cloud Shell，则应该已登录；但是，如果你有多个订阅，则仍可能需要选择 Azure 订阅。

  1. 在命令提示符中，运行 login 命令：

    az login

    按照说明使用代码进行身份验证，并通过 Web 浏览器登录 Azure 帐户。

  2. 如果有多个 Azure 订阅，登录 Azure 可获得与凭据关联的所有 Azure 帐户的访问权限。 使用以下命令列出可供使用的 Azure 帐户：

    az account list

    使用以下命令，选择想要用于运行命令以创建 IoT 中心的订阅。 可使用上一命令输出中的订阅名称或 ID：

    az account set --subscription {your subscription name or id}

配置存储帐户访问权限

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

若要配置设备的文件上传，需要确保 IoT 中心有权访问 Azure 存储帐户。 存储帐户必须与 IoT 中心位于同一订阅中。 还需要存储帐户中 Blob 容器的名称。

可以使用基于密钥的身份验证或基于标识的身份验证来提供访问权限。 Microsoft 建议使用基于标识的身份验证，这是更安全的选项。

基于密钥的身份验证

对于基于密钥的身份验证，请提供存储帐户的连接字符串。 使用 az storage account show-connection-string 命令检索存储帐户的密钥。

记下 connectionString 值。 连接字符串类似于以下输出：

{
  "connectionString": "DefaultEndpointsProtocol=https;EndpointSuffix=core.windows.net;AccountName={your_storage_account_name};AccountKey={your_storage_account_key}"
}

基于标识的身份验证

可以使用系统分配的托管标识或用户分配的托管标识进行基于标识的身份验证。 有关详细信息，请参阅 IoT 中心对托管标识的支持。

使用 az role assignment create 命令向托管标识分配角色。 有关详细信息，请参阅分配用于访问 Blob 数据的 Azure 角色。

配置 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 中心获取的 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 存储帐户的正确的基于角色的访问控制角色。 若要了解如何操作，请参阅托管标识的 IoT 中心支持。

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

以下命令可检索在 IoT 中心配置的用户分配的托管标识，并可使用其中一个标识来配置身份验证。 要使用用户分配的托管标识进行身份验证，必须先在 IoT 中心对其进行配置并为其授予针对 Azure 存储帐户的相应基于角色的访问控制角色。 若要了解详细信息和步骤，请参阅 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

后续步骤