Partilhar via

entre em contato com: delta

  • Artigo

Namespace: microsoft.graph

Importante

As APIs na versão /beta no Microsoft Graph estão sujeitas a alterações. Não há suporte para o uso dessas APIs em aplicativos de produção. Para determinar se uma API está disponível na v1.0, use o seletor Versão.

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

Uma chamada de função delta para contactos numa pasta é semelhante a um pedido GET, exceto que ao aplicar adequadamente tokens de estado numa ou mais destas chamadas, pode consultar alterações incrementais nos contactos nessa pasta. Isto permite-lhe manter e sincronizar um arquivo local dos contactos de um utilizador sem ter de obter sempre todo o conjunto de contactos do servidor.

Esta API está disponível nas seguintes implementações de cloud nacionais.

Serviço global US Government L4 US Government L5 (DOD) China operada pela 21Vianet
✅ ✅ ✅ ✅

Permissões

Escolha a permissão ou permissões marcadas como menos privilegiadas para esta API. Utilize uma permissão ou permissões com privilégios mais elevados apenas se a sua aplicação o exigir. Para obter detalhes sobre as permissões delegadas e de aplicação, veja Tipos de permissão. Para saber mais sobre estas permissões, veja a referência de permissões.

Tipo de permissão Permissões com menos privilégios Permissões com privilégios superiores
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 registo de alterações nos contactos implica uma ronda 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 parte do token da URL @odata.nextLink ou @odata.deltaLink fornecida na resposta. Você só precisa especificar uma vez os parâmetros de consulta desejados antecipadamente. Nos pedidos subsequentes, basta copiar e aplicar o @odata.nextLink URL ou @odata.deltaLink da resposta anterior, uma vez que esse URL já inclui os parâmetros codificados e pretendidos.

Parâmetro de consulta Tipo Descrição
$deltatoken string Um token de estado devolvido no @odata.deltaLink URL da chamada de função delta anterior para a mesma coleção de contactos, indicando a conclusão dessa ronda de controlo 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 desse conjunto.
$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. Saiba mais sobre autenticação e autorização.
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.

Pode encontrar um exemplo semelhante que mostra como utilizar os tokens de estado para controlar as alterações nas mensagens de uma pasta de correio: Obter alterações incrementais às mensagens numa pasta. As principais diferenças entre o controlo de contactos e o controlo de mensagens numa pasta estão nos URLs do pedido de consulta delta e nas respostas de consulta que devolvem o contactoem vez das coleções de mensagens.

GET https://graph.microsoft.com/beta/me/contactFolders/{id}/contacts/delta?$select=displayName

Prefer: odata.maxpagesize=2
Resposta

Se a solicitação for bem-sucedida, a resposta incluiria um token de estado que é um skipToken
(num cabeçalho de resposta @odata.nextLink ) ou num deltaToken (num cabeçalho de resposta @odata.deltaLink ). Respetivamente, indicam se deve continuar com a ronda ou se concluiu a obtenção de todas as alterações para essa ronda.

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

Conteúdo relacionado