差异查询 |Graph API 概念

项目
2021/10/21

**适用范围: ** Graph API | Azure Active Directory

本主题讨论 Azure AD Graph API 的差异查询功能。差异查询请求返回在两次连续请求之间对指定实体所做的所有更改。例如，如果你在上次差异查询请求后一个小时又发出差异查询请求，则只返回这一个小时内所做的更改。当与应用程序的数据存储同步租户目录数据时，此功能特别有用。

若要对租户的目录发出差异查询请求，你的应用程序必须获得租户的授权。有关详细信息，请参阅将应用程序与 Azure Active Directory 集成。

重要

强烈建议使用 Microsoft Graph 代替 Azure AD Graph API 来访问 Azure Active Directory 资源。现在我们的开发工作将重点集中在 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 属性）之一，但它也可以是租户的对象 ID（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	指示应在响应中包含哪些实体类型。可选。支持的实体类型包括: 用户、组和联系人。仅当 &ltresourceSet&g 是“directoryObjects”时有效；否则，&ltresourceSet&g 将覆盖筛选器。例如，如果 &ltresourceSet&gt 是“users”，而且还指定了 $filter 参数，则只返回对用户的更改，而无论在筛选器中指定了什么值。如果 &ltresourceSet&gt 是“directoryObjects”但未指定 $filter，则返回对所有支持的实体类型（User、Group 和 Contact）的更改。若要指定单个实体类型，请使用以下项之一: `$filter=isof('Microsoft.WindowsAzure.ActiveDirectory.Contact')` `$filter=isof('Microsoft.WindowsAzure.ActiveDirectory.User')` `$filter=isof('Microsoft.WindowsAzure.ActiveDirectory.Group')` 若要指定多个实体类型，请使用 or 运算符；例如，`$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`。如果将 &ltresourceSet&gt 指定为“directoryObjects”，则必须使用完全限定的属性；例如 `https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&deltaLink=&$select=User/displayName,Group/description`。非限定属性不指定实体类型，例如 `displayName`。仅当 &ltresourceSet&gt 指定为值而不是“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 实体，每个实体均包含对特定成员或管理器链接的更改。
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"
},

差异同步支持从“现在”开始同步 - 可以指定一个特殊的标头，请求仅获取最新 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）进行标示；此操作很有必要，从而确保应用程序可以了解以前创建的对象和链接是否被删除。

其他资源

Azure AD Graph API 参考