Table of contents

Consulta diferencial | Conceitos da API do Graph

Jimaco Brannian|Última Atualização: 05/09/2016
|
1 Colaborador

Aplica-se a: API do Graph | Azure Active Directory

Este tópico discute o recurso de consulta diferencial da API do Azure AD Graph. Uma solicitação de consulta diferencial retorna todas as alterações feitas para entidades especificas durante o tempo entre as duas solicitações consecutivas. Por exemplo, se você fizer uma solicitação de consulta diferencial uma hora após a solicitação de consulta diferencial anterior, apenas as alterações feitas durante essa hora serão retornadas. Essa funcionalidade é especialmente útil quando estiver sincronizando dados de diretório do locatário com o armazenamento de dados de um aplicativo.

Para fazer uma solicitação de consulta diferencial para o diretório de um locatário, seu aplicativo deve ser autorizado pelo locatário. Para obter mais informações, consulte Integrating Applications with Azure Active Directory (Integrando Aplicativos com o Azure Active Directory).

Importante

A funcionalidade da API do Azure AD Graph também está disponível por meio do Microsoft Graph, uma API unificada que também inclui APIs de outros serviços Microsoft, como Outlook, OneDrive, OneNote, Planner e Office Graph, sendo todas elas acessadas por meio de um ponto de extremidade com um token de acesso. Observe que a consulta diferencial atualmente não tem suporte no Microsoft Graph; você precisará usar a API do Azure AD Graph para esse recurso.

Solicitações de consulta diferencial

Esta seção descreve as solicitações de consulta diferencial. Todas as solicitações requerem os seguintes componentes:

  • Uma URL de solicitação válida, incluindo o ponto de extremidade da Graph para o locatário e os parâmetros de cadeia de caracteres de consulta aplicável.

  • Um cabeçalho de autorização, incluindo um token de acesso válido emitido pelo Active Directory do Azure. Para obter mais informações sobre autenticação usando a API do Graph, consulte Authentication Scenarios for Azure AD (Cenários de Autenticação para o Azure AD).

URL de solicitação de consulta diferencial

O exemplo a seguir mostra o formato da URL de solicitação de consulta diferencial; colchetes [] indicam elementos opcionais.

https://graph.windows.net/<tenantId>/<resourceSet>?api-version=<SupportedApiVersion>&deltaLink=<token>&[$filter=isof(<entityType>)]&[$select=<PropertyList>]

A URL é composta por segmentos hierárquicos seguidos por uma série de parâmetros de cadeia de caracteres de consulta expressa como pares de chave/valor.

URL: segmentos hierárquicos

SegmentoDescrição
tenantIdO identificador exclusivo do locatário no qual a consulta deve ser executada. Esse costuma ser um dos domínios verificados (propriedade verifiedDomains) do locatário, mas ele também pode ser a ID de objeto do locatário (propriedade objectId). Não diferencia maiúsculas de minúsculas.
resourceSetO conjunto de recursos de locatário específico no qual essa consulta deve ser executada. Determina quais recursos são retornados na resposta da consulta. Os valores com suporte são: “directoryObjects”, “users”, “contacts” ou “groups”. Os valores diferenciam maiúsculas de minúsculas.

URL: parâmetros de cadeia de caracteres de consulta

ParâmetroDescrição
api-versionEspecifica a versão da API do Graph na qual a solicitação é emitida. Obrigatório. Começando com a versão 1.5, o valor é expresso como um número de versão numérica; por exemplo, api-version=1.5. Para versões anteriores, o valor é uma cadeia de caracteres do formulário AAAA-MM-DD; por exemplo, api-version=2013-04-05.

(Substitui o uso do cabeçalho x-ms-dirapi-data-contract-version na versão de visualização da API do Graph.)
deltaLinkO token retornado na propriedade deltaLink ou na propriedade nextLink na última resposta. Necessário, mas estará vazio na primeira solicitação.

