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

  • Artigo

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

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.