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 サブスクリプションを作成します。
• 自動更新を使用してサブスクリプションのライフサイクルを管理します。
• イベントグリッドのフィルタリングおよびルーティング機能を使って複数の宛先にイベントをルーティングできます。

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

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

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

以下の表は、Graph APIを通じてイベントを取得できるイベントソースを示しています。 ほとんどのリソースにおいて、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を使って、単一のGraph APIサブスクリプションを使って複数の宛先にイベントをルーティングしたいのですが、複数のGraph APIサブスクリプションの管理は避けたいです。
• イベントの一部のプロパティに基づいて、さまざまなダウンストリーム アプリケーション、Webhook、または Azure サービスにイベントをルーティングする必要があります。 たとえば、Microsoft.Graph.UserUpdated や Microsoft.Graph.UserDeleted などのイベントの種類を、ユーザーのオンボードやオフボードを処理する特殊なアプリケーションにルーティングできます。 また、たとえば連絡先情報を同期する別のアプリケーションに Microsoft.Graph.UserUpdated イベントを送信することもできます。 Event Gridを通知宛先として使う場合、単一のGraph APIサブスクリプションを使うことでこれを実現できます。 詳細については、イベントのフィルター処理とイベント ハンドラーに関する記事を参照してください。
• 相互運用性が重要です。 クラウドネイティブコンピューティング財団(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のサブスクリプションを作成すると、システムがパートナートピックを作成します。 新しいGraph APIサブスクリプションに作成・関連付けるパートナートピックを指定するために、notificationUrlパラメータに以下の情報を渡します。

• パートナー トピック名
• パートナートピックのリソースグループ名
• リージョン (場所)
• Azure サブスクリプション

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

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

{
    "changeType": "Updated,Deleted",
    "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": "2026-08-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はGraph APIでサポートされていません。詳細はGraph APIドキュメントを参照してください)。 これらの 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:サブスクリプションが切れ、イベントの流れが停止する期限です。 これは Request for Comments(RFC)3339で指定されたフォーマットに準拠しなければなりません。 リソース の種類ごとに許容される最大サブスクリプション期間内に期限を指定する必要があります。

• clientState: このオプションプロパティを使って、イベントデリバリー中にイベントハンドラアプリケーションへの呼び出しを検証します。 詳細については、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": "2026-09-30T11:00:00.0000000Z"
     }
     

     アプリがリソースへのアクセス権限を失うと、更新が失敗する可能性があります。 その後、アプリはサブスクリプションを再承認するために新しいアクセストークンを取得する必要があるかもしれません。

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

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

新しい 有効期限を指定する際は、現在の時刻から少なくとも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 のセットアップ中に作成されたパートナー トピックをアクティブ化します。
• パートナートピックのためにイベントサブスクリプションを作成して、イベントに登録します。