次の方法で共有


Azure Event Hubsを介して変更通知を受け取る

Webhook は、高スループットのシナリオで変更通知を受信する場合や、受信者が一般公開されている通知 URL を公開できない場合には適していません。 別の方法として、Azure Event Hubsを使用できます。

Azure Event Hubsを使用できる高スループットシナリオの例としては、大規模なリソースセットをサブスクライブするアプリケーション、頻繁に変更されるリソースをサブスクライブするアプリケーション、大規模な組織のリソースをサブスクライブするマルチテナント アプリケーションなどがあります。

この記事では、Microsoft Graph サブスクリプションを管理するプロセスと、Azure Event Hubsを通じて変更通知を受け取る方法について説明します。

重要

共有アクセス署名 (SAS) を使用して Event Hubs を認証することは、今後非推奨になる予定です。 代わりに、Microsoft Entra IDロールベースのアクセス制御 (RBAC) を使用して Event Hubs を認証することをお勧めします。

Azure Event Hubsを使用して変更通知を受信する

Azure Event Hubs は、一般的なリアルタイム イベントの取り込みと配布サービスであり、規模に合わせて構築されています。 変更通知の受け取りに Azure Event Hub を使用する方法は、次のような点で Webhook とは異なります。

  • 公開されている通知 URL には依存しません。 Event Hubs SDK は、アプリケーションに通知を中継します。
  • 通知 URL の検証に返信する必要はありません。 受信した検証メッセージは無視してかまいません。
  • イベント ハブをプロビジョニングする必要があります。
  • Azure Key Vaultをプロビジョニングするか、Microsoft Graph Change Tracking サービスをイベント ハブのデータ送信者ロールに追加する必要があります。

Azure Event Hubs認証を設定する

Azure Event Hubsでは、共有アクセス署名 (SAS) またはロールベースのアクセス制御 (RBAC) Microsoft Entra IDによる認証がサポートされます。 詳細については、「Azure Event Hubsへのアクセスを承認する」を参照してください。

このセクションでは、Azure portal Microsoft Entra IDロールベースのアクセス制御 (RBAC) を使用してAzure Event Hubs認証を設定する方法について説明します。

イベント ハブを構成する
  1. Azure サブスクリプションにリソースを作成する権限を持つAzure portalにサインインします。
  2. [ リソースの作成] を選択し、検索バーに 「Event Hubs 」と入力し、 Event Hubs の提案を選択します。
  3. [Event Hubs の作成] ページで、[作成] を選択 します
  4. Event Hubs 名前空間の作成の詳細を入力し、[ 作成] を選択します。
  5. Event Hubs 名前空間がプロビジョニングされたら、名前空間のページに移動します。
  6. [ Event Hubs ] を選択し、[ + イベント ハブ] を選択します。
  7. 新しいイベント ハブに名前を付けて、[ 作成] を選択します。
  8. イベント ハブが作成されたら、Event Hubs 名前空間に移動し、サイドバーから [Access Control (IAM)] を選択します。
  9. [ ロールの割り当て] を選択します
  10. [ + 追加] を選択し、[ ロールの割り当ての追加] を選択します。
  11. [ロール] の [ジョブ関数ロール] に移動し、[Azure Event Hubsデータ送信者] を選択し、[次へ] を選択します。
  12. [ メンバー ] タブで、[ ユーザー、グループ、またはサービス プリンシパルへのアクセスを割り当てる] を選択します。
  13. [+ メンバーの選択] を選択し、[Microsoft Graph Change Tracking] を検索して選択します。
  14. [ 確認と割り当て] を選択してプロセスを完了します。

サブスクリプションを作成し、通知を受信する

必要な Azure KeyVault サービスとAzure Event Hubs サービスを作成した後、変更通知サブスクリプションを作成し、Azure Event Hubs経由で変更通知の受信を開始できるようになりました。

サブスクリプションを作成する

Event Hubs で変更通知を受信するサブスクリプションの作成は、Webhook サブスクリプションの作成とほぼ同じですが、 notificationUrl プロパティに重要な変更があります。 続行する前に、まず Webhook サブスクリプションの作成手順 を確認します。

サブスクリプションの作成時に、 notificationUrl は Event Hubs の場所をポイントする必要があります。

ロールベースのアクセス制御を使用している場合、 notificationUrl プロパティは次のようになります。

EventHub:https://<eventhubnamespace>.servicebus.windows.net/eventhubname/<eventhubname>?tenantId=<domainname>

  • <eventhubnamespace> は、Event Hubs 名前空間に付ける名前です。 [イベント ハブの概要] ページの [ホスト名] にあります。
  • <eventhubname> は、イベント ハブに付ける名前です。 Event Hubs -> 概要 -> Event Hubs にあります。
  • <domainname> はテナントの名前です。たとえば、 contoso.com。 このドメインはAzure Event Hubsにアクセスするために使用されるため、Azure Event Hubsを保持する Azure サブスクリプションで使用されるドメインと一致することが重要です。 この情報を取得するには、Azure portalの [Microsoft Entra ID] メニューを選択し、[概要] ページをチェックします。 ドメイン名はプライマリ ドメインの下に表示されます。

注:

重複するサブスクリプションは許可されません。 サブスクリプション要求に、既存のサブスクリプションに含まれている changeTypeリソース に同じ値が含まれている場合、要求は HTTP エラー コード 409 Conflictで失敗し、エラー メッセージ Subscription Id <> already exists for the requested combination

