Azure Event Grid を使用して Microsoft Graph API 変更イベントを受信する

Microsoft Graph API は、Microsoft Entra ID、Teams、Outlook、OneDrive など、Microsoft 365 サービス全体のリソースに対して変更通知を提供します。 Azure Event Grid を介してこれらのイベントをサブスクライブすることで、リソースの変更にリアルタイムで応答するイベント ドリブン アプリケーションを構築します。

この記事では、以下の方法について説明します。

• Azure Event Grid パートナー トピックにイベントを配信する Microsoft Graph API サブスクリプションを作成します。
• 自動更新を使用してサブスクリプションのライフサイクルを管理します。
• Event Grid のフィルター処理とルーティング機能を使用して、複数の宛先にイベントをルーティングします。

Azure Event Grid には、従来の Webhook ベースの Microsoft Graph API サブスクリプションよりもいくつかの利点があります。

• 簡略化されたルーティング: 1 つの Graph API サブスクリプションを使用して、複数の宛先にイベントを送信します。
• 高度なフィルター処理: イベント プロパティに基づいて、特定のイベントの種類をさまざまなアプリケーションにルーティングします。
• 標準コンプライアンス: 相互運用性を向上するために、CloudEvents 形式でイベントを受信します。
• 信頼性: 組み込みの再試行ロジックと配信不能キューにより、信頼性の高いイベント配信が保証されます。

サポートされているイベント ソース

次の表に、Graph API でイベントを使用できるイベント ソースの一覧を示します。 ほとんどのリソースでは、作成、更新、削除を通知するイベントがサポートされています。 イベント ソースに対してイベントが発生するリソースの詳細については、 Microsoft Graph API の変更通知でサポートされているリソースを参照してください。

Microsoft Graph API サブスクリプションを作成して、Graph API イベントをパートナー トピックにフローできるようにします。 パートナー トピックは、Graph API サブスクリプションの作成の一部として自動的に作成されます。 そのパートナー トピックを使用して イベント サブスクリプションを作成 し、イベントを処理するための要件を最も満たす、サポートされている イベント ハンドラー のいずれかにイベントを送信します。

Event Grid を使用して Microsoft Graph API ソースからイベントをサブスクライブする必要がある理由

Event Grid を介して Microsoft Graph API イベントをサブスクライブするだけでなく、(イベントではなく) 同様の通知を受け取る 他のオプション もあります。 次のいずれかの要件を満たしている場合は、Microsoft Graph API を使用して Event Grid にイベントを配信します。

• Microsoft Entra ID、Outlook、または Teams のイベントを使用してリソースの変更に対応するイベントドリブン ソリューションを開発しています。 Event Grid が提供する堅牢なイベント ドリブン モデルとパブリッシュ/サブスクライブ機能が必要です。 Event Grid の概要については、Event Grid の概念に関する記事を参照してください。
• Event Grid を使い、1 つの Graph API サブスクリプションを使って複数の宛先にイベントをルーティングし、複数の Graph API サブスクリプションを管理することを避けたいと考えています。
• イベントの一部のプロパティに基づいて、さまざまなダウンストリーム アプリケーション、Webhook、または Azure サービスにイベントをルーティングする必要があります。 たとえば、Microsoft.Graph.UserCreated や Microsoft.Graph.UserDeleted などのイベントの種類を、ユーザーのオンボードやオフボードを処理する特殊なアプリケーションにルーティングできます。 また、たとえば連絡先情報を同期する別のアプリケーションに Microsoft.Graph.UserUpdated イベントを送信することもできます。 Event Grid を通知先として使う場合、1 つの Graph API サブスクリプションを使ってこれを実現できます。 詳細については、イベントのフィルター処理とイベント ハンドラーに関する記事を参照してください。
• 相互運用性が重要です。 Cloud Native Computing Foundation (CNCF) の CloudEvents 仕様標準を使って、標準的な方法でイベントを転送および処理する必要がある場合もあります。
• CloudEvents が提供する機能拡張サポートを評価します。 たとえば、準拠しているシステム間でイベントをトレースするには、CloudEvents 拡張機能 の分散トレースを使用します。 CloudEvents 拡張機能の詳細を確認します。
• 業界で採用されている実証済みのイベントドリブン アプローチを使用します。

Graph API イベントがパートナー トピックに流れるようにする

Microsoft Graph API ソフトウェア開発キット (SDK) を使用して Graph API サブスクリプションを作成し、このセクションで 提供されているサンプルへのリンクの手順に従って 、イベントを Event Grid パートナー トピックに転送するように Microsoft Graph API に要求します。 使用可能な SDK のサポートについては、Microsoft Graph API SDK でサポートされている言語に関する記事を参照してください。

