Azure Digital Twins でエンドポイントを作成する

[アーティクル]
04/06/2023

この記事では、Azure portal または Azure CLI を使用して、Azure Digital Twin イベントのエンドポイントを作成する方法について説明します。 DigitalTwinsEndpoint コントロールプレーン API を使用してエンドポイントを管理することもできます。

Azure Digital Twins からダウンストリームサービスまたは接続されたコンピューティングリソースにイベント通知をルーティングするには、エンドポイントを作成してから、それらのエンドポイントにデータを送信するイベントルートを作成する 2 つの手順があります。この記事では、イベントを受信できるエンドポイントを設定する最初の手順について説明します。その後、Azure Digital Twins によって生成されるどのイベントをどのエンドポイントに配信するかを指定するイベントルートを作成できます。

前提条件

Azure アカウントが必要 (無料で設定できます)
ご利用の Azure サブスクリプションに Azure Digital Twins インスタンスが必要となります。まだインスタンスをお持ちでない場合は、「インスタンスと認証を設定する」の手順を使用して作成してください。セットアップ中、次の値をメモしておいてください。後でこの記事の中で使用します。
- インスタンス名
- リソースグループ
これらの詳細については、インスタンスの設定後に、Azure portal で確認できます。

次に、このガイドに従って Azure CLI を使用する場合は、次の手順に従ってください。

Azure CLI の環境を準備する

Azure Cloud Shell で Bash 環境を使用します。詳細については、「Azure Cloud Shell の Bash のクイックスタート」を参照してください。
CLI リファレンスコマンドをローカルで実行する場合、Azure CLI をインストールします。 Windows または macOS で実行している場合は、Docker コンテナーで Azure CLI を実行することを検討してください。詳細については、「Docker コンテナーで Azure CLI を実行する方法」を参照してください。
- ローカルインストールを使用する場合は、az login コマンドを使用して Azure CLI にサインインします。認証プロセスを完了するには、ターミナルに表示される手順に従います。その他のサインインオプションについては、Azure CLI でのサインインに関するページを参照してください。
- 初回使用時にインストールを求められたら、Azure CLI 拡張機能をインストールします。拡張機能の詳細については、Azure CLI で拡張機能を使用する方法に関するページを参照してください。
- az version を実行し、インストールされているバージョンおよび依存ライブラリを検索します。最新バージョンにアップグレードするには、az upgrade を実行します。

必要なリソースを作成する

インスタンスのために作成できる、サポートされているエンドポイントの種類は次のとおりです。

Event Grid トピック
- Event Grid エンドポイントの場合は、Event Grid トピックのみがサポートされます。 Event Grid ドメインは、エンドポイントとしてサポートされていません。
Event Hubs ハブ
Service Bus トピック

エンドポイントを Azure Digital Twins にリンクするには、エンドポイントで使おうとしている Event Grid トピック、イベントハブ、または Service Bus トピックが既に存在している必要があります。

次の表を使用して、エンドポイントを作成する前に設定する必要があるリソースを確認してください。

[エンドポイントの種類]	必要なリソース (作成手順にリンクされています)
Event Grid エンドポイント	Event Grid トピック *イベントスキーマは、Event Grid スキーマまたは Cloud Event スキーマ v1.0 である必要があります
Event Hubs エンドポイント	Event Hubs 名前空間イベントハブ (省略可能) キーベースの認証用の承認規則
Service Bus のエンドポイント	Service Bus 名前空間 Service Bus トピック (省略可能) キーベースの認証用の承認規則

エンドポイントを作成する

エンドポイントリソースを作成したら、それらを Azure Digital Twins エンドポイントのために使用できます。

ポータル
CLI

新しいエンドポイントを作成するには、Azure portal でインスタンスのページに移動します (ポータルの検索バーにインスタンスの名前を入力することで、それを見つけることができます)。

インスタンスのメニューから、[エンドポイント] を選択します。次に、[エンドポイント] ページで、[+ エンドポイントの作成] を選択します。そうすると、[エンドポイントの作成] ページが開きます。フィールドには以降の手順で入力します。
エンドポイントの [名前] を入力し、[エンドポイントの種類] を選択します。
エンドポイントの種類にとって必要なその他の詳細 (サブスクリプションや前に説明したエンドポイントリソースなど) を入力します。
1. Event Hubs と Service Bus エンドポイントの場合のみ、[認証の種類] を選択する必要があります。事前に作成された承認規則、またはシステム割り当てマネージド ID またはユーザー割り当てマネージド ID で、キーベースの認証を使用できます。 ID 認証オプションの使用の詳細については、「エンドポイントオプション: ID ベースの認証」を参照してください。
[保存] を選択して、エンドポイントの作成を終了します。

