Usar parámetros de consulta para personalizar respuestas

Microsoft Graph admite parámetros de consulta opcionales que puede usar para especificar y controlar la cantidad de datos devueltos en una respuesta. La compatibilidad con los parámetros de consulta exactos varía de una operación API a otra y, en función de la API, puede diferir entre los puntos de conexión de las versiones 1.0 y beta.

Sugerencia

En el punto de conexión beta, el prefijo $ es opcional. Por ejemplo, en lugar de $filter, puede usar filter. En el punto de conexión v1, el prefijo $ es opcional solo para un subconjunto de las API. Para simplificar, incluya $ siempre si usa el punto de conexión v1.

Los parámetros de consulta pueden ser opciones de consulta de sistema de OData u otros parámetros de consulta.

Opciones de consulta de sistema de OData

Una operación de API de Microsoft Graph podría admitir una o varias de las siguientes opciones de consulta de sistema de OData. Estas opciones de consulta son compatibles con el lenguaje de consulta de OData V4.

Nota: OData 4,0 es compatible con las opciones de consulta de sistema solo en operaciones GET.

Haga clic en los ejemplos para probarlos en Probador de Graph.

Nombre Descripción Ejemplo
$count Recupera el número total de recursos coincidentes. /me/messages?$top=2&$count=true
$expand Recupera los recursos relacionados. /groups?$expand=members
$filter Filtra los resultados (filas). /users?$filter=startswith(givenName,'J')
$format Devuelve los resultados en el formato de medio especificado. /users?$format=json
$orderby Ordena los resultados. /users?$orderby=displayName desc
$search Devuelve los resultados en función de criterios de búsqueda. /me/messages?$search=pizza
$select Filtra las propiedades (columnas). /users?$select=givenName,surname
$skip Indexa en un conjunto de resultados. También se usa en algunas API para implementar la paginación y se puede usar junto a $top para paginar manualmente los resultados. /me/messages?$skip=11
$top Establece el tamaño de la página de resultados. /users?$top=2

Otros parámetros de consulta

Nombre Descripción Ejemplo
$skipToken Recupera la siguiente página de resultados de conjuntos de resultados que abarcan varias páginas. (Algunas API usan $skip en su lugar). /users?$skiptoken=X%274453707402000100000017...

Otras funciones URL de OData

Las siguientes funciones de OData 4,0 son segmentos URL, no parámetros de consulta.

Nombre Descripción Ejemplo
$count Recupera el total entero de la colección. GET /users/$count
GET /groups/{id}/members/$count
$ref Actualice la pertenencia a entidades en una colección. POST /groups/{id}/members/$ref
$value Recupere o actualice el valor binario de un elemento. GET /me/photo/$value

Codificación de parámetros de consulta

Los valores de los parámetros de consulta deben ser codificados por porcentaje. Muchos clientes HTTP, exploradores y herramientas (como el Probador de Graph) le servirán de ayuda. Si una consulta produce un error, puede deberse a que los valores de los parámetros de consulta no se han codificado correctamente.

Una dirección URL sin codificar tiene el siguiente aspecto:

GET https://graph.microsoft.com/v1.0/users?$filter=startswith(givenName, 'J')

Una dirección URL codificada correctamente tiene el siguiente aspecto:

GET https://graph.microsoft.com/v1.0/users?$filter=startswith(givenName%2C+'J')

Escape para las comillas simples

En las solicitudes que usen comillas simples, si algún parámetro tiene valores que contengan también comillas simples, estas deben tener doble escape. De lo contrario, se producirá un error en la solicitud porque la sintaxis no es válida. En el ejemplo, el valor de cadena let''s meet for lunch? tiene el escape de comillas simples.

GET https://graph.microsoft.com/v1.0/me/messages?$filter=subject eq 'let''s meet for lunch?'

parámetro de recuento

Use el parámetro de consulta $count para incluir un recuento del número total de elementos de una colección junto con la página de valores de datos que se devuelve desde Microsoft Graph.

Nota

$count también se puede usar como un segmento de dirección URL para recuperar el total entero de la colección. En los recursos que derivan de directoryObject, solo se admite en una consulta avanzada. Consulte funcionalidades de consulta avanzadas en Azure AD objetos de directorio.

