將 Blob 新增至 Azure Digital Twins 中的物件

發行項
01/10/2020

重要

已發行新版本的 Azure Digital Twins 服務。鑒於新服務的擴充功能，原始的 Azure Digital Twins 服務（本檔集所述）已淘汰。

若要檢視新服務的檔，請流覽使用中的 Azure Digital Twins 檔。

Blob 是一般檔類型的非結構化表示法，例如圖片和記錄。 Blob 會使用 MIME 類型來追蹤代表的數據種類（例如：“image/jpeg”）和元數據（名稱、描述、類型等等）。

Azure Digital Twins 支援將 Blob 附加至裝置、空間和使用者。 Blob 可以代表使用者的配置檔圖片、裝置相片、視訊、地圖、韌體 zip、JSON 數據、記錄等。

本文假設您已熟悉向 Azure Digital Twins 管理 API 進行驗證。

若要深入瞭解使用管理 API 進行驗證，請參閱使用 Azure Digital Twins API 進行驗證。
若要使用Postman REST 用戶端向管理 API 進行驗證，請閱讀如何設定 Postman。

上傳 Blob 概觀

您可以使用多部分要求，將 Blob 上傳至特定端點及其各自的功能。

注意

多部分要求通常需要三個部分：

Content-Type 標頭：
- application/json; charset=utf-8
- multipart/form-data; boundary="USER_DEFINED_BOUNDARY"
Content-Disposition：
- form-data; name="metadata"
要上傳的檔案內容

內容類型和 Content-Disposition 會根據使用案例而有所不同。

您可以透過 REST 用戶端或 Postman 之類的工具，以程式設計方式提出多部分要求（透過 C#）。 REST 用戶端工具對於複雜多部分要求的支援層級可能不同。組態設定也可能因工具而異。確認哪一個工具最適合您的需求。

重要

對 Azure Digital Twins 管理 API 提出的多部分要求通常有兩個部分：

由 Content-Type 和/或 Content-Disposition 宣告的 Blob 元數據（例如相關聯的 MIME 類型）
Blob 內容，其中包含要上傳之檔案的非結構化內容

PATCH 要求不需要這兩個部分。 POST 或建立作業都需要兩者。

佔用快速入門原始程式碼包含完整的 C# 範例，示範如何針對 Azure Digital Twins 管理 API 提出多部分要求。

Blob 中繼資料

除了 Content-Type 和 Content-Disposition 之外，Azure Digital Twins 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	String	要與 Blob 產生關聯的父實體（空格、裝置或使用者）
name	String	Blob 的易記名稱
type	String	Blob 的類型 - 無法使用 type 和 typeId
typeId	整數	Blob 類型識別碼 - 無法使用 type 和 typeId
亞	String	Blob 子類型 - 無法使用 subtype 和 subtypeId
subtypeId	整數	Blob 的子類型標識碼 - 無法使用 subtype 和 subtypeId
description	String	Blob 的自定義描述
共用	String	Blob 是否可以共用 - 列舉 [`None`，， `TreeGlobal`]

Blob 元數據一律會以 Content-Type application/json 或檔案的形式提供作為第一個.json區塊。檔案數據會以第二個區塊提供，而且可以是任何支援的MIME類型。

Swagger 檔會詳細說明這些模型架構。

提示

提供 Swagger 偷偷預覽來示範 API 功能集。裝載於 docs.westcentralus.azuresmartspaces.net/management/swagger。

您可以在：

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

名稱	Replace with
YOUR_INSTANCE_NAME	Azure Digital Twins 實例的名稱
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	String	Blob 的唯一標識碼
name	String	Blob 的易記名稱
parentId	String	要與 Blob 產生關聯的父實體（空格、裝置或使用者）
type	String	Blob 的類型 - 無法使用 type 和 typeId
typeId	整數	Blob 類型識別碼 - 無法使用 type 和 typeId
亞	String	Blob 子類型 - 無法使用 subtype 和 subtypeId
subtypeId	整數	Blob 的子類型標識碼 - 無法使用 subtype 和 subtypeId
共用	String	Blob 是否可以共用 - 列舉 [`None`，， `TreeGlobal`]
description	String	Blob 的自定義描述
contentInfos	Array	指定非結構化元數據資訊，包括版本
fullName	String	Blob 的完整名稱
spacePaths	String	空間路徑

