Retornar campos específicos

Para retornar os campos exatos necessários e melhorar o desempenho, use o parâmetro do sistema fields na chamada de método.

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

Como o parâmetro de campos funciona

O parâmetro fields usa uma FieldMask para filtrar respostas. As máscaras de campo são usadas para especificar um subconjunto de campos que uma solicitação precisa retornar. O uso de 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 o 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 para o 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), é necessá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, além dos dados solicitados. Se o parâmetro de campos tiver um erro ou for inválido, o servidor vai retornar um código de status HTTP 400 Bad Request com uma mensagem de erro informando o que está errado com a seleção de campos. Por exemplo, files.list(fields='files(id,capabilities,canAddChildren)') gera um erro de "Seleção de campo inválida 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 você pode retornar para um arquivo, consulte a documentação do recurso files. Para mais termos de consulta específicos do arquivo, consulte Termos e operadores de pesquisa.

Regras de formatação de parâmetros de campo

O formato do valor do parâmetro de solicitação de campos baseia-se vagamente na sintaxe XPath. Confira a seguir as regras de formatação para o 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 Buscar os campos de um recurso aninhado.

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

  • Para retornar todos os campos em um objeto, use um asterisco (*) como um 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 caractere curinga pode afetar negativamente a 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 de campo 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
  }
}

Buscar 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 determinados campos do recurso de permissões aninhadas, como um parâmetro de consulta na solicitação. A resposta retorna os valores de campo 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"
    }
  ]
}