Usar operaciones de consulta de OData en solicitudes REST de SharePoint
Sugerencia
Antes de empezar, vea los recursos siguientes:
El servicio REST de SharePoint admite una amplia variedad de operadores de cadenas de consultas OData que permiten seleccionar, filtrar y ordenar los datos solicitados.
Sugerencia
El servicio REST de SharePoint Online (y SharePoint 2016 local y versiones posteriores) admite la combinación de varias solicitudes en una sola llamada al servicio mediante la opción de consulta OData $batch . Para obtener información detallada y vínculos a los ejemplos de código, vea Realizar solicitudes de lote con las API de REST.
Seleccionar los campos para devolver
Use la opción de consulta $select para especificar qué campos devolver para una lista determinada, un elemento de lista u otro objeto de SharePoint representado por un conjunto de entidades. Puede usar $select=* para devolver todos los campos disponibles.
Nota:
En general, si no especifica la opción de $select consulta, el servicio REST devuelve todos los campos disponibles de forma predeterminada. Sin embargo, en algunos casos, algunos objetos de SharePoint incluyen propiedades que consumen muchos recursos para recuperar; Para optimizar el rendimiento del servicio REST, estas propiedades no se incluyen en la consulta predeterminada y se deben solicitar explícitamente. Por ejemplo, la propiedad SPWeb.EffectiveBasePermissions no se devuelve de forma predeterminada y debe solicitarse explícitamente mediante la opción de $select consulta.
También puede especificar que la solicitud devuelva campos proyectados de otras listas y los valores de las búsquedas. Para ello, especifique el nombre del campo en las $select opciones de consulta y $expand . Por ejemplo:
GET https://{site_url}/_api/web/lists('{list_guid}')/items?$select=Title,Products/Name&$expand=Products/Name
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
No se admiten la expansión y selección masivas de elementos relacionados.
Seleccionar los elementos para devolver
Use la opción de consulta $filter para seleccionar qué elementos devolver. En la sección Operadores de consultas de OData compatibles con el servicio REST de SharePoint enumera las opciones y funciones de comparación de consultas de filtros que puede usar con el servicio REST de SharePoint.
Consulta para campos de búsqueda de valores únicos
Los campos de búsqueda de valores únicos se representan con dos campos separados en el servicio REST de SharePoint: un campo representa al valor de campo real, y otro representa al nombre del campo. Puede ejecutar consultas en el valor del campo de búsqueda como haría con cualquier otro campo de ese tipo de datos. Por ejemplo, si el valor del campo de búsqueda es una cadena, puede usar opciones de comparación de cadenas en la consulta.
Consulta para usuarios
En el servicio REST de SharePoint, los usuarios están representados con el nombre (visualización) de usuario fácil de recordar, y no sus alias o combinación dominio\alias. Por lo tanto, construya consultas de usuario con los nombres de usuario fáciles de recordar.
Nota:
No se admiten las consultas de usuario basadas en pertenencia. No se admite el uso del operador Current para realizar consultas con el identificador del usuario actual.
Consulta de usuarios y campos de búsqueda de varios valores
Dado que los campos de búsqueda de varios valores son devueltos como una cadena de varios valores, no existe una manera de consultarlos (por ejemplo, no se admite el equivalente de un elemento Includes o un elemento NotIncludes).
Ordenar elementos devueltos
Use la opción de consulta $orderby para especificar cómo ordenar los elementos del conjunto de devolución de consultas. Para ordenar según varios campos, especifique una lista de campos separada por comas. También puede especificar si los elementos se ordenarán de manera ascendente o descendente al agregar la palabra clave asc o desc a su consulta.
Pasar de una página a otra en elementos devueltos
Use las opciones de consulta $top y $skiptoken para seleccionar un subconjunto de los elementos que, de lo contrario, devolvería la consulta.
Nota:
La opción de consulta $skip no funciona con consultas para elementos de lista de SharePoint.
La $top opción le permite seleccionar los primeros n elementos del conjunto de devolución para la devolución. Por ejemplo, el siguiente URI solicita que solo se devuelvan realmente los primeros 10 elementos del conjunto de devolución potencial:
GET https://{site_url}/_api/web/lists('{list_guid}')/items?$top=10`
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
La opción de consulta $skiptoken le permite omitir elementos hasta llegar al elemento especificado y devolver el resto.
GET https://{site_url}/_api/web/lists('{list_guid}')/items?$skiptoken=Paged=TRUE%26p_ID=5`
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
Nota:
Cuando use estas opciones de consulta, tenga en cuenta que el paginado en OData es ordinal. Por ejemplo, supongamos que está implementando un botón de página siguiente para mostrar los elementos de lista de SharePoint. Use el servicio REST para habilitar el botón para devolver los elementos del 1 al 20 cuando se hace clic y, a continuación, los elementos 21 a 40, etc. Pero supongamos que otro usuario elimina los elementos 4 y 18 entre clics del botón siguiente. En tal caso, se restablece el posicionamiento ordinal de los elementos restantes, y la visualización de los elementos 21 a 40 omite dos elementos.
Operadores de consultas de OData compatibles con el servicio REST de SharePoint
| Admitido | No admitido |
|---|---|
| Comparaciones numéricas (lt le gt ge eq ne) | Operadores aritméticos (add, sub, mul, div, mod) Funciones matemáticas básicas (round, floor, ceiling) |
| Comparaciones de cadenas startswith( {Col to query},'{string to check}' ) substringof( '{string to check}', {Col to query} ) eq ne |
endswith, replace, substring, tolower, toupper, trim, concat |
| Funciones de fecha y hora day(), month(), year(), hour(), minute(), second() | Operador DateTimeRangesOverlap Consultar si una fecha y hora cae dentro de un patrón de fecha y hora recurrente. |
En la ilustración siguiente se muestran las opciones de consultas OData admitidas.
Opciones de consultas OData admitidas
