リソースデータの変更に関する通知を設定する
変更通知を使用すると、アプリケーションは、関心のある Microsoft Graph リソースが変更されたときにアラートを受け取ります。つまり、作成、更新、または削除されます。 Microsoft Graph は、指定したクライアント エンドポイントに通知を送信し、クライアント サービスはビジネス要件に従って通知を処理します。 たとえば、サービスは、より多くのデータをフェッチしたり、キャッシュとビューを更新したりします。
変更通知を受け取る理由
変更通知は、Microsoft Graph をポーリングするのではなく、変更が発生したときにアラートを受け取るイベント ドリブン モデルに従います。 ビジネス ロジックに応じて、変更通知は次の場合に適しています。
- 頻繁に変更されるリソースをサブスクライブしています。
- ほぼリアルタイムで変化に対応する必要があります。
- 調整の制限に達する可能性がある Microsoft Graph を頻繁にポーリングしないようにする必要があります。
変更通知の種類
Microsoft Graph では、次の 3 種類の変更通知がサポートされています。
- 基本的な通知: 変更されたリソース の ID 以外のリソース データを含まない通知を変更します。 アプリが基本的な通知を受け取ると、サービスは ID を 使用して変更されたオブジェクトに対してクエリを実行できます。
- リッチ通知: 変更されたオブジェクトのリソース データを含む通知を変更します。 リッチ通知の詳細については、「 リッチ通知」を参照してください。
- ライフサイクル通知: サブスクリプションのライフサイクルが原因で変更通知が見つからないリスクがある場合に顧客に警告する通知。 ライフサイクル通知の詳細については、「 ライフサイクル通知」を参照してください。
変更通知の受信
Microsoft Graph では、次のチャネルを介して変更通知をクライアントに配信できます。
- Webhooks。 詳細については、「 Webhook を使用して変更通知を受信する」を参照してください。
- Azure Event Hubs。 詳細については、「Azure Event Hubsを使用して変更通知を受信する」を参照してください。
- Azure Event Grid (プレビュー)。 詳細については、「Azure Event Gridを使用して変更通知を受信する」を参照してください。
サブスクリプションの管理
クライアントは、サブスクリプションを作成したり、サブスクリプションを更新したり、サブスクリプションを削除したりできます。 サブスクリプションがアクティブであり、サブスクライブされたリソースで変更が発生すると、Microsoft Graph は指定された通知エンドポイントに変更通知を送信します。
サブスクリプションは、 サブスクリプション リソースの種類 とその関連する方法を使用して管理します。 Microsoft Graph は、 changeNotificationCollection リソースの種類で定義されている構造体で変更通知を送信します。
サポートされているリソース
アプリは、表に一覧表示されている Microsoft Graph リソースの変更をサブスクライブできます。
注:
アスタリスク (*) でマークされたリソースへのサブスクリプションは、 /beta エンドポイントでのみ使用できます。
| リソース | サポートされているリソース パス | 制限事項 |
|---|---|---|
| クラウド印刷の printer | 印刷ジョブをダウンロードする準備ができたときに変更されます (jobFetchable イベント): /print/printers/{id}/jobs |
- |
| クラウド印刷の printTaskDefinition | キューに有効なジョブがある場合の変更 (jobStarted イベント): /print/printtaskdefinition/{id}/tasks |
- |
| 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 もトリガーされます。 |
| 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 | 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 オファーShiftRequest | チーム内のオファー シフト要求に対する変更: /teams/{id}/schedule/offerShiftRequests |
最大サブスクリプションのクォータ: |
| Teams Shifts openShiftChangeRequest | チーム内のオープン シフト要求に対する変更: /teams/{id}/schedule/openShiftChangeRequests |
最大サブスクリプションのクォータ: |
| Teams Shifts シフト | チーム内の任意のシフトに対する変更: /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 | 最大有効期限 |
|---|---|
| セキュリティの警告 | 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 オファーShiftRequest | 360 分 (6 時間) |
| Teams Shifts openShiftChangeRequest | 360 分 (6 時間) |
| Teams Shifts シフト | 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 日以内) |
| ユーザー、グループ、その他のディレクトリ リソース | 41,760 分 (29 日以内) |
| オンライン会議 | 4,230 分 (3 日以内) |
| プレゼンス | 60 分 (1 時間) |
| 印刷 printer | 4,230 分 (3 日以内) |
| 印刷 printTaskDefinition | 4,230 分 (3 日以内) |
| todoTask | 4,230 分 (3 日以内) このリソースの Webhook はグローバル エンドポイントでのみ使用でき、国内クラウドでは使用できません。 |
| baseTask (非推奨) | 4,230 分 (3 日以内) |
注: 既存のアプリケーションと新規アプリケーションのどちらもサポートされている値を超えてはなりません。 将来的には、最大値を超えるサブスクリプションを作成または更新する要求はすべて失敗します。
遅延
次の表は、サービスで発生するイベントと変更通知の配信との間で予想される待ち時間を示しています。
| リソース | 平均遅延時間 | 最大遅延時間 |
|---|---|---|
| アラート1 | 3 分未満 | 5 分 |
| 承認 | 10 秒未満 | 40 秒 |
| calendar | 1 分未満 | 3 分 |
| callRecord | 15 分未満 | 60 分 |
| callRecording | 10 秒未満 | 60 分 |
| callTranscript | 10 秒未満 | 60 分 |
| channel | 10 秒未満 | 60 分 |
| チャット | 10 秒未満 | 60 分 |
| chatMessage | 10 秒未満 | 1 分 |
| contact | 1 分未満 | 3 分 |
| 会話 | 不明 | 不明 |
| conversationMember | 10 秒未満 | 60 分 |
| driveItem | 1 分未満 | 5 分 |
| イベント | 不明 | 不明 |
| グループ | 不明 | 不明 |
| リスト | 1 分未満 | 5 分 |
| メッセージ | 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 アラート リソースに対して提供される待機時間は、 アラート が作成された後にのみ適用されます。 ルールがデータからアラートを作成するのにかかる時間は含まれません。
コード サンプル
GitHub では、次のコード サンプルを利用できます。
- Microsoft Graph トレーニング モジュール - Microsoft Graph で変更通知と変更履歴を使用する
- Node.js 用 Microsoft Graph Webhooks のサンプル
- ASP.NET 用 Microsoft Graph Webhooks のサンプル
- Java Spring 用 Microsoft Graph Webhooks のサンプル