Usar parâmetros da consulta para alterar a forma de uma resposta

Artigo
04/08/2023

A API do OneDrive oferece vários parâmetros de consulta opcionais que podem ser usados para controlar os dados específicos retornados em uma resposta.

O que é abordado neste tópico:

Selecionando propriedades
Expandindo coleções
Classificação de coleções

Selecionando propriedades

Você pode usar o parâmetro selecionar cadeia de caracteres de consulta para fornecer uma lista separada por vírgulas de propriedades para retornar em Itens.

Exemplo

Este exemplo seleciona somente as propriedades name e size a serem retornadas ao recuperar os filhos de um item.

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

Quando a solicitação é enviada com a cadeia de caracteres de consulta select=name,size, os objetos na resposta apresentam somente os valores de propriedade incluídos. Ao usar a instrução select, você precisa especificar todas as propriedades a serem retornadas na instrução.

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

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

Expandindo coleções

Em solicitações da API do OneDrive, coleções children (filhas) de itens referenciados não são expandidas automaticamente. Isso ocorre por design porque reduz o tráfego de rede e o tempo necessário para gerar uma resposta do serviço. No entanto, em alguns casos pode ser ideal incluir esses resultados em uma resposta.

Você pode usar o parâmetro da cadeia de caracteres de consulta expand para instruir a API da OneDrive a expandir uma coleção children e incluir aqueles resultados.

Por exemplo, para recuperar as informações da unidade raiz e os itens de nível superior em uma unidade, use o parâmetro expand, como no exemplo abaixo. Este exemplo também usa uma instrução select para retornar apenas as propriedades id e name dos itens filhos.

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

A solicitação retorna os itens da coleção, com a coleção children 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",
    }
  ]
}

Classificando coleções

Para controlar a ordem de classificação de itens retornados da API do OneDrive, você pode usar a cadeia de caracteres de consulta orderby. Para uma coleção de itens, use os campos a seguir no parâmetro orderby.

name
size
lastModifiedDateTime

No OneDrive for Business e no SharePoint Server 2016, a cadeia de caracteres de consulta orderby só funciona com name e url.

Para classificar os resultados em ordem crescente ou decrescente, anexe asc ou desc ao nome do campo, separado por um espaço, por exemplo, ?orderby=name%20desc.

Por exemplo, para retornar os conteúdos da raiz de uma unidade no OneDrive, ordenados do maior para o menor, use esta sintaxe: /drive/items/root/children?orderby=size%20desc.

Parâmetros de consulta OData opcionais

Aqui está uma tabela de parâmetros de consulta OData opcionais que você pode usar em suas solicitações da API do OneDrive.

Name	Valor	Status	Descrição
expand	string	disponível	Lista separada por vírgulas de relações para expandir e incluir na resposta. Por exemplo, para recuperar os filhos de uma pasta, use `expand=children`.
select	string	disponível	Lista separada por vírgulas de propriedades para incluir na resposta.
skipToken	string	disponível	Token de paginação usado para obter o conjunto seguinte de resultados.
top	int	disponível	O número de itens a serem retornados em um conjunto de resultados. A API do OneDrive pode ter um limite rígido que impede você de pedir mais itens por resposta.
orderby	string	disponível	Lista separada por vírgula de propriedades que são usadas para classificar a ordem dos itens na coleção de resposta. Funciona para os campos `name`, `size` e `lastModifiedDateTime`.
filter	string	não disponível	A cadeia de caracteres de filtro que permite filtrar a resposta com base em um conjunto de critérios.

Observação: O padrão OData coloca o prefixo $ nesses termos. A API do OneDrive oferece suporte para o uso desses parâmetros de consulta com ou sem o caractere especial, mas você deve ser consistente quanto ao uso do caractere $ nesses argumentos em toda a solicitação.

Compartilhar via