orgContact: delta
Namespace: microsoft.graph
Obtenha contatos organizacionais recém-criados, atualizados ou excluídos sem precisar executar uma leitura completa de toda a coleção. Confira controle de alterações para obter detalhes.
Essa API está disponível nas seguintes implantações nacionais de nuvem.
Serviço global | Governo dos EUA L4 | GOVERNO DOS EUA L5 (DOD) | China operada pela 21Vianet |
---|---|---|---|
✅ | ✅ | ✅ | ✅ |
Permissões
Escolha a permissão ou as permissões marcadas como menos privilegiadas para essa API. Use uma permissão ou permissões privilegiadas mais altas somente se o aplicativo exigir. Para obter detalhes sobre permissões delegadas e de aplicativo, consulte Tipos de permissão. Para saber mais sobre essas permissões, consulte a referência de permissões.
Tipo de permissão | Permissões menos privilegiadas | Permissões privilegiadas mais altas |
---|---|---|
Delegado (conta corporativa ou de estudante) | OrgContact.Read.All | Directory.Read.All, Directory.ReadWrite.All |
Delegado (conta pessoal da Microsoft) | Sem suporte. | Sem suporte. |
Application | OrgContact.Read.All | Directory.Read.All, Directory.ReadWrite.All |
Solicitação HTTP
Para começar a acompanhar as alterações, você faz uma solicitação, incluindo a função delta no recurso contatos.
GET /contacts/delta
Parâmetros de consulta
O acompanhamento de alterações nos contatos organizacionais incorre em uma rodada 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 todos os parâmetros de consulta uma vez antecipadamente.
Em solicitações subsequentes, copie e aplique a @odata.nextLink
URL ou @odata.deltaLink
da resposta anterior. Essa URL já inclui os parâmetros codificados.
Parâmetro de consulta | Tipo | Descrição |
---|---|---|
$deltatoken | string | Um token de estado retornado na @odata.deltaLink URL da chamada de função delta anterior para a mesma coleção de contatos da organização, indicando a conclusão dessa rodada de rastreamento de alterações. Salve e aplique toda @odata.deltaLink a URL, incluindo esse token, na primeira solicitação da próxima rodada de acompanhamento de alterações para essa coleção. |
$skiptoken | string | Um token de estado retornado na @odata.nextLink URL da chamada de função delta anterior, indicando que há outras alterações a serem rastreadas na mesma coleção de contatos da organização. |
Parâmetros de consulta OData
Esse método dá suporte a parâmetros opcionais de consulta OData para ajudar a personalizar a resposta.
- 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. - Há suporte limitado para
$filter
:- A única expressão
$filter
suportada é para controlar alterações em um objeto específico:$filter=id+eq+{value}
. É possível filtrar vários objetos. Por exemplo,https://graph.microsoft.com/v1.0/contacts/delta/?$filter= id eq '477e9fc6-5de7-4406-bb2a-7e5c83c9ffff' or id eq '004d6a07-fe70-4b92-add5-e6e37b8affff'
. Há um limite de 50 objetos filtrados.
- A única expressão
Cabeçalhos de solicitação
Nome | Descrição |
---|---|
Autorização | {token} de portador. Obrigatório. Saiba mais sobre autenticação e autorização. |
Preferir | return=minimal Especificar esse cabeçalho com uma solicitação que usa @odata.deltaLink retorna somente as propriedades do objeto que foram alteradas desde a última vez. Opcional. |
Corpo da solicitação
Não forneça um corpo de solicitação para esse método.
Resposta
Se for bem-sucedido, esse método retornará um 200 OK
código de resposta e um objeto de coleção orgContact no corpo da resposta. A resposta também inclui uma URL @odata.nextLink
ou @odata.deltaLink
.
Se uma URL
@odata.nextLink
for retornada:- Isso indica que há páginas adicionais de dados a serem recuperadas na sessão. O aplicativo continua fazendo solicitações usando a URL
@odata.nextLink
até uma URL@odata.deltaLink
ser incluída na resposta. - A resposta inclui o mesmo conjunto de propriedades como na solicitação de consulta delta inicial. Assim você pode capturar o estado atual de todos os objetos ao iniciar o ciclo de delta.
- Isso indica que há páginas adicionais de dados a serem recuperadas na sessão. O aplicativo continua fazendo solicitações usando a URL
Se uma URL
@odata.deltaLink
for retornada:- Isso indica que não há mais dados sobre o estado existente do recurso a ser retornado. Salve e use a URL
@odata.deltaLink
para saber mais sobre alterações ao recurso na próxima fase. - Você pode especificar o cabeçalho
Prefer:return=minimal
para incluir somente os valores de resposta das propriedades que foram alteradas desde a hora em que o@odata.deltaLink
foi emitido.
- Isso indica que não há mais dados sobre o estado existente do recurso a ser retornado. Salve e use a URL
Padrão: retornar as mesmas propriedades de uma solicitação delta inicial
Por padrão, as solicitações usando @odata.deltaLink
ou @odata.nextLink
retornam as mesmas propriedades selecionadas na consulta delta inicial das seguintes maneiras:
- Se a propriedade foi alterada, o novo valor será incluído na resposta. Isso inclui propriedades definidas com valor nulo.
- Se a propriedade não tiver sido alterada, o valor antigo será incluído na resposta.
- Se a propriedade nunca tiver sido definida antes, ela não será incluída na resposta.
Nota: Com esse comportamento, não é possível dizer se uma propriedade está mudando olhando para a resposta. Além disso, as respostas delta tendem a ser grandes porque contêm todos os valores de propriedade, conforme mostrado no Exemplo 2.
Alternativa: retornar somente as propriedades alteradas
Adicionar o cabeçalho prefer:return=minimal
opcional na solicitação resulta no comportamento a seguir:
- Se a propriedade foi alterada, o novo valor será incluído na resposta. Isso inclui propriedades definidas com valor nulo.
- Se a propriedade não tiver sido alterada, a propriedade não será incluída na resposta. (Diferente do comportamento padrão.)
Observação: é possível adicionar o cabeçalho a uma solicitação
@odata.deltaLink
a qualquer momento no ciclo de delta. O cabeçalho afeta apenas o conjunto de propriedades incluídas na resposta e não afeta como a consulta delta é executada. Veja o Exemplo 3.
Exemplos
Exemplo 1: Propriedades padrão
Solicitação
Aqui está um exemplo da solicitação. Não há parâmetro $select
, portanto, um conjunto padrão de propriedades é rastreado e retornado.
GET https://graph.microsoft.com/v1.0/contacts/delta
Resposta
Aqui está um exemplo da resposta ao usar @odata.deltaLink
obtido da inicialização da consulta.
Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context":"https://graph.microsoft.com/v1.0/$metadata#contacts",
"@odata.nextLink":"https://graph.microsoft.com/v1.0/contacts/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjsXoYQp_dpA3cNJWc",
"value": [
{
"companyName": "companyName-value",
"department": "department-value",
"displayName": "displayName-value",
"givenName": "givenName-value",
"id": "string (identifier)",
"jobTitle": "jobTitle-value",
"mail": "mail-value",
"mailNickname": "mailNickname-value",
"surname": "surname-value"
}
]
}
Exemplo 2: Escolher três propriedades
Solicitação
O próximo exemplo mostra uma solicitação inicial selecionando três propriedades para controle de alterações com comportamento de resposta padrão.
GET https://graph.microsoft.com/v1.0/contacts/delta?$select=displayName,jobTitle,mail
Resposta
Aqui está um exemplo da resposta ao usar @odata.deltaLink
obtido da inicialização da consulta. Todas as três propriedades estão incluídas na resposta e não se sabe quais foram alteradas desde que a @odata.deltaLink
foi obtida.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context":"https://graph.microsoft.com/v1.0/$metadata#contacts",
"@odata.nextLink":"https://graph.microsoft.com/v1.0/contacts/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjsXoYQp_dpA3cNJWc",
"value": [
{
"displayName": "displayName-value",
"jobTitle": "jobTitle-value",
"mail": null
}
]
}
Exemplo 3: Comportamento de resposta mínimo alternativo
Solicitação
O exemplo a seguir mostra uma solicitação inicial selecionando três propriedades para controle de alterações com o comportamento de resposta mínima alternativa.
GET https://graph.microsoft.com/v1.0/contacts/delta?$select=displayName,jobTitle,mail
Prefer: return=minimal
Resposta
Aqui está um exemplo da resposta ao usar @odata.deltaLink
obtido da inicialização da consulta. A mail
propriedade não está incluída, o que significa que ela não foi alterada desde a última consulta delta; displayName
e jobTitle
está incluída, o que significa que seus valores foram alterados.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context":"https://graph.microsoft.com/v1.0/$metadata#contacts",
"@odata.nextLink":"https://graph.microsoft.com/v1.0/contacts/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjsXoYQp_dpA3cNJWc",
"value": [
{
"displayName": "displayName-value",
"jobTitle": null
}
]
}