エンドポイントを作成したら、上部の Azure portal バーの通知アイコンを確認することで、エンドポイントが正常に作成されたことを確認できます。

Azure portal のエンドポイントの作成を確認する通知のスクリーンショット。

エンドポイントの作成に失敗した場合は、エラーメッセージを確認し、数分後に再試行してください。

また、Azure Digital Twins インスタンスの [エンドポイント] ページに戻って、作成したエンドポイントを表示することもできます。

これで、エンドポイント用に選択した名前で、Event Grid トピック、イベントハブ、または Service Bus トピックを、Azure Digital Twins 内のエンドポイントとして使用できるようになりました。通常は、その名前をイベントルートのターゲットとして使用します。この名前は、[ルートとフィルターの作成] で作成できます。

次の例では、Azure Digital Twins CLI の az dt endpoint create コマンドを使用してエンドポイントを作成する方法を示します。コマンドのプレースホルダーは、独自のリソースの詳細に置き換えます。

Event Grid エンドポイントを作成するには:

az dt endpoint create eventgrid --endpoint-name <Event-Grid-endpoint-name> --eventgrid-resource-group <Event-Grid-resource-group-name> --eventgrid-topic <your-Event-Grid-topic-name> --dt-name <your-Azure-Digital-Twins-instance-name>

Event Hubs エンドポイントを作成するには (キーベース認証):

az dt endpoint create eventhub --endpoint-name <Event-Hub-endpoint-name> --eventhub-resource-group <Event-Hub-resource-group> --eventhub-namespace <Event-Hub-namespace> --eventhub <Event-Hub-name> --eventhub-policy <Event-Hub-policy> --dt-name <your-Azure-Digital-Twins-instance-name>

Service Bus トピックエンドポイントを作成するには (キーベース認証):

az dt endpoint create servicebus --endpoint-name <Service-Bus-endpoint-name> --servicebus-resource-group <Service-Bus-resource-group-name> --servicebus-namespace <Service-Bus-namespace> --servicebus-topic <Service-Bus-topic-name> --servicebus-policy <Service-Bus-topic-policy> --dt-name <your-Azure-Digital-Twins-instance-name>

これらのコマンドが正常に実行されると、Event Grid トピック、イベントハブ、または Service Bus トピックを、Azure Digital Twins 内のエンドポイントとして、--endpoint-name 引数で指定した名前で使用できるようになります。通常は、その名前をイベントルートのターゲットとして使用します。この名前は、[ルートとフィルターの作成] で作成できます。

エンドポイントオプション: ID ベースの認証

このセクションでは、サポートされているルーティング先にイベントを転送するときに、Azure Digital Twins のインスタンスのマネージド ID を使用する方法を説明します。ルーティングにはマネージド ID の設定は必要ありませんが、Event Hubs、Service Bus 宛先、Azure Storage コンテナーなど、Microsoft Entra で保護された他のリソースにインスタンスが簡単にアクセスするのに役立つ場合があります。マネージド ID には、"システム割り当て" と "ユーザー割り当て" があります。

このセクションの残りの部分では、マネージド ID を使用してエンドポイントを設定するための 3 つの手順について説明します。

1.インスタンスのマネージド ID を有効にする

以下のタブを使用して、好みのエクスペリエンスの手順を確認してください。

ポータル
CLI

まず、Azure Digital Twins インスタンスに対してマネージド ID が有効になっていることを確認します。

また、そのインスタンスについて Azure Digital Twins データ所有者 ロールを持っていることを確認します。手順については、「ユーザーのアクセス許可を設定する」を参照してください。

2.Azure ロールを ID に割り当てる

Azure Digital Twins インスタンス用のマネージド ID が作成されたら、適切なロールを割り当てて、サポートされている送信先にイベントをルーティングするためにさまざまな種類のエンドポイントで認証を行うようにする必要があります。このセクションでは、ロールのオプションと、それらをマネージド ID に割り当てる方法について説明します。

重要

必ずこの手順を完了してください。行わないと、ID はエンドポイントにアクセスできず、イベントは配信されません。

送信先の種類に応じて、Azure Digital Twins ID がエンドポイントにアクセスするために必要な最小限のロールを次に示します。さらに高いアクセス許可を持つロール (データ所有者ロールなどの) も機能します。

宛先	Azure ロール
Azure Event Hubs	Azure Event Hubs データ送信者
Azure Service Bus	Azure Service Bus データ送信者
[Azure ストレージコンテナー]	ストレージ BLOB データ共同作成者

