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

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

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

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

  1. アプリケーションは、まず目的のリソースでデルタ関数を使用して GET 要求を呼び出します。

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

    a. @odata.nextLink URL が返される場合は、セッションに取得するデータの追加ページがあります。@odata.deltaLink URL が応答で返されるまで、アプリケーションは @odata.nextLink URL を使用してデータのすべてのページを取得する要求を実行し続けます。

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

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

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

注意

Azure Active Directory (ユーザーやグループなど) に保管されているリソースは、"今から同期を開始する" という状況をサポートしています。 このため、手順 1 と 2 をスキップし (リソースの完全な状態を取得する必要がない場合)、代わりに最新の @odata.deltaLink を要求することができます。 $deltaToken=latestdelta 関数に追加すると、応答には @odata.deltaLink が含まれ、リソー スデータは一切含まれません。 OneDrive と SharePoint のリソースもこの機能をサポートしています。 OneDrive および SharePoint のリソースの場合は、代わりに token=latest を追加します。

注意

デルタ クエリ機能は、通常、リソース名に /delta を付加することによって参照されます。 ただし、/delta は Microsoft Graph SDK によって生成された要求に表示される完全修飾名 /microsoft.graph.delta のショートカットです。

注意

デルタ クエリ関数への最初の要求 ($deltaToken または $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 に指定したパラメーターを自動的にエンコードします。呼び出し元のアプリケーションで必要な操作は、クエリ パラメーターを最初に一度指定することだけです。Microsoft Graph は、すべての後続の要求に対して自動的に指定されたパラメーターを追加します。

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

  • $orderby

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

  • $top

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

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

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

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

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

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

  • $select クエリ パラメーターが使用されている場合、パラメーターは、$select ステートメントで指定したプロパティまたはリレーションシップに関する変更のみを追跡することを、クライアントが優先していることを示します。選択されていないプロパティに変更が加えられた場合、そのプロパティが変更されたリソースは、後続の要求後のデルタ応答には表示されなくなります。

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

  • スコープ フィルターで、オブジェクト ID を使って 1 つまたは複数の特定のユーザーまたはグループに加えられた変更を追跡できます。たとえば、次の要求では、クエリ フィルターで指定された 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 オブジェクトは最初のデルタ クエリ応答と追跡された (deltaLink) 応答で返されます。デルタ クエリ要求を使用するクライアントは、応答に含まれるこれらのオブジェクトを処理できるよう設計する必要があります。

注意

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

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

デルタ クエリは現在、次のリソースでサポートされています。v1.0 で使用可能な一部のリソースには、対応する デルタ 関数がプレビュー状態にあることに注意してください。

リソース コレクション API
アプリケーション アプリケーション リソースのデルタ関数
管理単位 (プレビュー) administrativeUnit リソースのデルタ関数 (プレビュー)
チャネルのチャット メッセージ chatMessageデルタ関数 (プレビュー)
ディレクトリ ロール ディレクトリ ロール リソースのデルタ関数
ドライブの項目* driveItem リソースのデルタ関数
教育の割り当て educationAssignment リソースのデルタ関数
教育カテゴリ educationCategory リソースのデルタ関数
教育クラス educationClass リソースのデルタ関数
教育学校 educationSchool リソースのデルタ関数
教育ユーザー educationUser リソースのデルタ関数
標準として設定されている予定表の予定表ビュー (期間) 内のイベント イベントリソースのデルタ関数
グループ グループリソースのデルタ関数
リスト アイテム* リスト アイテム リソースのデルタ関数
メール フォルダー mailFolder リソースのデルタ関数
フォルダー内のメッセージ メッセージリソースのデルタ関数
組織の連絡先 orgContact リソースのデルタ関数
OAuth2PermissionGrants oauth2permissiongrant リソースのデルタ関数
個人用連絡先フォルダー contactFolder リソースのデルタ関数
フォルダー内の個人用連絡先 連絡先リソースのデルタ関数
プランナーの項目**(プレビュー) plannerUser リソースのすべてのセグメントのデルタ関数 (プレビュー)
サービス プリンシパル サービス プリンシパル リソースのデルタ関数
タスクリスト内の To Do タスク todoTask リソースのデルタ関数
To Do タスク リスト todoTaskList リソースのデルタ関数
ユーザー ユーザーリソースのデルタ関数

* OneDrive および SharePoint リソースの使用パターンは、サポートされている他のリソースと似ていますが、構文には若干の違いがあります。ドライブとリストのデルタ クエリは、他のリソースの種類との一貫性を保つために将来更新されます。現在の構文の詳細については、「driveItem: delta」および「listItem: delta」を参照してください。

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

制限事項

メイン データ ストアの外部に保存されているプロパティ

一部のリソースには、リソースのメイン データ ストアの外部に保存されているプロパティが含まれます (たとえば、スキル などの一部のプロパティが SharePoint Online に保存されている一方で、ユーザー リソースの大部分が Azure AD システムに保存されている場合)。 現在、これらのプロパティは、変更履歴の記録の一部としてサポートされていません。これらのプロパティのいずれかを変更しても、デルタ クエリ応答でオブジェクトが表示されることはありません。 現在、メイン データ ストアに保存されているプロパティのみ、デルタ クエリの変更をトリガーします。

デルタ クエリに使用されるプロパティを確認するには、リソース コレクションの通常の GET 操作の実行を試みて、関心があるプロパティを選択します。たとえば、ユーザー コレクションの skills プロパティを試すことができます。

GET https://graph.microsoft.com/v1.0/users/?$select=skills

Azure AD の外部に スキル プロパティが保存されているため、応答は次のようになります。

HTTP/1.1 501 Not Implemented
Content-type: application/json

{
    "error": {
        "code": "NotImplemented",
        "message": "This operation target is not yet supported.",
        "innerError": {
            "request-id": "...",
            "date": "2019-09-20T21:47:50"
        }
    }
}

これにより、スキル プロパティは、ユーザー リソースのデルタ クエリに対してサポートされていないことが分かります。

ナビゲーション プロパティはサポートされていません。たとえば、フォト プロパティへの変更が含まれるユーザー コレクションに対する変更は追跡できません。フォト は、ユーザー エンティティの外部に保存されているナビゲーションのプロパティであり、それに対する変更を行っても、デルタ応答にユーザー オブジェクトが含まれることはありません。

処理の遅延

アプリ インターフェイスまたは API を介してリソース インスタンスに変更が加えられてから、変更箇所がデルタ クエリの応答に反映されるまでの間で、さまざまな遅延が予測されます。

@odata.nextLink または @odata.deltaLink を選択したときに、オブジェクトに対して発生した変更が示されない場合があります。 これは、一部の要求で、最近作成、更新、または削除されたオブジェクトのレプリケーションの遅延が発生する可能性があるためです。 しばらくしてから、@odata.nextLink または @odata.deltaLink を再試行して、最新の変更を取得してください。

国別クラウド

デルタ クエリは、パブリック クラウドおよび 21Vianet のみが運営する Microsoft Graph China でホストされているお客様が利用できます。

再生

アプリケーションは、その後の応答で同じ変更が発生した場合に発生する再生に備えておく必要があります。 デルタ クエリは再生を減らすために最善を尽くしますが、それでも発生する可能性があります。

同期のリセット

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

トークン期間

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

  • ディレクトリ オブジェクトの場合、制限は 7 日間です。
  • 教育オブジェクト (EducationSchoolEducationUser、および EducationClass) の場合、制限は 7 日です。
  • Outlook エンティティ (messagemailFoldereventcontactcontactFoldertodoTask、および todoTaskList) の場合、上限は固定されていません。 これは、内部デルタ トークン キャッシュのサイズによって異なります。 新しいデルタ トークンはキャッシュに継続的に追加されますが、キャッシュ容量を超えた後、古いデルタ トークンは削除されます。

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

前提条件

特定のリソースを読み取るために必要なアクセス許可と同じアクセス許可も、そのリソースでデルタ クエリを実行するために必要です。

デルタ クエリ要求の例