リソースデータの変更に関する通知を設定する

変更通知を使用すると、アプリケーションは、関心のある Microsoft Graph リソースが変更されたときにアラートを受け取ります。つまり、作成、更新、または削除されます。 Microsoft Graph は、指定したクライアント エンドポイントに通知を送信し、クライアント サービスはビジネス要件に従って通知を処理します。 たとえば、サービスは、より多くのデータをフェッチしたり、キャッシュとビューを更新したりします。

変更通知を受け取る理由

変更通知は、Microsoft Graph をポーリングするのではなく、変更が発生したときにアラートを受け取るイベント ドリブン モデルに従います。 ビジネス ロジックに応じて、変更通知は次の場合に適しています。

  • 頻繁に変更されるリソースをサブスクライブしています。
  • ほぼリアルタイムで変化に対応する必要があります。
  • 調整の制限に達する可能性がある Microsoft Graph を頻繁にポーリングしないようにする必要があります。

変更通知の種類

Microsoft Graph では、次の 3 種類の変更通知がサポートされています。

  • 基本的な通知: 変更されたリソース の ID 以外のリソース データを含まない通知を変更します。 アプリが基本的な通知を受け取ると、サービスは ID を 使用して変更されたオブジェクトに対してクエリを実行できます。
  • リッチ通知: 変更されたオブジェクトのリソース データを含む通知を変更します。 リッチ通知の詳細については、「 リッチ通知」を参照してください。
  • ライフサイクル通知: サブスクリプションのライフサイクルが原因で変更通知が見つからないリスクがある場合に顧客に警告する通知。 ライフサイクル通知の詳細については、「 ライフサイクル通知」を参照してください。

変更通知の受信

Microsoft Graph では、次のチャネルを介して変更通知をクライアントに配信できます。

サブスクリプションの管理

クライアントは、サブスクリプションを作成したり、サブスクリプションを更新したり、サブスクリプションを削除したりできます。 サブスクリプションがアクティブであり、サブスクライブされたリソースで変更が発生すると、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 for Business の driveItem ルート フォルダーの階層内のコンテンツに対する変更: /drives/{id}/root/users/{id}/drive/root -
group すべてのグループに対する変更: /groups

特定のグループに対する変更: /groups/{id}

特定のグループの所有者に対する変更: /groups/{id}/owners