一般的な前提条件

アプリケーションを実装して Microsoft Graph API サブスクリプションを作成および更新する前に、次の一般的な前提条件を満たします。

• パートナー イベントをサブスクライブする手順の概要を理解している。 この記事で説明されているように、Graph API サブスクリプションを作成する前に、次の手順に従う必要があります。

  • Azure サブスクリプションに Event Grid リソース プロバイダーを登録する。

  • リソース グループにパートナー トピックを作成することの承認を Microsoft Graph API (パートナー) に与えます。

• Microsoft Graph API 通知に関する実用的な知識を持っている。 学習の一環として、Graph API エクスプローラーを使用して Graph API サブスクリプションを作成できます。

• パートナー イベントの概念を理解している。

• システム状態変更イベントの受信元となる Microsoft Graph API リソースを特定する。 詳細については、Microsoft Graph API の変更通知に関するページを参照してください。 たとえば、Microsoft Entra ID のユーザーに対する変更を追跡するには、ユーザー リソースを使用する必要があります。 ユーザー グループへの変更を追跡するには、グループを使用します。

• Microsoft 365 テナントのテナント管理者アカウントを持っている。 Microsoft 365 開発者プログラムに参加して、無料で開発テナントを取得します。

選択したプログラミング言語と使用する開発環境に固有のその他の前提条件は、次のセクションにある Microsoft Graph API サンプル リンクで確認できます。

Microsoft Graph API サブスクリプションを作成する方法

Graph API サブスクリプションを作成すると、パートナー トピックが自動的に作成されます。 パラメーター notificationUrl に次の情報を渡し、いかなるパートナートピックを作成して新しい Graph API サブスクリプションに関連付けるかを指定します。

• パートナー トピック名
• パートナー トピックが作成されるリソース グループ名
• リージョン (場所)
• Azure サブスクリプション

これらのコード サンプルでは、Graph API サブスクリプションを作成する方法を示します。 これには、Microsoft Entra ID テナント内のすべてのユーザーが作成、更新、または削除されたときにイベントを受信するサブスクリプションを作成する例が含まれます。

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

{
    "changeType": "Updated,Deleted,Created",
    "notificationUrl": "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic",
    "lifecycleNotificationUrl": "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic",
    "resource": "users",
    "expirationDateTime": "2024-03-31T00:00:00Z",
    "clientState": "secretClientValue"
}

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

// Dependencies
using Microsoft.Graph.Models;

var requestBody = new Subscription
{
	ChangeType = "updated,deleted,created",
	NotificationUrl = "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=youPartnerTopic&location=theNameOfAzureRegionFortheTopic",
    LifecycleNotificationUrl = "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic",
	Resource = "users",
	ExpirationDateTime = DateTimeOffset.Parse("2024-03-31T18:23:45.9356913Z"),
	ClientState = "secretClientValue",
};

// To initialize your graphClient, see `https://learn.microsoft.com/graph/sdks/create-client?from=snippets&tabs=csharp`
var result = await graphClient.Subscriptions.PostAsync(requestBody);

mgc subscriptions create --body '{\
   "changeType": "updated,deleted,created",\
   "notificationUrl": "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=youPartnerTopic&location=theNameOfAzureRegionFortheTopic",\
   "lifecycleNotificationUrl": "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic",\
   "resource": "users",\
   "expirationDateTime":"2024-03-31T18:23:45.9356913Z",\
   "clientState": "secretClientValue"\
}\
'

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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


requestBody := graphmodels.NewSubscription()
changeType := "updated,deleted,created"
requestBody.SetChangeType(&changeType) 
notificationUrl := "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic"
requestBody.SetNotificationUrl(&notificationUrl)
lifecycleNotificationUrl := "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic"
requestBody.SetLifecycleNotificationUrl(&lifecycleNotificationUrl)
resource := "users"
requestBody.SetResource(&resource) 
expirationDateTime , err := time.Parse(time.RFC3339, "2024-03-31T18:23:45.9356913Z")
requestBody.SetExpirationDateTime(&expirationDateTime) 
clientState := "secretClientValue"
requestBody.SetClientState(&clientState) 

subscriptions, err := graphClient.Subscriptions().Post(context.Background(), requestBody, nil)

GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

Subscription subscription = new Subscription();
subscription.changeType = "updated,deleted,created";
subscription.notificationUrl = "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic";
subscription.lifecycleNotificationUrl = "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic";
subscription.resource = "users";
subscription.expirationDateTime = OffsetDateTimeSerializer.deserialize("2024-03-31T18:23:45.9356913Z");
subscription.clientState = "secretClientValue";