Blob 元數據一律會以 Content-Type application/json 或檔案的形式提供作為第一個.json區塊。檔案數據會以第二個區塊提供，而且可以是任何支援的MIME類型。

Blob 多部分要求範例

在下列範例中， YOUR_MANAGEMENT_API_URL 指的是 Digital Twins API 的 URI：

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

名稱	Replace with
YOUR_INSTANCE_NAME	Azure Digital Twins 實例的名稱
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--

值	Replace with
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"

值	Replace with
YOUR_TOKEN	有效的 OAuth 2.0 令牌
YOUR_SPACE_ID	要與 Blob 產生關聯之空間的標識碼
PATH_TO_FILE	文字文件的路徑

成功的POST會傳回新 Blob 的識別碼。

API 端點

下列各節說明核心 Blob 相關 API 端點及其功能。

裝置

您可以將 Blob 附加至裝置。下圖顯示管理 API 的 Swagger 參考檔。它會指定要用於 Blob 耗用量的裝置相關 API 端點，以及傳入它們的任何必要路徑參數。

例如，若要更新或建立 Blob 並將 Blob 連結至裝置，請對下列專案提出已驗證的 HTTP PATCH 要求：

YOUR_MANAGEMENT_API_URL/devices/blobs/YOUR_BLOB_ID

參數	Replace with
YOUR_BLOB_ID	所需的 Blob 識別碼

成功的要求會傳回 JSON 物件，如先前所述。

空格

您也可以將 Blob 附加至空格。下圖列出負責處理 Blob 的所有空間 API 端點。它也會列出要傳入這些端點的任何路徑參數。

例如，若要傳回附加至空間的 Blob，請對下列專案提出已驗證的 HTTP GET 要求：

YOUR_MANAGEMENT_API_URL/spaces/blobs/YOUR_BLOB_ID

參數	Replace with
YOUR_BLOB_ID	所需的 Blob 識別碼

成功的要求會傳回 JSON 物件，如先前所述。

相同端點的 PATCH 要求會更新元數據描述，並建立 Blob 的版本。 HTTP 要求是透過 PATCH 方法進行，以及任何必要的中繼和多部分表單資料。

使用者

您可以將 Blob 附加至使用者模型（例如，建立設定文件圖片的關聯）。下圖顯示相關的使用者 API 端點和任何必要的路徑參數，例如 id：

例如，若要擷取附加至使用者的 Blob，請使用任何必要的表單資料來提出已驗證的 HTTP GET 要求：

YOUR_MANAGEMENT_API_URL/users/blobs/YOUR_BLOB_ID

參數	Replace with
YOUR_BLOB_ID	所需的 Blob 識別碼

成功的要求會傳回 JSON 物件，如先前所述。

常見錯誤

常見的錯誤牽涉到未提供正確的標頭資訊：
```
{
    "error": {
        "code": "400.600.000.000",
        "message": "Invalid media type in first section."
    }
}
```
若要解決此錯誤，請確認整體要求具有適當的 Content-Type 標頭：
- multipart/mixed
- multipart/form-data
此外，請確認每個 多部分區塊 都有適當的對應 Content-Type。
將多個 Blob 指派給空間智慧圖形中的相同資源時，就會發生第二個常見的錯誤：
```
{
    "error": {
        "code": "400.600.000.000",
        "message": "SpaceBlobMetadata already exists."
    }
}
```
注意

訊息屬性會根據資源而有所不同。

空間圖形內每個資源只能附加一個 Blob（每一種）。

若要解決此錯誤，請使用適當的 API HTTP PATCH 作業來更新現有的 Blob。這麼做會將現有的 Blob 數據取代為所需的數據。

下一步

若要深入瞭解 Azure Digital Twins 的 Swagger 參考檔，請參閱使用 Azure Digital Twins Swagger。
若要透過Postman上傳 Blob，請閱讀如何設定 Postman。

共用方式為

將 Blob 新增至 Azure Digital Twins 中的物件

上傳 Blob 概觀

Blob 中繼資料

Blob 回應數據

Blob 多部分要求範例

API 端點

裝置

空格

使用者

常見錯誤

下一步

其他資源