(Substitui o parâmetro de cadeia de caracteres da consulta skipToken na versão de visualização da API do Graph.)
$filterIndica quais tipos de entidade devem ser incluídos na resposta. Opcional. Os tipos de entidade com suporte são: User, Group e Contact. Válido somente quando &ltresourceSet&gt for “directoryObjects”; caso contrário, &ltresourceSet&gt substitui o filtro. Por exemplo, se &ltresourceSet&gt for "users" e o parâmetro $filter também for especificado, somente as alterações para usuários serão retornadas independentemente do que foi especificado no valor do filtro. Se &ltresourceSet&gt for “directoryObjects” e $filter não for especificado, as alterações para todos os tipos de entidade com suporte (User, Group e Contact) serão retornadas.

Para especificar um tipo de entidade única, use um dos seguintes:
  • $filter=isof('Microsoft.WindowsAzure.ActiveDirectory.Contact')
  • $filter=isof('Microsoft.WindowsAzure.ActiveDirectory.User')
  • $filter=isof('Microsoft.WindowsAzure.ActiveDirectory.Group')
Para especificar vários tipos de entidade, use o operador ou; por exemplo, $filter=isof('Microsoft.WindowsAzure.ActiveDirectory.User')%20or%20isof('Microsoft.WindowsAzure.ActiveDirectory.Group').

(Substitui o parâmetro de cadeia de caracteres de consulta objectScope na versão de visualização da API do Graph.)

Importante A partir da versão 1.5, o namespace da API do Graph mudou de Microsoft.WindowsAzure.ActiveDirectory para Microsoft.DirectoryServices. Versões anteriores da API do Graph continuam a usar o namespace anterior; por exemplo, $filter=isof('Microsoft.WindowsAzure.ActiveDirectory.Contact').
$selectEspecifica quais propriedades devem ser incluídas na resposta. Se *$select^ não for especificado, todas as propriedades serão incluídas.

As propriedades podem ser especificadas seja totalmente qualificadas ou não qualificadas. Várias propriedades são delimitadas por vírgulas.
  • Propriedades totalmente qualificadas têm o tipo de entidade especificado; por exemplo, User/displayName. Propriedades totalmente qualificadas DEVEM ser usadas se &ltresourceSet&gt é especificado como “directoryObjects”; por exemplo, https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&deltaLink=&$select=User/displayName,Group/description.
  • Propriedades não qualificadas não têm o tipo de entidade especificado; por exemplo, displayName. Elas só podem ser usadas quando &ltresourceSet&gt é especificado como um valor que não seja “directoryObjects”; por exemplo, https://graph.windows.net/contoso.com/users?api-version=2013-04-05&deltaLink=&$select=displayName,jobTitle.

Observação: os pares de chave/valor na cadeia de caracteres de consulta diferenciam maiúsculas de minúsculas, mas sua ordem não é significativa.

Veja a seguir um exemplo da consulta diferencial mais simples: Ele é usado durante a sincronização inicial.

https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&deltaLink=

Segue abaixo um exemplo de uma solicitação subsequente.

