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 fields parâmetro do sistema 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 um FieldMask para filtragem de 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, por sua vez, 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 list método no files recurso só retorna os campos kind, id, name, e mimeType. O get método no permissions recurso retorna um conjunto diferente de campos padrão.

Para todos os métodos dos recursos about, approvals, 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 "fields" tiver um erro ou for inválido, o servidor vai retornar um código de status HTTP 400 Bad Request, além de uma mensagem de erro informando o que há de errado com a 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 do arquivo, consulte Termos e operadores de consulta de pesquisa.

Regras de formato de parâmetro de campo

O formato do valor de parâmetro da 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 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 caractere 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 levar a impactos negativos no desempenho da solicitação.

  • Não é possível selecionar elementos individuais de um mapa quando as chaves contêm caracteres especiais (como barras / ou pontos .). Por exemplo, tentar selecionar uma chave de formato de exportação específica em exportLinks usando fields=exportLinks/application/pdf gera um erro HTTP 400 Bad Request porque o analisador de caminho interpreta a / como um delimitador de propriedade aninhada. Para recuperar pares de chave-valor com caracteres especiais nas chaves, solicite o mapa inteiro (como fields=exportLinks) e filtre os resultados no lado do cliente.

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 recuperar 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).

Para especificar campos aninhados em matrizes ou objetos aninhados, use parênteses aninhados. Por exemplo, para listar arquivos com o ID, o nome e os detalhes do proprietário aninhado (nome de exibição e endereço de e-mail), além de recuperar o token da próxima página para paginação: files.list com fields=nextPageToken,files(id,name,owners(displayName,emailAddress)).

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"
    }
  ]
}

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.