将 Blob 添加到 Azure 数字孪生中的对象

项目
01/10/2020

重要

Azure 数字孪生服务的新版本已发布。鉴于新服务的扩展功能，原始 Azure 数字孪生服务（本文档集中所述）已停用。

若要查看新服务的文档，请访问活动的 Azure 数字孪生文档。

Blob 是常见文件类型（例如图片和日志）的非结构化表示形式。 Blob 使用 MIME 类型（例如“image/jpeg”）和元数据（名称、说明、类型等）来跟踪它们表示的数据类型。

Azure 数字孪生支持将 Blob 附加到设备、空间和用户。 Blob 可以表示用户个人资料图片、设备照片、视频、地图、固件 zip、JSON 数据、日志，等等。

本文假定你熟悉对 Azure 数字孪生管理 API 进行身份验证。

若要详细了解如何使用管理 API 进行身份验证，请阅读使用 Azure 数字孪生 API 进行身份验证。
若要使用 Postman REST 客户端向管理 API 进行身份验证，请阅读如何配置 Postman。

上传 Blob 概述

可以使用多部分请求将 Blob 上传到特定的终结点及其相应功能。

注意

多部分请求通常需要三个信息片段：

Content-Type 标头：
- application/json; charset=utf-8
- multipart/form-data; boundary="USER_DEFINED_BOUNDARY"
内容处置：
- form-data; name="metadata"
要上传的文件内容

Content-Type 和 Content-Disposition 将因使用方案而异。

可以通过 REST 客户端或诸如 Postman 的工具以编程方式（通过 C#）进行多部分请求。各种 REST 客户端工具对复杂的多部分请求可能具有不同的支持级别。不同工具的配置设置也可能略有不同。请验证哪个工具最适合你的需求。

重要

向 Azure 数字孪生管理 API 发出的多部分请求通常包含两个部分：

由 Content-Type 和/或 Content-Disposition 声明的 Blob 元数据（例如关联的 MIME 类型）
包括要上传的文件的非结构化内容的 Blob 内容

对于 PATCH 请求，上述两个部分都不是必需的。对于 POST 请求或 create 操作，两者都是必需的。

采用快速入门源代码包含完整的 C# 示例，其中展示了如何针对 Azure 数字孪生管理 API 进行多部分请求。

Blob 元数据

除了 Content-Type 和 Content-Disposition 之外，Azure 数字孪生 blob 多部分请求还必须指定正确的 JSON 正文。要提交哪个 JSON 正文取决于执行的 HTTP 请求操作的类型。

四个主要 JSON 架构是：

JSON Blob 元数据符合以下模型：

{
    "parentId": "00000000-0000-0000-0000-000000000000",
    "name": "My First Blob",
    "type": "Map",
    "subtype": "GenericMap",
    "description": "A well chosen description",
    "sharing": "None"
  }

属性	类型	描述
parentId	字符串	要与 Blob 关联的父实体（空间、设备或用户）
name	字符串	Blob 的用户友好名称
type	字符串	Blob 的类型 - 不能使用 type 和 typeId
typeId	Integer	Blob 类型 ID - 不能使用 type 和 typeId
subtype	字符串	Blob 子类型 - 不能使用 subtype 和 subtypeId
subtypeId	Integer	Blob 的子类型 ID - 不能使用 subtype 和 subtypeId
说明	字符串	Blob 的自定义说明
sharing	字符串	是否可以共享 Blob - enum [`None`, `Tree`, `Global`]

Blob 元数据始终作为包含 Content-Type application/json 或文件的第一个.json区块提供。文件数据在第二个区块中提供，可以是任何受支持的 MIME 类型。

Swagger 文档完整详细地介绍了这些模型架构。

提示

我们提供了 Swagger 非公开预览版来演示 API 功能集。它托管在 docs.westcentralus.azuresmartspaces.net/management/swagger 中。

可以在以下位置访问你自己的已生成管理 API Swagger 文档：

https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/swagger

名称	替换为
YOUR_INSTANCE_NAME	Azure 数字孪生实例的名称
YOUR_LOCATION	托管实例的服务器区域

