デルタ クエリを使用して、Microsoft Graph データの変更を追跡する

  • [アーティクル]

差分クエリ ( 変更追跡とも呼ばれます) を使用すると、アプリケーションは、すべての要求でターゲット リソースの完全な読み取りを実行することなく、新しく作成、更新、または削除されたエンティティを検出できます。 Microsoft Graph アプリケーションはデルタ クエリを使用して、変更をローカル データ ストアと効率的に同期させることができます。

差分クエリを使用すると、アプリが前回の要求以降に変更されたデータのみを要求するため、Microsoft Graph のポーリングを常に回避できます。 このパターンにより、アプリケーションは要求するデータの量を削減できるため、要求のコストが削減されるため、要求が調整される可能性が制限 される可能性があります。

デルタ クエリを使用して、リソース コレクション内の変更を追跡する

標準的な呼び出しパターンは次のとおりです。

  1. アプリケーションは、目的のリソースに 対してデルタ 関数を使用して GET 要求を行います。 たとえば、「 GET https://graph.microsoft.com/v1.0/users/delta 」のように入力します。

    ヒント

    /delta は完全修飾名のショートカットです /microsoft.graph.delta。 Microsoft Graph SDK によって生成された要求では、完全修飾名が使用されます。

  2. Microsoft Graph は、要求されたリソースと 状態トークンで応答します。

    a. Microsoft Graph が URL を返す @odata.nextLink 場合、現在の応答に空の結果が含まれている場合でも、セッションで取得するデータのページが増えます。 アプリケーションでは、URL を @odata.nextLink 使用して、応答で URL が返 @odata.deltaLink されるまで、すべてのデータ ページを取得する要求を引き続き行います。

    b. Microsoft Graph から URL が返 @odata.deltaLink された場合、現在のセッションで返されるリソースの既存の状態に関するデータはそれ以上ありません。 以降の要求では、アプリケーションは @odata.deltaLink URL を使用して、リソースへの変更点を確認します。

    注:

    手順 2 の Microsoft Graph 応答には、 コレクションに現在 存在するリソースが含まれています。 最初のデルタ クエリの前に削除されたリソースは返されません。 最初の要求の前に行われた更新は、最新の状態として返されたリソースで要約されます。

  3. アプリケーションは、リソースの変更について学習する必要がある場合、手順 2 で受け取った URL を使用 @odata.deltaLink して要求を行います。 アプリケーションは、手順 2 を完了した直後、または変更を確認するときに、この要求を行うことができます。

  4. Microsoft Graph は、前の要求以降のリソースへの変更を説明する応答と、@odata.nextLink URL または @odata.deltaLink URL のいずれかを返します。

注:

  • Microsoft Entra IDに格納されているリソース (ユーザーやグループなど) では、"今からの同期" シナリオがサポートされます。 このため、手順 1 と 2 をスキップし (リソースの完全な状態を取得する必要がない場合)、代わりに最新の @odata.deltaLink を要求することができます。 $deltatoken=latest を delta 関数に追加すると、応答には @odata.deltaLink が含まれ、リソー スデータは一切含まれません。 OneDrive と SharePoint のリソースもこの機能をサポートしていますが、代わりに必要 token=latest です。
  • $selectクエリ パラメーターと$deltaLinkクエリ パラメーターは、一部のMicrosoft Entra リソースでサポートされているため、顧客は既存@odata.deltaLinkの を追跡するプロパティを変更できます。 と $skiptoken の両方$selectを持つデルタ クエリはサポートされていません。

状態トークン

デルタ クエリ GET 応答には、常に、または @odata.deltaLink 応答ヘッダーで指定された URL が@odata.nextLink含まれます。 URL には @odata.nextLink が $skiptoken含まれており、 @odata.deltaLink URL には が $deltatoken含まれます。

これらのトークンはクライアント アプリに対して不透明ですが、次のように重要です。

  • 各トークンは状態を反映し、そのラウンドの変更追跡におけるリソースのスナップショットを表します。
  • 状態トークンは、最初のデルタ クエリ要求で指定されたクエリ パラメーター (など $select) をエンコードして含めます。 したがって、後続のデルタ クエリ要求を変更して、これらのクエリ パラメーターを繰り返さないでください。
  • デルタ クエリを実行するときは、状態トークンなど、URL の内容を調べることなく、@odata.nextLink または @odata.deltaLink の URL を次のデルタ関数呼び出しにコピーして適用できます。

オプションのクエリ パラメーター

クライアントがクエリ パラメーターを使用する場合は、最初の要求で指定する 必要があります 。 Microsoft Graph は、指定されたクエリ パラメーター @odata.nextLink を応答内または @odata.deltaLink 後続のすべての @odata.nextLink@odata.deltaLink URL に自動的にエンコードします。

