変更通知を使用すると、アプリケーションは、関心のある Microsoft Graph リソースが変更されたときにアラートを受け取ることができます。つまり、作成、更新、または削除されます。 Microsoft Graph は指定されたクライアント エンドポイントに通知を送信し、クライアント サービスはビジネス要件に従って通知を処理します。 たとえば、サービスはより多くのデータをフェッチしたり、キャッシュやビューを更新したりする場合があります。
重要
変更通知機能は、外部テナントおよび Azure AD B2C テナントの Microsoft Entra 外部 ID ではサポートされていません。
変更通知を受け取る理由
変更通知はイベント駆動型モデルに従っており、顧客は Microsoft Graph をポーリングする代わりに、変更が発生したときにアラートを受け取ります。 ビジネス ロジックに応じて、変更通知は次の場合に適しています。
- サブスクライブしているリソースが頻繁に変更される場合。
- ほぼリアルタイムで変化に対応する必要があります。
- スロットリングの制限に達する原因となる可能性がある Microsoft Graph を頻繁にポーリングしないようにする必要があります。
次の画像は、変更通知のしくみを示し、 変更追跡との比較です。
次のビデオでは、Microsoft Graph の変更通知の概要を示します。
変更通知の種類
Microsoft Graph では、次の 3 種類の変更通知がサポートされています。
- 基本通知: 変更されたリソースの ID 以外のリソース データを含まない変更通知。 アプリが基本通知を受信すると、サービスは ID を使用して変更されたオブジェクトをクエリできます。
- リッチ通知: 変更されたオブジェクトのリソース データを含む変更通知。 リッチ通知の詳細については、「 リッチ通知」を参照してください。
- ライフサイクル通知: サブスクリプションのライフサイクルが原因で変更通知を見逃すリスクがある場合に、顧客に警告する通知。 ライフサイクル通知の詳細については、「 ライフサイクル通知」を参照してください。
変更通知の受信
Microsoft Graph では、次のチャネルを介してクライアントに変更通知を配信できます。
- Web フック。 詳細については、「 Webhook を使用して変更通知を受け取る」を参照してください。
- Azure Event Hubs。 詳細については、「Azure Event Hubs を使用した変更通知の受信」を参照してください。
- Azure Event Grid. 詳細については、「Azure Event Grid を介して変更通知を受け取る」を参照してください。
サブスクリプションの管理
クライアントは、サブスクリプションを作成したり、サブスクリプションを更新したり、サブスクリプションを削除したりできます。 サブスクリプションがアクティブな間、サブスクライブされているリソースに変更が発生すると、Microsoft Graph は指定した通知エンドポイントに変更通知を送信します。
サブスクリプション リソースの種類とそれに関連するメソッドを使用して、サブスクリプションを管理します。 Microsoft Graph は、 changeNotificationCollection リソースの種類で定義された構造体で変更通知を送信します。
サポートされているリソース
アプリは、表に一覧表示されている Microsoft Graph リソースの変更をサブスクライブできます。 アスタリスク (*) が付いたリソースへのサブスクリプションは、 /beta エンドポイントでのみ使用できます。
注:
Microsoft Teamsリソースの場合、organizationあたりの合計 10,000 サブスクリプションの制限は、テナント内のすべての Teams 変更通知サブスクリプション間で累積的に共有されます。 これには、チャット、チャット メッセージ、通話記録、通話録音、チャネル、チーム、会話メンバーなど、さまざまな Teams リソース用に作成されたサブスクリプションが含まれます。これらは すべて同じ組織のクォータにカウントされます。 アクティブな Teams サブスクリプションの合計数がこの制限に達すると、Teams リソースの追加サブスクリプション作成要求は403 Forbiddenエラーで失敗します。
| リソース | サポートされるリソース パス | 制限事項 |
|---|---|---|
| クラウド印刷の printer | 印刷ジョブをダウンロードする準備ができたときの変更 (jobFetchable イベント): /print/printers/{id}/jobs |
- |
| クラウド印刷の printTaskDefinition | キューに有効なジョブがある場合の変更 (jobStarted イベント): /print/printtaskdefinition/{id}/tasks |
- |
| Copilot aiInsights | 特定のユーザーが参加している会議からの Copilot AI 分析情報: /copilot/users/{userId}/onlineMeetings/getAllAiInsights 特定の会議に関する Copilot AI 分析情報: /copilot/users/{userId}/onlineMeetings/{onlineMeetingId}/aiInsights |
ユーザーのすべての会議にわたる AI 分析情報の最大サブスクリプション クォータ:
特定の会議の AI 分析情報の最大サブスクリプション クォータ:
|
| Copilot aiInteraction | 特定のユーザーが参加している Copilot AI 対話: copilot/users/{userId}/interactionHistory/getAllEnterpriseInteractions organization における Copilot AI の相互作用: copilot/interactionHistory/getAllEnterpriseInteractions |
最大サブスクリプションのクォータ:
|
| OneDrive (個人用) の driveItem |
任意のフォルダーの階層内のコンテンツに対する変更:/users/{id}/drive/root |
- |
| 職場または学校用 OneDrive の driveItem |
ルート フォルダーの階層内のコンテンツに対する変更: /drives/{id}/root ,/users/{id}/drive/root |
- |
| group | すべてのグループへの変更: /groups 特定のグループへの変更: /groups/{id} 特定のグループの所有者に対する変更: /groups/{id}/owners 特定のグループのメンバーに対する変更: /groups/{id}/members |
最大サブスクリプションのクォータ:
Azure AD B2C テナントではサポートされていません。 注: グループの作成と論理的な削除も updatedchangeType をトリガーします。 |
| Microsoft Entra Health Monitoring アラート | すべての正常性監視アラートに対する変更: /reports/healthmonitoring/alerts 特定の種類のアラートへの変更: 要求ペイロードの notificationQueryOptions プロパティが次に設定された/reports/healthmonitoring/alert$filter=alertType eq '{alertType}' |
- |
| SharePoint サイトのリスト |
リスト内のコンテンツに対する変更:/sites/{site-id}/lists/{list-id} |
- |
| Microsoft 365 グループ会話 | グループの会話に対する変更: groups/{id}/conversations |
- |
| Outlook メッセージ | ユーザーのメールボックス内のすべてのメッセージに対する変更: /users/{id}/messages , /me/messages ユーザーの受信トレイ内のメッセージに対する変更: /users/{id}/mailFolders('inbox')/messages , /me/mailFolders('inbox')/messages |
すべてのアプリケーションに対して、メールボックスあたり最大 1,000 のアクティブなサブスクリプションが許可されます。 |
| Outlook イベント | ユーザーのメールボックス内のすべてのイベントに対する変更: /users/{id}/events , /me/events |
すべてのアプリケーションに対して、メールボックスあたり最大 1,000 のアクティブなサブスクリプションが許可されます。 |
| Outlook 個人用連絡先 | ユーザーのメールボックス内のすべての個人用連絡先への変更: /users/{id}/contacts , /me/contacts |
すべてのアプリケーションに対して、メールボックスあたり最大 1,000 のアクティブなサブスクリプションが許可されます。 |
| セキュリティの警告 | 特定のアラートに対する変更: /security/alerts/{id} フィルター処理されたアラートに対する変更: /security/alerts/?$filter={parameters} |
詳細については、「Security APIアラート」を参照してください。 |
| Teams の承認 | テナント内のすべての承認に対する変更: /solutions/approval/approvalItems |
最大サブスクリプションのクォータ:
|
| Teams callRecord | すべての通話レコードを変更する: /communications/callRecords フィルター処理された通話レコードに対する変更: /communications/callRecords?$filter={parameters} |
詳細については、「 通話レコードの変更通知」を参照してください。 最大サブスクリプションのクォータ:
注: 通話記録の作成も updatedchangeType をトリガーします。 |
| Teams callRecording | すべてのレコーディング organization:communications/onlineMeetings/getAllRecordings 特定の会議のすべての記録: communications/onlineMeetings/{onlineMeetingId}/recordings 特定のユーザーによって開催された会議で利用可能になる通話録音: users/{id}/onlineMeetings/getAllRecordings 特定の Teams アプリがインストールされている会議で利用可能になる通話録音: appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllRecordings * |
最大サブスクリプションのクォータ:
|
| Teams callTranscript | All transcripts in an organization:communications/onlineMeetings/getAllTranscripts 特定の会議のすべてのトランスクリプト: communications/onlineMeetings/{onlineMeetingId}/transcripts 特定のユーザーによって開催された会議で利用可能になる通話記録: users/{id}/onlineMeetings/getAllTranscripts 特定の Teams アプリがインストールされている会議で利用可能になる通話記録: appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllTrancripts * |
最大サブスクリプションのクォータ:
|
| Teams チャット | テナント内のチャットに対する変更: /chats 特定のチャットへの変更: /chats/{id} notifyOnUserSpecificProperties クエリ パラメーターを使用して特定のチャットを変更します。 /chats/{id}?notifyOnUserSpecificProperties={Boolean} 特定の Teams アプリがインストールされている organization 内のすべてのチャットへの変更: /appCatalogs/teamsApps/{id}/installedToChats 特定のユーザーが参加しているすべてのチャットへの変更: /users/{id}/chats notifyOnUserSpecificProperties クエリ パラメーターを使用して、特定のユーザーが参加しているすべてのチャットへの変更: /users/{id}/chats?notifyOnUserSpecificProperties={Boolean} |
最大サブスクリプションのクォータ:
|
| Teams chatMessage | すべてのチームのすべてのチャネルのチャット メッセージに対する変更: /teams/getAllMessages 特定のチャネルのチャット メッセージに対する変更: /teams/{id}/channels/{id}/messages すべてのチャットのチャット メッセージに対する変更: /chats/getAllMessages 特定のチャットのチャット メッセージに対する変更: /chats/{id}/messages 特定のユーザーが参加しているすべてのチャットのチャット メッセージに対する変更: /users/{id}/chats/getAllMessages 特定の Teams アプリがインストールされている organization 内のすべてのチャットのチャット メッセージに対する変更: /appCatalogs/teamsApps/{id}/installedToChats/getAllMessages |
最大サブスクリプションのクォータ:
|
| Teams チャネル | すべてのチームのチャネルに対する変更: /teams/getAllChannels 特定のチームのチャネルに対する変更: /teams/{id}/channels |
最大サブスクリプションのクォータ:
|
| Teams conversationMember | 特定のチームのメンバーシップの変更: /teams/{id}/members 特定のチームの下にあるすべてのチャネルのメンバーシップの変更: teams/{id}/channels/getAllMembers 特定のチャットのメンバーシップの変更: /chats/{id}/members 特定の Teams アプリがインストールされている organization 内のすべてのチャットのメンバーシップへの変更: /appCatalogs/teamsApps/{id}/installedToChats/getAllMembers すべてのチャットのメンバーシップの変更: /chats/getAllMembers |
最大サブスクリプションのクォータ:
|
| Teams onlineMeeting* | オンライン会議への変更: /communications/onlineMeetings(joinWebUrl='{encodedJoinWebUrl}')/meetingCallEvents |
$select を使用して選択したプロパティのみを返すことはサポートしていません。 リッチ通知は、変更されたインスタンスのすべてのプロパティで構成されます。 オンライン会議につき、アプリケーションごとに 1 つのサブスクリプションが許可されます。 詳細については、「 Microsoft Teams 会議通話イベントの更新の変更通知を受け取る」を参照してください。 |
| Teams プレゼンス | 1 人のユーザーのプレゼンスに対する変更: /communications/presences/{id} 複数のユーザーのプレゼンスに対する変更: /communications/presences?$filter=id in ({id},{id}...) |
複数のユーザーのプレゼンスのサブスクリプションは、650 人の個別ユーザーに制限されます。
$select を使用して選択したプロパティのみを返すことはサポートしていません。 リッチ通知は、変更されたインスタンスのすべてのプロパティで構成されます。 委任されたユーザーごとにアプリケーションごとに 1 つのサブスクリプションが許可されます。 詳細については、「 Microsoft Teams でのプレゼンス更新の変更通知を受け取る」を参照してください。 |
| Teams チーム | テナント内のチームに対する変更: /teams 特定のチームに対する変更: /teams/{id} |
最大サブスクリプションのクォータ:
|
| Teams Shifts offerShiftRequest | チーム内のオファー シフト要求に対する変更: /teams/{id}/schedule/offerShiftRequests |
最大サブスクリプションのクォータ:
|
| Teams Shifts openShiftChangeRequest | チームの空きシフト要求に対する変更: /teams/{id}/schedule/openShiftChangeRequests |
最大サブスクリプションのクォータ:
|
| Teams シフト シフト | チーム内のシフトに対する変更: /teams/{id}/schedule/shifts |
最大サブスクリプションのクォータ:
|
| Teams Shifts swapShiftsChangeRequest | チーム内のスワップ シフト要求に対する変更: /teams/{id}/schedule/swapShiftsChangeRequests |
最大サブスクリプションのクォータ:
|
| Teams Shifts timeOffRequest | チーム内の休暇要求に対する変更: /teams/{id}/schedule/timeOffRequests |
最大サブスクリプションのクォータ:
|
| todoTask | 特定のタスク リスト内のすべてのタスクに対する変更: /me/todo/lists/{todoTaskListId}/tasks |
- |
| user | すべてのユーザーに対する変更: /users 特定のユーザーに対する変更: /users/{id} |
最大サブスクリプションのクォータ:
outlook.com などの個人用 Microsoft アカウントではサポートされていません。 Azure AD B2C テナントではサポートされていません。 注: ユーザーの作成と論理的な削除も updatedchangeType をトリガーします。 |
注:
多くのリソースには、そのリソースに対して作成できるサブスクリプションの数に関する制限またはクォータがあります。 この制限を超えると、サブスクリプションを作成しようとすると、 403 Forbidden エラー応答が生成されます。 エラー応答の message プロパティにより、超過した制限が説明されます。
これらのリソースの一部はリッチ通知 (リソース データを含む通知) をサポートしています。 詳細については、「 リソース データを含む変更通知の設定」を参照してください。
サブスクリプション ライフタイム
サブスクリプションのライフタイムには制限があります。 アプリは、有効期限が切れる前にサブスクリプションを更新する必要があります。それ以外の場合は、新しいサブスクリプションを作成する必要があります。 また、アプリはいつでも登録を解除して、変更通知の受信を停止できます。
次の表は、Microsoft Graph のリソースあたりのサブスクリプションの最大有効期限を示しています。
| Resource | 最大有効期限 |
|---|---|
| Copilot aiInteraction | 4,320 分 (3 日間) |
| セキュリティの警告 | 43,200 分 (30 日未満) |
| Teams の承認 | 43,200 分 (30 日未満) |
| Teams callRecord | 4,230分(3日以内) |
| Teams callRecording | 4,320 分 (3 日間) |
| Teams callTranscript | 4,320 分 (3 日間) |
| Teams チャネル | 4,320 分 (3 日間) |
| Teams チャット | 4,320 分 (3 日間) |
| Teams chatMessage | 4,320 分 (3 日間) |
| Teams conversationMember | 4,320 分 (3 日間) |
| Teams onlineMeeting | 4,320 分 (3 日間) |
| Teams チーム | 4,320 分 (3 日間) |
| Teams teamsAppInstallation | 4,320 分 (3 日間) |
| Teams Shifts offerShiftRequest | 360 分 (6 時間) |
| Teams Shifts openShiftChangeRequest | 360 分 (6 時間) |
| Teams シフト シフト | 360 分 (6 時間) |
| Teams Shifts swapShiftsChangeRequest | 360 分 (6 時間) |
| Teams Shifts timeOffRequest | 360 分 (6 時間) |
| グループ会話 | 4,230分(3日以内) |
| OneDrive driveItem | 42,300 分 (30 日未満) |
| SharePoint リスト | 42,300 分 (30 日未満) |
| Outlook メッセージ、イベント、連絡先 | 10,080 分 (7 日間未満) リソース データを含むサブスクリプション (リッチ通知サブスクリプション) の場合、サブスクリプションの有効期間は 1440 分 (1 日未満) です。 |
| ユーザー、グループ、その他のディレクトリ リソース | 41,760 分 (29 日未満) |
| オンライン会議 | 4,230分(3日以内) |
| プレゼンス | 60 分 (1 時間) |
| 印刷 printer | 4,230分(3日以内) |
| 印刷 printTaskDefinition | 4,230分(3日以内) |
| todoTask | 4,230分(3日以内) このリソースの Webhook はグローバル エンドポイントでのみ使用でき、国内クラウドでは使用できません。 |
| Microsoft Entra Health Monitoring アラート | 42,300 分 (30 日未満) |
| baseTask (非推奨) | 4,230分(3日以内) |
注: 既存のアプリケーションと新規アプリケーションのどちらもサポートされている値を超えてはなりません。 将来的には、最大値を超えるサブスクリプションを作成または更新する要求はすべて失敗します。
遅延
次の表は、サービスで発生するイベントと変更通知の配信との間で予想される待ち時間を示しています。
| リソース | 平均遅延時間 | 最大遅延時間 |
|---|---|---|
| aiInteraction | 10 秒未満 | 60 分 |
| アラート1 | 3 分未満 | 5 分 |
| 承認 | 10 秒未満 | 40 秒 |
| calendar | 1 分未満 | 3 分 |
| callRecord2 | 30 分以内 | 150 分 |
| callRecording | 10 秒未満 | 240 分 3 |
| callTranscript | 10 秒未満 | 240 分 3 |
| channel | 10 秒未満 | 60 分 |
| チャット | 10 秒未満 | 60 分 |
| chatMessage | 10 秒未満 | 1 分 |
| contact | 1 分未満 | 3 分 |
| 会話 | 不明 | 不明 |
| conversationMember | 10 秒未満 | 60 分 |
| driveItem | 1 分未満 | 6 時間 |
| イベント | 不明 | 不明 |
| グループ | 不明 | 不明 |
| 正常性監視アラート | 不明 | 不明 |
| リスト | 1 分未満 | 6 時間 |
| message | 1 分未満 | 3 分 |
| offerShiftRequest | 1 分未満 | 60 分 |
| onlineMeeting | 10 秒未満 | 1 分 |
| openShiftChangeRequest | 1 分未満 | 60 分 |
| プレゼンス | 10 秒未満 | 1 分 |
| printer | 1 分未満 | 5 分 |
| printTaskDefinition | 1 分未満 | 5 分 |
| シフト | 1 分未満 | 60 分 |
| swapShiftsChangeRequest | 1 分未満 | 60 分 |
| team | 10 秒未満 | 60 分 |
| teamsAppInstallation | 10 秒未満 | 60 分 |
| timeOffRequest | 1 分未満 | 60 分 |
| todoTask | 2 分未満 | 15 分 |
| ユーザー | 不明 | 不明 |
1アラート リソースに対して提供される待機時間は、アラートの作成後にのみ適用されます。 ルールがデータからアラートを作成するのにかかる時間は含まれません。
2callRecord リソースに対して提供される待機時間は、通話レコードの最初のバージョンにのみ適用されます。 それ以降のバージョンの通話記録は、記載されている遅延を超えて更新される場合があります。
3通話録音 と 通話トランスクリプト の変更通知は通常、レコーディングとトランスクリプトの生成から 10 秒以内に配信されます。これは、通話が終了してから数分後に発生する場合があります。
コード サンプル
GitHub では、次のコード サンプルを利用できます。
- Microsoft Graph トレーニング モジュール - Microsoft Graph で変更通知と変更履歴を使用する
- Node.js 用 Microsoft Graph Webhooks のサンプル
- ASP.NET 用 Microsoft Graph Webhooks のサンプル
- Java Spring 用 Microsoft Graph Webhooks のサンプル