请阅读如何使用 Swagger 了解如何使用参考文档。

Blob 响应数据

单独返回的 Blob 符合以下 JSON 架构：

{
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "string",
  "parentId": "00000000-0000-0000-0000-000000000000",
  "type": "string",
  "subtype": "string",
  "typeId": 0,
  "subtypeId": 0,
  "sharing": "None",
  "description": "string",
  "contentInfos": [
    {
      "type": "string",
      "sizeBytes": 0,
      "mD5": "string",
      "version": "string",
      "lastModifiedUtc": "2019-01-12T00:58:08.689Z",
      "metadata": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
      }
    }
  ],
  "fullName": "string",
  "spacePaths": [
    "string"
  ]
}

属性	类型	描述
id	字符串	Blob 的唯一标识符
name	字符串	Blob 的用户友好名称
parentId	字符串	要与 Blob 关联的父实体（空间、设备或用户）
type	字符串	Blob 的类型 - 不能使用 type 和 typeId
typeId	Integer	Blob 类型 ID - 不能使用 type 和 typeId
subtype	字符串	Blob 子类型 - 不能使用 subtype 和 subtypeId
subtypeId	Integer	Blob 的子类型 ID - 不能使用 subtype 和 subtypeId
sharing	字符串	是否可以共享 Blob - enum [`None`, `Tree`, `Global`]
说明	字符串	Blob 的自定义说明
contentInfos	数组	指定包括版本的非结构化元数据信息
fullName	字符串	Blob 的全名
spacePaths	字符串	空间路径

Blob 元数据始终作为包含 Content-Type application/json 或文件的第一个.json区块提供。文件数据在第二个区块中提供，可以是任何受支持的 MIME 类型。

Blob 多部分请求示例

在以下示例中，YOUR_MANAGEMENT_API_URL 代表数字孪生 API 的 URI：

https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/api/v1.0

名称	替换为
YOUR_INSTANCE_NAME	Azure 数字孪生实例的名称
YOUR_LOCATION	托管实例的区域

若要将文本文件上传为 blob 并将其与某个空间相关联，请向以下项发出经身份验证的 HTTP POST 请求：

YOUR_MANAGEMENT_API_URL/spaces/blobs

使用以下正文：

--USER_DEFINED_BOUNDARY
Content-Type: application/json; charset=utf-8
Content-Disposition: form-data; name="metadata"

{
  "ParentId": "54213cf5-285f-e611-80c3-000d3a320e1e",
  "Name": "My First Blob",
  "Type": "Map",
  "SubType": "GenericMap",
  "Description": "A well chosen description",
  "Sharing": "None"
}
--USER_DEFINED_BOUNDARY
Content-Disposition: form-data; name="contents"; filename="myblob.txt"
Content-Type: text/plain

This is my blob content. In this case, some text, but I could also be uploading a picture, an JSON file, a firmware zip, etc.

--USER_DEFINED_BOUNDARY--

值	替换为
USER_DEFINED_BOUNDARY	多部分内容边界名称

下面的代码使用 MultipartFormDataContent 类完成相同 Blob 上传操作的 .NET 实现：

//Supply your metadata in a suitable format
var multipartContent = new MultipartFormDataContent("USER_DEFINED_BOUNDARY");

var metadataContent = new StringContent(JsonConvert.SerializeObject(metaData), Encoding.UTF8, "application/json");
metadataContent.Headers.ContentType = MediaTypeHeaderValue.Parse("application/json; charset=utf-8");
multipartContent.Add(metadataContent, "metadata");

//MY_BLOB.txt is the String representation of your text file
var fileContents = new StringContent("MY_BLOB.txt");
fileContents.Headers.ContentType = MediaTypeHeaderValue.Parse("text/plain");
multipartContent.Add(fileContents, "contents");

var response = await httpClient.PostAsync("spaces/blobs", multipartContent);

最后，cURL 用户可以相同的方式发出多部分表单请求：

