Exportar (0) Imprimir
Expandir Tudo

Consulta diferencial do Azure AD Graph

Atualizado: abril de 2014

Este tópico aborda consultas diferenciais que podem ser feitas para o Azure Active Directory Graph. Uma solicitação de consulta diferencial retorna todas as alterações feitas nas entidades especificadas durante o tempo entre duas solicitações consecutivas. Por exemplo, se você fizer uma solicitação de consulta diferencial uma hora após a solicitação da consulta diferencial anterior, apenas as alterações feitas durante essa hora serão retornadas. Essa funcionalidade é especialmente útil ao sincronizar dados do diretório de locatário com armazenamento de dados de um aplicativo.

Para fazer uma solicitação de consulta diferencial para o diretório de um locatário, o aplicativo deve ser autorizado pelo locatário. Para obter mais informações, consulte Getting Started With Azure Active Directory Graph.

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

  • Um URI de solicitação válido, incluindo o ponto de extremidade Graph para o locatário e parâmetros de cadeia de caracteres de consulta aplicável.

  • Um cabeçalho de autorização, incluindo um token válido do Azure AD Access Control Service. Para obter mais informações sobre a autenticação no Graph, consulte Authenticating to Azure AD Graph.

Veja a seguir o formato do URI para 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>]

O URI é composto de segmentos hierárquicos, seguidos por uma série de parâmetros de cadeia de caracteres de consulta expressas como pares de valor de chave.

URI: Segmentos hierárquicos

Segmento Descrição

<tenantId>

O identificador exclusivo do locatário em relação ao qual a consulta deve ser executada. Esse identificador normalmente é um dos domínios verificados (propriedade verifiedDomains) do locatário, mas também pode ser a ID de objeto do locatário (propriedade objectId). Não diferencia maiúsculas de minúsculas.

<resourceSet>

O conjunto específico de recursos de locatário em relação ao qual essa consulta deve ser executada. Determina quais recursos são retornados na resposta à consulta. Os valores suportados são: “directoryObjects”, “users”, “contacts” ou “groups”. Os valores diferenciam maiúsculas de minúsculas.

URI: Parâmetros de cadeia de caracteres de consulta

Parâmetro Descrição

api-version

Especifica a versão da API Gráfica em relação à qual a solicitação é emitida. Obrigatório. 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 prévia da API Gráfica.)

deltaLink

Esse token é retornado na propriedade deltaLink e na propriedade nextLink na última resposta. Obrigatório, mas estará vazio na primeira solicitação.

(Substitui o parâmetro de cadeia de caracteres de consulta skipToken na versão prévia da API Gráfica.)

$filter

Indica quais tipos de entidade devem ser incluídos na resposta. Opcional. Os tipos de entidade suportados são: User, Group e Contact. Válido somente quando <resourceSet> for “directoryObjects”. Caso contrário, <resourceSet> substitui o filtro. Por exemplo, se <resourceSet> for "users” e o parâmetro $filter também for especificado, somente as alterações para os usuários serão devolvidas, independentemente do valor especificado do filtro. Se <resourceSet> for “directoryObjects” e $filter não for especificado, as alterações para todos os tipos de entidade suportados (usuário, grupo e contato) serão retornadas.

Para especificar um único tipo de entidade, use um dos seguintes procedimentos:

  • $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, utilize 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 prévia da API Gráfica.)

$select

Especifica 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 como totalmente qualificadas ou não-qualificadas. Várias propriedades são delimitadas por vírgulas.

  • As propriedades totalmente qualificadas têm o tipo de entidade especificado; por exemplo, User/displayName. As propriedades totalmente qualificadas devem ser usadas se <resourceSet> for especificado como “directoryObjects”; por exemplo, https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&deltaLink=&$select=User/displayName,Group/description.

  • As propriedades não-qualificadas não têm o tipo de entidade especificado; por exemplo, displayName. Eles só podem ser utilizados quando <resourceSet> for especificado como um valor diferente de “directoryObjects”; por exemplo, https://graph.windows.net/contoso.com/users?api-version=2013-04-05&deltaLink=&$select=displayName,jobTitle.

noteObservação
Os pares valores-chave 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: Isso é 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

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

  • Entidades de zero a 200 DirectoryObject, cada uma das quais contém alterações para um objeto específico User ou Grupo ou Contato.

  • Entidades de zero a 3000 DirectoryLinkChange, cada uma das quais contém alterações para um link específico Membro ou Gerenciador.

  • Um propriedade deltaLink ou nextLink. Nos dois casos, seu valor é uma cadeia de caracteres que diferencia maiúsculas de minúsculas de URL codificada que incorpora informações de estado sobre o conjunto de alterações de diretório que foram retornadas para o cliente, em relação às alterações restantes que ocorreram no diretório. Esta 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 restantes a sincronizar para o aplicativo após essa resposta. O aplicativo pode esperar por um tempo pré-determinado de acordo com os seus próprios requisitos para emitir a próxima solicitação de consulta diferencial.

    • Se a propriedade nextLink for retornada, não haverá alterações de diretório restantes a sincronizar para o aplicativo após essa resposta. O aplicativo deve emitir a próxima solicitação de consulta diferencial em sua primeira oportunidade.

As respostas são sempre retornadas em formato JSON.

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

  • As alterações retornadas por consulta diferencial representam o estado dos objetos de diretório no momento da 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 ocorreram. Os objetos alterados mais recentemente aparecem por último mesmo se o objeto tiver sido atualizado várias vezes. A sua ordem também não será afetada quando o cliente receber as alterações. Como resultado, é possível que as alterações sejam apresentadas fora de ordem em comparação ao modo em que ocorreram inicialmente no diretório.

  • Seu aplicativo deve estar preparado para reproduções, que ocorrem quando a mesma alteração aparece nas respostas subsequentes. Enquanto a consulta diferencial tentar da melhor maneira reduzir reproduções, eles ainda são possíveis.

  • Seu aplicativo deve estar preparado para lidar com uma alteração de eliminação para um objeto que ele desconhecia.

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

Veja a seguir um exemplo da 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

Veja a seguir um exemplo da 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
noteObservação
Nas duas solicitações de exemplo, o parâmetro de consulta $filter é mostrado para fins de demonstração somente. 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"
    }
  ]
}

Consulte também

Mostrar:
© 2014 Microsoft