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

[アーティクル]
07/04/2024

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

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

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

Azure Event Hubs を使用した変更通知の受信

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

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

Azure Event Hubs 認証を設定する

Azure CLI を使用すると、Azure の管理タスクをスクリプト化して自動化できます。 CLI は、ローカルコンピューターにインストールされているか、Azure Cloud Shell で直接実行することができます。

# --------------
# TODO: update the following values
#sets the name of the resource group
resourcegroup=rg-graphevents-dev
#sets the location of the resources
location='uk south'
#sets the name of the Azure Event Hubs namespace
evhamespacename=evh-graphevents-dev
#sets the name of the hub under the namespace
evhhubname=graphevents
#sets the name of the access policy to the hub
evhpolicyname=grapheventspolicy
#sets the name of the Azure KeyVault
keyvaultname=kv-graphevents
#sets the name of the secret in Azure KeyVault that will contain the connection string to the hub
keyvaultsecretname=grapheventsconnectionstring
# --------------
az group create --location $location --name $resourcegroup
az eventhubs namespace create --name $evhamespacename --resource-group $resourcegroup --sku Basic --location $location
az eventhubs eventhub create --name $evhhubname --namespace-name $evhamespacename --resource-group $resourcegroup --partition-count 2 --message-retention 1
az eventhubs eventhub authorization-rule create --name $evhpolicyname --eventhub-name $evhhubname --namespace-name $evhamespacename --resource-group $resourcegroup --rights Send
evhprimaryconnectionstring=`az eventhubs eventhub authorization-rule keys list --name $evhpolicyname --eventhub-name $evhhubname --namespace-name $evhamespacename --resource-group $resourcegroup --query "primaryConnectionString" --output tsv`
az keyvault create --name $keyvaultname --resource-group $resourcegroup --location $location --enable-soft-delete true --sku standard --retention-days 90
az keyvault secret set --name $keyvaultsecretname --value $evhprimaryconnectionstring --vault-name $keyvaultname --output none
graphspn=`az ad sp list --display-name 'Microsoft Graph Change Tracking' --query "[].appId" --output tsv`
az keyvault set-policy --name $keyvaultname --resource-group $resourcegroup --secret-permissions get --spn $graphspn --output none
keyvaulturi=`az keyvault show --name $keyvaultname --resource-group $resourcegroup --query "properties.vaultUri" --output tsv`
domainname=`az ad signed-in-user show --query 'userPrincipalName' | cut -d '@' -f 2 | sed 's/\"//'`
notificationUrl="EventHub:${keyvaulturi}secrets/${keyvaultsecretname}?tenantId=${domainname}"
echo "Notification Url:\n${notificationUrl}"

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

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

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

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

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

Key Vault の使用
ロールベースのアクセス制御の使用

Key Vault を使用している場合、 notificationUrl プロパティは次のようになります。 EventHub:https://<azurekeyvaultname>.vault.azure.net/secrets/<secretname>?tenantId=<domainname>、次の値を使用します。

azurekeyvaultname - キーコンテナーを作成したときに付けた名前。 DNS 名で見つけることができます。
secretname - シークレットを作成したときに付けた名前。 Azure Key Vault の [シークレット] ページで見つけることができます。
domainname - テナントの名前。たとえば、contoso.com。このドメインは Azure Key Vault へのアクセスに使用されるため、Azure Key Vault を保持する Azure サブスクリプションで使用されるドメインと一致することが重要です。この情報を取得するには、作成した Azure Key Vault の概要ページに移動し、サブスクリプションをクリックします。ドメイン名がディレクトリ フィールドの下に表示されます。

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

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

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

注:

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

通知を受信する

変更通知が 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 ストレージアカウントを追加する必要もあります。

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

ストレージアカウントを作成します。
ストレージアカウントにコンテナーを作成します。コンテナー名は、 microsoft-graph-change-notificationsに設定する必要があります。
ストレージアカウントのアクセスキーまたは接続文字列を取得します。
接続文字列をキーコンテナーに追加し、名前を付けます。この値はシークレット名です。
次の構文で 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 サービスプリンシパルは、テナントの作成時と管理操作によっては、テナントに存在しない可能性があります。サービスプリンシパルのグローバルに一意の appId が 0bf30f3b-4a52-48df-9a82-234910c4a086 され、次のクエリを実行して、テナントに存在するかどうかを確認できます。

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


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://video2.skills-academy.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.ServicePrincipalsWithAppId("{appId}").GetAsync();



