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

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

Microsoft のイベント ソース	リソース	使用可能なイベントの種類
Microsoft Entra ID	ユーザー、グループ	Microsoft Entra イベントの種類
Microsoft Outlook	イベント (予定表会議)、メッセージ (メール)、連絡先	Microsoft Outlook イベントの種類
Microsoft Teams	ChatMessage、CallRecord (会議)	Microsoft Teams イベントの種類
OneDrive	DriveItem	Microsoft OneDrive イベント
Microsoft SharePoint	一覧取得	Microsoft SharePoint イベント
To Do	To Do タスク	Microsoft ToDo イベント
セキュリティのアラート	Alert	Microsoft セキュリティ アラート イベント
クラウド印刷	プリンター、印刷タスク定義	Microsoft Cloud 印刷イベント
Microsoft Conversations	会話	Microsoft 365 グループ会話イベント

Microsoft Graph API イベントがパートナー トピックに流れるように Microsoft Graph API サブスクリプションを作成します。 パートナー トピックは、Graph API サブスクリプションの作成の一環で自動的に作成されます。 そのパートナー トピックを使って、イベント サブスクリプションを作成し、イベントを処理する要件に最適な、サポートされているイベント ハンドラーのいずれかにイベントを送信します。

重要

パートナー イベント機能についてよくわかっていない場合は、パートナー イベントの概要に関する記事を参照してください。

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

Event Grid を介して Microsoft Graph API イベントをサブスクライブする機能以外に、(イベントではなく) 同様の通知を受け取ることができる他のオプションがあります。 次の要件に 1 つでも該当する場合は、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 サンプル リンクで確認できます。

重要

アプリケーションを実装するための詳細な手順については、「サンプルと詳細な手順」のセクションを参照してください。この記事のセクションには、Event Grid を使用した Microsoft Graph API イベントの転送に関する追加の重要な情報が含まれているため、すべてのセクションをお読みください。

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

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

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

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

HTTP

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

C#

// 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);

CLI

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"\
}\
'

Go

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)

Java

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);

JavaScript

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

<?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();

PowerShell

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

Python

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 サブスクリプションのプロパティに関する記事を参照してください。

重要

• パートナー トピック名は、同じ Azure リージョン内で一意である必要があります。 各テナントとアプリケーション ID の組み合わせで、最大 10 個の一意のパートナー トピックを作成できます。

• ソリューションの開発時には、特定の Graph API リソースのサービスに関する制限事項に注意してください。

• lifecycleNotificationUrl プロパティのない既存の Graph API サブスクリプションは、ライフサイクル イベントを受け取りません。 lifecycleNotificationUrl プロパティを追加するには、既存のサブスクリプションを削除し、サブスクリプションの作成時にプロパティを指定する新しいサブスクリプションを作成する必要があります。

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 を呼び出すときに使用する認証トークンを取得します。

Note

Microsoft Graph API エクスプローラーを使用して Graph API サブスクリプションを作成できます。 認証やイベントの受信など、ソリューションの他の重要な側面については、引き続きサンプルを使用する必要があります。

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

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

重要

Graph API サブスクリプションの作成の一環として作成されたパートナー トピックをアクティブ化する必要があります。 また、イベントを受信するには、Web アプリケーションへの Event Grid イベント サブスクリプションを作成する必要があります。 そのためには、Web アプリケーションで構成された URL を使用して、イベント サブスクリプションの Webhook エンドポイントとしてイベントを受信します。 詳細については、「次のステップ」を参照してください。

重要

別の言語のサンプル コードが必要ですか、または質問がありますか? ask-graph-and-grid@microsoft.com までメールをお送りください。

次のステップ

Event Grid を使用して Microsoft Graph API イベントを受信するためのセットアップを完了するには、次の 2 つの手順に従います。

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

その他の便利なリンク:

• Azure Event Grid - パートナー イベントの概要
• Microsoft Graph API に関する情報。
• Microsoft Graph API の Webhook
• Microsoft Graph API の操作に関するベスト プラクティス
• Microsoft Graph API SDK
• Microsoft Graph API チュートリアル。Graph API の使用方法を示します。 この記事には、Event Grid にイベントを送信する例が必ずしも含まれているわけではありません。