次のタブを使用して、好みのエクスペリエンスを使用してロールを割り当てます。

ポータル
CLI

ID にロールを割り当てるには、まずブラウザーで Azure portal を開きます。

ポータルの検索バーで名前を検索して、お使いのエンドポイントリソース (イベントハブ、Service Bus トピック、またはストレージコンテナー) に移動します。
[アクセス制御 (IAM)] を選択します。
[追加]>[ロールの割り当ての追加] を選択して、[ロールの割り当ての追加] ページを開きます。

以下の情報を使用して、目的のロールを Azure Digital Twins インスタンスのマネージド ID に割り当てます。詳細な手順については、「Azure portal を使用して Azure ロールを割り当てる」を参照してください。

設定	値
ロール	オプションから目的のロールを選択します。
アクセスの割り当て先	マネージド ID
メンバー	ロールを割り当てる Azure Digital Twins インスタンスのユーザー割り当てまたはシステム割り当てのマネージド ID を選択します。ユーザー割り当て ID には ID の作成時に選択した名前が付けられ、システム割り当て ID には Azure Digital Twins インスタンスの名前と一致する名前が付けられます。

指定したロールを持つ 1 つ以上のスコープに ID を割り当てるために、--scopes パラメーターを az dt create コマンドに追加できます。このパラメーターを付加したコマンドは、最初にインスタンスを作成するときに使用することもできますし、既存のインスタンスの名前を渡すことで後から使用することもできます。

次の例では、システム割り当てマネージド ID を持つインスタンスを作成し、その ID にイベントハブの MyCustomRole という名前のカスタムロールを割り当てています。

az dt create --dt-name <new-instance-name> --resource-group <resource-group> --mi-system-assigned --scopes "/subscriptions/<subscription ID>/resourceGroups/<resource-group>/providers/Microsoft.EventHub/namespaces/<Event-Hubs-namespace>/eventhubs/<event-hub-name>" --role MyCustomRole

このコマンドを使用したロールの割り当てのその他の例については、「az dt create のリファレンスドキュメント」を参照してください。

また、ロールを作成および管理するために、az role assignment コマンドグループも使用できます。このコマンドは、create コマンドでロールの割り当てをグループ化したくない場合の別のシナリオをサポートするために使用できます。

3.ID ベースの認証を使用してエンドポイントを作成する

Azure Digital Twins インスタンスのマネージド ID を設定し、適切なロールを割り当てた後、認証に ID を使用するエンドポイントを作成できます。このオプションは、種類が Event Hubs と Service Bus のエンドポイントでのみ使用できます (Event Grid ではサポートされていません)。

Note

キーベースの ID で既に作成されているエンドポイントを編集して、ID ベースの認証に変更することはできません。最初にエンドポイントを作成するときに、認証の種類を選択する必要があります。

次のタブを使用して、好みのエクスペリエンスを使用してエンドポイントを作成します。

ポータル
CLI

まず、こちらの Azure Digital Twins のエンドポイントを作成する一般的な手順に従います。

エンドポイントの種類に必要な詳細を設定するステップになったら、[認証の種類] で [システム割り当て] または [ユーザー割り当て] (プレビュー) を選択します。

エンドポイントの設定を終了し、[保存] を選択します。

マネージド ID は、エンドポイントの作成に使用される az dt endpoint create コマンドにパラメーターを追加することによってエンドポイントに追加されます。 (このコマンドの詳細については、その「リファレンスドキュメント」または「Azure Digital Twins エンドポイントを設定するための一般的な手順」を参照してください)。

選択したマネージド ID の種類に応じて、次の CLI コマンドを使用します。

システム割り当て ID コマンド

システム割り当ての認証を使用するエンドポイントを作成するには、--auth-type パラメーターを使用して IdentityBased 認証の種類を指定します。下の例は、Event Hubs エンドポイントに対するこの機能を示しています。

az dt endpoint create eventhub --endpoint-name <endpoint-name> --eventhub-resource-group <eventhub-resource-group> --eventhub-namespace <eventhub-namespace> --eventhub <eventhub-name> --dt-name <instance-name> --auth-type IdentityBased

ユーザー割り当て ID コマンド

ユーザー割り当て ID 認証を使用するエンドポイントを作成するには、--user パラメーターを使用してユーザー割り当て ID リソース ID を指定します。下の例は、Event Hubs エンドポイントに対するこの機能を示しています。

