Azure Digital Twins 内のオブジェクトに BLOB を追加する

[アーティクル]
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 Management API シリーズを使用した認証についてある程度の知識があることを前提としています。

Management API シリーズを使用した認証の詳細については、Azure Digital Twins API を使用した認証に関するページを参照してください。
Postman REST クライアントで Management API シリーズを使用して認証するには、Postman を構成する方法に関するページを参照してください。

BLOB のアップロードの概要

マルチパート要求を使用して、特定のエンドポイントとそれぞれの機能に BLOB をアップロードできます。

Note

マルチパート要求には、一般的に次の 3 つの情報が必要です。

Content-Type ヘッダー:
- application/json; charset=utf-8
- multipart/form-data; boundary="USER_DEFINED_BOUNDARY"
コンテンツ処理:
- form-data; name="metadata"
アップロードするファイルの内容

Content-Type と Content-Disposition は使用シナリオによって異なる場合があります。

マルチパート要求は、プログラム (C# を使用)、REST クライアント、または Postman などのツールを使用して行うことができます。 REST クライアントツールには、複雑なマルチパート要求をサポートするさまざまなレベルがある場合があります。構成設定はツールによって若干異なる場合もあります。どのツールがニーズに最適であるかを確認してください。

重要

Azure Digital Twins Management API に対して行われるマルチパート要求には、一般的に 2 つの部分があります。

Content-Type および Content-Disposition で宣言される (関連付けられている MIME の種類などの) BLOB メタデータ
アップロードされるファイルの非構造化コンテンツを含む BLOB コンテンツ

2 つの部分のどちらも PATCH 要求には不要です。どちらも POST または作成操作に必要です。

占有率のクイックスタートのソースコードには、Azure Digital Twins Management API に対するマルチパート要求を行う方法を示す完全な C# の例が示されています。

BLOB のメタデータ

Content-Type と Content-Disposition に加えて、Azure Digital Twins BLOB のマルチパート要求では、正しい JSON 本文も指定する必要があります。送信する JSON 本文は、実行される HTTP 要求操作の種類によって決まります。

4 つの主な JSON スキーマは次のとおりです。

JSON BLOB のメタデータは、次のモデルに準拠しています。

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

属性	Type	説明
parentId	String	BLOB を (スペース、デバイス、またはユーザー) と関連付ける親エンティティ
name	String	BLOB のわかりやすい名前
type	String	BLOB の種類。type と typeId は使用できません
Typeid	Integer	BLOB の種類の ID。type と typeId は使用できません
サブタイプ	String	BLOB のサブタイプ。subtype と subtypeId は使用できません
subtypeId	Integer	BLOB のサブタイプ ID。subtype と subtypeId は使用できません
description	String	BLOB のカスタマイズした説明
共有	String	BLOB を共有できるかどうか - 列挙型 [`None`、`Tree`、`Global`]

BLOB メタデータは、常に Content-Typeapplication/json を含む最初のチャンクまたはファイルとして .json 提供されます。ファイルデータは 2 番目のチャンクで供給され、サポートされているいずれかの MIME の種類である可能性があります。

Swagger のドキュメントでは、これらのモデルスキーマが詳細に説明されています。

ヒント

API の機能を見ることができる Swagger のプレビューが提供されています。 docs.westcentralus.azuresmartspaces.net/management/swagger でホストされています。

生成された独自の Management API Swagger ドキュメントには、次の場所からアクセスできます。

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

名前	置換後の文字列
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"
  ]
}

属性	Type	説明
id	String	BLOB の一意識別子
name	String	BLOB のわかりやすい名前
parentId	String	BLOB を (スペース、デバイス、またはユーザー) と関連付ける親エンティティ
type	String	BLOB の種類。type と typeId は使用できません
Typeid	Integer	BLOB の種類の ID。type と typeId は使用できません
サブタイプ	String	BLOB のサブタイプ。subtype と subtypeId は使用できません
subtypeId	Integer	BLOB のサブタイプ ID。subtype と subtypeId は使用できません
共有	String	BLOB を共有できるかどうか - 列挙型 [`None`、`Tree`、`Global`]
description	String	BLOB のカスタマイズした説明
contentInfos	Array	バージョンを含む構造化されていないメタデータ情報を指定します
Fullname	String	BLOB の完全な名前
spacePaths	String	スペースパス

BLOB マルチパート要求の例

次の例では、YOUR_MANAGEMENT_API_URL は Digital Twins API の URI を参照しています。

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

名前	置換後の文字列
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--

値	置換後の文字列
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 をデバイスにアタッチできます。次の図では、Management API に関する Swagger のリファレンスドキュメントを示します。 BLOB を使用するためのデバイス関連の API エンドポイントと、それらに渡す必要があるパスパラメーターが指定されています。

たとえば、BLOB を更新または作成して、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
また、それぞれのマルチパートチャンクに適切な対応する Content-Type が含まれていることも確認します。
2 つ目の一般的なエラーは、空間インテリジェンスグラフ内の同じリソースに複数の BLOB が割り当てられている場合に発生します。
```
{
    "error": {
        "code": "400.600.000.000",
        "message": "SpaceBlobMetadata already exists."
    }
}
```
Note

message 属性は、リソースによって異なります。

空間グラフ内の各リソースには、(各種類の) BLOB を 1 つだけアタッチできます。

このエラーを解決するには、適切な API HTTP PATCH 操作を使用して、既存の BLOB を更新します。これにより、既存の BLOB データが目的のデータに置き換えられます。

次のステップ

Azure Digital Twins に関する Swagger の参照ドキュメントについて詳しくは、Azure Digital Twins Swagger の使用方法に関する記事をご覧ください。
Postman を通して BLOB をアップロードする場合は、Postman を構成する方法に関するページを参照してください。

Azure Digital Twins 内のオブジェクトに BLOB を追加する

BLOB のアップロードの概要

BLOB のメタデータ

BLOB の応答データ

BLOB マルチパート要求の例

API エンドポイント

デバイス

スペース

ユーザー

一般的なエラー

次のステップ

その他のリソース