Table of contents

差異查詢 | Graph API 概念Differential query | Graph API concepts

Jimaco Brannian|上次更新日期: 2018/6/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.差異查詢要求會傳回在兩個連續要求之間,對指定實體進行的所有變更。A differential query request returns all changes made to specified entities during the time between two consecutive requests.例如,如果您在先前的差異查詢要求後的一小時進行差異查詢要求,將只會傳回在該小時內進行的變更。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 DirectoryFor more information, see Integrating Applications with Azure Active Directory.

重要事項

我們強烈建議您使用 Microsoft Graph 來存取 Azure Active Directory 資源,而不是使用 Azure AD Graph API。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 開發人員中心的 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應對其執行查詢之租用戶的唯一識別碼。The unique identifier of the tenant that the query should be executed against.這一般是租用戶的其中一個經驗證網域 (verifiedDomains 屬性),但也可以是租用戶的物件識別碼 (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.支援的實體類型︰使用者、群組和連絡人。The supported entity types are: User, Group and Contact.只有在 為 "directoryObjects" 時有效;否則, 會覆寫篩選器。Only valid when &ltresourceSet&gt is “directoryObjects”; otherwise, &ltresourceSet&gt overrides the filter.例如,如果 為 "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.如果 為 "directoryObjects",同時未指定 $filter,便會傳回對所有支援的實體類型 (使用者、 群組和連絡人) 的變更。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/displayNameFully qualified properties have the entity type specified; for example, User/displayName. 指定為 “directoryObjects”,則必須使用完整屬性;例如 https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&deltaLink=&$select=User/displayName,Group/descriptionFully 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.
  • 非完整屬性則不具指定的實體類型;例如 displayNameNon-qualified properties do not have the entity type specified; for example, displayName.只能用於當 指定為不是 “directoryObjects” 的值時;例如 https://graph.windows.net/contoso.com/users?api-version=2013-04-05&deltaLink=&$select=displayName,jobTitleThey 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 實體,其中每個實體皆包含特定UserGroupContact 物件的變更。Zero to 200 DirectoryObject entities, each of which contains changes for a specific User, Group, or Contact object.

  • 0 到 3000 個 DirectoryLinkChange 實體,其中每個實體皆包含特定 membermanager 連結的變更。Zero to 3000 DirectoryLinkChange entities, each of which contains changes for a specific member or manager link.

  • 可以是 deltaLinknextLink 屬性。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