Table of contents

Consultas, filtros y opciones de paginación admitidos | Conceptos de Graph APISupported queries, filters, and paging options | Graph API concepts

Jimaco Brannian|Última actualización: 19/06/2018
|
2 Colaboradores

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.This topic lists query options, filters, and paging operations that you can use with the Azure Active Directory (AD) Graph API.La sección final ofrece algunos ejemplos de consultas comunes que puede realizar con la API de Azure AD Graph.The final section gives some examples of common queries that you can perform with the Azure AD Graph API.

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.We strongly recommend that you use Microsoft Graph instead of Azure AD Graph API to access Azure Active Directory resources.Nuestros esfuerzos de desarrollo se concentran ahora en Microsoft Graph y no están previstas mejoras adicionales para la API de Azure AD Graph.Our development efforts are now concentrated on Microsoft Graph and no further enhancements are planned for Azure AD Graph API.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.There are a very limited number of scenarios for which Azure AD Graph API might still be appropriate; for more information, see the Microsoft Graph or the Azure AD Graph blog post in the Office Dev Center.

Direccionamiento Addressing

Todas las consultas siguientes se dirigen al inquilino mediante un nombre de dominio.The queries below all address the tenant using a domain name.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).You can replace contoso.com with one of your tenant’s registered domain names, with your tenant's ID (GUID), or with the MyOrganization alias (for delegated access).En algunos casos, es posible que pueda usar el alias me.In some cases, you may be able to use the me alias.Para obtener información sobre cómo abordar el inquilino, consulte Información general de las operaciones.For information about ways of addressing the tenant, see Operations overview.

Opciones de consulta admitidas Supported query options

Graph es compatible con las siguientes opciones de consulta: $filter, $orderby, $expand, $top y $format.The Graph supports the following query options: $filter, $orderby, $expand, $top, and $format.Las siguientes opciones de consulta no son actualmente compatibles: $count, $inlinecount y $skip.The following query options are not currently supported: $count, $inlinecount, and $skip.

$filter$filter

Las restricciones generales siguientes se aplican a las consultas que contienen un filtro:The following general restrictions apply to queries that contain a filter:

  • $filter no se puede combinar con expresiones $orderby.$filter cannot be combined with $orderby expressions.

  • El filtrado no es compatible con consultas en los objetos de directorio DirectoryRole o SubscribedSku.Filtering is not supported for queries on DirectoryRole or SubscribedSku directory objects.

  • No todas las propiedades de los objetos de directorio compatibles se pueden usar en una expresión de filtro.Not all properties of supported directory objects can be used in a filter expression.Para obtener información sobre las propiedades filtrables de los tipos compatibles, consulte User, Group y Contact.For information about filterable properties of supported types, see User, Group, and Contact.

A las expresiones de filtro se les aplican las restricciones siguientes:The following restrictions apply to filter expressions:

  • Operadores lógicos: and y or son compatibles.Logical operators: and and or are supported.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')For example: 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.Comparison operators: eq (equal to), ge (greater than or equal to), and le (less than or equal to) are supported.

  • startswith es compatible.startswith is supported.Por ejemplo: https://graph.windows.net/contoso.com/users?api-version=2013-11-08&$filter=startswith(displayName,'Mary')For example: 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.any is supported when querying multi-valued properties.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')For example: 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.Arithmetic operators: not supported.

  • Funciones: no son compatibles.Functions: not supported.

  • No se admiten valores null como operando en expresiones de filtro.null values are not supported as an operand in filter expressions.Por ejemplo, no puede especificar un valor null para filtrar las propiedades sin establecer.For example, you cannot specify a null value to filter for unset properties.

  • 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.To filter on a binary property such as the issuerUserId in userIdentities, the value must first be base64 encoded before it can be used in the $filter string.

$orderby$orderby

$orderby ordenará los objetos devueltos según el parámetro especificado.$orderby will sort the returned objects by the specified parameter.Solicitudes de ejemplo que usan la opción $orderby:Example requests using the $orderby option:

SolicitudRequestDescripciónDescription
https://graph.windows.net/contoso.com/users?$orderby=displayName&api-version=1.6Devuelve una lista de usuarios ordenados por su nombre para mostrar.Returns a list of users ordered by their display name.
https://graph.windows.net/contoso.com/users?$orderby=displayName&$top=50&api-version=1.6Devuelve una lista de los 50 primeros usuarios ordenados por su nombre para mostrar.Returns a list of the first 50 users ordered by their display name.

A las expresiones $orderby se les aplican las restricciones siguientes:The following restrictions apply to $orderby expressions:

  • Actualmente se admiten dos criterios de ordenación: DisplayName para objetos User y Group, y UserPrincipalName para objetos User.Two sort orders are currently supported: DisplayName for User and Group objects, and UserPrincipalName for User objects.El criterio de ordenación predeterminado para usuarios es por UserPrincipalName.The default sort order for users is by UserPrincipalName.

  • $orderby no se puede combinar con expresiones $filter.$orderby cannot be combined with $filter expressions.

