デルタ クエリを使用して、Microsoft Graph データの変更を追跡するUse delta query to track changes in Microsoft Graph data

デルタ クエリを使用すると、アプリケーションは、要求ごとにターゲット リソースをすべて読み取ることなく、新しく作成、更新、または削除されたエンティティを検出できます。Microsoft Graph アプリケーションはデルタ クエリを使用して、変更をローカル データ ストアと効率的に同期させることができます。Delta query enables applications to discover newly created, updated, or deleted entities without performing a full read of the target resource with every request. Microsoft Graph applications can use delta query to efficiently synchronize changes with a local data store.

デルタ クエリを使用して、リソース コレクション内の変更を追跡するUse delta query to track changes in a resource collection

標準的な呼び出しパターンは次のとおりです。The typical call pattern is as follows:

  1. アプリケーションは、まず目的のリソースでデルタ関数を使用して GET 要求を呼び出します。The application begins by calling a GET request with the delta function on the desired resource.

  2. Microsoft Graph は、要求されたリソースと状態トークンを含む応答を送信します。Microsoft Graph sends a response containing the requested resource and a state token.

    a. nextLink URL が返される場合は、セッションに取得するデータの追加ページがあります。deltaLink URL が応答で返されるまで、アプリケーションは nextLink URL を使用してデータのすべてのページを取得する要求を実行し続けます。a. If a nextLink URL is returned, there may be additional pages of data to be retrieved in the session. The application continues making requests using the nextLink URL to retrieve all pages of data until a deltaLink URL is returned in the response.

    b.deltaLink URL が返される場合、返されるリソースの既存の状態に関するデータはありません。以降の要求では、アプリケーションは deltaLink URL を使用して、リソースへの変更点を確認します。b. If a deltaLink URL is returned, there is no more data about the existing state of the resource to be returned. For future requests, the application uses the deltaLink URL to learn about changes to the resource.

  3. アプリケーションがリソースの変更を把握する必要がある場合、アプリケーションは手順 2 で受け取った deltaLink URL を使用して、新しい要求を実行します。この要求は、手順 2 が完了した直後、またはアプリケーションが変更を確認する際に実行できる場合がありますWhen the application needs to learn about changes to the resource, it makes a new request using the deltaLink URL received in step 2. This request may be made immediately after completing step 2 or when the application checks for changes.

  4. Microsoft Graph は、前の要求以降のリソースへの変更を説明する応答と、nextLink URL または deltaLink URL のいずれかを返します。Microsoft Graph returns a response describing changes to the resource since the previous request, and either a nextLink URL or a deltaLink URL.

注: Azure Active Directory (ユーザーやグループなど) に保管されているリソースは、"今から同期を開始する" という状況をサポートしています。Note: Resources stored in Azure Active Directory (such as users and groups) support "sync from now" scenarios. このため、上記の手順 1 と 2 をスキップし (リソースの完全な状態を取得する必要がない場合)、代わりに最新の deltaLink を要求することができます。This allows you to skip steps 1 and 2 above (if you are not interested in retrieving the full state of the resource) and ask for the latest deltaLink instead. $deltaToken=latestdelta 関数に追加すると、応答には deltaLink が含まれ、リソー スデータは一切含まれません。Append $deltaToken=latest to the delta function and the response will contain a deltaLink and no resource data.

状態トークンState tokens

デルタ クエリの GET 応答には、nextLink または deltaLink の応答ヘッダーに指定された URL が常に含まれています。nextLink URL には skipTokendeltaLink URL には deltaToken が含まれています。A delta query GET response always includes a URL specified in a nextLink or deltaLink response header. The nextLink URL includes a skipToken, and a deltaLink URL includes a deltaToken.

