Consulta diferencial | Conceptos de Graph API
_ Se aplica a: Graph API | Azure Active Directory_
En este tema se describe la característica de consulta diferencial de la API de Azure AD Graph. Una solicitud de consulta diferencial devuelve todos los cambios realizados en entidades específicas durante el tiempo entre dos solicitudes consecutivas. Por ejemplo, si realizas una consulta diferencial una hora después de la solicitud de consulta diferencial anterior, solo se devolverán los cambios realizados durante esa hora. Esta funcionalidad es especialmente útil al sincronizar datos del directorio de inquilino con el almacén de datos de una aplicación.
Para realizar una solicitud de consulta diferencial en un directorio de inquilino, el inquilino debe autorizar a la aplicación. Para más información, consulte Integración de aplicaciones con Azure Active Directory.
Importante
Se recomienda encarecidamente que use Microsoft Graph en lugar de la API de Azure AD Graph para acceder a recursos de Azure Active Directory. Nuestros esfuerzos de desarrollo se concentran ahora en Microsoft Graph y no están previstas mejoras adicionales para la API de Azure AD Graph. Hay un número muy limitado de escenarios para los que la API de Azure AD Graph todavía podría ser adecuada; para más información, vea la entrada del blog Microsoft Graph o Azure AD Graph en el centro de desarrollo de Office.
Solicitudes de consulta diferencial
Esta sección describe las solicitudes de consulta diferencial. Todas las solicitudes necesitan los siguientes componentes:
Una URL de solicitud válida, incluido el extremo de Graph para el inquilino y los parámetros de cadena de consulta correspondientes.
Un encabezado de autorización, incluido un token de acceso válido emitido por Azure Active Directory. Para obtener más información sobre la autenticación con Graph API, consulte Escenarios de autenticación para Azure AD.
Dirección URL de solicitud de consulta diferencial
A continuación se muestra el formato de la URL de solicitud de consulta diferencial; los corchetes [] indican elementos opcionales.
https://graph.windows.net/<tenantId>/<resourceSet>?api-version=<SupportedApiVersion>&deltaLink=<token>&[$filter=isof(<entityType>)]&[$select=<PropertyList>]
La URL se compone de segmentos jerárquicos seguidos de una serie de parámetros de cadena de consulta expresados como pares de clave-valor.
Dirección URL: Segmentos jerárquicos
| Segmento | Descripción |
|---|---|
| tenantId | El identificador único del inquilino con respecto al cual se ejecuta la consulta. Normalmente es uno de los dominios comprobados (propiedad verifiedDomains) del inquilino, pero también puede ser el identificador de objeto del inquilino (propiedad objectId). No distingue mayúsculas de minúsculas. |
| resourceSet | El conjunto específico de recursos de inquilino con respecto al cual se debe ejecutar la consulta. Determina qué recursos se devuelven en la respuesta de la consulta. Los valores admitidos son: “directoryObjects”, “users”, “contacts” o “groups”. Los valores distinguen mayúsculas de minúsculas. |
Dirección URL: Parámetros de cadena de consulta
| Parámetro | Descripción |
|---|---|
| api-version | Especifica la versión de Graph API con la que se emite la solicitud. Obligatorio. A partir de la versión 1.5, el valor se expresa como un número de versión numérico; por ejemplo, api-version = 1.5. Para las versiones anteriores, el valor es una cadena con la forma AAAA-MM-DD; por ejemplo, api-version = 2013-04-05. (Reemplaza el uso del encabezado x-ms-dirapi-data-contract-version en la versión preliminar de Graph API). |
| deltaLink | El token devuelto en la propiedad deltaLink o en la propiedad nextLink en la última respuesta. Obligatorio, pero estará vacío en la primera solicitud. (Reemplaza el parámetro de cadena de consulta skipToken en la versión preliminar de Graph API). |
| $filter | Indica qué tipos de entidad deben estar incluidos en la respuesta. Opcional. Los tipos de entidad admitidos son: User, Group y Contact. Solo es válido cuando <resourceSet> es “directoryObjects”; de lo contrario, <resourceSet> invalida el filtro. Por ejemplo, si <resourceSet> es “users” y el parámetro $filter también está especificado, solo se devolverán los cambios de usuarios independientemente de lo que se especifique en el valor del filtro. Si <resourceSet> es “directoryObjects” y $filter no está especificado, se devuelven los cambios de todos los tipos de entidad admitidos (User, Group y Contact). Para especificar un solo tipo de entidad, usa una de las siguientes opciones:
$filter=isof('Microsoft.WindowsAzure.ActiveDirectory.User')%20or%20isof('Microsoft.WindowsAzure.ActiveDirectory.Group'). (Reemplaza el parámetro de cadena de consulta objectScope en la versión preliminar de Graph API). Importante A partir de la versión 1.5, el espacio de nombres de Graph API cambia de Microsoft.WindowsAzure.ActiveDirectory a Microsoft.DirectoryServices. Las versiones anteriores de Graph API seguirán usando el espacio de nombres anterior; por ejemplo, $filter=isof('Microsoft.WindowsAzure.ActiveDirectory.Contact'). |
| $select | Especifica qué propiedades se deben incluir en la respuesta. Si no está especificado *$select^, se incluyen todas las propiedades. Las propiedades se pueden especificar como completamente cualificadas o no cualificadas. Varias propiedades se delimitan por comas.
|
Nota: Los pares de clave-valor en la cadena de consulta distinguen mayúsculas de minúsculas pero su orden no es significativo.
A continuación se muestra un ejemplo de la consulta diferencial más sencilla. Esta se usa durante la sincronización inicial.
https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&deltaLink=
A continuación se muestra un ejemplo de una solicitud posterior.
https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&deltaLink=AAABAGCL8z4m%2bc9IJGIzYjFmYzU5LTg0YjgtNDQwMC1hNzE1LWVhOGE3ZTQwZjRmZQBuvX43ACZQT4LRVPug8An6AAABAANIABAfGgAQwAMAJDCHA5AAABAATCkAA44TADQnhAQAIAAAgAHAAwAQAAAA8rLSTyfq5U`
Respuestas de consulta diferencial
Esta sección describe el contenido de una respuesta de consulta diferencial que se devuelve cuando se realiza una solicitud de consulta diferencial. En la lista siguiente se describe el contenido de una respuesta:
De cero a 200 entidades DirectoryObject, cada una de las cuales contiene cambios de un objeto User, Group o Contact específico.
De cero a 3000 entidades DirectoryLinkChange, cada una de las cuales contiene cambios de un vínculo Member o Manager específico.
Una propiedad deltaLink o nextLink. En cualquier caso, su valor es una cadena con codificación URL que distingue mayúsculas de minúsculas y que incrusta información de estado sobre el conjunto de cambios del directorio que se han devuelto al cliente, en relación con los cambios restantes que se han producido en el directorio. Esta cadena (o token) se debe incluir en el parámetro de cadena de consulta deltaLink en la siguiente solicitud de consulta diferencial.
Si se devuelve la propiedad deltaLink, no quedan más cambios en el directorio para que los sincronice la aplicación después de esta respuesta. La aplicación puede esperar un tiempo predeterminado según sus propios requisitos para emitir la siguiente solicitud de consulta diferencial.
Si se devuelve la propiedad nextLink, hay cambios en el directorio pendientes para que la aplicación los sincronice después de esta respuesta. La aplicación debe emitir la siguiente solicitud de consulta diferencial con la mayor brevedad posible.
Las respuestas siempre se devuelven en formato JSON.
Consideraciones al usar una consulta diferencial
La siguiente lista resalta consideraciones importantes para aplicaciones que usan la consulta diferencial:
Los cambios devueltos por la consulta diferencial representan el estado de los objetos del directorio en el momento de la respuesta. La aplicación no debe tratar estos cambios como registros de transacción para la reproducción.
Los cambios aparecen en el orden en el que se produjeron. Los objetos modificados más recientes aparecen los últimos incluso si el objeto se actualizó varias veces. Su orden tampoco se ve afectado por el momento en que el cliente recibió los cambios. En consecuencia, es posible que los cambios se presenten desordenados en relación con la manera en que ocurrieron inicialmente en el directorio.
Su aplicación debe estar preparada para las reproducciones, que ocurren cuando aparece el mismo cambio en respuestas posteriores. Si bien una consulta diferencial hace lo posible por reducir las reproducciones, estas todavía pueden tener lugar.
Su aplicación debe estar preparada para tratar un cambio de eliminación de un objeto del que no tenía constancia.
La consulta diferencial puede devolver un vínculo a un objeto de origen o de destino que aún no ha sido devuelto por otras respuestas.
Consulte la sección Características adicionales de consulta diferencial, a continuación, para obtener más información sobre el uso de encabezados de solicitud para restringir las consultas y mejorar el rendimiento.
Ejemplos de solicitud y respuesta
A continuación se muestra un ejemplo de una solicitud de consulta diferencial:
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
A continuación se muestra un ejemplo de una solicitud 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
Nota: En ambas solicitudes de ejemplo, el parámetro de consulta $filter se muestra únicamente a efectos de demostración. Puesto que el filtro especifica todos los tipos de destino posibles para la consulta diferencial (User, Group y Contact), este se podría omitir y la consulta devolvería cambios de todos esos tipos de entidad de manera predeterminada.
La siguiente respuesta de ejemplo muestra el JSON devuelto:
{
"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"
}
]
}
Características adicionales de consulta diferencial
Ahora, las consultas diferenciales pueden devolver solamente propiedades y vínculos actualizados: esto permite realizar un procesamiento más rápido y reducir las cargas de las llamadas de consulta diferencial. Esta opción se habilita estableciendo el encabezado ocp-aad-dq-include-only-changed-properties como verdadero, como se muestra en este ejemplo.
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 ejemplo, si solo ha cambiado la propiedad “displayName” del usuario. El objeto devuelto sería similar al siguiente:
{
"displayName" : "AnUpdatedDisplayName",
"objectId" : "c1bf5c59-7974-4aff-a59a-f8dfe9809b18",
"objectType" : "User",
"odata.type" : "Microsoft.WindowsAzure.ActiveDirectory.User"
},
Compatibilidad con la sincronización diferencial para sincronizar desde "ahora": puede especificarse un encabezado especial que solicite solamente la obtención de un deltaToken actualizado. Este token puede usarse en las consultas posteriores, lo que devolverá solo los cambios desde "ahora". Esta es la llamada de ejemplo:
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
La respuesta contendrá la propiedad deltaLink, pero no tendrá los objetos modificados, similares al siguiente:
{ … "aad.deltaLink":https://graph.windows.net/contoso.com/users?deltaLink=MRa43...... }
Detección de un elemento eliminado: La respuesta también puede utilizarse para detectar un elemento eliminado. Los vínculos eliminados y los objetos eliminados se indican con la propiedad “aad.isDeleted” con un valor establecido como verdadero. Esto es necesario para que las aplicaciones puedan aprender de la eliminación de los vínculos y los objetos creados anteriormente.