graphClient.subscriptions()
	.buildRequest()
	.post(subscription);

const options = {
	authProvider,
};

const client = Client.init(options);

const subscription = {
   changeType: 'updated,deleted,created',
   notificationUrl: 'EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic',
   lifecycleNotificationUrl: 'EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic',
   resource: 'users',
   expirationDateTime: '2024-03-31T18:23:45.9356913Z',
   clientState: 'secretClientValue'
};

await client.api('/subscriptions')
	.post(subscription);

<?php

// THIS SNIPPET IS A PREVIEW VERSION OF THE SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new Subscription();
$requestBody->setChangeType('updated,deleted,created');
$requestBody->setNotificationUrl('EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic');
$requestBody->setLifecycleNotificationUrl('EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic');
$requestBody->setResource('users');
$requestBody->setExpirationDateTime(new \DateTime('2024-03-31T18:23:45.9356913Z'));
$requestBody->setClientState('secretClientValue');

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

Import-Module Microsoft.Graph.ChangeNotifications

$params = @{
	changeType = "updated,deleted,created"
	notificationUrl = "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic"
	lifecycleNotificationUrl = "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic"
	resource = "users"
	expirationDateTime = [System.DateTime]::Parse("2024-03-31T18:23:45.9356913Z")
	clientState = "secretClientValue"
}

New-MgSubscription -BodyParameter $params

graph_client = GraphServiceClient(credentials, scopes)

request_body = Subscription(
	change_type = "updated,deleted,created",
	notification_url = "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic",
    lifecycle_notification_url = "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic",
	resource = "users",
	expiration_date_time = "2024-03-31T18:23:45.9356913Z",
	client_state = "secretClientValue"
)

result = await graph_client.subscriptions.post(request_body)

• changeType: イベントを受信するリソース変更の種類。 有効な値: Updated、Deleted、Created。 これらの 1 つ以上の値をコンマ区切りで指定できます。
• notificationUrl: イベントの送信先となるパートナー トピックを定義するために使用される URI。 次のパターンに準拠する必要があります: EventGrid:?azuresubscriptionid=<you-azure-subscription-id>&resourcegroup=<your-resource-group-name>&partnertopic=<the-name-for-your-partner-topic>&location=<the-Azure-region-name-where-you-want-the-topic-created>。 場所 (Azure リージョンとも呼ばれます) name は、az account list-locations コマンドを実行すると取得できます。 場所の表示名は使用しないでください。 たとえば、[米国中西部] を使用しないでください。 代わりに westcentralus を使用してください

    az account list-locations
  

• lifecycleNotificationUrl: microsoft.graph.subscriptionReauthorizationRequiredイベントの送信先となるパートナー トピックを定義するために使用される URI。 このイベントは、Graph API サブスクリプションの有効期限が近づいていることをアプリケーションに通知します。 URI は、ライフサイクル イベントの送信先として Event Grid を使用する場合、前述の notificationUrl と同じパターンに従います。 その場合、パートナー トピックは notificationUrl で指定されたものと同じである必要があります。
• resource: 状態の変更をアナウンスするイベントを生成するリソース。
• expirationDateTime: サブスクリプションの有効期限とイベントのフローが停止する有効期限。 変更要求 (RFC) 3339 で規定されている形式に準拠する必要があります。 リソースの種類ごとに許容されるサブスクリプションの最大長以内の有効期限を指定する必要があります。
• クライアントの状態。 このプロパティは省略可能です。 これは、イベント配信中にイベント ハンドラー アプリケーションへの呼び出しの検証に使用されます。 詳細については、Graph API サブスクリプションのプロパティに関する記事を参照してください。

Graph API サブスクリプションを作成すると、Azure でパートナー トピックが作成されます。

Microsoft Graph API サブスクリプションを更新する

イベントのフローを停止しないように、有効期限が切れる前に Graph API サブスクリプションを更新します。 更新プロセスを自動化するために、Microsoft Graph API では、アプリケーションがサブスクライブできる ライフサイクル通知イベント がサポートされています。 現在、すべての種類の Microsoft Graph API リソースは、次のいずれかの条件が発生したときに送信される microsoft.graph.subscriptionReauthorizationRequired をサポートしています。

• アクセス トークンの有効期限がまもなく切れる。
• Graph API サブスクリプションの有効期限がまもなく切れる。
• テナント管理者が、リソースを読み取るアプリのアクセス許可を取り消した。