これらのトークンは、クライアントに対して不透明です。理解しておく必要のある事項の詳細を、以下に示します。These tokens are opaque to the client. The following details are what you need to know about them:

  • 各トークンは状態を反映し、そのラウンドの変更追跡におけるリソースのスナップショットを表します。Each token reflects the state and represents a snapshot of the resource in that round of change tracking.

  • 状態トークンは、初期デルタ クエリ要求で指定された他のクエリ パラメーター ($select など) もエンコードして含めます。したがって、後続のデルタ クエリ要求でそれらを繰り返す必要はありません。The state tokens also encode and include other query parameters (such as $select) specified in the initial delta query request. Therefore, it's not required to repeat them in subsequent delta query requests.

  • デルタ クエリを実行するときは、状態トークンなど、URL の内容を調べることなく、nextLink または deltaLink の URL を次のデルタ関数呼び出しにコピーして適用できます。When carrying out delta query, you can copy and apply the nextLink or deltaLink URL to the next delta function call without having to inspect the contents of the URL, including its state token.

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

クライアントがクエリ パラメーターを使用する場合は、最初の要求で指定する必要があります。Microsoft Graph は、応答で提供される nextLink または deltaLink に指定したパラメーターを自動的にエンコードします。呼び出し元のアプリケーションで必要な操作は、必要なクエリ パラメーターを最初に一度指定することだけです。Microsoft Graph は、すべての後続の要求に対して自動的に指定されたパラメーターを追加します。If a client uses a query parameter, it must be specified in the initial request. Microsoft Graph automatically encodes the specified parameter into the nextLink or deltaLink provided in the response. The calling application only needs to specify their desired query parameters once upfront. Microsoft Graph adds the specified parameters automatically for all subsequent requests.

ユーザーとグループには、いくつかのクエリ パラメーターの使用に関する制限があります。For users and groups, there are restrictions on using some query parameters:

  • $select クエリ パラメーターが使用されている場合、パラメーターは、$select ステートメントで指定したプロパティまたはリレーションシップに関する変更のみを追跡することを、クライアントが優先していることを示します。選択されていないプロパティに変更が加えられた場合、そのプロパティが変更されたリソースは、後続の要求後のデルタ応答には表示されなくなります。If a $select query parameter is used, the parameter indicates that the client prefers to only track changes on the properties or relationships specified in the $select statement. If a change occurs to a property that is not selected, the resource for which that property changed does not appear in the delta response after a subsequent request.

  • $expand は、それぞれのユーザーとグループのナビゲーション プロパティである manager および members についてのみサポートされます。$expand is only supported for the manager and members navigational property for users and groups respectively.

  • スコープ フィルターで、objectID を使って 1 つまたは複数の特定のユーザーまたはグループに加えられた変更を追跡できます。Scoping filters allow you to track changes to one or more specific users or groups by objectId. たとえば、https://graph.microsoft.com/beta/groups/delta/?$filter= id eq '477e9fc6-5de7-4406-bb2a-7e5c83c9ae5f' or id eq '004d6a07-fe70-4b92-add5-e6e37b8acd8e' の要求では、クエリ フィルターで指定された ID に一致するグループに加えられた変更が返されます。For example, the following request: https://graph.microsoft.com/beta/groups/delta/?$filter= id eq '477e9fc6-5de7-4406-bb2a-7e5c83c9ae5f' or id eq '004d6a07-fe70-4b92-add5-e6e37b8acd8e' returns changes for the groups matching the ids specified in the query filter.

デルタ クエリ応答でのリソース表記Resource representation in the delta query response

  • サポートされているリソースの新しく作成されたインスタンスは、標準的な表現を使用してデルタ クエリ応答で表されます。Newly created instances of a supported resource are represented in the delta query response using their standard representation.

  • 更新されたインスタンスは、少なくとも更新されたプロパティを持つ ID で表されますが、追加のプロパティが含まれる可能性があります。Updated instances are represented by their id with at least the properties that have been updated, but additional properties may be included.

  • ユーザーとグループのリレーションシップは、標準的なリソース表記で注釈として表されます。これらの注釈は propertyName@delta の形式で表示されます。注釈は最初のデルタ クエリ要求の応答に含まれます。Relationships on users and groups are represented as annotations on the standard resource representation. These annotations use the format propertyName@delta. The annotations are included in the response of the initial delta query request.

