Table of contents

Consulta diferencial | Conceitos da API do GraphDifferential query | Graph API concepts

Jimaco Brannian|Última Atualização: 19/06/2018
|
2 Colaboradores

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

Este tópico discute o recurso de consulta diferencial da API do Azure AD Graph.This topic discusses the differential query feature of Azure AD Graph API.Uma solicitação de consulta diferencial retorna todas as alterações feitas para entidades especificas durante o tempo entre as duas solicitações consecutivas.A differential query request returns all changes made to specified entities during the time between two consecutive requests.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.For example, if you make a differential query request an hour after the previous differential query request, only the changes made during that hour will be returned.Essa funcionalidade é especialmente útil quando estiver sincronizando dados de diretório do locatário com o armazenamento de dados de um aplicativo.This functionality is especially useful when synchronizing tenant directory data with an application’s data store.

Para fazer uma solicitação de consulta diferencial para o diretório de um locatário, seu aplicativo deve ser autorizado pelo locatário.To make a differential query request to a tenant’s directory, your application must be authorized by the tenant.Para obter mais informações, consulte Integrating Applications with Azure Active Directory (Integrando Aplicativos com o Azure Active Directory).For more information, see Integrating Applications with Azure Active Directory.

Importante

Recomendamos que você use o Microsoft Graph em vez da API do Azure AD Graph para acessar os recursos do Azure Active Directory.We strongly recommend that you use Microsoft Graph instead of Azure AD Graph API to access Azure Active Directory resources.Nossos esforços de implantação agora estão concentrados no Microsoft Graph e não há planos de novos aprimoramento para a API do Azure AD Graph.Our development efforts are now concentrated on Microsoft Graph and no further enhancements are planned for Azure AD Graph API.Há um número muito limitado de cenários para os quais a API do Azure AD Graph ainda pode ser adequada. Para saber mais, confira a postagem do blog sobre Microsoft Graph ou Azure AD Graph no Centro de Desenvolvimento do Office.There are a very limited number of scenarios for which Azure AD Graph API might still be appropriate; for more information, see the Microsoft Graph or the Azure AD Graph blog post in the Office Dev Center.

Solicitações de consulta diferencial Differential query requests

Esta seção descreve as solicitações de consulta diferencial.This section describes differential query requests.Todas as solicitações requerem os seguintes componentes:All requests require the following components:

  • 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.A valid request URL, including the Graph endpoint for the tenant and applicable query string parameters.

  • Um cabeçalho de autorização, incluindo um token de acesso válido emitido pelo Active Directory do Azure.An authorization header, including a valid access token issued by Azure Active Directory.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).For more information on authenticating to the Graph API, see Authentication Scenarios for Azure AD.

URL de solicitação de consulta diferencialDifferential query request URL

O exemplo a seguir mostra o formato da URL de solicitação de consulta diferencial; colchetes [] indicam elementos opcionais.The following shows the format of the URL for differential query request; square brackets [] indicate optional elements.

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.The URL is made up of a hierarchical segments followed by a series of query string parameters expressed as key-value pairs.

URL: segmentos hierárquicosURL: Hierarchical segments

SegmentoSegmentDescriçãoDescription
tenantIdtenantIdO identificador exclusivo do locatário no qual a consulta deve ser executada.The unique identifier of the tenant that the query should be executed against.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).This is typically one of the verified domains (verifiedDomains property) of the tenant, but it can also be the tenant’s object ID (objectId property).Não diferencia maiúsculas de minúsculas.Not case-sensitive.
resourceSetresourceSetO conjunto de recursos de locatário específico no qual essa consulta deve ser executada.The specific set of tenant resources this query should be executed against.Determina quais recursos são retornados na resposta da consulta.Determines what resources are returned in the query response.Os valores com suporte são: “directoryObjects”, “users”, “contacts” ou “groups”.Supported values are: “directoryObjects”, “users”, “contacts” or “groups”.Os valores diferenciam maiúsculas de minúsculas.Values are case-sensitive.

URL: parâmetros de cadeia de caracteres de consultaURL: Query string parameters

