contact: delta

命名空间：microsoft.graph

获取指定文件夹中已添加、删除或更新的联系人集。

对文件夹中的联系人的 delta 函数调用与 GET 请求相似，但是可通过在对其的一次或多次调用中正确应用 状态令牌来查询该文件夹中的联系人的增量更改这一点除外。通过此功能，你可以维护和同步本地存储的用户联系人，而无需每次都从服务器中获取整组联系人。

Permissions

要调用此 API，需要以下权限之一。要了解详细信息，包括如何选择权限的信息，请参阅权限。

权限类型	权限（从最低特权到最高特权）
委派（工作或学校帐户）	Contacts.Read、Contacts.ReadWrite
委派（个人 Microsoft 帐户）	Contacts.Read、Contacts.ReadWrite
应用程序	Contacts.Read、Contacts.ReadWrite

HTTP 请求

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

查询参数

跟踪联系人更改会引发一组对 delta 函数的一次或多次调用。如果要使用任意查询参数（$deltatoken 和 $skiptoken 除外），则必须在最初的 delta 请求中指定它。Microsoft Graph 自动将指定的任意参数编码为响应中提供的 @odata.nextLink 或 @odata.deltaLink URL 的令牌部分。你只需预先指定任意所需查询参数一次。在后续的请求中，只需复制并应用以前响应中的 @odata.nextLink 或 @odata.deltaLink URL，因为该 URL 已包含所需的编码参数。

查询参数	类型	说明
$deltatoken	string	对同一个联系人集合之前的 delta 函数调用的 @odata.deltaLink URL 中返回的 状态令牌，指示该组更改跟踪的完成状态。将此令牌包含在对该集合的下一组更改追踪的首次请求中，并保存和应用整个 @odata.deltaLink URL。
$skiptoken	string	之前的 delta 函数调用的 @odata.nextLink URL 中返回的 状态令牌，指示同一个联系人集合中有进一步的更改需要跟踪。

OData 查询参数

• 像在任何 GET 请求中一样，你可以使用 $select 查询参数以仅指定获取最佳性能所需的属性。始终返回 id 属性。

请求标头

名称	类型	说明
Authorization	string	Bearer {token}。必需。
Content-Type	string	application/json. Required.
Prefer	string	odata.maxpagesize={x}。可选。

响应

如果成功，此方法在响应正文中返回 200 OK 响应代码和 contact 集合对象。

示例

请求

下面的示例演示了如何调用单个 delta 函数，使用 $select 参数仅获取每个联系人的 displayName 属性并将响应正文中的联系人的最大数目限制为 2。

若要跟踪文件夹中联系人的更改，要使用正确的状态令牌执行一次或多次 delta 函数调用来获取上次增量查询后的增量更改集。

演示如何使用状态令牌跟踪邮件文件夹中的邮件更改的示例与其相似：获取文件夹中邮件的增量更改。跟踪联系人和跟踪文件夹中的邮件之间的主要区别在于增量查询请求 URL 以及查询响应将返回 mailFolder 集合而非 message 集合。

HTTP

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

C#

GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var delta = await graphClient.Me.ContactFolders["{contactFolder-id}"].Contacts
    .Delta()
    .Request()
    .Header("Prefer","odata.maxpagesize=2")
    .Select("displayName")
    .GetAsync();

有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息，请参阅 SDK 文档。

JavaScript

const options = {
    authProvider,
};

const client = Client.init(options);

let delta = await client.api('/me/contactFolders/{id}/contacts/delta')
    .header('Prefer','odata.maxpagesize=2')
    .select('displayName')
    .get();

有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息，请参阅 SDK 文档。

Objective-C

MSHTTPClient *httpClient = [MSClientFactory createHTTPClientWithAuthenticationProvider:authenticationProvider];

NSString *MSGraphBaseURL = @"https://graph.microsoft.com/v1.0/";
NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:[MSGraphBaseURL stringByAppendingString:@"/me/contactFolders/{id}/contacts/delta?$select=displayName"]]];
[urlRequest setHTTPMethod:@"GET"];
[urlRequest setValue:@"odata.maxpagesize=2" forHTTPHeaderField:@"Prefer"];

MSURLSessionDataTask *meDataTask = [httpClient dataTaskWithRequest:urlRequest 
    completionHandler: ^(NSData *data, NSURLResponse *response, NSError *nserror) {

        NSError *jsonError = nil;
        MSCollection *collection = [[MSCollection alloc] initWithData:data error:&jsonError];
        MSGraphContact *contact = [[MSGraphContact alloc] initWithDictionary:[[collection value] objectAtIndex: 0] error:&nserror];

}];

[meDataTask execute];

有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息，请参阅 SDK 文档。

Java

GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

LinkedList<Option> requestOptions = new LinkedList<Option>();
requestOptions.add(new HeaderOption("Prefer", "odata.maxpagesize=2"));

ContactDeltaCollectionPage delta = graphClient.me().contactFolders("{id}").contacts()
    .delta()
    .buildRequest( requestOptions )
    .select("displayName")
    .get();

有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息，请参阅 SDK 文档。

Go

//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClient(requestAdapter)

requestParameters := &msgraphsdk.DeltaRequestBuilderGetQueryParameters{
    Select: "displayName",
}
headers := map[string]string{
    "Prefer": "odata.maxpagesize=2"
}
options := &msgraphsdk.DeltaRequestBuilderGetRequestConfiguration{
    QueryParameters: requestParameters,
    Headers: headers,
}
contactFolderId := "contactFolder-id"
result, err := graphClient.Me().ContactFoldersById(&contactFolderId).Contacts().Delta()(contactFolder-id).GetWithRequestConfigurationAndResponseHandler(options, nil)

有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息，请参阅 SDK 文档。

PowerShell

Import-Module Microsoft.Graph.Users.Functions

# A UPN can also be used as -UserId.
Get-MgUserContactFolderContactDelta -UserId $userId -ContactFolderId $contactFolderId -Property "displayName" 

有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息，请参阅 SDK 文档。

响应

如果请求成功，响应将包含一个状态令牌，其为 skipToken
（位于 @odata.nextLink 响应头中）或 deltaToken（位于 @odata.deltaLink 响应头中）。它们分别指示应继续此组调用还是已获取该组的所有更改。

以下响应显示了 @odata.nextLink 响应头中的 skipToken。

注意：为了提高可读性，可能缩短了此处显示的响应对象。

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

{
  "@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"
    }
  ]
}

另请参阅

• 使用增量查询跟踪 Microsoft Graph 数据更改
• 获取文件夹中邮件的增量更改