削除されたインスタンスは、ID@removed オブジェクトを使用して表されます。@removed オブジェクトには、インスタンスが削除された理由に関する追加情報が含まれる場合があります。たとえば、"@removed": {"reason": “changed”} です。Removed instances are represented by their id and an @removed object. The @removed object may include additional information about why the instance was removed. For example, "@removed": {"reason": “changed”}.

"@removed" で考えられる理由は、changed または deleted です。Possible @removed reasons can be changed or deleted.

  • Changed は、項目は削除されたものの、deletedItems から復元できることを表します。Changed indicates the item was deleted and can be restored from deletedItems.

  • Deleted は、項目は削除され、復元できないことを表します。Deleted indicates the item is deleted and cannot be restored.

@removed オブジェクトは最初のデルタ クエリ応答と追跡された (deltaLink) 応答で返されます。デルタ クエリ要求を使用するクライアントは、応答に含まれるこれらのオブジェクトを処理できるよう設計する必要があります。The @removed object can be returned in the initial delta query response and in tracked (deltaLink) responses. Clients using delta query requests should be designed to handle these objects in the responses.

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

デルタ クエリは現在、次のリソースでサポートされています。Delta query is currently supported for the following resources.

リソース コレクションResource collection APIAPI
アプリケーション (プレビュー)Applications (preview) アプリケーション リソース (プレビュー) のデルタ関数delta function of the application resource (preview)
ディレクトリ オブジェクトDirectory objects ディレクトリ オブジェクト リソース (プレビュー) のデルタ関数delta function of the directoryObjects resource (preview)
ディレクトリ ロールDirectory roles ディレクトリ ロール リソースのデルタ関数delta function of the directoryRole resource
標準として設定されている予定表の予定表ビュー (期間) 内のイベントEvents in a calendar view (date range) of the primary calendar イベントリソースのデルタ関数delta function of the event resource
グループGroups グループリソースのデルタ関数delta function of the group resource
メール フォルダーMail folders mailFolder リソースのデルタ関数delta function of the mailFolder resource
フォルダー内のメッセージMessages in a folder メッセージリソースのデルタ関数delta function of the message resource
個人用連絡先フォルダーPersonal contact folders contactFolder リソースのデルタ関数delta function of the contactFolder resource
フォルダー内の個人用連絡先Personal contacts in a folder 連絡先リソースのデルタ関数delta function of the contact resource
サービス プリンシパル (プレビュー)Service principals (preview) サービス プリンシパル リソース (プレビュー) のデルタ関数delta function of the servicePrincipal resource (preview)
ユーザーUsers ユーザーリソースのデルタ関数delta function of the user resource
ドライブの項目*Drive items* driveItem リソースのデルタ関数delta function of the driveItem resource
Planner の項目**Planner items** plannerUser リソースのすべてのセグメントのデルタ関数 (プレビュー)delta function of the all segment of plannerUser resource (preview)

* OneDrive リソースの使用パターンは、他のサポートされているリソースと似ていますが、構文には若干の違いがあります。* The usage pattern for OneDrive resources is similar to the other supported resources with some minor syntax differences. ドライブのデルタ クエリは、他のリソースの種類との一貫性を保つために将来更新されます。Delta query for drives will be updated in the future to be consistent with other resource types. 現在の構文の詳細については、 「ドライブの変更履歴を記録する」を参照してください。For more detail about the current syntax, see Track changes for a drive.

** Planner リソースの使用パターンは、他のサポートされているリソースと似ていますが、若干の違いがあります。** The usage pattern for Planner resources is similar to other supported resources with a few differences. 詳細については、「Planner の変更履歴を記録する」を参照してください。For details, see Track changes for Planner.

前提条件Prerequisites

特定のリソースを読み取るために必要なアクセス許可と同じアクセス許可も、そのリソースでデルタ クエリを実行するために必要です。The same permissions that are required to read a specific resource are also required to perform delta query on that resource.

デルタ クエリ要求の例Delta query request examples