Usar parámetros de consulta para cambiar la forma de una respuesta

Artículo
04/08/2023

La API de OneDrive proporciona varios parámetros de consulta opcionales que pueden usarse para controlar los datos específicos que se devuelven en una respuesta.

En este tema se trata:

Seleccionar propiedades
Expandir colecciones
Ordenar colecciones

Seleccionar propiedades

Puede usar el parámetro de cadena de consulta select para proporcionar una lista separada por comas de propiedades que se va a devolver en Items.

Ejemplo

Este ejemplo selecciona solo las propiedades name y size para devolverse, al recuperar los elementos secundarios de un elemento.

GET /drive/root/children?select=name,size

Al enviar la solicitud con la cadena de consulta select=name,size, los objetos en la respuesta solo incluirán esos valores de propiedad. Cuando se usa la instrucción Select, necesita especificar todas las propiedades que se van a devolver en la instrucción.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "value": [
    {
      "id": "13140a9sd9aba",
      "name": "Documents",
      "size": 1024
    },
    {
      "id": "123901909124a",
      "name": "Pictures",
      "size": 1012010210
    }
  ]
}

Expandir colecciones

En las solicitudes de la API de OneDrive, las colecciones de elementos secundarios de elementos de referencia no se expanden automáticamente. Esto es así por diseño para reducir el tráfico de la red y el tiempo que se tarda en generar una respuesta desde el servicio. En cambio, en algunos casos puede que quiera incluir esos resultados en una respuesta.

Puede usar el parámetro de cadena de consulta expand para indicar a la API de OneDrive que amplíe una colección de elementos secundarios e incluya esos resultados.

Por ejemplo, para recuperar la información de la unidad de raíz y los elementos del nivel superior en una unidad, use el parámetro expand como se muestra en el ejemplo siguiente. En este ejemplo, también se usa una instrucción select para devolver solo las propiedades id y name de los elementos secundarios.

GET /drive/root?expand=children(select=id,name)

La solicitud devuelve los elementos de la colección, con la colección de elementos secundarios expandida.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "12312312541",
  "name": "root",
  "size": 218753122201,
  "webUrl": "https://onedrive.live.com/?cid=0f040...",
  "folder": {
    "childCount": 4
  },
  "children": [
    {
      "id": "F04AA961744A809!48443",
      "name": "Applications",
    },
    {
      "id": "F04AA961744A809!92647",
      "name": "Attachments",
    },
    {
      "id": "F04AA961744A809!93269",
      "name": "Balsmiq Sketches",
    },
    {
      "id": "F04AA961744A809!65191",
      "name": "Camera imports",
    }
  ]
}

Ordenar colecciones

Para controlar el orden de clasificación de los elementos devueltos de la API de OneDrive, puede usar la cadena de consulta orderby. Para obtener una colección de elementos, use los campos siguientes en el parámetro orderby.

name
size
lastModifiedDateTime

Observe que en OneDrive para la Empresa y en SharePoint Server 2016, la cadena de consulta orderby solo funciona con name y url.

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.

Por ejemplo, para devolver el contenido de la raíz de una unidad en OneDrive, ordenado de mayor a menor, use esta sintaxis: /drive/items/root/children?orderby=size%20desc.

Parámetros de consulta opcionales de OData

Aquí se muestra una tabla de parámetros de consulta opcionales de OData que puede usar en sus solicitudes de API de OneDrive.

Nombre	Valor	Estado	Descripción
expand	string	disponible	Lista separada por comas de las relaciones para expandir e incluir en la respuesta. Por ejemplo, para recuperar los elementos secundarios de una carpeta use `expand=children`.
select	string	disponible	Lista separada por comas de las propiedades para incluir en la respuesta.
skipToken	string	disponible	Token de paginación que se usa para obtener el siguiente conjunto de resultados.
top	int	disponible	El número de elementos que se va a devolver en un conjunto de resultados. La API de OneDrive puede tener un límite fijo que le impide pedir más elementos por respuesta.
orderby	string	disponible	Lista separada por comas de las propiedades que se usan para cambiar el orden de los elementos de la colección de respuesta. Funciona para los campos `name`, `size` y `lastModifiedDateTime`.
filter	string	no disponible	Cadena de filtro que le permite filtrar la respuesta basándose en un conjunto de criterios.

Nota: El estándar de OData agrega un prefijo a estos términos con $. La API de OneDrive admite el uso de estos parámetros de consulta con o sin el carácter especial, pero debe ser coherente en toda la solicitud con el uso del carácter $ en estos argumentos.

Compartir a través de