az dt endpoint create eventhub --endpoint-name <endpoint-name> --eventhub-resource-group <eventhub-resource-group> --eventhub-namespace <eventhub-namespace> --eventhub <eventhub-name> --dt-name <instance-name> --user <user-assigned-identity-resource-ID>

マネージド ID を無効にする場合の考慮事項

ID は、それを使用するエンドポイントとは別に管理されているため、ID またはそのロールを変更したときの Azure Digital Twins インスタンスのエンドポイントに対する影響について考慮することが重要です。 ID を無効にした場合、またはエンドポイントに必要なロールを削除した場合、エンドポイントにアクセスできなくなり、イベントのフローが中断される可能性があります。

設定されていたマネージド ID を無効にした後もエンドポイントを引き続き使用するには、エンドポイントを削除し、異なる認証の種類で再作成する必要があります。この変更を行った後、エンドポイントへのイベントの配信が再開されるまで、最大で 1 時間かかることがあります。

エンドポイントオプション: 配信不能

エンドポイントでは、一定期間内にイベントを配信できない場合や、イベントの配信を一定回数試行した後も配信できない場合、未配信イベントをストレージアカウントに送信できます。このプロセスは配信不能処理と呼ばれます。

必要なストレージリソースは、Azure portal または Azure Digital Twins CLI を使用して設定できます。ただし、配信不能処理が有効なエンドポイントを作成するには、Azure Digital Twins CLI またはコントロールプレーン API を使用する必要があります。

配信不能処理の詳細については、「エンドポイントとイベントルート」を参照してください。配信不能処理を構成してエンドポイントを設定する方法については、このセクションの残りの部分を読み進めます。

ストレージリソースを設定する

配信不能の場所を設定するには、ご使用の Azure アカウントにコンテナーが設定されたストレージアカウントが必要です。

後でエンドポイントを作成するときに、このコンテナーの URI を指定します。配信不能の場所は、SAS トークンを含むコンテナー URI としてエンドポイントに提供されます。このトークンには、ストレージアカウント内の宛先コンテナーに対する write アクセス許可が必要です。完全形式の配信不能 SAS URI は、https://<storage-account-name>.blob.core.windows.net/<container-name>?<SAS-token> の形式になります。

以下の手順に従って、Azure アカウントでこれらのストレージリソースを設定し、次のセクションでエンドポイント接続の設定を準備します。

「ストレージアカウントを作成する」の手順に従って、Azure サブスクリプションにストレージアカウントを作成します。後で使用するために、そのストレージアカウント名を書き留めておきます。
「コンテナーを作成する」の手順に従って、新しいストレージアカウント内にコンテナーを作成します。後で使用するために、そのコンテナー名を書き留めておきます。

SAS トークンを作成する

次に、ストレージアカウント用に SAS トークンを作成して、エンドポイントからアクセスするときにこれを使用できるようにします。

ポータル
CLI

まず、Azure portal でご自分のストレージアカウントに移動します (ポータルの検索バーを使って名前で見つけることができます)。
ストレージアカウントのページで、左側のナビゲーションバーの [Shared Access Signature] リンクを選択し、SAS トークンの設定を開始します。
Shared Access Signature のページの [使用できるサービス] と [使用できるリソースの種類] で、目的の設定を選択します。カテゴリごとに少なくとも 1 つのボックスを選択する必要があります。 [与えられているアクセス許可] で [書き込み] を選択します (必要に応じて他のアクセス許可を選択することもできます)。
残りの設定には、任意の値を設定します。
完了後、[SAS と接続文字列を生成する] ボタンを選択して SAS トークンを生成します。
そうすると、同じページの下部の選択した設定の下に、いくつかの SAS と接続文字列の値が生成されます。下にスクロールして値を表示し、[クリップボードにコピー] アイコンを使用して SAS トークン値をコピーします。後で使用するために保存します。

次のコマンドを使用してストレージアカウントキーを取得し、いずれかのキーの値をコピーします。
```
az storage account keys list --account-name <storage-account-name>
```
次のコマンドを使用して、有効期限を選択し、ストレージアカウントの SAS トークンを生成します。
```
az storage account generate-sas --account-name <storage-account-name> --account-key <storage-account-key> --expiry <expiration-date> --services bfqt --resource-types o --permissions w
```
このコマンドの出力は SAS トークンです。後で使用するために SAS トークン値をコピーします。

Note

このコマンドには、"blob"、"file"、"queue"、および "table" の "サービス" と、"object" の "リソースの種類" が含まれ、"write" の "権限" を許可しています。