No se admite el uso de $count en inquilinos de Azure AD B2C.

Por ejemplo, la siguiente solicitud devuelve tanto la colección de contactos del usuario actual como el número de elementos de la colección de contactos en la propiedad @odata.count.

GET  https://graph.microsoft.com/v1.0/me/contacts?$count=true

El parámetro de consulta $count se admite para estas colecciones de recursos y sus relaciones que derivan de directoryObject y solo en consultas avanzadas:

parámetro de expansión

Muchos de los recursos de Microsoft Graph exponen ambas propiedades declaradas de los recursos, así como sus relaciones con otros recursos. Estas relaciones también se denominan propiedades de referencia o propiedades de navegación, y pueden hacer referencia a un único recurso o a una colección de recursos. Por ejemplo, las carpetas de correo, el administrador y los informes directos de un usuario se exponen como relaciones.

Normalmente, se pueden consultar las propiedades de un recurso o una de sus relaciones en una sola solicitud, pero no ambas. Puede usar el parámetro de cadena de consulta $expand para incluir en los resultados de la consulta el recurso expandido o la colección a la que se hace referencia con una única relación (propiedad de navegación). Solo se puede expandir una relación en una única solicitud.

En el ejemplo siguiente se obtiene la información de la unidad raíz junto con los elementos secundarios de nivel superior de una unidad:

GET https://graph.microsoft.com/v1.0/me/drive/root?$expand=children

Con algunas colecciones de recursos, también se pueden especificar las propiedades que se van a devolver en los recursos expandidos si se agrega un parámetro $select. En el ejemplo siguiente se realiza la misma consulta que en el anterior, pero se usa una instrucción $select para limitar las propiedades devueltas para los elementos secundarios expandidos a las propiedades id y name.

GET https://graph.microsoft.com/v1.0/me/drive/root?$expand=children($select=id,name)

Nota

No todas las relaciones y recursos admiten el parámetro de consulta $expand. Por ejemplo, puede expandir las relaciones de directReports, manager y memberOf en un usuario, pero no puede expandir sus relaciones de eventos, mensajes o fotos. No todos los recursos o relaciones admiten el uso de $select en elementos expandidos.

Con recursos de Azure AD que derivan de directoryObject, como usuario y grupo, $expand normalmente devuelve un máximo de 20 elementos para la relación expandida y no tiene @odata.nextLink. Vea más problemas conocidos.

parámetro de filtrado

Use el parámetro de consulta $filter para recuperar solo un subconjunto de una colección. El $filter parámetro de consulta también se puede usar para recuperar relaciones como members, memberOf, transitiveMembers y transitiveMemberOf. Por ejemplo, puede usar el parámetro para buscar todos los grupos de seguridad a los que usted pertenece.

En el ejemplo siguiente se buscan usuarios cuyo nombre para mostrar comienza por la letra "J":

GET https://graph.microsoft.com/v1.0/users?$filter=startsWith(displayName,'J')

La compatibilidad con los operadores $filter varía en función de la API de Microsoft Graph. Generalmente, se admiten los siguientes operadores lógicos:

Tipo de operador Operador
Operadores de igualdad
  • Igual aeq
  • no es igual a ne
  • Negación not
  • en in
Operadores relacionales
  • menor que lt
  • mayor que gt
  • menor o igual que le
  • mayor o igual que ge
Operador lambda
  • cualquiera any
  • todo all
Operadores condicionales
  • y and
  • o or
Funciones
  • Empieza por startsWith
  • Termina en endsWith
  • Contiene contains

Nota: la compatibilidad con estos operadores varía según la entidad y algunas propiedades solo admiten $filter en consultas avanzadas. Consulte la documentación de la entidad específica para más información.

Filtrar mediante operadores lambda

OData define los operadores any y all para evaluar coincidencias en propiedades multivalor, es decir, en cualquier colección de valores primitivos, como String tipos o colección de entidades.

El operador any aplica iterativamente una expresión booleana a cada miembro de una colección y devuelve true si la expresión es true para cualquier miembro de la colección; de lo contrario, devuelve false. La siguiente es la sintaxis del operador any :

$filter=param/any(var:var/subparam eq 'value-to-match')

