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

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

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

前提条件

• Azure アカウントが必要 (無料で設定できます)

• ご利用の Azure サブスクリプションに Azure Digital Twins インスタンスが必要となります。 まだインスタンスをお持ちでない場合は、「インスタンスと認証を設定する」の手順を使用して作成してください。 セットアップ中、次の値をメモしておいてください。後でこの記事の中で使用します。

  • インスタンス名
  • Resource group

  これらの詳細については、インスタンスの設定後に、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 エンドポイントのために使用できます。

ポータル

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

1. インスタンスのメニューから、 [エンドポイント] を選択します。 次に、 [エンドポイント] ページで、 [+ エンドポイントの作成] を選択します。 そうすると、[エンドポイントの作成] ページが開きます。フィールドには以降の手順で入力します。

   

2. エンドポイントの [名前] を入力し、 [エンドポイントの種類] を選択します。

3. サブスクリプションや 前述のエンドポイント リソースなど、エンドポイントの種類に必要なその他の詳細を入力します。

   1. Event Hubs と Service Bus エンドポイントの場合のみ、[認証の種類] を選択する必要があります。 事前に作成された承認規則、またはシステム割り当てマネージド ID またはユーザー割り当てマネージド ID でキーベースの認証を使用できます。 ID 認証オプションの使用の詳細については、「 エンドポイント オプション: ID ベースの認証」を参照してください。

   

4. [保存] を選択して、エンドポイントの作成を終了します。

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

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

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

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

CLI

次の例では、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 コンテナーなど、Azure AD で保護された他のリソースにインスタンスが簡単にアクセスするのに役立つ場合があります。 マネージド ID には、"システム割り当て" と "ユーザー割り当て" があります。

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

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

好みのエクスペリエンスに一致する手順については、以下のタブを使用してください。

ポータル

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

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

CLI

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

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

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

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 データ共同作成者

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

ポータル

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

1. ポータルの検索バーで名前を検索して、お使いのエンドポイント リソース (イベント ハブ、Service Bus トピック、またはストレージ コンテナー) に移動します。

2. [アクセス制御 (IAM)] を選択します。

3. [追加][ロールの割り当ての追加] を選択して、[ロールの割り当ての追加] ページを開きます。

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

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

   

CLI

指定したロールを持つ 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 ベースの認証に変更することはできません。 最初にエンドポイントを作成するときに、認証の種類を選択する必要があります。

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

ポータル

一般的な手順に従って 、Azure Digital Twins エンドポイントを作成します。

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

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

CLI

マネージド 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 アカウントでこれらのストレージ リソースを設定し、次のセクションでエンドポイント接続の設定を準備します。

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

SAS トークンを作成する

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

ポータル

1. まず、Azure portal でご自分のストレージ アカウントに移動します (ポータルの検索バーを使って名前で見つけることができます)。

2. ストレージ アカウントのページで、左側のナビゲーション バーの [Shared Access Signature] リンクを選択し、SAS トークンの設定を開始します。

   

3. Shared Access Signature のページの [使用できるサービス] と [使用できるリソースの種類] で、目的の設定を選択します。 カテゴリごとに少なくとも 1 つのボックスを選択する必要があります。 [与えられているアクセス許可] で [書き込み] を選択します (必要に応じて他のアクセス許可を選択することもできます)。

4. 残りの設定には、任意の値を設定します。

5. 完了後、 [SAS と接続文字列を生成する] ボタンを選択して SAS トークンを生成します。

   

6. そうすると、同じページの下部の選択した設定の下に、いくつかの SAS と接続文字列の値が生成されます。 下にスクロールして値を表示し、 [クリップボードにコピー] アイコンを使用して SAS トークン値をコピーします。 後で使用するために保存します。

   

CLI

1. 次のコマンドを使用してストレージ アカウント キーを取得し、いずれかのキーの値をコピーします。

   az storage account keys list --account-name <storage-account-name>
   

2. 次のコマンドを使用して、有効期限を選択し、ストレージ アカウントの 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" の "サービス" と、"object" の "リソースの種類" が含まれ、"write" の "権限" を許可しています。

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

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

ポータル

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

この種類のエンドポイントを、Azure CLI を使用して作成する方法の手順については、このセクションの [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 つのルートで、複数の通知とイベントの種類を選択できるようにします。 引き続き、「ルートとフィルターの作成」でエンドポイントへのイベント ルートを作成します。