az storage account generate-sas コマンドとそのパラメーターの詳細については、Azure CLI のリファレンスを参照してください。

配信不能処理が有効なエンドポイントを作成するには、Azure portal ではなく CLI コマンドまたはコントロールプレーン API を使用してエンドポイントを作成する必要があります。

この種類のエンドポイントを、Azure CLI を使用して作成する方法の手順については、このセクションの [CLI] タブに切り替えてください。

配信不能処理が有効なエンドポイントを作成するには、エンドポイントを作成する az dt endpoint create コマンドに --deadletter-sas-uri パラメーターを追加します。

パラメーターの値は、前のセクションで収集したストレージアカウント名、コンテナー名、SAS トークンで構成された配信不能 SAS URI です。このパラメーターにより、キーベースの認証を使用するエンドポイントが作成されます。パラメーターは次のようになります。

--deadletter-sas-uri https://<storage-account-name>.blob.core.windows.net/<container-name>?<SAS-token>

ヒント

ID ベースの認証を使用して配信不能エンドポイントを作成するには、このセクションの配信不能パラメーターと適切なマネージド ID パラメーターの両方を同じコマンドに追加します。

CLI の代わりに Azure Digital Twins コントロールプレーン API を使用して配信不能エンドポイントを作成することもできます。それを行うには、DigitalTwinsEndpoint のドキュメントを参照し、要求を構成して配信不能パラメーターを追加する方法を確認してください。

メッセージストレージスキーマ

配信不能処理を行うエンドポイントが設定されると、配信不能メッセージが次の形式でストレージアカウントに格納されます。

<container>/<endpoint-name>/<year>/<month>/<day>/<hour>/<event-ID>.json

配信不能メッセージは、元のエンドポイントに配信されることを意図していた元のイベントのスキーマと一致します。

次に、ツイン作成通知用の配信不能メッセージの例を示します。

{
  "specversion": "1.0",
  "id": "xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "type": "Microsoft.DigitalTwins.Twin.Create",
  "source": "<your-instance>.api.<your-region>.da.azuredigitaltwins-test.net",
  "data": {
    "$dtId": "<your-instance>xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "$etag": "W/\"xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx\"",
    "TwinData": "some sample",
    "$metadata": {
      "$model": "dtmi:test:deadlettermodel;1",
      "room": {
        "lastUpdateTime": "2020-10-14T01:11:49.3576659Z"
      }
    }
  },
  "subject": "<your-instance>xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "time": "2020-10-14T01:11:49.3667224Z",
  "datacontenttype": "application/json",
  "traceparent": "00-889a9094ba22b9419dd9d8b3bfe1a301-f6564945cb20e94a-01"
}

次のステップ

Azure Digital Twins からエンドポイントに実際にデータを送信するには、イベントルートを定義する必要があります。これらのルートにより、開発者はシステム全体およびダウンストリームサービスへのイベントフローを結び付けることができます。 1 つのルートで、複数の通知とイベントの種類を選択できるようにします。引き続き、[ルートとフィルターの作成] でエンドポイントへのイベントルートを作成します。

次の方法で共有

Azure Digital Twins でエンドポイントを作成する

前提条件

Azure CLI の環境を準備する

必要なリソースを作成する

エンドポイントを作成する

エンドポイントオプション: ID ベースの認証

1.インスタンスのマネージド ID を有効にする

2.Azure ロールを ID に割り当てる

3.ID ベースの認証を使用してエンドポイントを作成する

システム割り当て ID コマンド

ユーザー割り当て ID コマンド

マネージド ID を無効にする場合の考慮事項

エンドポイントオプション: 配信不能

ストレージリソースを設定する

SAS トークンを作成する

配信不能エンドポイントを作成する

メッセージストレージスキーマ

次のステップ

フィードバック

その他のリソース

次の方法で共有

Azure Digital Twins でエンドポイントを作成する

前提条件

Azure CLI の環境を準備する

必要なリソースを作成する

エンドポイントを作成する

エンドポイント オプション: ID ベースの認証

1.インスタンスのマネージド ID を有効にする

2.Azure ロールを ID に割り当てる

3.ID ベースの認証を使用してエンドポイントを作成する

マネージド ID を無効にする場合の考慮事項

エンドポイント オプション: 配信不能

ストレージ リソースを設定する

SAS トークンを作成する

配信不能エンドポイントを作成する

メッセージ ストレージ スキーマ

次のステップ

フィードバック

その他のリソース

エンドポイントオプション: ID ベースの認証

エンドポイントオプション: 配信不能

ストレージリソースを設定する

メッセージストレージスキーマ