$expand$expand

$expand devolverá un objeto y sus objetos vinculados.$expand will return an object and its linked objects.Solicitudes de ejemplo que usan la opción $expand:Example requests using the $expand option:

SolicitudRequestDescripciónDescription
https://graph.windows.net/contoso.com/groups/1747ad35-dd4c-4115-8604-09b54f89277d?$expand=members&api-version=1.6Devuelve el objeto de grupo y sus miembros.Returns both the group object as well as its members.
https://graph.windows.net/contoso.com/users/derek@contoso.com?$expand=directReports&api-version=1.6Devuelve el objeto de usuario y los subordinados directos.Returns both the user object as well as its direct reports.
https://graph.windows.net/contoso.com/users/adam@contoso.com?$expand=manager&api-version=1.6Devuelve el objeto de usuario y su administrador.Returns both the user object as well as its manager.

A las expresiones $expand se les aplican las restricciones siguientes:The following restrictions apply to $expand expressions:

  • El número máximo de objetos devueltos para una solicitud es 20.The maximum number of returned objects for a request is 20.

$top$top

$top no es compatible con consultas en los objetos de directorio DirectoryRole o SubscribedSku.$top is not supported for queries on DirectoryRole or SubscribedSku directory objects.

Compatibilidad con paginación Paging support

Puede avanzar o retroceder páginas en Graph.You can page forward and backward in the 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.A response that contains paged results will include a skip token (odata.nextLink) that allows you to get the next page of results.Este token de omisión se puede combinar con un argumento de consulta previous-page=true para retroceder páginas.This skip token can be combined with a previous-page=true query argument to page backwards.

La siguiente solicitud de ejemplo demuestra el avance de páginas:The follow example request demonstrates paging forward:

SolicitudRequestDescripciónDescription
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.The $skiptoken parameter from the previous response is included, and allows you to get the next page of results.

La siguiente solicitud de ejemplo demuestra el retroceso de páginas:The following example request demonstrates paging backward:

SolicitudRequestDescripciónDescription
https://graph.windows.net/contoso.com/users?$top=5&api-version=2013-11-08&$skiptoken=X'4453707.....00000'&previous-page=trueSe incluye el parámetro $skiptoken de la respuesta anterior.The $skiptoken parameter from the previous response is included.Cuando se combine con el parámetro &previous-page=true, se recuperará la página anterior de resultados.When this is combined with the &previous-page=true parameter, the previous page of results will be retrieved.

Los siguientes pasos demuestran el flujo de solicitud/respuesta para avanzar y retroceder páginas:The following steps demonstrate the request/response flow to page forward and backward:

  1. Se realiza una solicitud para obtener una lista de los 10 primeros usuarios de 15.A request is made to get a list of the first 10 users out of 15.La respuesta contiene un token de omisión para indicar la última página de los 10 usuarios.The response contains a skip token to indicate the final page of 10 users.
  2. Para obtener los 5 últimos usuarios, se realiza otra solicitud que contiene el token de omisión devuelto de la respuesta anterior.To get the final 5 users, another request is made that contains the skip token returned from the previous response.
  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.To page backward, a request is made using the skip token returned in step 1 and the parameter &previous-page=true is added to the request.
  4. La respuesta contiene la página anterior (primera) de 10 usuarios.The response contains the previous (first) page of 10 users.En un escenario diferente en el que se dejan más páginas, se devolvería un nuevo token de omisión.In a different scenario where more pages are left, a new skip token would be returned.Este nuevo token de omisión se puede agregar a la solicitud junto con &previous-page=true para volver a retroceder páginas.This new skip token can be added to the request along with &previous-page=true to page backward again.

A las solicitudes paginadas se les aplican las restricciones siguientes:The following restrictions apply to paged requests:

  • El tamaño de página predeterminado es 100.The default page size is 100.El tamaño de página máximo es 999.The maximum page size is 999.
  • Las consultas en roles no admiten paginación.Queries against roles do not support paging.Esto incluye la lectura de los propios objetos de rol, así como los miembros de roles.This includes reading role objects themselves as well as role members.
  • Las consultas de listas de recursos, como una búsqueda de todos los usuarios de un inquilino (/users), sí admiten la paginación.Resource listing, such as a search for all users in a tenant (/users), queries do support paging.Por ejemplo: https://graph.windows.net/contoso.com/users?api-version=1.6.For example: 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.However, across all types when a filter is applied, paging is not supported and only the first page of results is returned.
  • La paginación no se admite para las búsquedas de vínculos, como las búsquedas de miembros de grupo.Paging is not supported for link searches, such as for querying group members.Por ejemplo: https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/$links/members?api-version=1.6.For example: https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/$links/members?api-version=1.6.

Criterio de ordenación Sort order

  • El conjunto de resultados de una consulta para todos los usuarios se ordena mediante la propiedad UserPrincipalName.The result set of a query for all users is ordered by the UserPrincipalName property.Por ejemplo: https://graph.windows.net/contoso.com/users?api-version=1.6.For example: 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.The result set of a query for all other top-level resources, such as Groups, Contacts, etc. is ordered by the objectId property.Por ejemplo: https://graph.windows.net/contoso.com/groups?api-version=1.6.For example: 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.The order of the results of queries other than for top-level resources is indeterminate.

