contact: deltacontact: delta

获取指定文件夹中已添加、删除或更新的联系人集。Get a set of contacts that have been added, deleted, or updated in a specified folder.

对文件夹中的联系人的 delta 函数调用与 GET 请求相似,但是可通过在对其的一次或多次调用中正确应用状态令牌来查询该文件夹中的联系人的增量更改这一点除外。通过此功能,你可以维护和同步本地存储的用户联系人,而无需每次都从服务器中获取整组联系人。A delta function call for contacts in a folder is similar to a GET request, except that by appropriately applying state tokens in one or more of these calls, you can query for incremental changes in the contacts in that folder. This allows you to maintain and synchronize a local store of a user's contacts without having to fetch the entire set of contacts from the server every time.

权限Permissions

要调用此 API,需要以下权限之一。要了解详细信息,包括如何选择权限的信息,请参阅权限One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

权限类型Permission type 权限(从最低特权到最高特权)Permissions (from least to most privileged)
委派(工作或学校帐户)Delegated (work or school account) Contacts.Read、Contacts.ReadWriteContacts.Read, Contacts.ReadWrite
委派(个人 Microsoft 帐户)Delegated (personal Microsoft account) Contacts.Read、Contacts.ReadWriteContacts.Read, Contacts.ReadWrite
应用程序Application Contacts.Read、Contacts.ReadWriteContacts.Read, Contacts.ReadWrite

HTTP 请求HTTP request

GET /me/contactFolders/{id}/contacts/delta
GET /users/{id}/contactFolders/{id}/contacts/delta

查询参数Query parameters

跟踪联系人更改会引发一组对 delta 函数的一次或多次调用。如果要使用任意查询参数($deltatoken$skiptoken 除外),则必须在最初的 delta 请求中指定它。Microsoft Graph 自动将指定的任意参数编码为响应中提供的 nextLinkdeltaLink URL 的令牌部分。你只需预先指定任意所需查询参数一次。在后续的请求中,只需复制并应用以前响应中的 nextLinkdeltaLink URL,因为该 URL 已包含所需的编码参数。Tracking changes in contacts incurs a round of one or more delta function calls. If you use any query parameter (other than $deltatoken and $skiptoken), you must specify it in the initial delta request. Microsoft Graph automatically encodes any specified parameters into the token portion of the nextLink or deltaLink URL provided in the response. You only need to specify any desired query parameters once upfront. In subsequent requests, simply copy and apply the nextLink or deltaLink URL from the previous response, as that URL already includes the encoded, desired parameters.

查询参数Query parameter 类型Type 说明Description
$deltatoken$deltatoken stringstring 对同一个联系人集合之前的 delta 函数调用的 deltaLink URL 中返回的状态令牌,指示该组更改跟踪的完成状态。将此令牌包含在对该集合的下一组更改追踪的首次请求中,并保存和应用整个 deltaLink URL。A state token returned in the deltaLink URL of the previous delta function call for the same contact collection, indicating the completion of that round of change tracking. Save and apply the entire deltaLink URL including this token in the first request of the next round of change tracking for that collection.
$skiptoken$skiptoken stringstring 之前的 delta 函数调用的 nextLink URL 中返回的状态令牌,指示同一个联系人集合中有进一步的更改需要跟踪。A state token returned in the nextLink URL of the previous delta function call, indicating there are further changes to be tracked in the same contact collection.

OData 查询参数OData query parameters

  • 像在任何 GET 请求中一样,你可以使用 $select 查询参数以仅指定获取最佳性能所需的属性。始终返回 id 属性。You can use a $select query parameter as in any GET request to specify only the properties your need for best performance. The id property is always returned.

请求标头Request headers

名称Name 类型Type 说明Description
AuthorizationAuthorization stringstring Bearer {token}。必需。Bearer {token}. Required.
Content-TypeContent-Type stringstring application/json. Required.application/json. Required.
PreferPrefer stringstring odata.maxpagesize={x}。可选。odata.maxpagesize={x}. Optional.

响应Response

如果成功,此方法在响应正文中返回 200 OK 响应代码和 contact 集合对象。If successful, this method returns a 200 OK response code and contact collection object in the response body.

示例Example

请求Request

下面的示例演示了如何调用单个 delta 函数,使用 $select 参数仅获取每个联系人的 displayName 属性并将响应正文中的联系人的最大数目限制为 2。The following example shows how to make a single delta function call, use the $select parameter to get only each contact's displayName property, and limit the maximum number of contacts in the response body to 2.

若要跟踪文件夹中联系人的更改,要使用正确的状态令牌执行一次或多次 delta 函数调用来获取上次增量查询后的增量更改集。To track changes in the contacts in a folder, you would make one or more delta function calls, with appropriate state tokens, to get the set of incremental changes since the last delta query.

演示如何使用状态令牌跟踪邮件文件夹中的邮件更改的示例与其相似:获取文件夹中邮件的增量更改。跟踪联系人和跟踪文件夹中的邮件之间的主要区别在于增量查询请求 URL 以及查询响应将返回 mailFolder 集合而非 message 集合。You can find a similar example that shows how to use the state tokens to track changes in the messages of a mail folder: Get incremental changes to messages in a folder. The main differences between tracking contacts and tracking messages in a folder are in the delta query request URLs, and the query responses returning contact rather than message collections.

GET https://graph.microsoft.com/v1.0/me/contactFolders/{id}/contacts/delta?$select=displayName
Prefer: odata.maxpagesize=2
响应Response

如果请求成功,响应将包含一个状态令牌,其为 skipTokenIf the request is successful, the response would include a state token, which is either a skipToken
(位于 _@odata.nextLink_ 响应头中)或 deltaToken(位于 _@odata.deltaLink_ 响应头中)。它们分别指示应继续此组调用还是已获取该组的所有更改。(in an _@odata.nextLink_ response header) or a deltaToken (in an _@odata.deltaLink_ response header). Respectively, they indicate whether you should continue with the round or you have completed getting all the changes for that round.

以下响应显示了 _@odata.nextLink_ 响应头中的 skipTokenThe response below shows a skipToken in an _@odata.nextLink_ response header.

注意:为了简单起见,可能会将此处所示的响应对象截断。将从实际调用中返回所有属性。Note: The response object shown here may be truncated for brevity. All of the properties will be returned from an actual call.

HTTP/1.1 200 OK
Content-type: application/json
Content-length: 337

{
  "@odata.nextLink":"https://graph.microsoft.com/v1.0/me/contactfolders/{id}/contacts/delta?$skiptoken={_skipToken_}",
  "value": [
    {
      "parentFolderId": "parentFolderId-value",
      "birthday": "2016-10-19T10:37:00Z",
      "fileAs": "fileAs-value",
      "displayName": "displayName-value",
      "givenName": "givenName-value",
      "initials": "initials-value"
    }
  ]
}

另请参阅See also