Dónde

  • param es la propiedad que contiene una colección de valores o una colección de entidades.
  • var:var es una variable de intervalo que contiene el elemento actual de la colección durante la iteración. Esta variable puede tener casi cualquier nombre, por ejemplo, adele:adele o x:x.
  • subparam es necesaria cuando la consulta se aplica a una colección de entidades. Representa la propiedad del tipo complejo cuyo valor se va a buscar.
  • value-to-match representa el miembro de la colección con la que se busca la coincidencia.

Por ejemplo, la propiedad imAddresses del recurso de usuario contiene una colección de tipo primitivo String. La consulta siguiente recupera solo los usuarios con una imAddress de admin@contoso.com.

GET https://graph.microsoft.com/v1.0/users?$filter=imAddresses/any(s:s eq 'admin@contoso.com')

La propiedad assignedLicenses del recurso usuario contiene una colección de objetos assignedLicense, un tipo complejo con dos propiedades, skuId y disabledPlans. La consulta siguiente recupera solo los usuarios con una licencia asignada identificada por el skuId 184efa21-98c3-4e5d-95ab-d07053a96e67.

GET https://graph.microsoft.com/v1.0/users?$filter=assignedLicenses/any(s:s/skuId eq 184efa21-98c3-4e5d-95ab-d07053a96e67)

Para negar el resultado de la expresión dentro de la cláusula any use el operador NOT no el operador ne. Por ejemplo, la consulta siguiente recupera solo los usuarios a los que no se les asigna e imAddress de admin@contoso.com.

Nota: para objetos de directorio como usuarios, los operadores NOT y ne solo se admiten en consultas avanzadas.

GET https://graph.microsoft.com/v1.0/users?$filter=NOT(imAddresses/any(s:s eq 'admin@contoso.com'))&$count=true
ConsistencyLevel: eventual

El operador all aplica una expresión booleana a cada miembro de una colección y devuelve true si la expresión es true para todos los miembros de la colección; de lo contrario, devuelve false. No es compatible con ninguna propiedad.

Ejemplos que usan el operador de consulta de filtro

En la tabla siguiente se muestran algunos ejemplos de uso del parámetro de consulta $filter. Para obtener detalles adicionales sobre la sintaxis de $filter, vea el protocolo OData.

Nota: Haga clic en los ejemplos para probarlos en Probador de Graph.

Descripción Ejemplo
Obtener todos los usuarios con el nombre Mary en varias propiedades. GET ../users?$filter=startswith(displayName,'mary') or startswith(givenName,'mary') or startswith(surname,'mary') or startswith(mail,'mary') or startswith(userPrincipalName,'mary')
Obtener todos los usuarios con un dominio de correo igual a 'hotmail.com'
GET ../users?$count=true&$filter=endsWith(mail,'@hotmail.com'). Esto es unaconsulta avanzada .
Obtener todos los eventos del usuario que inició sesión que comiencen después del 1/7/2017. GET ../me/events?$filter=start/dateTime ge '2017-07-01T08:00'
Obtener todos los correos electrónicos de una dirección específica recibidos por el usuario que inició sesión. GET ../me/messages?$filter=from/emailAddress/address eq 'someuser@example.com'
Obtener todos los correos electrónicos recibidos en abril de 2017 por el usuario que inició sesión. GET ../me/mailFolders/inbox/messages?$filter=ReceivedDateTime ge 2017-04-01 and receivedDateTime lt 2017-05-01
Obtener todos los correos electrónicos no leídos en la Bandeja de entrada del usuario que inició sesión. GET ../me/mailFolders/inbox/messages?$filter=isRead eq false
Obtener todos los usuarios de los departamentos de ventas y minoristas.
GET ../users?$filter=department in ('Retail', 'Sales')
Enumerar a los usuarios con un plan de servicio determinado que se encuentra en un estado suspendido.
GET ../users?$filter=assignedPlans/any(a:a/servicePlanId eq 2e2ddb96-6af9-4b1d-a3f0-d6ecfd22edb2 and a/capabilityStatus eq 'Suspended')&$count=true. Esto es unaconsulta avanzada .
Enumerar todos los grupos que no sean de Microsoft 365 de una organización.
GET ../groups?$filter=NOT groupTypes/any(c:c eq 'Unified')&$count=true. Esto es unaconsulta avanzada .
Enumerar todos los usuarios cuyo nombre de empresa no sea indefinido (es decir, no es un valor de null ) o Microsoft.
GET ../users?$filter=companyName ne null and NOT(companyName eq 'Microsoft')&$count=true. Esto es unaconsulta avanzada .
Enumere todos los usuarios cuyo nombre de empresa sea indefinido o Microsoft.
GET ../users?$filter=companyName in (null, 'Microsoft')&$count=true. Esto es unaconsulta avanzada .
Emplee la transmisión de OData para obtener la pertenencia transitiva en grupos con un nombre para mostrar que comience por "a", incluido un recuento de objetos devueltos.
GET ../me/transitiveMemberOf/microsoft.graph.group?$count=true&$filter=startswith(displayName, 'a'). Esto es unaconsulta avanzada .