次のオプション クエリ パラメーターの一般的な限定サポートに注意してください。

  • $orderby

    デルタ クエリから返される応答の特定のシーケンスを想定しないでください。 @odata.nextLink シーケンスのどこにでも同じアイテムが出現する可能性があると想定し、マージ ロジックの中でそれを処理します。

  • $top

    各ページのオブジェクトの数は、リソース タイプとリソースに加えられた変更のタイプによって異なります。

メッセージ リソースについては、「デルタ クエリでのクエリ パラメーター サポート」の詳細を参照してください。

ユーザーとグループ リソースには、いくつかのクエリ パラメーターの使用に関する制限があります。

  • $expand はサポートされていません。

  • $top はサポートされていません。

  • $orderby はサポートされていません。

  • クエリ パラメーターを $select 使用する場合、 パラメーターは、クライアントが ステートメントで $select 指定されたプロパティまたはリレーションシップの変更のみを追跡することを好むことを示します。 選択されていないプロパティに変更が発生した場合、そのプロパティが変更されたリソースは、後続の要求の後に差分応答に表示されません。

  • $select 、ユーザーとグループのそれぞれのマネージャーとメンバーのナビゲーション プロパティもサポートします。 これらのプロパティを選択すると、ユーザーのマネージャーとグループ メンバーシップの変更を追跡できます。

  • スコープ フィルターを使用すると、1 つ以上の特定のユーザーまたはグループに対する変更を追跡し、 オブジェクト ID によってのみフィルター処理できます。 たとえば次のリクエストは、クエリ フィルターで指定された ID と一致するグループの変更を返します。

https://graph.microsoft.com/beta/groups/delta/?$filter=id eq '477e9fc6-5de7-4406-bb2a-7e5c83c9ae5f' or id eq '004d6a07-fe70-4b92-add5-e6e37b8acd8e'

デルタ クエリ応答でのリソース表記

  • サポートされているリソースの新しく作成されたインスタンスは、標準的な表現を使用してデルタ クエリ応答で表されます。

  • 更新されたインスタンスは、少なくとも更新されたプロパティを持つ ID で表されますが、他のプロパティが含まれる場合があります。

  • ユーザーとグループのリレーションシップは、標準リソース表現の注釈として表されます。 これらの注釈では、 形式propertyName@deltaが使用されます。 注釈は、最初のデルタ クエリ要求の応答に含まれます。

  • 削除されたインスタンスは、 ID と @removed オブジェクトで表されます。 @removed オブジェクトには、インスタンスが削除された理由に関する追加情報が含まれる場合があります。 たとえば、「 "@removed": {"reason": "changed"} 」のように入力します。 考えられる @removed の理由は、changed または deleted である可能性があります。

    • changed は、項目は削除されたものの、deletedItems から復元できることを表します。

    • deleted は、アイテムが削除され、復元できないことを示します。

      @removed オブジェクトは、最初のデルタ クエリ応答と追跡 (@odata.nextLink) 応答で返すことができます。 たとえば、削除済みアイテムから復元できる削除済みディレクトリ オブジェクトは として "@removed": {"reason": "changed"}表示されます。 デルタ クエリ要求を使用するクライアントは、応答でこれらのオブジェクトを処理するように設計する必要があります。

  • deletedItems から復元されたインスタンスは、差分クエリ応答に新しく作成されたインスタンスとして表示されます。

注:

1 つのエンティティを応答に複数回含めることができます。そのエンティティが複数回変更され、特定の条件下で変更された場合。 デルタ クエリを使用すると、アプリケーションはすべての変更を一覧表示できますが、エンティティを 1 つの応答で統合することはできません。

サポートされているリソース

デルタ クエリは現在、次のリソースでサポートされています。 v1.0 で使用できる一部のリソースには、示されているように、対応する デルタ 関数がプレビュー状態のままです。

注: アスタリスク (*) でマークされたリソースのデルタ関数は、エンドポイントでのみ使用できます /beta 。

