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

2025-06-19

この記事では、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 の概要」を参照してください。
CLI リファレンスコマンドをローカルで実行する場合、Azure CLI をインストールします。 Windows または macOS で実行している場合は、Docker コンテナーで Azure CLI を実行することを検討してください。詳細については、「Docker コンテナーで Azure CLI を実行する方法」を参照してください。
- ローカルインストールを使用する場合は、az login コマンドを使用して Azure CLI にサインインします。認証プロセスを完了するには、ターミナルに表示される手順に従います。その他のサインインオプションについては、「 Azure CLI を使用した Azure への認証」を参照してください。
- 初回使用時にインストールを求められたら、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 スキーマまたはクラウドイベントスキーマ 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 を有効にした場合にのみ使用できます。 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 ではサポートされていません)。

注

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

好みのエクスペリエンスを使用してエンドポイントを作成するには、次のセクションを使用します。

ポータル
CLI

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

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

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

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

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

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

システム割り当ての認証を使用するエンドポイントを作成するには、IdentityBased パラメーターを使用して --auth-type 認証の種類を指定します。次の例は、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 でストレージアカウントに移動します (名前はポータルの検索バーで確認できます)。
ストレージアカウントページで、左側のナビゲーションバーの [セキュリティとネットワーク > 共有アクセス署名 ] リンクを選択して、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 トークン値をコピーします。

注

前のコマンドのパラメーターセットの例には、"blob"、"file"、"queue"、および "table" サービス (--services bfqt)、"object" リソースの種類 (--resource-types o)、および "write" アクセス許可 (--permissions w) があります。

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

デッドレタリングが有効なエンドポイントを作成するには、CLI コマンドまたはコントロールプレーン APIを使用してエンドポイントを作成します。この種類のエンドポイントは、Azure portal では作成できません。

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

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

パラメーターの値は、前のセクションで収集したストレージアカウント名、コンテナー名、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"
}

次のステップ

エンドポイントを作成したら、エンドポイントにデータを送信するイベントルートを定義します。イベントルートを使用すると、システム全体およびダウンストリームサービスへのイベントフローを設定できます。 1 つのルートで、複数の通知とイベントの種類を許可できます。「ルートとフィルターの作成」を参照して、エンドポイントへのイベントルートを作成します。