Consulta diferencial | Conceitos da Graph API
Aplica-se a: Graph API | Azure Active Directory
Este tópico descreve a funcionalidade de consulta diferencial do AD Graph API do Azure. Um pedido de consulta diferencial devolve todas as alterações efetuadas para entidades especificadas durante o período de tempo entre dois pedidos consecutivos. Por exemplo, se efetuar uma consulta diferencial pedir uma hora após o pedido de consulta diferencial anterior, serão devolvidas apenas as alterações efetuadas durante essa hora. Esta funcionalidade é especialmente útil quando o arquivo de dados de diretório do inquilino sincronizar com dados de uma aplicação.
Para efetuar um pedido de consulta diferencial para o diretório de um inquilino, a aplicação tem de ser autorizada por inquilino. Para obter mais informações, consulte integrar aplicações com o Azure Active Directory.
Importante
Recomendamos vivamente que utilize Microsoft Graph em vez do AD Graph API do Azure para aceder aos recursos do Azure Active Directory. A nossa esforços de desenvolvimento são agora concentrated no Microsoft Graph e estão a ser planeados sem melhoramentos adicionais para AD Graph API do Azure. Existem um número muito limitado de cenários para o qual AD Graph API do Azure ainda poderá ser apropriado; Para obter mais informações, consulte o Microsoft Graph ou o Azure AD Graph blogue no Dev Center do Office.
Pedidos de consulta diferencial
Esta secção descreve os pedidos de consulta diferencial. Todos os pedidos requerem os seguintes componentes:
Um URL de pedido válido, incluindo o ponto final de gráfico para o inquilino e parâmetros de cadeia de consulta aplicável.
Um cabeçalho de autorização, incluindo um token de acesso válido emitido pelo Azure Active Directory. Para obter mais informações sobre a autenticação para a Graph API, consulte cenários de autenticação para o Azure AD.
URL do pedido de consulta diferencial
O seguinte mostra o formato do URL para o pedido de consulta diferencial; entre parênteses Retos [-] indicar elementos opcionais.
https://graph.windows.net/<tenantId>/<resourceSet>?api-version=<SupportedApiVersion>&deltaLink=<token>&[$filter=isof(<entityType>)]&[$select=<PropertyList>]
O URL é constituído por um segmentos hierárquica seguido por uma série de parâmetros de cadeia de consulta expresso como pares chave-valor.
URL: Os segmentos hierárquicos
| Segmento | Descrição |
|---|---|
| tenantId | O identificador exclusivo do inquilino que a consulta deve ser executada contra. Isto é, normalmente, um dos domínios verificados (verifiedDomains propriedade) do inquilino, mas também pode ser o ID de objeto do inquilino (objectId propriedade). Não maiúsculas e minúsculas. |
| resourceSet | O conjunto específico de recursos de inquilino que deve ser executada em relação a esta consulta. Determina os recursos que são devolvidos em resposta a consulta. Os valores suportados são: "directoryObjects", "utilizadores", "contactos" ou "grupos". Os valores são maiúsculas e minúsculas. |
URL: Parâmetros de cadeia de consulta
| Parâmetro | Descrição |
|---|---|
| api-version | Especifica a versão da API de gráfico com a qual o pedido é emitido. Necessário. A partir da versão 1.5, o valor é expresso como um número de versão numérico; Por exemplo, a api-version = 1.5. Para versões anteriores, o valor é uma cadeia com o formato AAAA-MM-DD; Por exemplo, a api-version = 2013-04-05. (Substitui a utilização de x-ms-dirapi-data-contract-version cabeçalho na versão de pré-visualização de Graph API.) |
| deltaLink | O token devolvido no deltaLink propriedade ou o nextLink propriedade na última resposta. Necessário, mas estará vazio, o primeiro pedido. (Substitui o skipToken consultar o parâmetro de cadeia na versão de pré-visualização de Graph API.) |
| $filter | Indica que tipos de entidade devem ser incluídos na resposta. Opcional. Os tipos de entidade suportados são: contacto, grupo e utilizador. Apenas válida quando & ltresourceSet & gt é "directoryObjects"; caso contrário, & ltresourceSet & gt substitui o filtro. Por exemplo, se & ltresourceSet & gt é "utilizadores" e o $filter parâmetro também for especificado, apenas as alterações para os utilizadores serão devolvidas, independentemente do que é especificado no valor de filtro. Se & ltresourceSet & gt é "directoryObjects" e $filter não é especificado, são devolvidas as alterações para todos os tipos de entidade suportados (utilizador, grupo e contacte). Para especificar um tipo de entidade única, utilize um dos seguintes:
$filter=isof('Microsoft.WindowsAzure.ActiveDirectory.User')%20or%20isof('Microsoft.WindowsAzure.ActiveDirectory.Group'). (Substitui o objectScope consultar o parâmetro de cadeia na versão de pré-visualização de Graph API.) Importante a partir da versão 1.5, a Graph API o espaço de nomes é alterado de Microsoft.WindowsAzure.ActiveDirectory para Microsoft.DirectoryServices. Versões anteriores da Graph API continuam a utilizar o espaço de nomes anterior; Por exemplo, $filter=isof('Microsoft.WindowsAzure.ActiveDirectory.Contact'). |
| $select | Especifica as propriedades que devem ser incluídas na resposta. Se * $select ^ não for especificado, todas as propriedades estão incluídas. Propriedades podem ser especificadas completamente qualificado ou não qualificado. Várias propriedades são delimitadas por vírgulas.
|
Tenha em atenção: os pares chave-valor na cadeia de consulta são maiúsculas e minúsculas, mas a sua ordem não é significativa.
Segue-se um exemplo da consulta diferencial mais simples. Isto é utilizado durante a sincronização inicial.
https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&deltaLink=
Segue-se um exemplo de um pedido subsequente.
https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&deltaLink=AAABAGCL8z4m%2bc9IJGIzYjFmYzU5LTg0YjgtNDQwMC1hNzE1LWVhOGE3ZTQwZjRmZQBuvX43ACZQT4LRVPug8An6AAABAANIABAfGgAQwAMAJDCHA5AAABAATCkAA44TADQnhAQAIAAAgAHAAwAQAAAA8rLSTyfq5U`
Respostas de consulta diferencial
Esta secção descreve o conteúdo de uma resposta de consulta diferencial que são devolvidos quando é efetuado um pedido de consulta diferencial. A lista seguinte descreve os conteúdos de uma resposta:
Zero para 200 DirectoryObject entidades, cada um dos quais contém alterações para específico utilizador, grupo, ou contacte objeto.
Até 3000 DirectoryLinkChange entidades, cada um dos quais contém alterações para específico membro ou manager ligação.
É um deltaLink ou um nextLink propriedade. Em ambos os casos, o respetivo valor é uma cadeia de maiúsculas e minúsculas, com codificação URL que o atacante incorpora informações de estado sobre o conjunto de alterações de diretório que foi devolvido para o cliente, no que respeita à restantes alterações ocorridas no diretório. Esta cadeia (ou token) deve ser incluído o deltaLink parâmetro de cadeia no pedido de consulta diferencial seguinte de consulta.
Se o deltaLink propriedade é devolvido, não foram efetuadas alterações de diretório mais à esquerda para a aplicação ao sincronizar após esta resposta. A aplicação pode aguardar algum tempo, de acordo com os seus próprios requisitos para emitir o pedido de consulta diferencial seguinte predeterminado.
Se o nextLink propriedade é devolvida, existem alterações de diretório restante para a aplicação ao sincronizar após esta resposta. A aplicação deve emitir o pedido de consulta diferencial seguinte na sua conveniência mais antigo.
As respostas são devolvidas sempre no formato JSON.
Considerações quando utilizar consulta diferencial
A lista seguinte destaca considerações importantes para aplicações que utilizam diferencial consulta:
As alterações devolvidas pela consulta diferencial representam o estado dos objetos de diretório no momento da resposta. A aplicação não deve tratar estas alterações como registos de transações para repetição.
As alterações são apresentados pela ordem em que ocorreram. Os objetos mais recentemente alterados pela última vez aparecem mesmo que o objeto foi atualizado várias vezes. Sua ordem também não é afetada por quando o cliente recebeu as alterações. Como resultado, é possível que as alterações a ser apresentados fora de ordem comparada com a forma como ocorreram inicialmente no diretório.
A aplicação deve estar preparada para repetições, o que ocorrer quando a mesma alteração aparece no respostas subsequentes. Enquanto consulta diferencial efetua um melhor esforço para reduzir as repetições, são ainda possíveis.
A aplicação tem de ser preparada para processar uma alteração de eliminação para um objeto não estava ciente.
Consulta diferencial pode devolver uma ligação a um objeto de origem ou de destino que ainda não foi devolvido por outras respostas.
Consulte o funcionalidades adicionais consulta diferencial secção abaixo para obter mais informações sobre como utilizar os cabeçalhos de pedido para limitar as suas consultas para melhorar o desempenho.
Exemplos de pedido e resposta
Segue-se um exemplo de um pedido 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
Segue-se um exemplo de um pedido de consulta diferencial incrementais:
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
Tenha em atenção: em ambos estes pedidos de exemplo, o $filter parâmetro de consulta é apresentado para fins de demonstração. Porque o filtro especifica todos os tipos de destino possível para a consulta diferencial (utilizador, grupo e contacte), pode ser omitido e a consulta devolvam alterações para todos estes tipos de entidade, por predefinição.
A resposta de exemplo seguinte demonstra o JSON devolvido:
{
"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"
}
]
}
Funcionalidades de consulta diferencial adicionais
Consultas diferenciais agora podem devolver apenas propriedades atualizadas e ligações – Isto permite que o processamento mais rápido e payloads reduzidas para chamadas de consulta diferencial. Esta opção está ativada por definição de cabeçalho ocp-aad-dq-include-only-changed-properties como 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 utilizador foi alterada. O objeto devolvido é semelhante a isto:
{
"displayName" : "AnUpdatedDisplayName",
"objectId" : "c1bf5c59-7974-4aff-a59a-f8dfe9809b18",
"objectType" : "User",
"odata.type" : "Microsoft.WindowsAzure.ActiveDirectory.User"
},
Suporte de sincronização diferencial para sincronizar a partir de "agora" -um cabeçalho especial pode ser especificado, a solicitar a obter só pode ser utilizado um deltaToken atualizado, este token em consultas subsequentes, que irá devolver apenas as alterações a partir de "agora". Segue-se 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 irá conter o deltaLink, mas não terão os objetos alterados, semelhantes a isto:
{ … "aad.deltaLink":https://graph.windows.net/contoso.com/users?deltaLink=MRa43...... }
Detetar um item eliminado – a resposta também pode ser utilizada para detetar um item eliminado. Objetos eliminados e eliminadas ligações são indicadas pela propriedade de "aad.isDeleted" com um valor definido para verdadeiro; Isto é necessário para se certificar de que aplicações podem saber mais sobre a eliminação de objetos criados anteriormente e ligações.