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

如何使用 IoT Central REST API 上传文件

项目
10/27/2023

借助 IoT Central，可以将媒体和其他文件从联网的设备上传到云存储。可以在 IoT Central 应用程序中配置文件上传功能，然后在设备代码中实现文件上传。在本文中，将学习以下内容：

使用 REST API 在 IoT Central 应用程序中配置文件上传功能。
通过运行一些示例设备代码来测试文件上传。

使用 IoT Central REST API 可进行以下操作：

添加文件上传存储帐户配置
更新文件上传存储帐户配置
获取文件上传存储帐户配置
删除文件上传存储配置

每个 IoT Central REST API 调用都需要授权标头。有关详细信息，请参阅如何对 IoT Central REST API 调用进行身份验证和授权。

有关 IoT Central REST API 的参考文档，请参阅 Azure IoT Central REST API 参考。

提示

可以使用 Postman 尝试本文所述的 REST API 调用。下载 IoT Central Postman 集合并将其导入 Postman。在集合中需要设置变量，例如应用子域和管理员令牌。

若要了解如何使用 IoT Central UI 上传文件，请参阅如何配置文件上传。

先决条件

若要测试文件上传，请在本地开发环境中安装以下先决条件：

添加文件上传存储帐户配置

添加文件上传存储帐户配置：

创建存储帐户

要使用此 Azure 存储 REST API，需要 management.azure.com 资源的持有者令牌。若要获取持有者令牌，可使用以下 Azure CLI：

az account get-access-token --resource https://management.azure.com

如果没有 Blob 的存储帐户，可以使用以下请求在订阅中创建一个：

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{accountName}?api-version=2021-09-01

请求标头具有以下字段：

subscriptionId：目标订阅 ID。
resourceGroupName：订阅中资源组的名称。此名称不区分大小写。
accountName：存储帐户在指定资源组中的名称。存储帐户名称长度必须为 3 到 24 个字符，并且只能使用数字和小写字母。

请求正文包含以下必需属性：

kind：存储帐户的类型
location：资源所在的地理位置
sku：SKU 名称。

{
 "kind": "BlockBlobStorage",
 "location": "West US",
 "sku": "Premium_LRS"
}

创建容器

使用以下请求为 Blob 在存储帐户中创建调用 fileuploads 的容器：

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{accountName}/blobServices/default/containers/fileuploads?api-version=2021-09-01

containerName：Blob 容器名称长度必须为 3 到 63 个字符，并且只能使用数字、小写字母和破折号（-）。每个短划线（-）字符的前后必须紧跟字母或数字。

发送包含此请求的空请求正文，如以下示例所示：

{
}

对此请求的响应如以下示例所示：

{
  "id": "/subscriptions/your-subscription-id/resourceGroups/yourResourceGroupName/providers/Microsoft.Storage/storageAccounts/yourAccountName/blobServices/default/containers/fileuploads",
  "name": "fileuploads",
  "type": "Microsoft.Storage/storageAccounts/blobServices/containers"
}

获取存储帐户密钥

使用以下请求检索在 IoT Central 中配置上传时所需的存储帐户密钥：

POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{accountName}/listKeys?api-version=2021-09-01

对此请求的响应如以下示例所示：

{
  "keys": [
    {
      "creationTime": "2022-05-19T19:22:40.9132287Z",
      "keyName": "key1",
      "value": "j3UTm**************==",
      "permissions": "FULL"
    },
    {
      "creationTime": "2022-05-19T19:22:40.9132287Z",
      "keyName": "key2",
      "value": "Nbs3W**************==",
      "permissions": "FULL"
    }
  ]
}

创建上传配置

使用以下请求在 IoT Central 应用程序中创建文件上传 Blob 存储帐户配置：

PUT https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31

请求正文具有以下字段：

account：要在其中上传文件的存储帐户名称。
connectionString：要连接到存储帐户的连接字符串。将上一 listKeys 请求中的某个 value 值用作 AccountKey 值。
container：存储帐户中容器的名称。以下示例使用的名称为 fileuploads。
etag： ETag 可防止与多个上传冲突
sasTtl：ISO 8601 持续时间标准，设备上传文件的请求在文件过期之前有效的时间。

{
  "account": "yourAccountName",
  "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/",
  "container": "fileuploads",
  "sasTtl": "PT1H"
}

对此请求的响应如以下示例所示：

{
  "account": "yourAccountName",
  "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/",
  "container": "fileuploads",
  "sasTtl": "PT1H",
  "state": "pending",
  "etag": "\"7502ac89-0000-0300-0000-627eaf100000\""

}

获取文件上传存储帐户配置