イベント ハブ認証を RBAC にMicrosoft Entra ID移行する

共有アクセス署名 (SAS) を使用して Event Hubs を認証することは、今後非推奨になる予定です。 代わりに、Microsoft Entra IDロールベースのアクセス制御 (RBAC) を使用して Event Hubs を認証することをお勧めします。

このセクションでは、SAS 認証を使用して既存の Event Hubs を RBAC 認証をMicrosoft Entra IDに移行する方法について説明します。 Azure CLI または Azure portalを使用して、SAS 認証で使用したのと同じイベント ハブ名前空間を使用します。

  1. 既存のサブスクリプションに使用しているのと同じイベント ハブ名前空間の下に、新しいイベント ハブを作成します。
  2. URL の前の手順の新しいイベント ハブの名前を使用する以外は、既存のサブスクリプションと同じ詳細を持つ新しいサブスクリプションを作成します。 詳細については、「 サブスクリプションの作成: RBAC の使用」を参照してください。

新しいイベント ハブで通知を受け取ります。 イベント ハブの [メッセージ ] グラフを調べることで、トラフィックが古いサブスクリプションに似ているかどうかを検証できます。 また、通知を受信する際のエラーまたはエラーについても検証します。

通知を受け取り、新しいイベント ハブが正しく動作することを検証したら、古いサブスクリプション、古いイベント ハブ、SAS ベースの認証を削除して、新しいサブスクリプションの使用を開始できます。

通知を受信する

変更通知が Event Hubs によってアプリケーションに配信されるようになりました。 詳細については、Event Hubs ドキュメントで「イベントの受け取り」を参照してください。

アプリケーションで通知を受信するには、「イベント ハブの構成」に記載されている手順と同様に、"リッスン" アクセス許可を持つ別の共有アクセス ポリシーを作成し、接続文字列を取得する必要があります。

ヒント

Azure KeyVault で設定したのと同じ接続文字列を再利用するのではなく、Event Hubs メッセージをリッスンするアプリケーション用の別のポリシーを作成します。 この分離は、ソリューションの各コンポーネントが必要なアクセス許可のみを持っていることを確認することで、最小限の特権の原則に従います。

検証通知の処理

アプリケーションは、新しいサブスクリプションを作成するたびに検証通知を受け取ります。 これらの通知は無視してください。 次の例は、検証メッセージの本文を表します。

 {
    "value":[
        {
            "subscriptionId":"NA",
            "subscriptionExpirationDateTime":"NA",
            "clientState":"NA",
            "changeType":"Validation: Testing client application reachability for subscription Request-Id: 522a8e7e-096a-494c-aaf1-ac0dcfca45b7",
            "resource":"NA",
            "resourceData":{
                "@odata.type":"NA",
                "@odata.id":"NA",
                "id":"NA"
            }
        }
    ]
}

大きなペイロードを持つリッチ通知のサブスクリプション

Event Hubs の最大メッセージ サイズは 1 MB です。 リッチ通知を使用すると、この制限を超える通知が予想される場合があります。 Event Hubs を介して 1 MB を超える通知を受信するには、サブスクリプション要求に BLOB ストレージ アカウントを追加する必要もあります。

ストレージを設定し、サブスクリプションを作成する

  1. ストレージ アカウントを作成します
  2. ストレージ アカウントにコンテナーを作成します。 コンテナー名は、 microsoft-graph-change-notificationsに設定する必要があります。
  3. ストレージ アカウントのアクセス キーまたは接続文字列を取得します。
  4. 接続文字列をキー コンテナーに追加し、名前を付けます。 この値はシークレット名です。
  5. 次の構文で blobStoreUrl プロパティを含め、サブスクリプションを作成または再作成します。 blobStoreUrl: "https://<azurekeyvaultname>.vault.azure.net/secrets/<secretname>?tenantId=<domainname>"

リッチ通知を受け取る

Event Hubs が 1 MB を超える通知ペイロードを受信すると、通知には、リッチ通知に含まれる リソースresourceDataおよび encryptedContent プロパティは含まれません。 通知には、代わりに、これらのプロパティが格納されているストレージ アカウント内の BLOB を指す ID を持つ additionalPayloadStorageId プロパティが含まれています。

Microsoft Graph Change Tracking アプリケーションが見つからない場合はどうなりますか?

Microsoft Graph Change Tracking サービス プリンシパルは、テナントの作成時と管理操作によっては、テナントに存在しない可能性があります。 サービス プリンシパルのグローバルに一意の appId0bf30f3b-4a52-48df-9a82-234910c4a086 され、次のクエリを実行して、テナントに存在するかどうかを確認できます。

GET https://graph.microsoft.com/v1.0/servicePrincipals(appId='0bf30f3b-4a52-48df-9a82-234910c4a086')

サービス プリンシパルが存在しない場合は、次のように作成します。 この操作を実行するには、呼び出し元アプリに Application.ReadWrite.All アクセス許可を付与する必要があります。

方法 1

POST https://graph.microsoft.com/v1.0/servicePrincipals
Content-type: application/json

{
    "appId": "0bf30f3b-4a52-48df-9a82-234910c4a086"
}

方法 2

POST https://graph.microsoft.com/v1.0/servicePrincipals(appId='0bf30f3b-4a52-48df-9a82-234910c4a086')
Content-type: application/json
Prefer: create-if-missing

{
    "displayName": "Microsoft Graph Change Tracking"
}