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.

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.

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:

Solicitud Descripción
https://graph.windows.net/contoso.com/users?$orderby=displayName&api-version=1.6 Devuelve una lista de usuarios ordenados por su nombre para mostrar.
https://graph.windows.net/contoso.com/users?$orderby=displayName&$top=50&api-version=1.6 Devuelve una lista de los 50 primeros usuarios ordenados por su nombre para mostrar.

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:

Solicitud Descripción
https://graph.windows.net/contoso.com/groups/1747ad35-dd4c-4115-8604-09b54f89277d?$expand=members&api-version=1.6 Devuelve el objeto de grupo y sus miembros.
https://graph.windows.net/contoso.com/users/derek@contoso.com?$expand=directReports&api-version=1.6 Devuelve el objeto de usuario y los subordinados directos.
https://graph.windows.net/contoso.com/users/adam@contoso.com?$expand=manager&api-version=1.6 Devuelve el objeto de usuario y su administrador.

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:

Solicitud Descripción
https://graph.windows.net/contoso.com/users?$top=5&api-version=2013-11-08&$skiptoken=X'4453707402.....0000' Se incluye el parámetro $skiptoken de la respuesta anterior y le permite obtener la siguiente página de resultados.

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

Solicitud Descripción
https://graph.windows.net/contoso.com/users?$top=5&api-version=2013-11-08&$skiptoken=X'4453707.....00000'&previous-page=true Se incluye el parámetro $skiptoken de la respuesta anterior. Cuando se combine con el parámetro &previous-page=true, se recuperará la página anterior de resultados.

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.

Recurso de nivel superior Resultados de la consulta URI (para contoso.com)
Recursos de nivel superior Devuelve la lista de URI de los recursos de nivel superior para los servicios de directorio (también se muestran a continuación) https://graph.windows.net/contoso.com?api-version=1.6
Información de la compañía Devuelve información de la compañía https://graph.windows.net/contoso.com/tenantDetails?api-version=1.6
Contactos Devuelve información de contacto organizativa https://graph.windows.net/contoso.com/contacts?api-version=1.6
Usuarios Devuelve información de usuarios https://graph.windows.net/contoso.com/users?api-version=1.6
Grupos Devuelve datos de grupos https://graph.windows.net/contoso.com/groups?api-version=1.6
Roles de directorio Devuelve todos los roles de directorio activados en el inquilino https://graph.windows.net/contoso.com/directoryRoles?api-version=1.6
SubscribedSkus Devuelve las suscripciones del inquilino https://graph.windows.net/contoso.com/subscribedSkus?api-version=1.6
Metadatos de directorio Devuelve un documento de metadatos de servicio que describe el modelo de datos (es decir, la estructura y la organización de los recursos del directorio) https://graph.windows.net/contoso.com/$metadata?api-version=1.6

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.

Operación de consulta URI (para contoso.com)
Mostrar todos los usuarios y grupos https://graph.windows.net/contoso.com/users?api-version=1.6

https://graph.windows.net/contoso.com/groups?api-version=1.6
Recuperar un usuario individual especificando objectId o userPrincipalName https://graph.windows.net/contoso.com/users/d1f67a6c-02c9-4fe5-81fb-58160ce24fe5?api-version=1.6

https://graph.windows.net/contoso.com/users/admin@contoso.com?api-version=1.6
Solicitud y filtrado de un usuario cuyo displayName es igual a "Jon Doe" https://graph.windows.net/contoso.com/users?$filter=displayName eq 'Jon Doe'&api-version=1.6
Solicitar y filtrar usuarios específicos cuyo firstName es igual que "Jon" https://graph.windows.net/contoso.com/users?$filter=givenName eq 'Jon'&api-version=1.6
Filtrar por valores givenName y surname https://graph.windows.net/contoso.com/users?$filter=givenName eq 'Jon' and surname eq 'Doe'&api-version=1.6
Recuperar un grupo individual especificando objectId https://graph.windows.net/contoso.com/groups/06790a81-0382-434c-b40e-216fa41bda21?api-version=1.6
Recuperar el administrador de un usuario https://graph.windows.net/contoso.com/users/John.Smith@contoso.com/manager?api-version=1.6
Recuperar la lista de subordinados directos de un usuario https://graph.windows.net/contoso.com/users/3c4a09b0-a7b6-444e-9702-96983635a66e/directReports?api-version=1.6
Recuperar una lista de vínculos a los subordinados directos de un usuario https://graph.windows.net/contoso.com/users/3c4a09b0-a7b6-444e-9702-96983635a66e/$links/directReports?api-version=1.6
Recuperar la lista de pertenencias de un grupo https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/members?api-version=1.6
Recuperar una lista de vínculos a los miembros de un grupo https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/$links/members?api-version=1.6
Recuperar la pertenencia a grupos de un usuario (no transitiva) https://graph.windows.net/contoso.com/users/ee6308f6-646a-4845-a4e1-57ac96ccc0c8/memberOf?api-version=1.6
Recuperar una lista de los grupos de los que el usuario es miembro (no transitiva) https://graph.windows.net/contoso.com/users/ee6308f6-646a-4845-a4e1-57ac96ccc0c8/$links/memberOf?api-version=1.6
Solicitud y filtrado para grupos con displayName >= "az" y <= "dz" https://graph.windows.net/contoso.com/groups?$filter=displayName ge 'az' and displayName le 'dz'&api-version=1.6
Devolver todos los usuarios de cuentas locales en un inquilino de Azure Active Directory B2C https://graph.windows.net/contoso.com/users?filter=creationType eq 'LocalAccount'&api-version=1.6
Devolver el usuario de cuenta local con el nombre de inicio de sesión "joe@example.com" desde un inquilino de Azure Active Directory B2C https://graph.windows.net/contoso.com/users?$filter=signInNames/any(x:x/value eq 'joe@example.com')&api-version=1.6

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