差異查詢 | Graph API 概念

發行項
2021/10/21

**適用於︰**Graph API | Azure Active Directory

本主題討論 Azure AD Graph API 的差異查詢功能。差異查詢要求會傳回在兩個連續要求之間，對指定實體進行的所有變更。例如，如果您在先前的差異查詢要求後的一小時進行差異查詢要求，將只會傳回在該小時內進行的變更。對應用程式的資料存放區同步租用戶目錄資料時，此功能特別實用。

若要對租用戶的目錄進行差異查詢要求，您的應用程式必須經過租用戶授權。如需詳細資訊，請參閱整合應用程式與 Azure Active Directory。

重要

我們強烈建議您使用 Microsoft Graph 來存取 Azure Active Directory 資源，而不是使用 Azure AD Graph API。我們目前致力於開發 Microsoft Graph，對於 Azure AD Graph API 則沒有進一步增強的計劃。Azure AD Graph API 仍適用於非常少數的案例；如需詳細資訊，請參閱 Office 開發人員中心的 Microsoft Graph 或 Azure AD Graph (英文) 部落格文章。

差異查詢要求

本節將描述差異查詢要求。所有要求均需要下列元件：

有效的要求 URL，包括租用戶和適用查詢字串參數的 Graph 端點。
授權標頭，包含 Azure Active Directory 所發出的有效存取權杖。如需 Graph API 驗證的詳細資訊，請參閱 Azure AD 的驗證案例。

差異查詢要求 URL

以下顯示差異查詢要求 URL 的格式，方括弧 [] 表示選擇性元素。

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

URL 是由階層式區段組成，後面接著一系列以機碼值組表示的查詢字串參數。

URL：階層式區段

區段	說明
tenantId	應對其執行查詢之租用戶的唯一識別碼。這一般是租用戶的其中一個經驗證網域 (verifiedDomains 屬性)，但也可以是租用戶的物件識別碼 (objectId 屬性)。不區分大小寫。
resourceSet	應對其執行查詢之租用戶資源的特定集。判斷在查詢回應中傳回的資源。支援的值為："directoryObjects"、"users"、"contacts" 或 "groups"。這些值會區分大小寫。

URL︰查詢字串參數

參數	說明
api-version	指定發出要求的 Graph API 版本。必要。從 1.5 版開始，此值會以數值版本號碼表示；例如 api-version = 1.5。在舊版中，值是 YYYY-MM-DD 格式的字串；例如 api-version=2013-04-05。 (取代預覽版 Graph API 中使用的 x-ms-dirapi-data-contract-version 標頭。)
deltaLink	在上次回應的 deltaLink 屬性或 nextLink 屬性中傳回的權杖。必要，但在第一次要求中會是空白。 (取代預覽版 Graph API 中的 skipToken 查詢字串參數。)
$filter	表示回應中應該包含的實體類型。選擇性。支援的實體類型︰使用者、群組和連絡人。只有在為 "directoryObjects" 時有效；否則，會覆寫篩選器。例如，如果為 "users"，同時也指定了 $filter 參數，則只會傳回使用者的變更，而不論在篩選器值中指定的為何。如果為 "directoryObjects"，同時未指定 $filter，便會傳回對所有支援的實體類型 (使用者、群組和連絡人) 的變更。若要指定單一實體類型，請使用下列其中一項： `$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')`。 (取代預覽版 Graph API 中的 objectScope 查詢字串參數。) 重要自 1.5 版起，Graph API 命名空間從 Microsoft.WindowsAzure.ActiveDirectory 變更為 Microsoft.DirectoryServices。舊版的 Graph API 繼續使用先前的命名空間；例如 `$filter=isof('Microsoft.WindowsAzure.ActiveDirectory.Contact')`。
$select	指定應在回應中併入的屬性。如果未指定 *$select^，則會包括所有屬性。指定屬性時可採用完整或不完整方式來指定。使用逗點分隔多個屬性。完整屬性具有指定的實體類型；例如 `User/displayName`。若指定為 “directoryObjects”，則必須使用完整屬性；例如 `https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&deltaLink=&$select=User/displayName,Group/description`。非完整屬性則不具指定的實體類型；例如 `displayName`。只能用於當指定為不是 “directoryObjects” 的值時；例如 `https://graph.windows.net/contoso.com/users?api-version=2013-04-05&deltaLink=&$select=displayName,jobTitle`。