mgc service-principals-with-app-id get --app-id {app-id}



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  //other-imports
)


// To initialize your graphClient, see https://video2.skills-academy.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
appId := "{appId}"
servicePrincipals, err := graphClient.ServicePrincipalsWithAppId(&appId).Get(context.Background(), nil)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

ServicePrincipal result = graphClient.servicePrincipalsWithAppId("{appId}").get();

Snippet not available


<?php
use Microsoft\Graph\GraphServiceClient;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);


$result = $graphServiceClient->servicePrincipalsWithAppId('{appId}', )->get()->wait();


Import-Module Microsoft.Graph.Applications

Get-MgServicePrincipalByAppId


from msgraph import GraphServiceClient

graph_client = GraphServiceClient(credentials, scopes)


result = await graph_client.service_principals_with_app_id("{appId}").get()

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

方法 1

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

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


// Code snippets are only available for the latest version. Current version is 5.x

// Dependencies
using Microsoft.Graph.Models;

var requestBody = new ServicePrincipal
{
	AppId = "0bf30f3b-4a52-48df-9a82-234910c4a086",
};

// To initialize your graphClient, see https://video2.skills-academy.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.ServicePrincipals.PostAsync(requestBody);



mgc service-principals create --body '{\
    "appId": "0bf30f3b-4a52-48df-9a82-234910c4a086"\
}\
'



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
	  //other-imports
)

requestBody := graphmodels.NewServicePrincipal()
appId := "0bf30f3b-4a52-48df-9a82-234910c4a086"
requestBody.SetAppId(&appId) 

// To initialize your graphClient, see https://video2.skills-academy.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
servicePrincipals, err := graphClient.ServicePrincipals().Post(context.Background(), requestBody, nil)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

ServicePrincipal servicePrincipal = new ServicePrincipal();
servicePrincipal.setAppId("0bf30f3b-4a52-48df-9a82-234910c4a086");
ServicePrincipal result = graphClient.servicePrincipals().post(servicePrincipal);


const options = {
	authProvider,
};

const client = Client.init(options);

const servicePrincipal = {
    appId: '0bf30f3b-4a52-48df-9a82-234910c4a086'
};

await client.api('/servicePrincipals')
	.post(servicePrincipal);


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Models\ServicePrincipal;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new ServicePrincipal();
$requestBody->setAppId('0bf30f3b-4a52-48df-9a82-234910c4a086');

$result = $graphServiceClient->servicePrincipals()->post($requestBody)->wait();


Import-Module Microsoft.Graph.Applications

$params = @{
	appId = "0bf30f3b-4a52-48df-9a82-234910c4a086"
}

New-MgServicePrincipal -BodyParameter $params


from msgraph import GraphServiceClient
from msgraph.generated.models.service_principal import ServicePrincipal

graph_client = GraphServiceClient(credentials, scopes)

request_body = ServicePrincipal(
	app_id = "0bf30f3b-4a52-48df-9a82-234910c4a086",
)

result = await graph_client.service_principals.post(request_body)

方法 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"
}

通知の変更の概要
次の Azure Event Hubs クイックスタートをご覧ください。
- .NET Core
- Java
- Python
- JavaScript

次の方法で共有

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

Azure Event Hubs を使用した変更通知の受信

Azure Event Hubs 認証を設定する

イベントハブを構成する

Azure Key Vault を構成する

イベントハブを構成する

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

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

通知を受信する

検証通知の処理

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

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

リッチ通知を受け取る

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

フィードバック

フィードバック

その他のリソース

次の方法で共有

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

Azure Event Hubs を使用した変更通知の受信

Azure Event Hubs 認証を設定する

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

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

通知を受信する

検証通知の処理

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

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

リッチ通知を受け取る

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

関連コンテンツ

フィードバック

フィードバック

その他のリソース