データレジストリの作成方法

[アーティクル]
08/07/2023

データレジストリサービスを使用すると、Azure Maps アカウントを使用して Azure Storage アカウントにデータコンテンツを登録できます。データの例として、Azure Maps ジオフェンシングサービスで使用されるジオフェンスのコレクションなどがあります。他の例としては、Azure Maps でフロアガイドの作成・更新に使用される、描画パッケージ (DWG) や GeoJSON ファイルが格納された ZIP ファイルがあります。

前提条件

重要

この記事では、地理的な URL us.atlas.microsoft.comを使用します。米国内で作成さたアカウントでない場合は、別の地理的な URL を使用する必要があります。詳細については、「Creator サービスにアクセスする」を参照してください。
この記事の URL 例では、次の内容を置き換える必要があります。
- {Azure-Maps-Subscription-key} を Azure Maps サブスクリプションキーに置き換えます。
- {udid} をデータレジストリのユーザーデータ ID に置き換えます。詳細については、「ユーザーデータ ID」を参照してください。

Azure Maps にデータを登録する準備

Azure Maps にデータを登録する前に、必要なすべてのコンポーネントを含む環境を作成する必要があります。登録するファイルを格納したコンテナーを 1 つ以上持つストレージアカウントと、認証用のマネージド ID が必要です。このセクションでは、Azure Maps にデータを登録するために Azure 環境を準備する方法について説明します。

マネージド ID を作成する

マネージド ID には、システム割り当てとユーザー割り当ての 2 種類があります。システム割り当てマネージド ID のライフサイクルは、それらを作成したリソースに関連付けられています。ユーザー割り当てマネージド ID は、複数のリソースで使用できます。詳細については、「Azure リソース用マネージド ID」を参照してください。

次の手順に従い、マネージド ID を作成して Azure Maps アカウントに追加します。

システム割り当て
ユーザー割り当て

システム割り当てマネージド ID を作成する:

Azure portal で Azure Maps アカウントに移動します。
左側のメニューから [ID] を選択します。
[状態] を [オン] に切り替えます。

詳細については、「Azure リソース用マネージド ID」を参照してください。

コンテナーを作成してデータファイルをアップロードする

データレジストリにファイルを追加する前に、Azure ストレージアカウントのコンテナーにファイルをアップロードする必要があります。コンテナーは、ファイルシステムにおけるディレクトリに似ており、Azure ストレージアカウントでファイルを整理するために使用します。

Azure portal でコンテナーを作るには、次の手順のようにします。

Azure ストレージアカウント内から、ナビゲーションウィンドウの [データストレージ] セクションから [コンテナー] を選択します。
[コンテナー] ペインで [+ コンテナー] を選択して、[新しいコンテナー] ペインを表示します。
[作成] を選択して、コンテナーを作成します。

コンテナーが作成できたら、そのコンテナーにファイルをアップロードできます。
コンテナーが作成できたら、コンテナーを選択します。
ツールバーで [アップロード] を選択し、1 つ以上のファイルを選択します
[アップロード] ボタンを選択します。

データストアを追加する

Azure ストレージアカウントを作成し、1 つ以上のコンテナーにファイルをアップロードした時点で、ストレージアカウントを Azure Maps アカウントにリンクさせるデータストアを作成する準備が整ったことになります。

重要

1 つの Azure Maps アカウントにリンクされているすべてのストレージアカウントは、同じ地理的な場所にある必要があります。詳しくは、「Azure Maps サービスの地域スコープ」をご覧ください。

Note

ストレージアカウントがない場合は、「ストレージアカウントの作成」を参照してください。

Azure Maps アカウントの左側のメニューから、[データストア] を選択します。
[追加] ボタンを選びます。右側に [データストアの追加] 画面が表示されます。
目的のデータストア ID を入力し、ドロップダウンリストからサブスクリプション名とストレージアカウントを選択します。
[追加] を選択します。

新しいデータストアがデータストアの一覧に表示されるようになります。

マネージド ID にロールを割り当て、データストアに追加する

