Consulta diferencial | Conceitos da API do Graph
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
Recomendamos que você use o Microsoft Graph em vez da API do Azure AD Graph para acessar os recursos do Azure Active Directory. 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. 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.
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
| Segmento | Descrição |
|---|---|
| tenantId | O 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. |
| resourceSet | O 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âmetro | Descrição |
|---|---|
| api-version | Especifica 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.) |
| deltaLink | O 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.) |
| $filter | Indica 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 <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 usuários serão retornadas independentemente do que foi especificado no valor do filtro. Se <resourceSet> 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.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'). |
| $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 seja totalmente qualificadas ou não qualificadas. Várias propriedades são delimitadas por vírgulas.
|
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.