Retornar campos específicos

Este documento explica como usar o parâmetro fields no Google Drive.

Para retornar os campos exatos de que você precisa e melhorar o desempenho, use o parâmetro de sistema fields na chamada de método.

Para informações sobre outros parâmetros do sistema que se aplicam à API Drive, consulte Parâmetros alternativos do sistema.

Como o parâmetro "fields" funciona

O parâmetro fields usa uma FieldMask para filtragem de respostas. As máscaras de campo são usadas para especificar um subconjunto de campos que uma solicitação deve retornar. Usar uma máscara de campo é uma boa prática de design para garantir que você não solicite dados desnecessários, o que ajuda a evitar tempo de processamento desnecessário.

Se você não especificar o parâmetro fields, o servidor vai retornar um conjunto padrão de campos específicos do método. Por exemplo, o método list no método files retorna apenas os campos kind, id, name e mimeType. O método get no recurso permissions retorna um conjunto diferente de campos padrão.

Para todos os métodos dos recursos about, comments (exceto delete) e replies (exceto delete), é obrigatório definir o parâmetro fields. Esses métodos não retornam um conjunto padrão de campos.

Depois que um servidor processa uma solicitação válida que inclui o parâmetro fields, ele retorna um código de status HTTP 200 OK, junto com os dados solicitados. Se o parâmetro fields tiver um erro ou for inválido, o servidor retornará um código de status HTTP 400 Bad Request com uma mensagem de erro informando o que há de errado com sua seleção de campos. Por exemplo, files.list(fields='files(id,capabilities,canAddChildren)') gera um erro de "Invalid field selection canAddChildren". O parâmetro de campos correto para este exemplo é files.list(fields='files(id,capabilities/canAddChildren)').

Para determinar os campos que podem ser retornados usando o parâmetro fields, acesse a página de documentação do recurso que você está consultando. Por exemplo, para saber quais campos podem ser retornados para um arquivo, consulte a documentação do recurso files. Para mais termos de consulta específicos de arquivos, consulte Termos e operadores de consulta de pesquisa.

Regras de formato de parâmetro de campo

O formato do valor do parâmetro de solicitação "fields" baseia-se vagamente na sintaxe XPath. Confira a seguir as regras de formatação do parâmetro fields. Todas essas regras usam exemplos relacionados ao método files.get.

  • Use uma lista separada por vírgulas para selecionar vários campos, como 'name, mimeType'.

  • Use a/b para selecionar o campo b aninhado no campo a, como 'capabilities/canDownload'. Para mais informações, consulte Extrair os campos de um recurso aninhado.

  • Use um subseletor para solicitar um conjunto de subcampos específicos de matrizes ou objetos colocando as expressões entre parênteses "()". Por exemplo, 'permissions(id)' retorna apenas o ID da permissão para cada elemento na matriz de permissões.

  • Para retornar todos os campos em um objeto, use um asterisco (*) como curinga nas seleções de campo. Por exemplo, 'permissions/permissionDetails/*' seleciona todos os campos de detalhes de permissão disponíveis por permissão. O uso do curinga pode ter um impacto negativo na performance da solicitação.

Solicitação

Neste exemplo, fornecemos o parâmetro de caminho do ID do arquivo e vários campos como um parâmetro de consulta na solicitação. A resposta retorna os valores dos campos para o ID do arquivo.

GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=name,starred,shared

Resposta

{
  "name": "File1",
  "starred": false,
  "shared": true
  }
}

Extrair os campos de um recurso aninhado

Quando um campo se refere a outro recurso, é possível especificar quais campos do recurso aninhado precisam ser buscados.

Por exemplo, para extrair o campo role (recurso aninhado) do recurso permissions, use uma das seguintes opções:

  • permissions.get com fields=role.
  • permissions.get com fields=* para mostrar todos os campos permissions.
  • files.get com fields=permissions(role) ou fields=permissions/role.
  • files.get com fields=permissions para mostrar todos os campos permissions.
  • changes.list com fields=changes(file(permissions(role))).

Para recuperar vários campos, use uma lista separada por vírgulas. Por exemplo, files.list com fields=files(id,name,createdTime,modifiedTime,size).

Solicitação

Neste exemplo, fornecemos o parâmetro de caminho do ID do arquivo e vários campos, incluindo alguns campos do recurso de permissões aninhadas, como um parâmetro de consulta na solicitação. A resposta retorna os valores dos campos para o ID do arquivo.

GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=name,starred,shared,permissions(kind,type,role)

Resposta

{
  "name": "File1",
  "starred": false,
  "shared": true,
  "permissions": [
    {
      "kind": "drive#permission",
      "type": "user",
      "role": "owner"
    }
  ]
}

Parâmetros alternativos do sistema

Os parâmetros de consulta que se aplicam a todas as operações da API Google Drive estão documentados em Parâmetros do sistema.