特定のグループのメンバーに対する変更: /groups/{id}/members
最大サブスクリプションのクォータ:
  • アプリごと (すべてのテナントを組み合わせた場合): 合計サブスクリプション数 50,000。
  • テナントごと (すべてのアプリケーションを組み合わせた場合): すべてのアプリ全体で合計 1,000 個のサブスクリプション。
  • アプリとテナントの組み合わせごとに:合計 100 個のサブスクリプション。

    Azure AD B2C テナントではサポートされていません。

    メモ:グループの作成と論理的な削除によって、changeType もトリガーされますupdated
  • 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 callRecord すべての通話レコードを変更する: /communications/callRecords 最大サブスクリプションのクォータ:
  • organizationあたり: 合計 100 個のサブスクリプション。
  • Teams callRecording organization内のすべての録音:communications/onlineMeetings/getAllRecordings

    特定の会議のすべての記録: communications/onlineMeetings/{onlineMeetingId}/recordings

    特定のユーザーが開催した会議で使用できる通話記録: users/{id}/onlineMeetings/getAllRecordings
    最大サブスクリプションのクォータ:
  • アプリとオンライン会議の組み合わせごとに: 1
  • アプリとユーザーの組み合わせごとに: 1
  • ユーザーごと (ユーザーが整理したすべての onlineMeetings の記録を追跡するサブスクリプションの場合): 10 個のサブスクリプション。
  • organizationあたり: 合計 10,000 個のサブスクリプション。
  • Teams callTranscript organization内のすべてのトランスクリプト:communications/onlineMeetings/getAllTranscripts

    特定の会議のすべてのトランスクリプト: communications/onlineMeetings/{onlineMeetingId}/transcripts

    特定のユーザーが開催した会議で使用できる通話トランスクリプト: users/{id}/onlineMeetings/getAllTranscripts
    最大サブスクリプションのクォータ:
  • アプリとオンライン会議の組み合わせごとに: 1
  • アプリとユーザーの組み合わせごとに: 1
  • ユーザーごと (ユーザーが整理したすべての onlineMeetings のトランスクリプトを追跡するサブスクリプションの場合): 10 個のサブスクリプション。
  • organizationあたり: 合計 10,000 個のサブスクリプション。
  • Teams チャット テナント内のすべてのチャットに対する変更: /chats

    特定のチャットに対する変更: /chats/{id}

    特定の Teams アプリがインストールされているorganization内のすべてのチャットに対する変更:/appCatalogs/teamsApps/{id}/installedToChats
    最大サブスクリプションのクォータ:
  • アプリとチャットの組み合わせごとに:1 つのサブスクリプション。
  • organizationあたり: 合計 10,000 個のサブスクリプション。
  • 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
    最大サブスクリプションのクォータ:
  • アプリとチャネルまたはチャットの組み合わせごとに:1 つのサブスクリプション。
  • ユーザーごと (ユーザーが参加しているすべてのチャット内のチャット メッセージを追跡するサブスクリプションの場合): 10 個のサブスクリプション。
  • organizationあたり: 合計 10,000 個のサブスクリプション。
  • Teams チャネル すべてのチームのチャネルに対する変更: /teams/getAllChannels

    特定のチームのチャネルに対する変更: /teams/{id}/channels
    最大サブスクリプションのクォータ:
  • アプリとチームの組み合わせごとに:1 つのサブスクリプション。
  • organizationあたり: 合計 10,000 個のサブスクリプション。
  • Teams conversationMember 特定のチームのメンバーシップの変更: /teams/{id}/members

    特定のチームのすべてのチャネルのメンバーシップに対する変更: teams/{id}/channels/getAllMembers

    特定のチャットでのメンバーシップの変更: /chats/{id}/members

    特定の Teams アプリがインストールされているorganization内のすべてのチャットのメンバーシップに対する変更:/appCatalogs/teamsApps/{id}/installedToChats/getAllMembers

    すべてのチャットのメンバーシップに対する変更: /chats/getAllMembers
    最大サブスクリプションのクォータ:
  • アプリとチームの組み合わせごとに:1 つのサブスクリプション。
  • organizationあたり: 合計 10,000 個のサブスクリプション。
  • Teams onlineMeeting* オンライン会議の変更: /communications/onlineMeetings/?$filter=JoinWebUrl eq {joinWebUrl}
    Teams プレゼンス 1 人のユーザーのプレゼンスに対する変更: /communications/presences/{id}

    複数のユーザー プレゼンスに対する変更: /communications/presences?$filter=id in ({id},{id}...)
    Teams チーム テナント内の任意のチームに対する変更: /teams

    特定のチームへの変更: /teams/{id}
    最大サブスクリプションのクォータ:
  • アプリとチームの組み合わせごとに:1 つのサブスクリプション。
  • organizationあたり: 合計 10,000 個のサブスクリプション。
  • todoTask 特定のタスク リスト内のすべてのタスクに対する変更: /me/todo/lists/{todoTaskListId}/tasks -
    user すべてのユーザーに対する変更: /users

    特定のユーザーに対する変更: /users/{id}
    最大サブスクリプションのクォータ:
  • アプリごと (すべてのテナントを組み合わせた場合): 合計サブスクリプション数 50,000。
  • テナント 1 つあたり (すべてのアプリケーションの合計): すべてのアプリケーションでの合計サブスクリプション数 1,000
  • アプリとテナントの組み合わせごとに:合計 100 個のサブスクリプション。

    outlook.com などの個人の Microsoft アカウントではサポートされていません。

    Azure AD B2C テナントではサポートされていません。

    メモ:ユーザーの作成と論理的な削除によって、changeType もトリガーされますupdated
  • メモ: 多くのリソースには、そのリソースに対して実行できるサブスクリプションの数に関する制限またはクォータがあります。 この制限を超えると、サブスクリプションを作成しようとするとエラー応答が 403 Forbidden 発生します。 エラー応答の message プロパティは、超過した制限について説明します。

    これらのリソースの一部では、リッチ通知 (リソース データを含む通知) がサポートされています。 リッチ通知をサポートするリソースの詳細については、「 リソース データを含む変更通知を設定する」を参照してください。

    サブスクリプション ライフタイム

    サブスクリプションのライフタイムには制限があります。 アプリは、有効期限が切れる前にサブスクリプションを更新する必要があります。それ以外の場合は、新しいサブスクリプションを作成する必要があります。 また、アプリはいつでも登録を解除して、変更通知の受信を停止できます。

    次の表は、Microsoft Graph のリソースあたりのサブスクリプションの最大有効期限を示しています。

    Resource 最大有効期限
    セキュリティの警告 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 日間)
    グループ会話 4,230 分 (3 日以内)
    OneDrive driveItem 42,300 分 (30 日以内)
    SharePoint リスト 42,300 分 (30 日以内)
    Outlook メッセージイベント連絡先 4,230 分 (3 日以内)
    ユーザーグループ、その他のディレクトリ リソース 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 分
    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 分
    イベント 不明 不明
    グループ 2 分未満 15 分
    リスト 1 分未満 5 分
    メッセージ 1 分未満 3 分
    onlineMeeting 10 秒未満 1 分
    プレゼンス 10 秒未満 1 分
    printer 1 分未満 5 分
    printTaskDefinition 1 分未満 5 分
    team 10 秒未満 60 分
    todoTask 2 分未満 15 分
    ユーザー 2 分未満 15 分

    1 アラート リソースに対して提供される待機時間は、 アラート が作成された後にのみ適用されます。 ルールがデータからアラートを作成するのにかかる時間は含まれません。

    コード サンプル

    GitHub では、次のコード サンプルを利用できます。