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

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.

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.