デルタ クエリを使用して、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 the query parameters once upfront. Microsoft Graph adds the specified parameters automatically for all subsequent requests.

オプションのクエリ パラメーターについては、次の点に注意してください。Note the following regarding optional query parameters:

  • $orderby は、差分クエリに対してサポートされません。$orderby is not a supported for delta queries.
    • 差分クエリから返された応答の特定のシーケンスは想定しません。Do not assume a specific sequence of the responses returned from a delta query. nextLink シーケンスのどこにでも同じアイテムが出現する可能性があると想定し、マージ ロジックの中でそれを処理します。Assume that the same item can show up anywhere in the nextLink sequence and handle that in your merge logic.
  • $topは差分クエリではサポートされていません。各ページのオブジェクトの数は、リソース タイプとリソースに加えられた変更のタイプによって異なります。$top is not supported for delta queries, and the number of objects in each page can vary depending on the resource type and the type of changes made to the resource.

ユーザーおよびグループの場合、一部のクエリ パラメーターの使用には以下の制限が適用されます。For users and groups, the following restrictions apply to using using some query parameters:

ユーザーとグループには、いくつかのクエリ パラメーターの使用に関する制限があります。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.

  • $select は、それぞれのユーザーとグループのナビゲーション プロパティである manager および members もサポートします。$select also supports manager and members navigational property for users and groups respectively. これらのプロパティを選択すると、ユーザーのマネージャーとグループ メンバーシップの変更を追跡できます。Selecting those properties allows tracking of changes to user's manager and group memberships.

  • スコープ フィルターで、object ID を使って 1 つまたは複数の特定のユーザーまたはグループに加えられた変更を追跡できます。Scoping filters allow you to track changes to one or more specific users or groups by object ID. たとえば次のリクエストは、クエリ フィルターで指定された ID と一致するグループの変更を返します。For example, the following request returns changes for the groups matching the IDs specified in the query filter.

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

デルタ クエリ応答でのリソース表記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 instances are represented by their id and an @removed object. @removed オブジェクトには、インスタンスが削除された理由に関する追加情報が含まれる場合があります。The @removed object may include additional information about why the instance was removed. たとえば、「@removed」: {"reason": “changed”} です。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)
クラス (プレビュー)Classes (preview) クラス リソース (プレビュー) のデルタ関数delta function of the Class resource (preview)
ディレクトリ オブジェクト (プレビュー)Directory objects (preview) ディレクトリ オブジェクト リソース (プレビュー) のデルタ関数delta function of the directoryObjects resource (preview)
ディレクトリ ロールDirectory roles ディレクトリ ロール リソースのデルタ関数delta function of the directoryRole resource
ドライブの項目*Drive items* driveItem リソースのデルタ関数delta function of the driveItem resource
教育ユーザー (プレビュー)Education users (preview) 教育ユーザーリソース (プレビュー) のデルタ関数delta function of the Education user resource (preview)
標準として設定されている予定表の予定表ビュー (期間) 内のイベント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
学校 (プレビュー)Schools (preview) 学校リソース (プレビュー) のデルタ関数delta function of the School resource (preview)
サービス プリンシパル (プレビュー)Service principals (preview) サービス プリンシパル リソース (プレビュー) のデルタ関数delta function of the servicePrincipal resource (preview)
ユーザーUsers ユーザーリソースのデルタ関数delta function of the user resource
プランナーの項目**(プレビュー)Planner items** (preview) plannerUser リソースのすべてのセグメントのデルタ関数 (プレビュー)delta function of the all segment of plannerUser resource (preview)
チャネルの chatMessages (プレビュー)chatMessages in a channel (preview) chatMessageデルタ関数delta function of the chatMessage

* 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.


メイン データ ストアの外部に保存されているプロパティProperties stored outside of the main data store

一部のリソースには、リソースのメイン データ ストアの外部に保存されているプロパティが含まれます (たとえば、スキル などの一部のプロパティが SharePoint Online に保存されている一方で、ユーザー リソースの大部分が Azure AD システムに保存されている場合)。Some resources contain properties that are stored outside of the main data store for the resource (for example, the user resource is mostly stored in the Azure AD system, while some properties, like skills, are stored in SharePoint Online). 現在、これらのプロパティは、変更履歴の記録の一部としてサポートされていません。これらのプロパティのいずれかを変更しても、デルタ クエリ応答でオブジェクトが表示されることはありません。Currently, those properties are not supported as part of change tracking; a change to one of those properties will not result in an object showing up in the delta query response. 現在、メイン データ ストアに保存されているプロパティのみ、デルタ クエリの変更をトリガーします。Currently, only the properties stored in the main data store trigger changes in the delta query.

デルタ クエリに使用されるプロパティを確認するには、リソース コレクションの通常の GET 操作の実行を試みて、関心があるプロパティを選択します。To verify that a property can be used in delta query, try to perform a regular GET operation on the resource collection, and select the property you're interested in. たとえば、ユーザー コレクションの スキル プロパティを試します。For example, you can try the skills property on the users collection.

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

Azure AD の外部にスキル プロパティが保存されているため、応答は次のようになります。Because the skills property is stored outside of Azure AD, the following is the response.

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"

これにより、スキル プロパティは、ユーザー リソースのデルタ クエリに対してサポートされていないことが分かります。This tells you that the skills property is not supported for delta query on the user resource.

ナビゲーションのプロパティはサポートされていません。Navigation properties are not supported. たとえば、フォト プロパティへの変更が含まれるユーザー コレクションに対する変更履歴は記録されません。フォト は、ユーザー エンティティの外部に保存されているナビゲーションのプロパティであり、それに対する変更を行っても、デルタ応答にユーザー オブジェクトが含まれることはありません。For example, you cannot track changes to the users collection that would include changes to their photo property; photo is a navigation property stored outside of the user entity, and changes to it do not cause the user object to be included in the delta response.


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