Consultas comunes Common queries

En las siguientes secciones se muestran algunos ejemplos de las consultas comunes que puede realizar con Graph API.The following sections show some examples of common queries you can perform with the Graph API.

Consulta de recursos de nivel superiorQuerying top-level resources

Las siguientes consultas muestran cómo acceder a recursos de nivel superior con Graph API con contoso.com como el inquilino de ejemplo.The following queries demonstrate how to access top-level resources with the Graph API using contoso.com as the example tenant.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.Note that an Authorization header containing a valid bearer token received from Azure AD will be required to run queries against a tenant.

Recurso de nivel superiorTop-Level ResourceResultados de la consultaQuery ResultsURI (para contoso.com)URI (for contoso.com)
Recursos de nivel superiorTop-level resourcesDevuelve la lista de URI de los recursos de nivel superior para los servicios de directorio (también se muestran a continuación)Returns URI list of the top-level resources for directory services (also listed below)https://graph.windows.net/contoso.com?api-version=1.6
Información de la compañíaCompany informationDevuelve información de la compañíaReturns company informationhttps://graph.windows.net/contoso.com/tenantDetails?api-version=1.6
ContactosContactsDevuelve información de contacto organizativaReturns organizational contact informationhttps://graph.windows.net/contoso.com/contacts?api-version=1.6
UsuariosUsersDevuelve información de usuariosReturns user informationhttps://graph.windows.net/contoso.com/users?api-version=1.6
GruposGroupsDevuelve datos de gruposReturns group datahttps://graph.windows.net/contoso.com/groups?api-version=1.6
Roles de directorioDirectory RolesDevuelve todos los roles de directorio activados en el inquilinoReturns all activated directory roles in the tenanthttps://graph.windows.net/contoso.com/directoryRoles?api-version=1.6
SubscribedSkusSubscribedSkusDevuelve las suscripciones del inquilinoReturns the tenant's subscriptionshttps://graph.windows.net/contoso.com/subscribedSkus?api-version=1.6
Metadatos de directorioDirectory metadataDevuelve 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)Returns a Service Metadata Document that describes the data model (that is, structure and organization of directory resources)https://graph.windows.net/contoso.com/$metadata?api-version=1.6

Otras operaciones de consultaOther query operations

En la tabla siguiente se muestran algunas consultas de Graph API de ejemplo adicionales con contoso.com como el inquilino de ejemplo.The following table shows some additional example Graph API queries using contoso.com as the example tenant.

Operación de consultaQuery OperationURI (para contoso.com)URI (for contoso.com)
Mostrar todos los usuarios y gruposList all Users and Groupshttps://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 userPrincipalNameRetrieve individual User by specifying the objectId or userPrincipalNamehttps://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"Request and Filter for a user with displayName equal to “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"Request and Filter for specific users with firstName equal to “Jon”https://graph.windows.net/contoso.com/users?$filter=givenName eq 'Jon'&api-version=1.6
Filtrar por valores givenName y surnameFilter for givenName and surname values.https://graph.windows.net/contoso.com/users?$filter=givenName eq 'Jon' and surname eq 'Doe'&api-version=1.6
Recuperar un grupo individual especificando objectIdRetrieve individual group by specifying the objectIdhttps://graph.windows.net/contoso.com/groups/06790a81-0382-434c-b40e-216fa41bda21?api-version=1.6
Recuperar el administrador de un usuarioRetrieve a user’s managerhttps://graph.windows.net/contoso.com/users/John.Smith@contoso.com/manager?api-version=1.6
Recuperar la lista de subordinados directos de un usuarioRetrieve a user’s direct reports listhttps://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 usuarioRetrieve a list of links to a user’s direct reportshttps://graph.windows.net/contoso.com/users/3c4a09b0-a7b6-444e-9702-96983635a66e/$links/directReports?api-version=1.6
Recuperar la lista de pertenencias de un grupoRetrieve membership list of a grouphttps://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 grupoRetrieve a list of links to the members of a group.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)Retrieve a user’s group membership (not transitive)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)Retrieve a list of the groups that the user is a member of (not transitive)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"Request and filter for groups with displayName >= "az" and <= "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 B2CReturn all local account users in an Azure Active Directory B2C tenanthttps://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 B2CReturn local account user with the sign-in name "joe@example.com" from an Azure Active Directory B2C tenanthttps://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.Note: White space in the query string should be URL-encoded before sending a request.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.For example, the following query string, https://graph.windows.net/contoso.com/users?$filter=displayName eq 'Jon Doe'&api-version=1.6, should be URL encoded as: https://graph.windows.net/contoso.com/users?$filter=displayName%20eq%20'Jon%20Doe'&api-version=1.6.

Recursos adicionales Additional resources

© 2018 Microsoft