entre em contato com: delta

Namespace: microsoft.graph

Obtenha um conjunto de contatos que foram adicionados, excluídos ou atualizados em uma pasta especificada.

Uma chamada de função delta de contatos em uma pasta é semelhante a uma solicitação GET, exceto que, aplicando adequadamente os tokens de estado em uma ou mais dessas chamadas, permite consultar alterações incrementais nos contatos dessa pasta. Isso permite manter e sincronizar um armazenamento local de contatos do usuário sem ter de buscar todo o conjunto de contatos do usuário sempre que precisar dele.

Permissões

Uma das seguintes permissões é obrigatória para chamar esta API. Para saber mais, incluindo como escolher permissões, confira Permissões.

Tipo de permissão	Permissões (da com menos para a com mais privilégios)
Delegado (conta corporativa ou de estudante)	Contacts.Read, Contacts.ReadWrite
Delegado (conta pessoal da Microsoft)	Contacts.Read, Contacts.ReadWrite
Aplicativo	Contacts.Read, Contacts.ReadWrite

Solicitação HTTP

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

Parâmetros de consulta

O controle de alterações em contatos corresponde a uma série de uma ou mais chamadas de função delta. Se você usar qualquer parâmetro de consulta (diferente de $deltatoken e $skiptoken), especifique-o na primeira solicitação delta. O Microsoft Graph codifica automaticamente todos os parâmetros especificados na porção do token da URL @odata.nextLink ou @odata.deltaLink fornecida na resposta. Você só precisa especificar os parâmetros de consulta desejados uma vez antecipados. Em solicitações subsequentes, basta copiar e aplicar a URL @odata.nextLink ou @odata.deltaLink da resposta anterior já que essa URL inclui os parâmetros codificados desejados.

Parâmetro de consulta	Tipo	Descrição
$deltatoken	string	Um token de estado retornado na URL @odata.deltaLink da chamada de função delta anterior da mesma coleção de contatos indicando a conclusão da série de controle de alterações. Salve e aplique toda a URL @odata.deltaLink, incluindo esse token na primeira solicitação da próxima série de controle de alterações da coleção.
$skiptoken	string	Um token de estado retornado na URL @odata.nextLink da chamada de função delta anterior indicando que não há mais alterações a serem controladas na mesma coleção de contatos.

Parâmetros de consulta OData

• Você pode usar um parâmetro de consulta $select como em qualquer solicitação GET para especificar somente as propriedades necessárias para obter melhor desempenho. A propriedade id sempre será retornada.

Cabeçalhos de solicitação

Nome	Tipo	Descrição
Autorização	string	{token} de portador. Obrigatório.
Content-Type	string	application/json. Obrigatório.
Preferir	cadeia de caracteres	odata.maxpagesize={x}. Opcional.

Resposta

Se bem-sucedido, este método retorna o código de resposta 200 OK e uma coleção de objetos contact no corpo da resposta.

Exemplo

Solicitação

O exemplo a seguir mostra como fazer uma única chamada de função delta, use o parâmetro $select para obter apenas a propriedade displayName de cada contato e limite o número máximo de contatos no corpo de resposta a 2.

Para controlar as alterações nos contatos em uma pastas, faça uma ou mais chamadas de função delta, com os tokens de estado apropriados, para obter o conjunto de alterações incrementais desde a última consulta delta.

Você pode encontrar um exemplo semelhante que mostra como usar os tokens de estado para controlar alterações em mensagens de uma pasta de email: Obtenha alterações incrementais para as mensagens em uma pasta. As principais diferenças entre o controle de contatos e de mensagens em uma pasta encontram-se nas URLs das solicitações da consulta delta e nas respostas da consulta que retornam contact em vez de coleções de mensagens.

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();

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider , consulte a documentação do 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();

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider , consulte a documentação do 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];

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider , consulte a documentação do 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();

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider , consulte a documentação do 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)

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider , consulte a documentação do SDK.

PowerShell

Import-Module Microsoft.Graph.Users.Functions

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

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider , consulte a documentação do SDK.

Resposta

Se a solicitação for bem-sucedida, a resposta incluiria um token de estado que é um skipToken
(em um cabeçalho de resposta @odata.nextLink) ou um deltaToken (em um cabeçalho de resposta @odata.deltaLink). Respectivamente, elas indicam se você deverá continuar com a série ou se já concluiu a obtenção de todas as alterações dessa série.

A resposta abaixo mostra um skipToken em um cabeçalho de resposta @odata.nextLink.

Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.

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

Confira também

• Usar a consulta delta para controlar alterações nos dados do Microsoft Graph
• Obter as alterações incrementais para as mensagens em uma pasta