注意：查詢字串中的機碼值組區分大小寫，但順序不重要。

以下是最簡易的差異查詢的範例。這是在初始同步期間使用。

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

以下是後續要求的範例。

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

差異查詢回應

本節說明在進行差異查詢要求時，所傳回差異查詢回應的內容。下列清單說明回應的內容：

0 到 200 個 DirectoryObject 實體，每個均包含特定 User、Group 或 Contact 物件的變更。
0 到 3000 個 DirectoryLinkChange 實體，每個均包含特定 member 或 manager 連結的變更。
可以是 deltaLink 或 nextLink 屬性。在任一情況下，值都是區分大小寫且以 URL 編碼的字串，內嵌了就目錄中所發生的其餘變更，傳回到用戶端之目錄變更集的相關狀態資訊。此字串 (或權杖) 應在下一次的差異查詢要求中併入 deltaLink 查詢字串參數。
- 如果傳回了 deltaLink 屬性，則在此回應之後，便沒有需要應用程式進行同步的其他目錄變更。應用程式可以根據自己的需要等候一段預定的時間，再發出下一次的差異查詢要求。
- 如果傳回了 nextLink 屬性，則在此回應之後，還有需要應用程式進行同步的其他目錄變更。應用程式應該在方便時盡快發出下一次的差異查詢要求。

一律會以 JSON 格式傳回回應。

使用差異查詢時的考量

下列清單將強調對於使用差異查詢之應用程式的重要考量：

差異查詢傳回的變更表示回應時目錄物件的狀態。您的應用程式不得將這些變更視為要重新執行的交易記錄。
變更會以其發生的順序顯示。最近變更的物件會出現在最後，即使已更新物件多次也是如此。其順序也不會受用戶端收到變更時間的影響。因此，變更出現的順序有可能相較於最初在目錄中發生的順序不同。
您的應用程式必須準備重新執行，它會在後續回應中出現相同的變更時發生。雖然差異查詢會盡力降低重新執行的情況，但仍可能發生。
您的應用程式必須準備對它未注意到的物件處理刪除變更。
差異查詢可能傳回其他資源未傳回之來源或目標物件的連結。
請參閱下方的其他差異查詢功能一節，了解使用要求標頭的詳細資訊，以限制查詢並改善效能。

要求和回應範例

以下是初始差異查詢要求的範例：

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

以下是累加差異查詢要求的範例：

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 查詢參數。因為篩選器會指定差異查詢 (User、Group 和 Contact) 的所有可能目標類型，因此可加以忽略，而查詢預設會傳回這所有實體類型的變更。

下列範例回應示範傳回的 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"
    }
  ]
}

其他的差異查詢功能

只更新的屬性和連結，現在可以傳回差異查詢，因為這可讓處理速度和減少的裝載的差異查詢呼叫。如此範例所示，透過將標頭 ocp-aad-dq-include-only-changed-properties 設定為 true 來啟用此選項。

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" 屬性的使用者已變更。傳回的物件會如下所示︰

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

從 “now” 同步處理差異的同步處理支援 - 可以指定特殊標頭，要求只取得最新的 deltaToken，此權杖可用於後續只從 “now” 傳回變更的查詢。以下是範例呼叫︰

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，但不會有變更的物件，如下所示：

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

偵測已刪除的項目 – 回應也可用來偵測已刪除的項目。已刪除的物件和已刪除的連結會以"aad.isDeleted"屬性設定值設為 true，表示這是為了確定應用程式可以了解刪除先前建立的物件和連結。

其他資源

Azure AD Graph API 參考