curl -X POST "YOUR_MANAGEMENT_API_URL/spaces/blobs" \
 -H "Authorization: Bearer YOUR_TOKEN" \
 -H "Accept: application/json" \
 -H "Content-Type: multipart/form-data" \
 -F "meta={\"ParentId\":\"YOUR_SPACE_ID\",\"Name\":\"My CURL Blob\",\"Type\":\"Map\",\"SubType\":\"GenericMap\",\"Description\":\"A well chosen description\",\"Sharing\":\"None\"};type=application/json" \
 -F "text=PATH_TO_FILE;type=text/plain"

值	替换为
YOUR_TOKEN	有效的 OAuth 2.0 令牌
YOUR_SPACE_ID	要与 Blob 关联的空间的 ID
PATH_TO_FILE	文本文件的路径

成功的 POST 返回新 Blob 的 ID。

API 终结点

以下部分介绍与核心 blob 相关的 API 终结点及其功能。

设备

可以将 blob 附加到设备。下图显示了管理 API 的 Swagger 参考文档。其中指定了使用 Blob 时所需的设备相关 API 终结点，以及要传入其中的所有必需路径参数。

例如，若要更新或创建某个 Blob 并将其附加到设备，请向以下项发出经身份验证的 HTTP PATCH 请求：

YOUR_MANAGEMENT_API_URL/devices/blobs/YOUR_BLOB_ID

参数	替换为
YOUR_BLOB_ID	所需的 Blob ID

成功的请求返回如前所述的 JSON 对象。

空格

此外，还可以将 blob 附加到空间。下图列出了负责处理 Blob 的所有空间 API 终结点。此外，它还列出了传入这些终结点的所有路径参数。

例如，若要返回附加到某个空间的 Blob，请向以下项发出经身份验证的 HTTP GET 请求：

YOUR_MANAGEMENT_API_URL/spaces/blobs/YOUR_BLOB_ID

参数	替换为
YOUR_BLOB_ID	所需的 Blob ID

成功的请求返回如前所述的 JSON 对象。

对同一个终结点发出 PATCH 请求会更新元数据说明并创建 Blob 的版本。 HTTP 请求是通过 PATCH 方法以及任何所需的元和多部分表单数据发出的。

用户

可将 Blob 附加到用户模型（例如，关联个人资料图片）。下图显示了相关的用户 API 终结点和所有必需的路径参数（例如 id）：

例如，若要提取附加到某个用户的 Blob，请向以下项发出包含所有必需表单数据的经身份验证的 HTTP GET 请求：

YOUR_MANAGEMENT_API_URL/users/blobs/YOUR_BLOB_ID

参数	替换为
YOUR_BLOB_ID	所需的 Blob ID

成功的请求返回如前所述的 JSON 对象。

常见错误

一种常见错误的原因是未提供正确的标头信息：
```
{
    "error": {
        "code": "400.600.000.000",
        "message": "Invalid media type in first section."
    }
}
```
若要解决此错误，请检查整个请求是否包含相应的 Content-Type 标头：
- multipart/mixed
- multipart/form-data
此外，请验证每个 多部分区块 是否具有相应的相应 内容类型。
将多个 Blob 分配到空间智能图中的同一资源时，会出现第二个常见错误：
```
{
    "error": {
        "code": "400.600.000.000",
        "message": "SpaceBlobMetadata already exists."
    }
}
```
注意

消息属性因资源而异。

空间图中的每个资源只能附加一个 Blob（每种类型的 Blob）。

若要解决此错误，请使用相应的 API HTTP PATCH 操作更新现有 Blob。这样做会将现有 Blob 数据替换为所需的数据。

后续步骤

若要详细了解 Azure 数字孪生 Swagger 参考文档，请阅读使用数字孪生 Swagger。
若要通过 Postman 上传 Blob，请参阅如何配置 Postman。

通过

将 Blob 添加到 Azure 数字孪生中的对象

上传 Blob 概述

Blob 元数据

Blob 响应数据

Blob 多部分请求示例

API 终结点

设备

空格

用户

常见错误

后续步骤

其他资源