使用以下请求在 IoT Central 应用程序中检索文件上传 Blob 存储帐户配置详情：

GET https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31

对此请求的响应如以下示例所示：

{
  "account": "yourAccountName",
  "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/",
  "container": "yourContainerName",
  "state": "succeeded",
  "etag": "\"7502ac89-0000-0300-0000-627eaf100000\""

}

更新文件上传存储帐户配置

使用以下请求在 IoT Central 应用程序中更新文件上传 blob 存储帐户连接字符串：

PATCH https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31

{
  "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/"
}

对此请求的响应如以下示例所示：


{
  "account": "yourAccountName",
  "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/",
  "container": "yourContainerName",
  "sasTtl": "PT1H",
  "state": "succeeded",
  "etag": "\"7502ac89-0000-0300-0000-627eaf100000\""
}

移除文件上传存储帐户配置

使用以下请求删除存储帐户配置：

DELETE https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31

测试文件上传

在 IoT Central 应用程序中配置文件上传后，可以使用示例代码对其进行测试。如果尚未克隆文件上传示例存储库，请使用以下命令将其克隆到本地计算机上的合适位置并安装相关程序包：

git clone https://github.com/azure-Samples/iot-central-file-upload-device
cd iotc-file-upload-device
npm i
npm build

创建设备模板并导入模型

若要测试文件上传，请运行示例设备应用程序。为要使用的示例设备创建设备模板。

在 IoT Central UI 中打开应用程序。
在左侧窗格中导航到“设备模板”选项卡，选择“+ 新建”：
选择 IoT 设备作为模板类型。
在向导的“自定义”页上，输入设备模板的名称，例如“文件上传设备示例”。
在“查看”页上，选择“创建” 。
选择“导入模型”，然后从之前下载的存储库中的文件夹 iotc-file-upload-device\setup 中上传 FileUploadDeviceDcm.json 清单文件。
选择“发布”以发布设备模板。

添加设备

若要将设备添加到 Azure IoT Central 应用程序：

在左侧窗格中选择“设备”。
选择之前创建的文件上传设备示例设备模板。
选择 + “新建”，然后选择“创建”。
选择创建的设备，然后选择连接

复制 ID scope、Device ID 以及 Primary key 的值。在设备示例代码中使用这些值。

运行示例代码

打开在 VS Code 中下载的 git 存储库。在项目的根目录中创建一个“.env”文件，并添加之前复制的值。该文件应类似于以下示例，其中包含前面记下的值。

scopeId=<YOUR_SCOPE_ID>
deviceId=<YOUR_DEVICE_ID>
deviceKey=<YOUR_PRIMARY_KEY>
modelId=dtmi:IoTCentral:IotCentralFileUploadDevice;1

打开在 VS Code 中下载的 git 存储库。按 F5 运行/调试示例。在终端窗口中，可以看到设备已注册并已连接到 IoT Central：

Starting IoT Central device...
 > Machine: Windows_NT, 8 core, freemem=6674mb, totalmem=16157mb
Starting device registration...
DPS registration succeeded
Connecting the device...
IoT Central successfully connected device: 7z1xo26yd8
Sending telemetry: {
    "TELEMETRY_SYSTEM_HEARTBEAT": 1
}
Sending telemetry: {
    "TELEMETRY_SYSTEM_HEARTBEAT": 1
}
Sending telemetry: {
    "TELEMETRY_SYSTEM_HEARTBEAT": 1
}

示例项目附带名为 datafile.json 的示例文件。在 IoT Central 应用程序中使用 “上传文件”命令时，将上传此文件 。

若要测试上传，请打开应用程序并选择创建的设备。选择“命令”选项卡，可以看到名为“运行”的按钮。选择该按钮时，IoT Central 应用会在设备上调用直接方法来上传文件。可以在 /device.ts 文件的示例代码中看到此直接方法。该方法名为 uploadFileCommand。

选择“原始数据”选项卡以验证文件上传状态。

Screenshot showing the U I of how to verify a file upload.

还可以进行 REST API 调用，以验证存储容器中的文件上传状态。

后续步骤

现在你已了解如何使用 REST API 配置文件上传，建议接下来了解如何通过 IoT Central GUI 创建设备模板。

Share via

如何使用 IoT Central REST API 上传文件

先决条件

添加文件上传存储帐户配置

创建存储帐户

创建容器

获取存储帐户密钥

创建上传配置

获取文件上传存储帐户配置

更新文件上传存储帐户配置

移除文件上传存储帐户配置

测试文件上传

创建设备模板并导入模型

添加设备

运行示例代码

后续步骤

其他资源