Table of contents

差分クエリ | Graph API の概念Differential query | Graph API concepts

Jimaco Brannian|最終更新日: 2018/06/19
|
2 投稿者

適用対象: Graph API | Azure Active DirectoryApplies to: Graph API | Azure Active Directory

このトピックでは、Azure AD Graph API の差分クエリ機能について説明します。This topic discusses the differential query feature of Azure AD Graph API.差分クエリ要求は、2 つの連続した要求の間に指定されたエンティティに行われたすべての変更を返します。A differential query request returns all changes made to specified entities during the time between two consecutive requests.たとえば、前回の差分クエリ要求の 1 時間後に差分クエリ要求を行う場合、その 1 時間で行われた変更のみが返されます。For example, if you make a differential query request an hour after the previous differential query request, only the changes made during that hour will be returned.この機能は、テナント ディレクトリ データとアプリケーションのデータ ストアを同期させるときに特に便利です。This functionality is especially useful when synchronizing tenant directory data with an application’s data store.

テナントのディレクトリに対して差分クエリ要求を行うには、アプリケーションはテナントによって承認される必要があります。To make a differential query request to a tenant’s directory, your application must be authorized by the tenant.詳細については、「Azure Active Directory とアプリケーションの統合」を参照してください。For more information, see Integrating Applications with Azure Active Directory.

重要

Azure Active Directory のリソースにアクセスするには、Azure AD Graph API ではなく Microsoft Graph を使用することを強くお勧めします。We strongly recommend that you use Microsoft Graph instead of Azure AD Graph API to access Azure Active Directory resources.現在は Microsoft Graph を中心にして開発が進められており、Azure AD Graph API の今後の機能強化は予定されていません。Our development efforts are now concentrated on Microsoft Graph and no further enhancements are planned for Azure AD Graph API.Azure AD Graph API の使用が適切である場合もありますが、非常にまれです。詳細については、Office Dev Center の Microsoft Graph または Azure AD Graph ブログの記事をご覧ください。There are a very limited number of scenarios for which Azure AD Graph API might still be appropriate; for more information, see the Microsoft Graph or the Azure AD Graph blog post in the Office Dev Center.

差分クエリ要求Differential query requests

ここでは、差分クエリ要求について説明します。This section describes differential query requests.すべての要求に次のコンポーネントが必要です。All requests require the following components:

  • 有効な要求 URL。テナントの Graph エンドポイントと該当するクエリ文字列パラメーターが含まれます。A valid request URL, including the Graph endpoint for the tenant and applicable query string parameters.

  • 承認ヘッダー。Azure Active Directory によって発行される有効なアクセス トークンが含まれます。An authorization header, including a valid access token issued by Azure Active Directory.Graph API への認証の詳細については、「Azure AD の認証シナリオ」を参照してください。For more information on authenticating to the Graph API, see Authentication Scenarios for Azure AD.

差分クエリ要求 URLDifferential query request URL

差分クエリ要求の URL の形式を次に示します。角かっこ [] は省略可能な要素を示しています。The following shows the format of the URL for differential query request; square brackets [] indicate optional elements.

https://graph.windows.net/<tenantId>/<resourceSet>?api-version=<SupportedApiVersion>&deltaLink=<token>&[$filter=isof(<entityType>)]&[$select=<PropertyList>]

URL は、キーと値のペアで表される一連のクエリ文字列パラメーターが後に続く階層セグメントで構成されています。The URL is made up of a hierarchical segments followed by a series of query string parameters expressed as key-value pairs.

URL: 階層セグメントURL: Hierarchical segments

セグメントSegment説明Description
tenantIdtenantIdクエリが実行される対象のテナントの一意の ID。The unique identifier of the tenant that the query should be executed against.通常、テナントの確認済みのドメイン (verifiedDomains プロパティ) の 1 つですが、テナントのオブジェクト ID (objectId プロパティ) である場合もあります。This is typically one of the verified domains (verifiedDomains property) of the tenant, but it can also be the tenant’s object ID (objectId property).大文字と小文字は区別されません。Not case-sensitive.
resourceSetresourceSetこのクエリが実行される対象のテナント リソースの特定のセット。The specific set of tenant resources this query should be executed against.クエリの応答で返されるリソースを決定します。Determines what resources are returned in the query response.サポートされている値は、“directoryObjects”、“users”、“contacts”、または “groups” です。Supported values are: “directoryObjects”, “users”, “contacts” or “groups”.これらの値は大文字と小文字が区別されます。Values are case-sensitive.

URL: クエリ文字列パラメーターURL: Query string parameters