Graph API サブスクリプションの有効期限が切れた後に更新されない場合は、新しい Graph API サブスクリプションを作成します。 有効期限が 30 日未満である限り、有効期限が切れたサブスクリプションで使用されているのと同じパートナー トピックを参照してください。 Graph API サブスクリプションの有効期限が切れてからの日数が 30 日を超えた場合、既存のパートナー トピックを再利用することはできません。 この場合、別のパートナー トピック名を指定する必要があります。 または、既存のパートナー トピックを削除して、Graph API サブスクリプションの作成時に同じ名前の新しいパートナー トピックを作成することもできます。

Microsoft Graph API サブスクリプションを更新する方法

microsoft.graph.subscriptionReauthorizationRequired イベントを受け取ると、アプリケーションは次のアクションを実行して Graph API サブスクリプションを更新する必要があります。

1. Graph API サブスクリプションの作成時に clientState プロパティにクライアント シークレットを指定した場合、そのクライアント シークレットはイベントに含まれます。 イベントの clientState が、Graph API サブスクリプションの作成時に使用した値と一致しているか検証します。

2. 次の手順を実行するために、アプリに有効なアクセス トークンがあることを確認します。 詳細については、次の「サンプルと詳細な手順」のセクションを参照してください。

3. 次の 2 つの API のいずれかを呼び出します。 API 呼び出しが成功すると、変更通知フローが再開されます。

   • 有効期限を延長せずにサブスクリプションを再認証する /reauthorize アクションを呼び出します。

     POST  https://graph.microsoft.com/beta/subscriptions/{id}/reauthorize
     

   • サブスクリプションを同時に再認証 "および" 更新するには、通常の「更新」アクションを実行します。

     PATCH https://graph.microsoft.com/beta/subscriptions/{id}
     Content-Type: application/json
     
     {
        "expirationDateTime": "2024-04-30T11:00:00.0000000Z"
     }
     

     アプリがリソースへのアクセスを許可されなくなった場合、更新が失敗する可能性があります。 その後、サブスクリプションを正常に再認証するために、アプリが新しいアクセス トークンを取得することが必要になる場合があります。

承認チャレンジが可能だからといって、有効期限が切れる前にサブスクリプションを更新する必要性がなくなるわけではありません。 アクセス トークンとサブスクリプションの有効期限のライフサイクルは同じではありません。 アクセス トークンは、サブスクリプションの前に期限切れになる可能性があります。 エンドポイントを定期的に再認証して、アクセス トークンを更新できるようにしておくことが重要です。 エンドポイントを再認証しても、サブスクリプションは更新されません。 ただし、サブスクリプションを更新すると、エンドポイントも再認証されます。

Graph API サブスクリプションを更新または再認証するときは、サブスクリプションの作成時に指定されたのと同じパートナー トピックが使用されます。

新しい expirationDateTime を指定するときは、現在の時刻から少なくとも 3 時間であることを確認します。 さもないと、アプリケーションは更新後すぐに microsoft.graph.subscriptionReauthorizationRequired イベントを受信する可能性があります。

サポートされている言語のいずれかを使用して Graph API サブスクリプションを再認証する方法の例については、サブスクリプションの再認証要求に関する記事を参照してください。

サポートされている言語のいずれかを使用して Graph API サブスクリプションを更新および再認証する方法の例については、サブスクリプション要求の更新に関する記事を参照してください。

サンプルと詳細な手順

Microsoft Graph API のドキュメントには、次の手順を含むコード サンプルが用意されています。

• 使用する言語に応じて、特定の手順を使用して開発環境を設定します。 手順には、開発目的で Microsoft 365 テナントを取得する方法も含まれています。
• Graph API サブスクリプションを作成します。 サブスクリプションを更新するには、Graph API サブスクリプションを更新する方法に関する記事のコード スニペットを使用して Graph API を呼び出すことができます。
• Microsoft Graph API を呼び出すときに使用する認証トークンを取得します。

Web アプリケーションのサンプルは次の言語で利用できます。

• C# サンプル を確認ください。 これは、Graph API サブスクリプションを作成および更新する方法を含む最新のサンプルであり、イベントのフローを有効にする手順の一部について説明するものです。
• Java サンプル
• Node.js サンプル.

関連コンテンツ

Event Grid を使用して Microsoft Graph API イベントの受信を設定するには、次の 2 つの手順に従います。

• Microsoft Graph API のセットアップ中に作成されたパートナー トピックをアクティブ化します。
• パートナー トピックのイベント サブスクリプションを作成して、イベントをサブスクライブします。