Compartir a través de


Usar parámetros de consulta para personalizar respuestas

Microsoft Graph admite parámetros de consulta 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 de API a otra y, en función de la API, puede diferir entre los puntos de conexión v1.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.0 , el $ prefijo es opcional solo para un subconjunto de API. Por motivos de simplicidad, incluya siempre $ en todas las versiones.

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 compatibles con una API y sus propiedades, consulte la tabla "Propiedades" de la página de recursos y la sección "Parámetros de consulta opcionales" de las operaciones LIST y GET para 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

Obtener un recuento de usuarios
$ref Actualice la pertenencia a entidades en una colección. POST /groups/{id}/members/$ref

Adición de un miembro a un grupo
$value Recupere o actualice el valor binario de un elemento. GET /me/photo/$value

Obtener la foto de un usuario, grupo o equipo
$batch Combine varias solicitudes HTTP en una solicitud por lotes. POST /$batch

Procesamiento por lotes JSON

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 Explorador de Graph) controlan esta codificación automáticamente. Si se produce un error en una consulta, una posible causa es un error al codificar los valores de parámetro de consulta correctamente. En algunos casos, debe codificar dos veces los valores.

Nota:

Hay un problema conocido relacionado con la codificación de símbolos de ampersand (&) en $search expresiones en el punto de conexión v1.0 . 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 el caso de las solicitudes que usan comillas simples, si los valores de parámetro también contienen comillas simples, deben tener dos caracteres de escape; De lo contrario, se produce un error en la solicitud debido a una sintaxis no 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 de una propiedad @odata.count .

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

En el caso de los objetos de directorio, es decir, los recursos que derivan de directoryObject, el parámetro de $count consulta solo se admite en consultas avanzadas.

parámetro de expansión

Muchos de los recursos de Microsoft Graph exponen ambas propiedades declaradas de los recursos y 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.

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). Para algunas API, solo se puede expandir una relación en una sola 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 los recursos de Microsoft Entra 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 $format parámetro de consulta admite varios formatos (por ejemplo, , atomxmly json), pero es posible que los resultados no se devuelvan en todos los formatos.

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 siguiente solicitud devuelve los usuarios de la organización ordenados por su nombre para mostrar en orden ascendente:

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

Algunas API admiten la ordenación 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 o ascdesc al nombre del campo, separados por un espacio; por ejemplo, ?$orderby=name desc (sin codificar), ?$orderby=name%20desc (url codificada). Si no se especifica el criterio de ordenación, se deduce el orden ascendente predeterminado.

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:

Cuando se especifica $filter, el servicio deduce 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 $select consulta para devolver un subconjunto de propiedades para un recurso. 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 la versión 1.0, algunos recursos de Microsoft Entra 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 abarcan varias páginas, estas API devuelven una propiedad @odata.nextLink con una dirección URL que contiene un $skip parámetro. 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.
Este parámetro contiene un token opaco que hace referencia a la página siguiente de resultados y se devuelve en la dirección URL proporcionada en la propiedad @odata.nextLink de la respuesta. Para obtener 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 contiene 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 devuelven 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"
        }
    }
}

Sin embargo, a veces los parámetros de consulta especificados en una solicitud producen un error silencioso. Por ejemplo, para parámetros de consulta no admitidos y para combinaciones no admitidas 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.