Table of contents

差異查詢 | Graph API 概念

Jimaco Brannian|上次更新日期: 2016/9/6
|
1 投稿人

適用於︰Graph API | Azure Active Directory

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

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

重要事項

您也可以透過 Microsoft Graph 取得 Azure AD Graph API 功能,這個統一 API 同時也包含如 Outlook、OneDrive、OneNote、Planner 和 Office Graph 等其他 Microsoft 服務 API,讓您可以使用單一的存取權杖透過單一端點存取所有 API。 請注意,Microsoft Graph 目前不支援差異查詢,您必須使用 Azure AD Graph API 來取得這項功能。

差異查詢要求

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

  • 有效的要求 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 實體,其中每個實體皆包含特定UserGroupContact 物件的變更。

  • 0 到 3000 個 DirectoryLinkChange 實體,其中每個實體皆包含特定 membermanager 連結的變更。

  • 可以是 deltaLinknextLink 屬性。 在任一情況下,值都是區分大小寫且以 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"
},

差異同步功能支援從「現在」開始同步:可以指定特殊標頭要求只取得最新的 deltaToken。此語彙基元也可在後續查詢中使用,而且只會傳回從「現在」開始之後的變更。 以下是範例呼叫︰

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,表示這是為了確定應用程式可以了解刪除先前建立的物件和連結。

其他資源

© 2017 Microsoft