Consultas, filtros y opciones de paginación admitidos | Conceptos de Graph API

En este tema se enumeran las opciones de consulta, los filtros y las operaciones de paginación que se pueden usar con la API de Azure Active Directory (AD) Graph. La sección final ofrece algunos ejemplos de consultas comunes que puede realizar con la API de Azure AD Graph.

Direccionamiento

Todas las consultas siguientes se dirigen al inquilino mediante un nombre de dominio. Puede reemplazar contoso.com por uno de los nombres de dominio registrados de su inquilino, por el identificador de su inquilino (GUID) o por el alias MyOrganization (para acceso delegado). En algunos casos, es posible que pueda usar el alias me. Para obtener información sobre cómo abordar el inquilino, consulte Información general de las operaciones.

Opciones de consulta admitidas

Graph es compatible con las siguientes opciones de consulta: $filter, $orderby, $expand, $top y $format. Las siguientes opciones de consulta no son actualmente compatibles: $count, $inlinecount y $skip.

$filter

Las restricciones generales siguientes se aplican a las consultas que contienen un filtro:

• $filter no se puede combinar con expresiones $orderby.

• El filtrado no es compatible con consultas en los objetos de directorio DirectoryRole o SubscribedSku.

• No todas las propiedades de los objetos de directorio compatibles se pueden usar en una expresión de filtro. Para obtener información sobre las propiedades filtrables de los tipos compatibles, consulte User, Group y Contact.

A las expresiones de filtro se les aplican las restricciones siguientes:

• Operadores lógicos: and y or son compatibles. Por ejemplo: https://graph.windows.net/contoso.com/users?api-version=2013-11-08&$filter=accountEnabled eq true and (userPrincipalName eq 'jonlawr@contoso.com' or mail eq 'jonlawr@contoso.com')

• Operadores de comparación: eq (igual que), ge (mayor o igual que) y le (menor o igual que) son compatibles.

• startswith es compatible. Por ejemplo: https://graph.windows.net/contoso.com/users?api-version=2013-11-08&$filter=startswith(displayName,'Mary')

• any es compatible cuando se consultan propiedades de valor múltiple. Por ejemplo: https://graph.windows.net/contoso.com/users?api-version=2013-11-08&$filter=userPrincipalName eq 'Mary@Contoso.com' or proxyAddresses/any(c:c eq 'smtp:Mary@Contoso.com')

• Operadores aritméticos: no son compatibles.

• Funciones: no son compatibles.

• No se admiten valores null como operando en expresiones de filtro. Por ejemplo, no puede especificar un valor null para filtrar las propiedades sin establecer.

• Para establecer un filtro en una propiedad binaria, como por issuerUserId en userIdentities, el valor primero debe estar cifrado con base64 antes de poder usarse en la cadena $filter.

$orderby

$orderby ordenará los objetos devueltos según el parámetro especificado. Solicitudes de ejemplo que usan la opción $orderby:

A las expresiones $orderby se les aplican las restricciones siguientes:

• Actualmente se admiten dos criterios de ordenación: DisplayName para objetos User y Group, y UserPrincipalName para objetos User. El criterio de ordenación predeterminado para usuarios es por UserPrincipalName.

• $orderby no se puede combinar con expresiones $filter.

$expand

$expand devolverá un objeto y sus objetos vinculados. Solicitudes de ejemplo que usan la opción $expand:

A las expresiones $expand se les aplican las restricciones siguientes:

• El número máximo de objetos devueltos para una solicitud es 20.

$top

$top no es compatible con consultas en los objetos de directorio DirectoryRole o SubscribedSku.

Compatibilidad con paginación

Puede avanzar o retroceder páginas en Graph. Una respuesta que contiene resultados paginados incluirá un token de omisión (odata.nextLink) que le permite obtener la siguiente página de resultados. Este token de omisión se puede combinar con un argumento de consulta previous-page=true para retroceder páginas.

La siguiente solicitud de ejemplo demuestra el avance de páginas:

La siguiente solicitud de ejemplo demuestra el retroceso de páginas:

Los siguientes pasos demuestran el flujo de solicitud/respuesta para avanzar y retroceder páginas:

1. Se realiza una solicitud para obtener una lista de los 10 primeros usuarios de 15. La respuesta contiene un token de omisión para indicar la última página de los 10 usuarios.
2. Para obtener los 5 últimos usuarios, se realiza otra solicitud que contiene el token de omisión devuelto de la respuesta anterior.
3. Para retroceder páginas, se realiza una solicitud con el token de omisión devuelto en el paso 1 y se agrega el parámetro &previous-page=true a la solicitud.
4. La respuesta contiene la página anterior (primera) de 10 usuarios. En un escenario diferente en el que se dejan más páginas, se devolvería un nuevo token de omisión. Este nuevo token de omisión se puede agregar a la solicitud junto con &previous-page=true para volver a retroceder páginas.

A las solicitudes paginadas se les aplican las restricciones siguientes:

• El tamaño de página predeterminado es 100. El tamaño de página máximo es 999.
• Las consultas en roles no admiten paginación. Esto incluye la lectura de los propios objetos de rol, así como los miembros de roles.
• Las consultas de listas de recursos, como una búsqueda de todos los usuarios de un inquilino (/users), sí admiten la paginación. Por ejemplo: https://graph.windows.net/contoso.com/users?api-version=1.6. Sin embargo, en todos los tipos, cuando se aplica un filtro no se admite la paginación y solo se devuelve la primera página de resultados.
• La paginación no se admite para las búsquedas de vínculos, como las búsquedas de miembros de grupo. Por ejemplo: https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/$links/members?api-version=1.6.

Criterio de ordenación

• El conjunto de resultados de una consulta para todos los usuarios se ordena mediante la propiedad UserPrincipalName. Por ejemplo: https://graph.windows.net/contoso.com/users?api-version=1.6.
• El conjunto de resultados de una consulta para todos los demás recursos de nivel superior, como grupos, contactos, etc., se ordena mediante la propiedad objectId. Por ejemplo: https://graph.windows.net/contoso.com/groups?api-version=1.6.
• El orden de los resultados de consultas que no sean para recursos de nivel superior es indeterminado.

Consultas comunes

En las siguientes secciones se muestran algunos ejemplos de las consultas comunes que puede realizar con Graph API.

Consulta de recursos de nivel superior

Las siguientes consultas muestran cómo acceder a recursos de nivel superior con Graph API con contoso.com como el inquilino de ejemplo. Tenga en cuenta que será necesario un encabezado Authorization que contenga un token de portador válido recibido de Azure AD para ejecutar consultas en un inquilino.

Otras operaciones de consulta

En la tabla siguiente se muestran algunas consultas de Graph API de ejemplo adicionales con contoso.com como el inquilino de ejemplo.

Nota: El espacio en blanco de la cadena de consulta debe codificarse para URL antes de enviar una solicitud. Por ejemplo, la siguiente cadena de consulta, https://graph.windows.net/contoso.com/users?$filter=displayName eq 'Jon Doe'&api-version=1.6, debe codificarse para URL como: https://graph.windows.net/contoso.com/users?$filter=displayName%20eq%20'Jon%20Doe'&api-version=1.6.

Recursos adicionales

• Consulta diferencial de la API de Azure AD Graph
• Referencia de la API de Azure AD Graph