Azure Event Grid を使用して Microsoft Graph API 変更イベントを受信する (プレビュー)

[アーティクル]
12/09/2023

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

重要

Azure Event Grid にイベントを送信する Microsoft Graph API の機能は、現在パブリックプレビュー段階です。ご質問がある場合、またはサポートが必要な場合は、ask-graph-and-grid@microsoft.com までお問い合わせください。

Microsoft のイベントソース	使用可能なイベントの種類
Microsoft Entra ID	Microsoft Entra イベントの種類
Microsoft Outlook	Microsoft Outlook イベントの種類
Microsoft 365 グループの会話
Microsoft Teams	Microsoft Teams イベントの種類
Microsoft SharePoint と OneDrive
Microsoft SharePoint
セキュリティのアラート
Microsoft Conversations
Microsoft ユニバーサル印刷

重要

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

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.UserDeletedオフボーディングを処理する特殊なアプリケーションなどMicrosoft.Graph.UserCreated、イベントの種類をルーティングできます。たとえば、連絡先情報を同期する別のアプリケーションにイベントを送信 Microsoft.Graph.UserUpdated することもできます。 Event Grid を通知先として使う場合、1 つの 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 サンプルリンクで確認できます。

重要

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

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

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

パートナートピック名
パートナートピックが作成されるリソースグループ名
region (location)
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 コマンドを実行すると取得できます。場所の表示名は使用しないでください。たとえば、"West Central US" などを使用しないでください。代わりに、westcentralus を使用してください。
```
  az account list-locations
```
lifecycleNotificationUrl: イベントの送信先となるパートナートピックを定義するために使用される microsoft.graph.subscriptionReauthorizationRequiredURI。このイベントは、Graph API サブスクリプションの有効期限が近づいていることをアプリケーションに通知します。 URI は、ライフサイクルイベントの送信先として Event Grid を使用する場合、前述の notificationUrl と同じパターンに従います。その場合、パートナートピックは notificationUrl で指定されたものと同じである必要があります。
resource: 状態の変更をアナウンスするイベントを生成するリソース。
expirationDateTime: サブスクリプションの有効期限とイベントのフローが停止する有効期限。 RFC 3339 で規定されている形式に準拠する必要があります。リソースの種類ごとに許容されるサブスクリプションの最大長以内の有効期限を指定する必要があります。
クライアントの状態。このプロパティは省略可能です。これは、イベント配信中にイベントハンドラーアプリケーションへの呼び出しの検証に使用されます。詳細については、Graph API サブスクリプションのプロパティに関する記事を参照してください。

重要

パートナートピック名は、同じ Azure リージョン内で一意である必要があります。各テナントとアプリケーション ID の組み合わせで、最大 10 個の一意のパートナートピックを作成できます。
ソリューションの開発時には、特定の Graph API リソースのサービスに関する制限事項に注意してください。
プロパティのない lifecycleNotificationUrl 既存の Graph API サブスクリプションは、ライフサイクルイベントを受け取りません。 lifecycleNotificationUrl プロパティを追加するには、既存のサブスクリプションを削除し、サブスクリプションの作成時にプロパティを指定する新しいサブスクリプションを作成する必要があります。

Note

プライベートプレビュー中にアプリケーションが要求と共にヘッダーx-ms-enable-featuresを使用して 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 サブスクリプションを更新する必要があります。

Graph API サブスクリプションの作成時に clientState プロパティにクライアントシークレットを指定した場合、そのクライアントシークレットはイベントに含まれます。イベントの clientState が、Graph API サブスクリプションの作成時に使用した値と一致することを検証します。
次の手順を実行するために、アプリに有効なアクセストークンがあることを確認します。詳細については、今後のサンプルと詳細な手順に関するセクションを参照してください。
次の 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 サンプル
- GraphAPIController には、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
Graph API の使用方法を示す Microsoft Graph API チュートリアル。この記事には、Event Grid にイベントを送信する例が必ずしも含まれているわけではありません。