パラメーターParameter説明Description
api-versionapi-version要求の発行対象となる Graph API のバージョンを指定します。Specifies the version of the Graph API against which the request is issued.必須。Required.バージョン 1.5 以降では、この値は数値のバージョン番号として表されます (たとえば、api-version=1.5)。Beginning with version 1.5, the value is expressed as a numeric version number; for example, api-version=1.5.これより前のバージョンでは、この値は YYYY-MM-DD という形式の文字列です (たとえば、api-version=2013-04-05)。For previous versions, the value is a string of the form YYYY-MM-DD; for example, api-version=2013-04-05.

(Graph API のプレビュー バージョンで x-ms-dirapi-data-contract-version ヘッダーの使用を置き換えます)。(Replaces the use of x-ms-dirapi-data-contract-version header in the preview version of Graph API.)
deltaLinkdeltaLink前回の応答で deltaLink プロパティまたは nextLink プロパティのどちらかに返されたトークン。The token returned in either the deltaLink property or the nextLink property in the last response.必須ですが、最初の要求では空になります。Required, but will be empty on the first request.

(Graph API のプレビュー バージョンで skipToken クエリ文字列パラメーターを置き換えます)。(Replaces the skipToken query string parameter in the preview version of Graph API.)
$filter$filter応答に含める必要があるエンティティの種類を指定します。Indicates which entity types should be included in the response.任意。Optional.サポートされているエンティティの種類は、User、Group、および Contact です。The supported entity types are: User, Group and Contact.&ltresourceSet&gt が “directoryObjects” の場合にのみ有効です。それ以外の場合は、&ltresourceSet&gt はフィルターをオーバーライドします。Only valid when &ltresourceSet&gt is “directoryObjects”; otherwise, &ltresourceSet&gt overrides the filter.たとえば、&ltresourceSet&gt が “users” で、$filter パラメーターも指定されている場合、指定されたフィルター選択値に関係なく、ユーザーに対する変更のみが返されます。For example, if &ltresourceSet&gt is “users”, and the $filter parameter is also specified, only changes for users will be returned regardless of what is specified in the filter value.&ltresourceSet&gt が “directoryObjects” で、$filter パラメーターが指定されていない場合、サポートされるすべてのエンティティの種類 (User、Group、および Contact) への変更が返されます。If &ltresourceSet&gt is “directoryObjects” and $filter is not specified, changes for all of the supported entity types (User, Group, and Contact) are returned.

単一のエンティティの種類を指定するには、次のいずれかの方法を使用します。To specify a single entity type, use one of the following:
  • $filter=isof('Microsoft.WindowsAzure.ActiveDirectory.Contact')
  • $filter=isof('Microsoft.WindowsAzure.ActiveDirectory.User')
  • $filter=isof('Microsoft.WindowsAzure.ActiveDirectory.Group')
複数のエンティティの種類を指定するには、または 演算子を使用します (たとえば、$filter=isof('Microsoft.WindowsAzure.ActiveDirectory.User')%20or%20isof('Microsoft.WindowsAzure.ActiveDirectory.Group'))。To specify multiple entity types, use the or operator; for example, $filter=isof('Microsoft.WindowsAzure.ActiveDirectory.User')%20or%20isof('Microsoft.WindowsAzure.ActiveDirectory.Group').

(Graph API のプレビュー バージョンで objectScope クエリ文字列パラメーターを置き換えます)。(Replaces the objectScope query string parameter in the preview version of Graph API.)

重要: バージョン 1.5 以降では、Graph API の名前空間は Microsoft.WindowsAzure.ActiveDirectory から Microsoft.DirectoryServices に変更されます。Important Beginning with version 1.5, the Graph API namespace is changed from Microsoft.WindowsAzure.ActiveDirectory to Microsoft.DirectoryServices.これより前のバージョンの Graph API では、引き続き以前の名前空間を使用します (たとえば、$filter=isof('Microsoft.WindowsAzure.ActiveDirectory.Contact'))。Earlier versions of the Graph API continue to use the previous namespace; for example, $filter=isof('Microsoft.WindowsAzure.ActiveDirectory.Contact').
$select$select応答に含めるプロパティを指定します。Specifies which properties should be included in the response.*$select^ を指定しない場合、すべてのプロパティが含められます。If *$select^ is not specified, all properties are included.

