デルタ クエリを使用して、Microsoft Graph データの変更を追跡する
- [アーティクル]
-
-
差分クエリ ( 変更追跡とも呼ばれます) を使用すると、アプリケーションは、すべての要求でターゲット リソースの完全な読み取りを実行することなく、新しく作成、更新、または削除されたエンティティを検出できます。 Microsoft Graph アプリケーションはデルタ クエリを使用して、変更をローカル データ ストアと効率的に同期させることができます。
差分クエリを使用すると、アプリが前回の要求以降に変更されたデータのみを要求するため、Microsoft Graph のポーリングを常に回避できます。 このパターンにより、アプリケーションは要求するデータの量を削減できるため、要求のコストが削減されるため、要求が調整される可能性が制限 される可能性があります。
デルタ クエリを使用して、リソース コレクション内の変更を追跡する
標準的な呼び出しパターンは次のとおりです。
アプリケーションは、目的のリソースに 対してデルタ 関数を使用して GET 要求を行います。 たとえば、「 GET https://graph.microsoft.com/v1.0/users/delta
」のように入力します。
ヒント
/delta
は、完全修飾名 /microsoft.graph.delta
のショートカットです。 Microsoft Graph SDK によって生成された要求では、完全修飾名が使用されます。
Microsoft Graph は、要求されたリソースと 状態トークンで応答します。
a. Microsoft Graph が @odata.nextLink
URL を返す場合、現在の応答に空の結果が含まれている場合でも、セッションで取得するデータのページが増えます。 アプリケーションでは、 @odata.nextLink
URL を使用して、Microsoft Graph が応答で @odata.deltaLink
URL を返すまで、データのすべてのページを取得する要求を引き続き行います。
b. Microsoft Graph から @odata.deltaLink
URL が返された場合、現在のセッションで返されるリソースの既存の状態に関するデータはそれ以上ありません。 以降の要求では、アプリケーションは @odata.deltaLink
URL を使用して、リソースへの変更点を確認します。
注意
手順 2 の Microsoft Graph 応答には、 コレクションに現在 存在するリソースが含まれています。 最初のデルタ クエリの前に削除されたリソースは返されません。 最初の要求の前に行われた更新は、最新の状態として返されたリソースで要約されます。
アプリケーションは、リソースの変更について学習する必要がある場合、手順 2 で受け取った @odata.deltaLink
URL を使用して要求を行います。 アプリケーションは、手順 2 を完了した直後、または変更を確認するときに、この要求を行うことができます。
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
に対して追跡するプロパティを変更できます。
$select
と$skiptoken
の両方を持つデルタ クエリはサポートされていません。
デルタ クエリ GET 応答には、常に、 @odata.nextLink
または @odata.deltaLink
応答ヘッダーで指定された URL が含まれます。
@odata.nextLink
URL には$skiptoken
が含まれており、@odata.deltaLink
URL には$deltatoken
が含まれています。
これらのトークンはクライアント アプリに対して不透明ですが、次のように重要です。
- 各トークンは状態を反映し、そのラウンドの変更追跡におけるリソースのスナップショットを表します。
- 状態トークンは、初期デルタ クエリ要求で指定されたクエリ パラメーター (
$select
など) をエンコードして含めます。 したがって、後続のデルタ クエリ要求を変更して、これらのクエリ パラメーターを繰り返さないでください。
- デルタ クエリを実行するときは、状態トークンなど、URL の内容を調べることなく、
@odata.nextLink
または @odata.deltaLink
の URL を次のデルタ関数呼び出しにコピーして適用できます。
クライアントがクエリ パラメーターを使用する場合は、最初の要求で指定する 必要があります 。 Microsoft Graph は、指定したクエリ パラメーターを応答内の @odata.nextLink
または @odata.deltaLink
に自動的にエンコードし、それ以降のすべての @odata.nextLink
または @odata.deltaLink
URL にエンコードします。
次のオプション クエリ パラメーターの一般的な限定サポートに注意してください。
メッセージ リソースについては、「デルタ クエリでのクエリ パラメーター サポート」の詳細を参照してください。
ユーザーとグループ リソースには、いくつかのクエリ パラメーターの使用に関する制限があります。
$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
エンドポイントでのみ使用できます。
サポートされているリソースのデルタ クエリは、パブリック クラウド、Microsoft Cloud for US Government、21Vianet が運営する Microsoft Cloud China でホストされているお客様に対して使用できます。
メイン データ ストアの外部に格納されているプロパティの変更は追跡されません
一部のリソースには、リソースのメイン データ ストアの外部に格納されるプロパティが含まれています。 たとえば、 ユーザー リソース データは主に Microsoft Entra ID に格納されますが、 スキルなどのプロパティの一部は SharePoint Online に格納されます。 現時点では、メイン データ ストアに格納されているプロパティのみがデルタ クエリで変更されます。メイン データ ストアの外部に格納されているプロパティは、変更追跡の一部としてサポートされていません。 したがって、これらのプロパティのいずれかに変更を加えた場合、デルタ クエリ応答にオブジェクトが表示されることはありません。
メイン データ ストアの外部に格納されているプロパティの詳細については、 ユーザー と グループ のドキュメントを参照してください。
リソース インスタンスが変更されてから、追跡された変更がデルタ クエリ応答に反映されるまでの遅延はさまざまです。
レプリケーションの遅延が原因で、 @odata.nextLink
または @odata.deltaLink
を選択すると、オブジェクトに対する変更がすぐに表示されないことがあります。 しばらくしてから、@odata.nextLink
または @odata.deltaLink
を再試行して、最新の変更を取得してください。
アプリケーションは、その後の応答で同じ変更が発生した場合に発生する再生に備えておく必要があります。 デルタ クエリはリプレイを減らすためのベスト エフォートですが、引き続き可能です。
デルタ クエリは、410 Gone
の応答コードと空の $deltatoken
を含む要求 URL を含む位置ヘッダーを返すことができます (最初のクエリと同じ)。 通常、この状態は、ターゲット テナントの内部メンテナンスまたは移行によるデータの不整合を防ぐために発生し、ターゲット テナントの完全な同期を使用してアプリケーションを再起動する必要があることを示しています。
デルタ トークンは、クライアント アプリケーションが完全同期を再度実行する必要がある前の特定の期間のみ有効です。
-
ディレクトリ オブジェクトの場合、制限は 7 日間です。
- 教育オブジェクト (EducationSchool、EducationUser、および EducationClass) の場合、制限は 7 日です。
- Outlook エンティティ (メッセージ、 mailFolder、 イベント、 連絡先、 contactFolder、 todoTask、 todoTaskList) の場合、上限は修正されません。これは、内部デルタ トークン キャッシュのサイズに依存します。 新しいデルタ トークンはキャッシュに継続的に追加されますが、キャッシュ容量を超えた後、古いデルタ トークンは削除されます。
トークンの有効期限が切れた場合、サービスは、 syncStateNotFound
などのエラー コードを含む 40X シリーズのエラーで応答する必要があります。 詳細については、「Microsoft Graph のエラー コード」を参照してください。
アプリでは、Microsoft Graph の変更通知を 使用して、特定のリソースが変更されたときに通知されるようにサブスクライブできます。 アプリケーションはデルタ クエリを使用して、前回要求を行った後のすべての変更を要求することができます。
アプリケーションはこの戦略を使用して、Microsoft Graph を頻繁にポーリングし、それらの変更を処理してローカル データ ストアの同期を維持する必要性をほぼ排除し (サポートされているリソースの場合のみ)、要求が調整される可能性を大幅に減らすことができます。
デルタ クエリの詳細については、次のチュートリアルを参照してください。