ParâmetroParameterDescriçãoDescription
api-versionapi-versionEspecifica a versão da API do Graph na qual a solicitação é emitida.Specifies the version of the Graph API against which the request is issued.Obrigatório.Required.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.Beginning with version 1.5, the value is expressed as a numeric version number; for example, 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.For previous versions, the value is a string of the form YYYY-MM-DD; for example, 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.)(Replaces the use of x-ms-dirapi-data-contract-version header in the preview version of Graph API.)
deltaLinkdeltaLinkO token retornado na propriedade deltaLink ou na propriedade nextLink na última resposta.The token returned in either the deltaLink property or the nextLink property in the last response.Necessário, mas estará vazio na primeira solicitação.Required, but will be empty on the first request.

(Substitui o parâmetro de cadeia de caracteres da consulta skipToken na versão de visualização da API do Graph.)(Replaces the skipToken query string parameter in the preview version of Graph API.)
$filter$filterIndica quais tipos de entidade devem ser incluídos na resposta.Indicates which entity types should be included in the response.Opcional.Optional.Os tipos de entidade com suporte são: User, Group e Contact.The supported entity types are: User, Group and Contact.Válido somente quando &ltresourceSet&gt for “directoryObjects”; caso contrário, &ltresourceSet&gt substitui o filtro.Only valid when &ltresourceSet&gt is “directoryObjects”; otherwise, &ltresourceSet&gt overrides the filter.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.For example, if &ltresourceSet&gt is “users”, and the $filter parameter is also specified, only changes for users will be returned regardless of what is specified in the filter value.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.If &ltresourceSet&gt is “directoryObjects” and $filter is not specified, changes for all of the supported entity types (User, Group, and Contact) are returned.

Para especificar um tipo de entidade única, use um dos seguintes:To specify a single entity type, use one of the following:
  • $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').To specify multiple entity types, use the or operator; for example, $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.)(Replaces the objectScope query string parameter in the preview version of Graph API.)

Importante A partir da versão 1.5, o namespace da API do Graph mudou de Microsoft.WindowsAzure.ActiveDirectory para Microsoft.DirectoryServices.Important Beginning with version 1.5, the Graph API namespace is changed from Microsoft.WindowsAzure.ActiveDirectory to Microsoft.DirectoryServices.Versões anteriores da API do Graph continuam a usar o namespace anterior; por exemplo, $filter=isof('Microsoft.WindowsAzure.ActiveDirectory.Contact').Earlier versions of the Graph API continue to use the previous namespace; for example, $filter=isof('Microsoft.WindowsAzure.ActiveDirectory.Contact').
$select$selectEspecifica quais propriedades devem ser incluídas na resposta.Specifies which properties should be included in the response.Se *$select^ não for especificado, todas as propriedades serão incluídas.If *$select^ is not specified, all properties are included.

As propriedades podem ser especificadas seja totalmente qualificadas ou não qualificadas.Properties can be specified either fully qualified or non-qualified.Várias propriedades são delimitadas por vírgulas.Multiple properties are delimited by commas.
  • Propriedades totalmente qualificadas têm o tipo de entidade especificado; por exemplo, User/displayName.Fully qualified properties have the entity type specified; for example, 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.Fully qualified properties MUST be used if &ltresourceSet&gt is specified as “directoryObjects”; for example, 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.Non-qualified properties do not have the entity type specified; for example, 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.They can only be used when &ltresourceSet&gt is specified as a value other than “directoryObjects”; for example, 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.Note: The key-value pairs in the query string are case-sensitive, but their order is not significant.

Veja a seguir um exemplo da consulta diferencial mais simples:The following is an example of the simplest differential query.Ele é usado durante a sincronização inicial.This is used during initial sync.

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

Segue abaixo um exemplo de uma solicitação subsequente.The following is an example of a subsequent request.

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

Respostas de consulta diferencial Differential query responses

Esta seção descreve o conteúdo de uma resposta de consulta diferencial que é retornado quando uma solicitação de consulta diferencial é feita.This section describes the contents of a differential query response that is returned when a differential query request is made.A lista a seguir descreve o conteúdo de uma resposta:The following list describes the contents of a response:

  • Zero a 200 entidades DirectoryObject, cada uma delas contém alterações para um objeto User, Group ou Contact específico.Zero to 200 DirectoryObject entities, each of which contains changes for a specific User, Group, or Contact object.

  • Zero a 3000 entidades DirectoryLinkChange, cada uma delas contém as alterações para um determinado link membro ou gerenciador.Zero to 3000 DirectoryLinkChange entities, each of which contains changes for a specific member or manager link.

  • Uma propriedade deltaLink ou nextLink.Either a deltaLink or a nextLink property.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.In either case, its value is a case-sensitive, URL-encoded string that embeds state information about the set of directory changes that have been returned to the client, with respect to remaining changes that have occurred in the directory.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.This string (or token) should be included in the deltaLink query string parameter in the next differential query request.

    • 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.If the deltaLink property is returned, there are no more directory changes left for the application to synchronize after this response.O aplicativo pode aguardar algum tempo predeterminado de acordo com seus próprios requisitos para emitir a próxima solicitação de consulta diferencial.The application can wait for some predetermined time according to its own requirements to issue the next differential query request.

    • Se a propriedade nextLink for retornada, haverá alterações de diretório restantes para o aplicativo para serem sincronizadas após essa resposta.If the nextLink property is returned, there are directory changes remaining for the application to synchronize after this response.O aplicativo deve emitir a próxima solicitação de consulta diferencial o mais rápido possível.The application should issue the next differential query request at its earliest convenience.