プロパティは、完全修飾または非完全修飾のいずれかで指定できます。Properties can be specified either fully qualified or non-qualified.複数のプロパティはコンマで区切ります。Multiple properties are delimited by commas.
  • 完全修飾プロパティには、エンティティの種類が指定されます (たとえば、User/displayName)。Fully qualified properties have the entity type specified; for example, User/displayName.&ltresourceSet&gt を “directoryObjects” として指定した場合、完全修飾プロパティを使用する必要があります (たとえば、 https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&deltaLink=&$select=User/displayName,Group/description)。Fully qualified properties MUST be used if &ltresourceSet&gt is specified as “directoryObjects”; for example, https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&deltaLink=&$select=User/displayName,Group/description.
  • 非完全修飾プロパティには、エンティティの種類が指定されません (たとえば、displayName)。Non-qualified properties do not have the entity type specified; for example, displayName.&ltresourceSet&gt を "directoryObjects" 以外の値として指定した場合にのみ使用できます (たとえば、https://graph.windows.net/contoso.com/users?api-version=2013-04-05&deltaLink=&$select=displayName,jobTitle)。They can only be used when &ltresourceSet&gt is specified as a value other than “directoryObjects”; for example, https://graph.windows.net/contoso.com/users?api-version=2013-04-05&deltaLink=&$select=displayName,jobTitle.

: クエリ文字列のキーと値のペアでは、大文字と小文字が区別されますが、その順序は重要ではありません。Note: The key-value pairs in the query string are case-sensitive, but their order is not significant.

最も簡単な差分クエリの例を次に示します。The following is an example of the simplest differential query.これは最初の同期中に使用されます。This is used during initial sync.

https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&deltaLink=

後続の要求の例を次に示します。The following is an example of a subsequent request.

https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&deltaLink=AAABAGCL8z4m%2bc9IJGIzYjFmYzU5LTg0YjgtNDQwMC1hNzE1LWVhOGE3ZTQwZjRmZQBuvX43ACZQT4LRVPug8An6AAABAANIABAfGgAQwAMAJDCHA5AAABAATCkAA44TADQnhAQAIAAAgAHAAwAQAAAA8rLSTyfq5U`

差分クエリ応答 Differential query responses

ここでは、差分クエリ要求が行われたときに返される差分クエリ応答の内容について説明します。This section describes the contents of a differential query response that is returned when a differential query request is made.次の一覧は応答の内容を示しています。The following list describes the contents of a response:

  • 0 ~ 200 個の DirectoryObject エンティティ。それぞれのエンティティに特定の UserGroup、または Contact オブジェクトに対する変更が含まれます。Zero to 200 DirectoryObject entities, each of which contains changes for a specific User, Group, or Contact object.

  • 0 ~ 3000 個の DirectoryLinkChange エンティティ。それぞれのエンティティに特定の member または manager リンクに対する変更が含まれます。Zero to 3000 DirectoryLinkChange entities, each of which contains changes for a specific member or manager link.

  • deltaLink または nextLink プロパティのいずれかです。Either a deltaLink or a nextLink property.いずれの場合も、ディレクトリで発生した変更の保持に関して、クライアントに返されたディレクトリ変更の設定に関する状態情報が埋め込まれた URL エンコード文字列です。この値は大文字と小文字が区別されます。In either case, its value is a case-sensitive, URL-encoded string that embeds state information about the set of directory changes that have been returned to the client, with respect to remaining changes that have occurred in the directory.この文字列 (トークン) は、次の差分クエリ要求内の deltaLink クエリ文字列パラメーターに含める必要があります。This string (or token) should be included in the deltaLink query string parameter in the next differential query request.

    • deltaLink プロパティが返された場合、この応答の後に同期するアプリケーションへのディレクトリ変更はありません。If the deltaLink property is returned, there are no more directory changes left for the application to synchronize after this response.アプリケーションは、次の差分クエリ要求を行うための独自の要件に従って、あらかじめ定義した時間待機させることができます。The application can wait for some predetermined time according to its own requirements to issue the next differential query request.

    • nextLink プロパティが返された場合、この応答の後に同期するためにアプリケーションへのディレクトリ変更が保持されます。If the nextLink property is returned, there are directory changes remaining for the application to synchronize after this response.アプリケーションは、できる限り早く次の差分クエリ要求を発行する必要があります。The application should issue the next differential query request at its earliest convenience.

応答は常に JSON 形式で返されます。Responses are always returned in JSON format.

差分クエリを使用する際の注意事項 Considerations when using differential query

次の一覧は、差分クエリを使用するアプリケーションに関する重要な注意事項を示しています。The following list highlights important considerations for applications that use differential query:

  • 差分クエリによって返される変更は、応答時のディレクトリ オブジェクトの状態を表します。Changes returned by differential query represent the state of the directory objects at the time of the response.お使いのアプリケーションで、これらの変更を応答に対するトランザクション ログとして扱うことはできません。Your application must not treat these changes as transaction logs for replay.

  • 変更は発生順に表示されます。Changes appear in the order in which they occurred.オブジェクトが複数回更新された場合でも、前回変更されたオブジェクトが最後に表示されます。The most-recently changed objects appear last even if the object was updated multiple times.また、クライアントが変更を受信しても、この順序に影響はありません。Their order is also not affected by when the client received the changes.結果として、順序どおりに表示されない複数の変更を最初にディレクトリで発生した状態と比較することができます。As a result, it is possible for changes to be presented out of order compared to how they initially occurred in the directory.

  • お使いのアプリケーションは応答の準備をする必要があります。この応答は同じ変更が後続の応答に表示される場合に発生します。Your application must be prepared for replays, which occur when the same change appears in subsequent responses.差分クエリが応答を減らすために最も適している場合、継続して使用できます。While differential query makes a best effort to reduce replays, they are still possible.

  • お使いのアプリケーションは、認識していなかったオブジェクトへの削除変更を処理するために準備する必要があります。Your application must be prepared to handle a deletion change for an object it was not aware of.

  • 差分クエリは、まだ他の応答によって返されていないソース オブジェクトまたはターゲット オブジェクトへのリンクを返すことができます。Differential query can return a link to a source or target object that has not yet been returned by other responses.

  • 要求ヘッダーでクエリを制限してパフォーマンスを向上させる方法の詳細については、下記の「差分クエリの追加機能」セクションを参照してください。See the Additional differential query features section below for more information on using request headers to constrain your queries to improve performance.

要求と応答の例 Request and response examples

最初の差分クエリ要求の例を次に示します。The following is an example of an initial differential query request:

GET https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&$filter=isof('Microsoft.WindowsAzure.ActiveDirectory.User')%20or%20isof('Microsoft.WindowsAzure.ActiveDirectory.Group')%20or%20isof('Microsoft.WindowsAzure.ActiveDirectory.Contact')&deltaLink= HTTP /1.1
Authorization: Bearer eyJ0eXAiOiJKV . . . KUAe1EQ
Host: graph.windows.net

増分の差分クエリ要求の例を次に示します。The following is an example of an incremental differential query request:

https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&$filter=isof('Microsoft.WindowsAzure.ActiveDirectory.User')%20or%20isof('Microsoft.WindowsAzure.ActiveDirectory.Group')%20or%20isof('Microsoft.WindowsAzure.ActiveDirectory.Contact')&deltaLink=AAABAGCL8z4m%2bc9IJGIzYjFmYzU5LTg0YjgtNDQwMC1hNzE1LWVhOGE3ZTQwZjRmZQBuvX43ACZQT4LRVPug8An6AAABAANIABAfGgAQwAMAJDCHA5AAABAATCkAA44TADQnhAQAIAAAgAHAAwAQAAAA8rLSTyfq5U
 HTTP /1.1
Authorization: Bearer eyJ0eXAiOiJKV . . . KUAe1EQ
Host: graph.windows.net

: いずれの要求例も、$filter クエリ パラメーターは、デモの目的のためだけに示されています。Note: In both of these sample requests, the $filter query parameter is shown for demonstration purposes only.フィルターは差分クエリに可能なターゲットの種類をすべて指定するため (User、Group、および Contact)、フィルターは省略することができ、既定ではクエリはすべてのエンティティの種類に対する変更を返します。Because the filter specifies all of the possible target types for the differential query (User, Group, and Contact), it could be omitted and the query would return changes for all of these entity types by default.

次の応答の例は、返される JSON を示しています。The following example response demonstrates the returned JSON:

{
  "odata.metadata": "https://graph.windows.net/contoso.com/$metadata#directoryObjects",


  # This is the deltaLink to be used for the next query
  "aad.deltaLink": "https://graph.windows.net/contoso.com/directoryObjects?deltaLink=XARBN7ivjcS6QIhSZDQR3OkT15SO1eeY-01BZSS0sOct6sh5oEyqOLLKRVhRmBMLHhePUF... [Truncated]",
  "value": [

    # User object for John Smith
    {
      "odata.type": "Microsoft.WindowsAzure.ActiveDirectory.User",
      "objectType": "User",
      "objectId": "dca803ab-bf26-4753-bf20-e1c56a9c34e2",
      "accountEnabled": true,
      "displayName": "John Smith",
      "givenName": "John",
      "mailNickname": "johnsmith",
      "passwordPolicies": "None",
      "surname": "Smith",
      "usageLocation": "US",
      "userPrincipalName": "johnsmith@contoso.com"
    },

    # Group object for IT Administrators
    {
      "odata.type": "Microsoft.WindowsAzure.ActiveDirectory.Group",
      "objectType": "Group",
      "objectId": "7373b0af-d462-406e-ad26-f2bc96d823d8",
      "description": "IT Administrators",
      "displayName": "Administrators",
      "mailNickname": "Administrators",
      "mailEnabled": false,
      "securityEnabled": true
    },

    # Contact object for Jane Smith
    {
      "odata.type": "Microsoft.WindowsAzure.ActiveDirectory.Contact",
      "objectType": "Contact",
      "objectId": "d711a1f8-21cf-4dc0-834a-5583e5324c44",
      "displayName": "Jane Smith",
      "givenName": "Jane",
      "mail": "johnsmith@contoso.com",
      "mailNickname": "johnsmith",
      "proxyAddresses": [
        "SMTP:janesmith@fabrikam.com"
      ],
      "surname": "Smith"
    },

    # Member link indicating John Smith is a member of IT Admin Group
    {
      "odata.type": "Microsoft.WindowsAzure.ActiveDirectory.DirectoryLinkChange",
      "objectType": "DirectoryLinkChange",
      "objectId": "00000000-0000-0000-0000-000000000000",
      "associationType": "Member",
      "sourceObjectId": "7373b0af-d462-406e-ad26-f2bc96d823d8",
      "sourceObjectType": "Group",
      "sourceObjectUri": "https://graph.windows.net/contoso.com/groups/7373b0af-d462-406e-ad26-f2bc96d823d8",
      "targetObjectId": "dca803ab-bf26-4753-bf20-e1c56a9c34e2",
      "targetObjectType": "User",
      "targetObjectUri": "https://graph.windows.net/contoso.com/users/dca803ab-bf26-4753-bf20-e1c56a9c34e2"
    }
  ]
}

差分クエリのその他の機能 Additional differential query features

差分クエリで、更新されたプロパティとリンクのみを返すことができるようになりました。これにより、差分クエリの呼び出しの処理を高速化し、ペイロードを削減できます。Differential Queries can now return only updated properties and links – this allows faster processing and reduced payloads for Differential Query calls.このオプションを有効にするは、次の例で示すように、ヘッダー ocp-aad-dq-include-only-changed-properties を true に設定します。This option is enabled by setting the header ocp-aad-dq-include-only-changed-properties to true as shown in this example.

GET https://graph.windows.net/contoso.com/users?api-version=2013-11-08&deltaLink= furK18V1T….
HTTP /1.1
ocp-aad-dq-include-only-changed-properties : true
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5nl0aEV1T….
Response: 200 OK

たとえば、ユーザーの "displayName" プロパティのみが変更された場合、For example if only the “displayName” property of user has changed.次のようなオブジェクトが返されます。The returned object would be similar to this:

{     
          "displayName" : "AnUpdatedDisplayName",
         "objectId" :  "c1bf5c59-7974-4aff-a59a-f8dfe9809b18",
         "objectType" :  "User",
          "odata.type" :  "Microsoft.WindowsAzure.ActiveDirectory.User"
},

"現時点" から同期する差分同期サポート - 最新の deltaToken のみを取得することを要求する特殊なヘッダーを指定できます。このトークンは、後続のクエリで使用でき、"現時点" からの変更のみを返します。Differential Sync support to sync from “now” - a special header can be specified, requesting to only get an up-to-date deltaToken, this token can be used in subsequent queries, which will return only changes from “now”.呼び出しの例を次に示します。Here’s the example call:

GET https://graph.windows.net/contoso.com/users?api-version=2013-11-08&deltaLink= smLYT8V1T…
HTTP /1.1
ocp-aad-dq-include-only-delta-token: true
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5nl0aEV1T….
Response: 200 OK

応答には、次のように、deltaLink が含まれますが、変更されたオブジェクトは含まれません。The response will contain the deltaLink, but will not have the changed object(s), similar to this:

{   …  "aad.deltaLink":https://graph.windows.net/contoso.com/users?deltaLink=MRa43......   }

削除された項目を検出する – 応答を使用して、削除された項目を検出することもできます。Detecting a deleted item – the response can also be used to detect a deleted item.削除されたオブジェクトと削除されたリンクは、"aad.isDeleted" プロパティの値が true に設定されていることで示されます。これは、アプリケーションが、以前に作成したオブジェクトとリンクの削除について学習できるようにするために必要です。Deleted objects and deleted links are indicated by the "aad.isDeleted" property with a value set to true; this is necessary to make sure applications can learn about the deletion of previously created objects and links.

その他のリソースAdditional resources

© 2018 Microsoft