マネージド ID とデータストアが作成されたら、そのマネージド ID をデータストアに追加し、同時にそれに共同作成者とストレージ BLOB データ閲覧者のロールを割り当てることができます。マネージド ID またはストレージアカウントで直接マネージド ID にロールを追加できますが、これは、同時にそれをデータストアペインで直接 Azure Maps データストアに関連付けながら簡単に行うことができます。

Note

データストアに関連付けられる各マネージド ID には、共同作成者ロールとストレージ BLOB データ閲覧者ロールが付与されている必要があります。マネージド ID にロールを付与するために必要なアクセス許可がない場合は、Azure 管理者に相談してください。マネージド ID にロールを割り当て、データストアに関連付ける方法:

Azure Maps アカウントの左側のメニューから、[データストア] を選択します。
リストからデータストアを 1 つ以上選択し、[ロールを割り当てる] を選択します。
選択したデータストアに関連付けるマネージド ID をドロップダウンリストから選択します。
[割り当てるロール] ドロップダウンリストで、[共同作成者] と [ストレージ BLOB データ閲覧者] の両方を選択します。
[割り当て] ボタンを選択します。

データレジストリのプロパティ

Azure Maps アカウントにデータストアが作成されたので、データレジストリの作成に必要なプロパティを収集する準備が整いました。

HTTP 要求の本文で渡す AzureBlob プロパティと、URL で渡されるユーザーデータ ID があります。

AzureBlob

AzureBlob は、データレジストリの作成に必要なプロパティを定義する JSON オブジェクトです。

プロパティ	説明
`kind`	登録するオブジェクトの種類を定義します。現在、サポートされている種類は AzureBlob のみです。
`dataFormat`	blobUrl にあるファイルのデータ形式。空間サービス用の GeoJSON、変換サービス用の ZIP のいずれかの形式を指定できます。
`msiClientId`	データレジストリの作成に使用するマネージド ID の ID。
`linkedResource`	Azure Maps アカウントに登録するデータストアの ID。データストアには、登録されるファイルへのリンクが含まれています。
`blobUrl`	コンテナーにインポートされたファイルである AzurebBlob の場所を示す URL。

次の 2 つのセクションでは、msiClientId プロパティと blobUrl プロパティに使用する値を取得する方法について詳細に説明します。

msiClientId プロパティ

msiClientId プロパティは、データレジストリの作成に使用するマネージド ID の IDです。マネージド ID には、システム割り当てとユーザー割り当ての 2 種類があります。システム割り当てマネージド ID のライフサイクルは、それらを作成したリソースに関連付けられています。ユーザー割り当てマネージド ID は、複数のリソースで使用できます。詳細については、「Azure リソース用マネージド ID」を参照してください。

システム割り当て
ユーザー割り当て

システム割り当てマネージド ID を使用する場合、msiClientId プロパティに値を指定する必要はありません。 msiClientId が null である場合、データレジストリサービスでは Azure Maps アカウントのシステム割り当て ID を自動的に使用します。

blobUrl プロパティ

blobUrl プロパティは、登録されるファイルへのパスです。この値は、データレジストリに追加されたコンテナーから取得できます。

Azure portal で、お使いのストレージアカウントを選択します。
左側のメニューから [コンテナー] を選択します。
コンテナーの一覧が表示されます。登録するファイルが格納されているコンテナーを選択します。
コンテナーが開き、以前にアップロードしたファイルの一覧が表示されます。
目的のファイルを選択し、URL をコピーします。

ユーザーデータ ID

データレジストリのユーザーデータ ID (udid) はユーザー定義の GUID であり、次の Regex パターンに従う必要があります。

^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$

ヒント

udid はユーザー定義の GUID であり、データレジストリの作成時に指定する必要があります。グローバル一意識別子 (GUID) を確実に指定したい場合は、Guidgen.exe コマンドラインプログラム (Visual Studio で使用可能) などの GUID 生成ツールを実行して作成することを検討してください。

データレジストリを作成する

目的のファイルを格納したストレージアカウントをデータストア経由で Azure Maps アカウントにリンクし、必要なプロパティをすべて収集したので、データレジストリ API を使用してこれらのファイルを登録する準備ができました。登録するファイルが Azure ストレージアカウントに複数ある場合は、ファイル (udid) ごとに登録要求を実行する必要があります。