As respostas são sempre retornadas no formato JSON.Responses are always returned in JSON format.

Considerações ao usar a consulta diferencial Considerations when using differential query

A lista a seguir destaca as considerações importantes para aplicativos que usam a consulta diferencial:The following list highlights important considerations for applications that use differential query:

  • As alterações retornadas pela consulta diferencial representam o estado dos objetos de diretório no tempo de resposta.Changes returned by differential query represent the state of the directory objects at the time of the response.Seu aplicativo não deve tratar essas alterações como logs de transação para reprodução.Your application must not treat these changes as transaction logs for replay.

  • As alterações aparecem na ordem em que elas ocorreram.Changes appear in the order in which they occurred.Os objetos alterados mais recentemente aparecem por último mesmo que o objeto tenha sido atualizado várias vezes.The most-recently changed objects appear last even if the object was updated multiple times.Sua ordem também não é afetada quando o cliente recebe as alterações.Their order is also not affected by when the client received the changes.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.As a result, it is possible for changes to be presented out of order compared to how they initially occurred in the directory.

  • Seu aplicativo precisa estar preparado para repetições, que ocorrem quando a mesma alteração aparece nas respostas subsequentes.Your application must be prepared for replays, which occur when the same change appears in subsequent responses.Enquanto a consulta diferencial se esforça para reduzir as repetições, elas ainda são possíveis.While differential query makes a best effort to reduce replays, they are still possible.

  • Seu aplicativo deve estar preparado para lidar com uma alteração de exclusão para um objeto do qual ele não estava ciente.Your application must be prepared to handle a deletion change for an object it was not aware of.

  • A consulta diferencial pode retornar um link para um objeto de origem ou de destino que ainda não foi retornado por outras respostas.Differential query can return a link to a source or target object that has not yet been returned by other responses.

  • 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.See the Additional differential query features section below for more information on using request headers to constrain your queries to improve performance.

Exemplos de solicitação e resposta Request and response examples

Este é um exemplo de uma solicitação de consulta diferencial inicial:The following is an example of an initial differential query request:

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:The following is an example of an incremental differential query request:

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.Note: In both of these sample requests, the $filter query parameter is shown for demonstration purposes only.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.Because the filter specifies all of the possible target types for the differential query (User, Group, and Contact), it could be omitted and the query would return changes for all of these entity types by default.

A resposta de exemplo a seguir demonstra o JSON retornado:The following example response demonstrates the returned JSON:

{
  "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 Additional differential query features

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.Differential Queries can now return only updated properties and links – this allows faster processing and reduced payloads for Differential Query calls.Esta opção é habilitada ao configurar o cabeçalho ocp-aad-dq-include-only-changed-properties para verdadeiro, conforme mostrado neste exemplo.This option is enabled by setting the header ocp-aad-dq-include-only-changed-properties to true as shown in this example.

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.For example if only the “displayName” property of user has changed.O objeto retornado seria semelhante a este:The returned object would be similar to this:

{     
          "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”.Differential Sync support to sync from “now” - a special header can be specified, requesting to only get an up-to-date deltaToken, this token can be used in subsequent queries, which will return only changes from “now”.Aqui está a chamada de exemplo:Here’s the example call:

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:The response will contain the deltaLink, but will not have the changed object(s), similar to this:

{   …  "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.Detecting a deleted item – the response can also be used to detect a deleted item.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.Deleted objects and deleted links are indicated by the "aad.isDeleted" property with a value set to true; this is necessary to make sure applications can learn about the deletion of previously created objects and links.

Recursos adicionais Additional resources

© 2018 Microsoft