リソース コレクション API
application application: delta 関数
administrativeUnit administrativeUnit: delta 関数
callRecording * callRecording: delta 関数
callTranscript * callTranscript: delta 関数
chatMessage chatMessage: デルタ 関数
device device: delta 関数
directoryRole directoryRole: delta 関数
directoryObject directoryObject: delta 関数
driveItem1 driveItem: delta 関数
educationAssignment educationAssignment: delta 関数
educationCategory educationCategory: delta 関数
educationClass educationClass: デルタ 関数
educationSchool educationSchool: delta 関数
educationUser educationUser: delta 関数
event event: delta 関数
group group: delta 関数
listItem1 listItem: delta 関数
mailFolder mailFolder: delta 関数
message message: delta 関数
orgContact orgContact: delta 関数
oAuth2PermissionGrant oAuth2PermissionGrant: デルタ 関数
contactFolder contactFolder: delta 関数
リソースに問い合わせる contact: delta 関数
plannerBucket * plannerBucket: デルタ 関数
plannerUser2 plannerUser: delta 関数
sites サイト リソースの delta 関数
servicePrincipal servicePrincipal: delta 関数
todoTask todoTask: delta 関数
todoTaskList todoTaskList: delta 関数
user user: delta 関数

注:

1 OneDrive リソースと SharePoint リソースの使用パターンは、サポートされている他のリソースと似ていますが、構文に若干の違いがあります。 現在の構文の詳細については、 driveItem: delta と listItem: delta に関 するページを参照してください。

2 Planner リソースの使用パターンは、サポートされている他のリソースと似ていますが、いくつかの違いがあります。 詳細については、「 planner: delta」を参照してください。

国別クラウド

サポートされているリソースのデルタ クエリは、21Vianet が運営するパブリック クラウド、Microsoft Cloud for US Government、Microsoft Cloud China でホストされているお客様が利用できます。

制限事項

メイン データ ストアの外部に格納されているプロパティの変更は追跡されません

一部のリソースには、リソースのメイン データ ストアの外部に格納されるプロパティが含まれています。 たとえば、ユーザー リソース データは主にMicrosoft Entra IDに格納されますが、スキルなどのプロパティの一部は SharePoint Online に格納されます。 現時点では、メイン データ ストアに格納されているプロパティのみがデルタ クエリで変更をトリガーします。メイン データ ストアの外部に格納されているプロパティは、変更追跡の一部としてサポートされていません。 したがって、これらのプロパティのいずれかに変更を加えた場合、デルタ クエリ応答にオブジェクトが表示されることはありません。

メイン データ ストアの外部に格納されているプロパティの詳細については、ユーザーとグループのドキュメントを参照してください。

処理の遅延

リソース インスタンスが変更されてから、追跡された変更がデルタ クエリ応答に反映されるまでの遅延はさまざまです。

レプリケーションの遅延が原因で、 または @odata.deltaLinkを選択@odata.nextLinkすると、オブジェクトに対する変更がすぐに表示されないことがあります。 しばらくしてから、@odata.nextLink または @odata.deltaLink を再試行して、最新の変更を取得してください。

再生

アプリケーションは、その後の応答で同じ変更が発生した場合に発生する再生に備えておく必要があります。 デルタ クエリはリプレイを減らすためのベスト エフォートですが、引き続き可能です。

同期のリセット

デルタ クエリは、410 Gone の応答コードと空の $deltatoken を含む要求 URL を含む位置ヘッダーを返すことができます (最初のクエリと同じ)。 通常、この状態は、ターゲット テナントの内部メンテナンスまたは移行によるデータの不整合を防ぐために発生し、ターゲット テナントの完全な同期を使用してアプリケーションを再起動する必要があることを示しています。

トークン期間

デルタ トークンは、クライアント アプリケーションが完全同期を再度実行する必要がある前の特定の期間のみ有効です。

  • ディレクトリ オブジェクトの場合、制限は 7 日間です。
  • 教育オブジェクト (EducationSchool、EducationUser、および EducationClass) の場合、制限は 7 日です。
  • Outlook エンティティ (メッセージ、 mailFolder、 イベント、 連絡先、 contactFolder、 todoTask、 todoTaskList) の場合、上限は修正されません。これは、内部デルタ トークン キャッシュのサイズに依存します。 新しいデルタ トークンはキャッシュに継続的に追加されますが、キャッシュ容量を超えた後、古いデルタ トークンは削除されます。

トークンの有効期限が切れた場合、サービスは 40X シリーズのエラー (など syncStateNotFound) と共に応答する必要があります。 詳細については、「Microsoft Graph のエラー コード」を参照してください。

デルタ クエリと変更通知を組み合わせる

アプリでは、Microsoft Graph の変更通知を 使用して、特定のリソースが変更されたときに通知されるようにサブスクライブできます。 アプリケーションはデルタ クエリを使用して、前回要求を行った後のすべての変更を要求することができます。

アプリケーションはこの戦略を使用して、Microsoft Graph を頻繁にポーリングし、それらの変更を処理してローカル データ ストアの同期を維持する必要性をほぼ排除し (サポートされているリソースの場合のみ)、要求が調整される可能性を大幅に減らすことができます。

関連コンテンツ

デルタ クエリの詳細については、次のチュートリアルを参照してください。