Note

Azure Maps データストアに登録できるファイルの最大サイズは、1 ギガバイトです。

データレジストリを作成する:

システム割り当て
ユーザー割り当て

データレジストリに追加するストレージアカウントを参照するために必要な情報を HTTP 要求の本文内で指定します。情報は JSON 形式で、以下のフィールドを含んでいる必要があります。
```
{
"kind": "AzureBlob",
    "azureBlob": {
        "dataFormat": "geojson",
        "linkedResource": "{datastore ID}",
        "blobUrl": "https://teststorageaccount.blob.core.windows.net/testcontainer/test.geojson"
    }
}
```
Note

システム割り当てマネージド ID を使用している場合、HTTP 要求で msiClientId プロパティの値を指定するとエラーが発生します。

HTTP 要求本文に必要なプロパティの詳細については、「データレジストリのプロパティ」を参照してください。
HTTP 要求の本文が準備できたら、次の HTTP PUT 要求を実行します。
```
https://us.atlas.microsoft.com/dataRegistries/{udid}?api-version=2023-06-01&subscription-key={Your-Azure-Maps-Subscription-key} 
```
udid プロパティの詳細については、「ユーザーデータ ID」を参照してください。
応答ヘッダーから Operation-Location キーの値をコピーします。

データレジストリに追加するストレージアカウントを参照するために必要な情報を HTTP 要求の本文内で指定します。情報は JSON 形式で、以下のフィールドを含んでいる必要があります。
```
{
"kind": "AzureBlob",
    "azureBlob": {
        "dataFormat": "geojson",
        "msiClientId": "{The client ID of the managed identity}",
        "linkedResource": "{datastore ID}",
        "blobUrl": "https://teststorageaccount.blob.core.windows.net/testcontainer/test.geojson"
    }
}
```
Note

ユーザー割り当てマネージド ID を使用している場合、HTTP 要求で msiClientId プロパティの値を指定しないとエラーが発生します。

HTTP 要求本文に必要なプロパティの詳細については、「データレジストリのプロパティ」を参照してください。
HTTP 要求の本文が準備できたら、次の HTTP PUT 要求を実行します。
```
https://us.atlas.microsoft.com/dataRegistries/{udid}?api-version=2023-06-01&subscription-key={Your-Azure-Maps-Subscription-key} 
```
udid プロパティの詳細については、「ユーザーデータ ID」を参照してください。
応答ヘッダーから Operation-Location キーの値をコピーします。

ヒント

以前に登録したファイルの内容が変更された場合、そのファイルのデータ検証が失敗し、再登録されるまで Azure Maps では使用できなくなります。ファイルを再登録するには、元の登録の作成に使用したのと同じ AzureBlob を渡して登録要求を再実行します。 Operation-Location キーの値は、次のセクションで行うデータレジストリの作成状態の確認で使用する状態 URL です。これには、GET 操作 API で使用される操作 ID が含まれています。

Note

Operation-Location キーの値に、subscription-key は含まれません。データレジストリの作成状態を確認する際に使用する場合は、要求 URL に追加する必要があります。

データレジストリの作成状態を確認する

(必要に応じて) データレジストリ作成プロセスの状態を確認するには、「データレジストリを作成する」セクションでコピーした状態 URL を入力し、クエリ文字列パラメーターとしてサブスクリプションキーを追加します。要求は次の URL のようなものになります。

https://us.atlas.microsoft.com/dataRegistries/operations/{udid}?api-version=2023-06-01&subscription-key={Your-Azure-Maps-Primary-Subscription-key}

データレジストリ内のすべてのファイルのリストを取得する

Azure Maps アカウントに登録されているすべてのファイルの一覧を取得するには、List 要求を使用します。

https://us.atlas.microsoft.com/dataRegistries?api-version=2023-06-01&subscription-key={Azure-Maps-Subscription-key}

次のサンプルは、完了、実行中、失敗という、可能性のある 3 つの状態を示しています。