parámetro de formato

Use el parámetro de consulta $format para especificar el formato de medio de los elementos devueltos desde Microsoft Graph

Por ejemplo, la solicitud siguiente devuelve los usuarios de la organización en formato JSON:

GET https://graph.microsoft.com/v1.0/users?$format=json

Nota: El parámetro de consulta $format admite varios formatos, como atom, xml y json, pero puede que no todos los formatos devuelvan resultados.

parámetro orderby

Use el parámetro de consulta $orderby para especificar el criterio de ordenación de los elementos devueltos desde Microsoft Graph El orden predeterminado es ascendente.

Por ejemplo, la solicitud siguiente devuelve los usuarios de la organización ordenados por su nombre para mostrar:

GET https://graph.microsoft.com/v1.0/users?$orderby=displayName

También puede ordenar por entidades de tipo complejo. La solicitud siguiente obtiene los mensajes y los ordena por el campo address de la propiedad from, que es del tipo complejo emailAddress:

GET https://graph.microsoft.com/v1.0/me/messages?$orderby=from/emailAddress/address

Para ordenar los resultados en orden ascendente o descendente, anexe asc o desc al nombre del campo, separado por un espacio. Por ejemplo, ?$orderby=name%20desc. Si no se especifica el criterio de ordenación, se deduce el valor predeterminado (orden ascendente).

Por ejemplo, en la siguiente solicitud se ordenan los mensajes en la bandeja de entrada del usuario; primero por el nombre de la persona que lo envió en orden descendente (de la Z a la A) y, después, por asunto en orden ascendente (el valor predeterminado).

GET https://graph.microsoft.com/v1.0/me/mailFolders/Inbox/messages?$orderby=from/emailAddress/name desc,subject

Nota: Al especificar $filter el servidor deducirá un criterio de ordenación para los resultados. Si usa $orderby y $filter para obtener mensajes, como el servidor siempre deduce un criterio de ordenación para los resultados de un $filter, debe especificar las propiedades de algunas formas.

En el siguiente ejemplo, se muestra una consulta filtrada por las propiedades subject y importance, y después ordenada por las propiedades subject, importance y receivedDateTime en orden descendente.

GET https://graph.microsoft.com/v1.0/me/messages?$filter=Subject eq 'welcome' and importance eq 'normal'&$orderby=subject,importance,receivedDateTime desc

Nota

Se admite la combinación de parámetros de consulta $orderby y $filter para los objetos de directorio. Consulte funcionalidades de consulta avanzadas en Azure AD objetos de directorio.

parámetro de búsqueda

Use el parámetro de consulta $search para restringir los resultados de una solicitud para que coincidan con un criterio de búsqueda Su sintaxis y comportamiento varían de una operación de API a otra. Para ver la sintaxis de $search en distintos recursos, consulte Usar el parámetro de consulta $search para que coincida con un criterio de búsqueda.

parámetro de selección

Use el parámetro de consulta $select para devolver un conjunto de propiedades diferente al predeterminado para un recurso individual o una colección de recursos. Con $select, puede especificar un subconjunto o un superconjunto de las propiedades predeterminadas.

Por ejemplo, al recuperar los mensajes del usuario que ha iniciado sesión, puede especificar que solo se devuelvan las propiedades from y subject:

GET https://graph.microsoft.com/v1.0/me/messages?$select=from,subject

