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 OData V4 y solo se admiten 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 con $top para realizar manualmente los resultados de la página. /me/messages?$skip=11
$top Establece el tamaño de la página de resultados. /users?$top=2

Para conocer las opciones de consulta del sistema OData que admite una API y sus propiedades, consulte la tabla Propiedades en la página de recursos y la sección Parámetros de consulta opcionales de las operaciones LIST y GET de la API.

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
$batch Combine varias solicitudes HTTP en una solicitud por lotes. POST /$batch

Codificación de parámetros de consulta

Los valores de los parámetros de consulta deben estar codificados por porcentaje según RFC 3986. Por ejemplo, todos los caracteres reservados de las cadenas de consulta deben estar codificados en 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. En algunos casos, es posible que tenga que codificar dos veces los valores.

Nota:

Hay un problema conocido relacionado con la codificación desímboloss (&) símbolos en $search expresiones en el v1.0 punto de conexión. Para obtener más información sobre el problema y la solución alternativa recomendada, vea Problema conocido: $search para los objetos de directorio produce un error en los caracteres de & y de amperar codificados.

Por ejemplo, una dirección URL no codificada tiene el siguiente aspecto:

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

La dirección URL correctamente codificada en porcentaje tiene el siguiente aspecto:

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

La dirección URL con codificación doble tiene el siguiente aspecto:

GET https://graph.microsoft.com/v1.0/users?$filter=startswith%28givenName%2C%20%27J%27%29

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 recuperar el recuento del número total de elementos de una colección o para buscar coincidencias con una expresión. $count puede realizarse de las siguientes maneras:

  1. Como parámetro de cadena de consulta con la sintaxis $count=true para incluir un recuento del número total de elementos de una colección junto con la página de valores de datos devueltos por Microsoft Graph. Por ejemplo, users?$count=true.
  2. Como segmento de dirección URL para recuperar el total entero de la colección. Por ejemplo, users/$count.
  3. En una expresión $filter con operadores de igualdad para recuperar una colección de datos donde la propiedad filtrada es una colección vacía. Consulte Uso del parámetro de consulta $filter para filtrar una colección de objetos.

Nota:

  1. En los recursos que derivan de directoryObject, $count solo se admite en una consulta avanzada. Consulte Funcionalidades avanzadas de consulta en objetos de directorio.
  2. 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 colecciones de los siguientes recursos usados con frecuencia 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 puede especificar las propiedades que se devolverán en los recursos expandidos agregando un $select parámetro. En el ejemplo siguiente se realiza la misma consulta que en el ejemplo anterior, pero se usa una $select instrucción 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, managery memberOf en un usuario, pero no puede expandir sus relaciones deeventos, mensajeso fotos. No todos los recursos o relaciones admiten el uso de $select en elementos expandidos.

  • Con Microsoft Entra recursos 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. Para obtener más información, consulte limitaciones de parámetros de consulta.

  • $expand no se admite actualmente con las consultas avanzadas.

parámetro de filtrado

Use el parámetro de consulta $filter para recuperar solo un subconjunto de una colección. Para obtener instrucciones sobre el uso $filterde , consulte Uso del parámetro de consulta $filter para filtrar una colección de objetos.

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), aunque 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 siguiente solicitud obtiene mensajes y los ordena por el campo de dirección 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).

Con algunas API se pueden ordenar los resultados por varias propiedades. 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 avanzadas de consulta en 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.

Al realizar una solicitud GET sin usar $select para limitar la cantidad de datos de propiedades, Microsoft Graph incluye una propiedad @microsoft.graph.tips que proporciona una recomendación de procedimientos recomendados para usar $select de forma similar al siguiente mensaje:

"@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET groups?$select=appMetadata,assignedLabels",

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 aquellas 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 Microsoft Entra recursos que derivan de directoryObject, como usuario y grupo, devuelven un subconjunto limitado y predeterminado de propiedades en las lecturas. Para estos recursos, debe usar $select para devolver propiedades fuera del conjunto predeterminado.

parámetros de omisión

Use el $skip parámetro de consulta para establecer el número de elementos que se omitirán al principio de una colección. Por ejemplo, la siguiente solicitud devuelve eventos para el usuario ordenado 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

En algunas API de Microsoft Graph, como Correo y Calendario de Outlook (mensaje, evento y calendario), 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.

Los objetos de directorio , como el usuario, el grupo y la aplicación , no admiten $skip.

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 los 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 $top consulta para especificar el número de elementos que se incluirán en el resultado.

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

Nota:

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 user/photo relación.

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.