{
  "value": [
    {
      "udid": "f6495f62-94f8-0ec2-c252-45626f82fcb2",
      "description": "Contoso Indoor Design",
      "kind": "AzureBlob",
      "azureBlob": {
        "dataFormat": "zip",
        "msiClientId": "3263cad5-ed8b-4829-b72b-3d1ba556e373",
        "linkedResource": "my-storage-account",
        "blobUrl": "https://mystorageaccount.blob.core.windows.net/my-container/my/blob/path1.zip",
        "sizeInBytes": 29920,
        "contentMD5": "CsFxZ2YSfxw3cRPlqokV0w=="
      },
      "status": "Completed"
    },
    {
      "udid": "8b1288fa-1958-4a2b-b68e-13a7i5af7d7c",
      "kind": "AzureBlob",
      "azureBlob": {
        "dataFormat": "geojson",
        "msiClientId": "3263cad5-ed8b-4829-b72b-3d1ba556e373",
        "linkedResource": "my-storage-account",
        "blobUrl": "https://mystorageaccount.blob.core.windows.net/my-container/my/blob/path2.geojson",
        "sizeInBytes": 1339
      },
      "status": "Running"
    },
    {
      "udid": "7c1288fa-2058-4a1b-b68f-13a6h5af7d7c",
      "description": "Contoso Geofence GeoJSON",
      "kind": "AzureBlob",
      "azureBlob": {
        "dataFormat": "geojson",
        "linkedResource": "my-storage-account",
        "blobUrl": "https://mystorageaccount.blob.core.windows.net/my-container/my/blob/path3.geojson",
        "sizeInBytes": 1650,
        "contentMD5": "rYpEfIeLbWZPyaICGEGy3A=="
      },
      "status": "Failed",
      "error": {
        "code": "ContentMD5Mismatch",
        "message": "Actual content MD5: sOJMJvFParkSxBsvvrPOMQ== doesn't match expected content MD5: CsFxZ2YSfxw3cRPlqokV0w==."
      }
    }
  ]
}

List 要求の実行時に返されるデータは、レジストリの作成時に返されるデータと似ていますが、次のような追加項目がいくつかあります。

property	description
contentMD5	登録されるファイルの内容から作成された MD5 ハッシュ。詳しくは、「データの検証」を参照してください
sizeInBytes	内容のサイズ (バイト単位)。

データレジストリを置き換える

以前に登録したファイルを別のファイルに置き換える必要がある場合は、blobUrl を除き、元の登録の作成に使用したのと同じ AzureBlob を渡して登録要求を再実行します。 BlobUrl は、新しいファイルを指すように変更する必要があります。

データの検証

データレジストリ API を使用して Azure Maps にファイルを登録すると、ファイルの内容から MD5 ハッシュが作成され、128 ビットのフィンガープリントにエンコードされて、AzureBlob に contentMD5 プロパティとして保存されます。 contentMD5 プロパティに格納されている MD5 ハッシュは、ファイルのデータ整合性を確保するために使用されます。 MD5 ハッシュアルゴリズムは、同じ入力を指定すると常に同じ出力を生成するため、データ検証プロセスでは、登録時のファイルの contentMD5 プロパティと Azure ストレージアカウント内のファイルのハッシュを比較することにより、ファイルが無傷で変更されていないことを確認できます。ハッシュが同じでない場合、検証は失敗します。基になるストレージアカウント内のファイルが変更された場合、検証は失敗します。 Azure Maps に登録されているファイルの内容を変更する必要がある場合は、それを再び登録する必要があります。

データ レジストリの作成方法

前提条件

Azure Maps にデータを登録する準備

マネージド ID を作成する

コンテナーを作成してデータ ファイルをアップロードする

データストアを追加する

マネージド ID にロールを割り当て、データストアに追加する

データ レジストリのプロパティ

AzureBlob

msiClientId プロパティ

blobUrl プロパティ

ユーザー データ ID

データ レジストリを作成する

データ レジストリの作成状態を確認する

データ レジストリ内のすべてのファイルのリストを取得する

データ レジストリを置き換える

データの検証

その他のリソース

データレジストリの作成方法

コンテナーを作成してデータファイルをアップロードする

データレジストリのプロパティ

ユーザーデータ ID

データレジストリを作成する

データレジストリの作成状態を確認する

データレジストリ内のすべてのファイルのリストを取得する

データレジストリを置き換える