Importante: En general, se recomienda usar $select para limitar las propiedades devueltas por una consulta a las necesarias para la aplicación. Esto es especialmente cierto para las consultas que potencialmente pueden devolver un conjunto de resultados grande. Limitar las propiedades devueltas en cada fila reducirá la carga en la red y ayudará a mejorar el rendimiento de la aplicación.

En v1.0, algunos recursos de Azure AD que se derivan de directoryObject, como user y group, devuelven un subconjunto predeterminado limitado de propiedades en las operaciones de lectura. Para estos recursos, debe usar $select para devolver propiedades fuera el conjunto predeterminado.

parámetros de omisión

Use el parámetro de consulta $skip para establecer el número de elementos que se omitirán al inicio de una colección. Por ejemplo, la solicitud siguiente devuelve eventos para el usuario ordenados por fecha de creación, empezando por el evento 21 de la colección:

GET  https://graph.microsoft.com/v1.0/me/events?$orderby=createdDateTime&$skip=20

Nota: En algunas API de Microsoft Graph, como Correo y Calendario de Outlook (message, event y calendar), se usa $skip para implementar la paginación. Cuando los resultados de una consulta ocupen varias páginas, estas API devolverán una propiedad @odata:nextLink con una dirección URL que contendrá un parámetro $skip. Puede usar esta dirección URL para devolver la siguiente página de resultados. Para obtener más información, vea Paginación.

El encabezado ConsistencyLevel necesario para las consultas avanzadas en objetos de directorio no se incluye de forma predeterminada en las solicitudes de página posteriores. Debe establecerse explícitamente en páginas posteriores.

parámetro skipToken

Algunas consultas devuelven varias páginas de datos debido a la paginación del servidor o al uso del parámetro $top para limitar el tamaño de página de la respuesta. Muchas API de Microsoft Graph usan el parámetro de consulta skipToken para hacer referencia a las páginas siguientes del resultado.
El parámetro $skiptoken contiene un token opaco que hace referencia a la siguiente página de resultados y se devuelve en la dirección URL proporcionada en la propiedad @odata.nextLink en la respuesta. Para más información, vea Paginación.

Nota: Si usa el recuento de OData (agregando $count=true en la cadena de consulta) para las consultas en objetos de directorio, la propiedad @odata.count solo está presente en la primera página.

El encabezado ConsistencyLevel necesario para las consultas avanzadas en objetos de directorio no se incluye de forma predeterminada en las solicitudes de página posteriores. Debe establecerse explícitamente en páginas posteriores.

parámetro superior

Use el parámetro de consulta $top para especificar el tamaño de página del conjunto de resultados.

Si quedan más elementos en el conjunto de resultados, el cuerpo de la respuesta contendrá un parámetro @odata.nextLink. Este parámetro contiene una dirección URL que se puede usar para obtener la siguiente página de resultados. Para obtener más información, vea Paginación.

El valor mínimo de $top es 1 y el máximo depende de la API correspondiente.

Por ejemplo, la solicitud siguiente de mensajes de lista devuelve los cinco primeros mensajes en el buzón del usuario:

GET https://graph.microsoft.com/v1.0/me/messages?$top=5

El encabezado ConsistencyLevel necesario para las consultas avanzadas en objetos de directorio no se incluye de forma predeterminada en las solicitudes de página posteriores. Debe establecerse explícitamente en páginas posteriores.

Control de errores para parámetros de consulta

Algunas solicitudes devolverán un mensaje de error si no se admite un parámetro de consulta especificado. Por ejemplo, no se puede usar $expand en la relación user/photo.

https://graph.microsoft.com/v1.0/me?$expand=photo
{
    "error":{
        "code":"ExpandNotSupported",
        "message":"Expand is not allowed for property 'Photo' according to the entity schema.",
        "innerError":{
            "request-id":"1653fefd-bc31-484b-bb10-8dc33cb853ec",
            "date":"2017-07-31T20:55:01"
        }
    }
}

Pero es importante tener en cuenta que los parámetros de consulta especificados en una solicitud pueden devolver un error silenciosamente. Esto puede suceder con parámetros de consulta no admitidos, así como con combinaciones no compatibles de parámetros de consulta. En estos casos, debe examinar los datos devueltos por la solicitud para determinar si los parámetros de consulta especificados tuvieron el efecto previsto.

Vea también