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:
- 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.
- Para obtener los 5 últimos usuarios, se realiza otra solicitud que contiene el token de omisión devuelto de la respuesta anterior.
- 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.
- 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.