https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&deltaLink=AAABAGCL8z4m%2bc9IJGIzYjFmYzU5LTg0YjgtNDQwMC1hNzE1LWVhOGE3ZTQwZjRmZQBuvX43ACZQT4LRVPug8An6AAABAANIABAfGgAQwAMAJDCHA5AAABAATCkAA44TADQnhAQAIAAAgAHAAwAQAAAA8rLSTyfq5U`

Respostas de consulta diferencial

Esta seção descreve o conteúdo de uma resposta de consulta diferencial que é retornado quando uma solicitação de consulta diferencial é feita. A lista a seguir descreve o conteúdo de uma resposta:

  • Zero a 200 entidades DirectoryObject, cada uma delas contém alterações para um objeto User, Group ou Contact específico.

  • Zero a 3000 entidades DirectoryLinkChange, cada uma delas contém as alterações para um determinado link membro ou gerenciador.

  • Uma propriedade deltaLink ou nextLink. Em ambos os casos, seu valor é uma cadeia de caracteres codificada por URL e que diferencia maiúsculas de minúsculas, que incorpora informações de estado sobre o conjunto de alterações do diretório que foi retornado ao cliente, em relação ao restante das alterações que ocorreram no diretório. Essa cadeia de caracteres (ou token) deve ser incluída no parâmetro de cadeia de caracteres de consulta deltaLink na próxima solicitação de consulta diferencial.

    • Se a propriedade deltaLink for retornada, não haverá mais alterações de diretório deixadas para o aplicativo para serem sincronizadas após essa resposta. O aplicativo pode aguardar algum tempo predeterminado de acordo com seus próprios requisitos para emitir a próxima solicitação de consulta diferencial.

    • Se a propriedade nextLink for retornada, haverá alterações de diretório restantes para o aplicativo para serem sincronizadas após essa resposta. O aplicativo deve emitir a próxima solicitação de consulta diferencial o mais rápido possível.

As respostas são sempre retornadas no formato JSON.

Considerações ao usar a consulta diferencial

A lista a seguir destaca as considerações importantes para aplicativos que usam a consulta diferencial:

  • As alterações retornadas pela consulta diferencial representam o estado dos objetos de diretório no tempo de resposta. Seu aplicativo não deve tratar essas alterações como logs de transação para reprodução.

  • As alterações aparecem na ordem em que elas ocorreram. Os objetos alterados mais recentemente aparecem por último mesmo que o objeto tenha sido atualizado várias vezes. Sua ordem também não é afetada quando o cliente recebe as alterações. Como resultado, é possível para que as alterações sejam apresentadas fora da ordem em comparação com como elas inicialmente ocorreram no diretório.

  • Seu aplicativo precisa estar preparado para repetições, que ocorrem quando a mesma alteração aparece nas respostas subsequentes. Enquanto a consulta diferencial se esforça para reduzir as repetições, elas ainda são possíveis.

  • Seu aplicativo deve estar preparado para lidar com uma alteração de exclusão para um objeto do qual ele não estava ciente.

  • A consulta diferencial pode retornar um link para um objeto de origem ou de destino que ainda não foi retornado por outras respostas.

  • Consulte a seção Recursos de consulta diferencial adicionais abaixo para obter mais informações sobre o uso de cabeçalhos de solicitação para restringir suas consultas para melhorar o desempenho.

Exemplos de solicitação e resposta

Este é um exemplo de uma solicitação de consulta diferencial inicial:

GET https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&$filter=isof('Microsoft.WindowsAzure.ActiveDirectory.User')%20or%20isof('Microsoft.WindowsAzure.ActiveDirectory.Group')%20or%20isof('Microsoft.WindowsAzure.ActiveDirectory.Contact')&deltaLink= HTTP /1.1
Authorization: Bearer eyJ0eXAiOiJKV . . . KUAe1EQ
Host: graph.windows.net

Este é um exemplo de uma solicitação de consulta diferencial incremental:

https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&$filter=isof('Microsoft.WindowsAzure.ActiveDirectory.User')%20or%20isof('Microsoft.WindowsAzure.ActiveDirectory.Group')%20or%20isof('Microsoft.WindowsAzure.ActiveDirectory.Contact')&deltaLink=AAABAGCL8z4m%2bc9IJGIzYjFmYzU5LTg0YjgtNDQwMC1hNzE1LWVhOGE3ZTQwZjRmZQBuvX43ACZQT4LRVPug8An6AAABAANIABAfGgAQwAMAJDCHA5AAABAATCkAA44TADQnhAQAIAAAgAHAAwAQAAAA8rLSTyfq5U
 HTTP /1.1
Authorization: Bearer eyJ0eXAiOiJKV . . . KUAe1EQ
Host: graph.windows.net

Observação: em ambas essas solicitações de exemplo, o parâmetro de consulta $filter é mostrado apenas para fins de demonstração. Como o filtro especifica todos os tipos de destino possíveis para a consulta diferencial (User, Group e Contact), ele pode ser omitido e a consulta retornaria alterações para todos esses tipos de entidade por padrão.

A resposta de exemplo a seguir demonstra o JSON retornado:

{
  "odata.metadata": "https://graph.windows.net/contoso.com/$metadata#directoryObjects",


  # This is the deltaLink to be used for the next query
  "aad.deltaLink": "https://graph.windows.net/contoso.com/directoryObjects?deltaLink=XARBN7ivjcS6QIhSZDQR3OkT15SO1eeY-01BZSS0sOct6sh5oEyqOLLKRVhRmBMLHhePUF... [Truncated]",
  "value": [

    # User object for John Smith
    {
      "odata.type": "Microsoft.WindowsAzure.ActiveDirectory.User",
      "objectType": "User",
      "objectId": "dca803ab-bf26-4753-bf20-e1c56a9c34e2",
      "accountEnabled": true,
      "displayName": "John Smith",
      "givenName": "John",
      "mailNickname": "johnsmith",
      "passwordPolicies": "None",
      "surname": "Smith",
      "usageLocation": "US",
      "userPrincipalName": "johnsmith@contoso.com"
    },

    # Group object for IT Administrators
    {
      "odata.type": "Microsoft.WindowsAzure.ActiveDirectory.Group",
      "objectType": "Group",
      "objectId": "7373b0af-d462-406e-ad26-f2bc96d823d8",
      "description": "IT Administrators",
      "displayName": "Administrators",
      "mailNickname": "Administrators",
      "mailEnabled": false,
      "securityEnabled": true
    },

    # Contact object for Jane Smith
    {
      "odata.type": "Microsoft.WindowsAzure.ActiveDirectory.Contact",
      "objectType": "Contact",
      "objectId": "d711a1f8-21cf-4dc0-834a-5583e5324c44",
      "displayName": "Jane Smith",
      "givenName": "Jane",
      "mail": "johnsmith@contoso.com",
      "mailNickname": "johnsmith",
      "proxyAddresses": [
        "SMTP:janesmith@fabrikam.com"
      ],
      "surname": "Smith"
    },

    # Member link indicating John Smith is a member of IT Admin Group
    {
      "odata.type": "Microsoft.WindowsAzure.ActiveDirectory.DirectoryLinkChange",
      "objectType": "DirectoryLinkChange",
      "objectId": "00000000-0000-0000-0000-000000000000",
      "associationType": "Member",
      "sourceObjectId": "7373b0af-d462-406e-ad26-f2bc96d823d8",
      "sourceObjectType": "Group",
      "sourceObjectUri": "https://graph.windows.net/contoso.com/groups/7373b0af-d462-406e-ad26-f2bc96d823d8",
      "targetObjectId": "dca803ab-bf26-4753-bf20-e1c56a9c34e2",
      "targetObjectType": "User",
      "targetObjectUri": "https://graph.windows.net/contoso.com/users/dca803ab-bf26-4753-bf20-e1c56a9c34e2"
    }
  ]
}

Recursos de consulta diferencial adicionais

As Consultas Diferenciais agora podem retornar apenas as propriedades atualizadas e links - isso permite o processamento mais rápido e cargas reduzidas para chamadas de Consultas Diferenciais. Esta opção é habilitada ao configurar o cabeçalho ocp-aad-dq-include-only-changed-properties para verdadeiro, conforme mostrado neste exemplo.

GET https://graph.windows.net/contoso.com/users?api-version=2013-11-08&deltaLink= furK18V1T….
HTTP /1.1
ocp-aad-dq-include-only-changed-properties : true
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5nl0aEV1T….
Response: 200 OK

Por exemplo, se apenas a propriedade “displayName” do usuário foi alterada. O objeto retornado seria semelhante a este:

{     
          "displayName" : "AnUpdatedDisplayName",
         "objectId" :  "c1bf5c59-7974-4aff-a59a-f8dfe9809b18",
         "objectType" :  "User",
          "odata.type" :  "Microsoft.WindowsAzure.ActiveDirectory.User"
},

Suporte de Sincronização diferencial para sincronizar "agora" - um cabeçalho especial pode ser especificado, solicitando apenas obter um deltaToken atualizado, este token pode ser usado em consultas subsequentes, que retornará somente alterações de “agora”. Aqui está a chamada de exemplo:

GET https://graph.windows.net/contoso.com/users?api-version=2013-11-08&deltaLink= smLYT8V1T…
HTTP /1.1
ocp-aad-dq-include-only-delta-token: true
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5nl0aEV1T….
Response: 200 OK

A resposta conterá o deltaLink, mas não terá os objetos alterados, semelhante ao item a seguir:

{   …  "aad.deltaLink":https://graph.windows.net/contoso.com/users?deltaLink=MRa43......   }

Detectando um item excluído – a resposta pode ser usada para detectar um item excluído. Os objetos excluídos e links excluídos são indicados pela propriedade "aad.isDeleted" com um valor definido para verdadeiro. Isso é necessário para se certificar de que os aplicativos podem aprender sobre a exclusão de objetos e links criados anteriormente.

Recursos adicionais

© 2017 Microsoft