Retornar campos específicos para um arquivo

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

Por padrão, o servidor retorna um conjunto de campos específicos para o recurso que está sendo consultado. Por exemplo, o método files.get pode retornar apenas id, name e mimeType para o recurso files. O método permissions.get retorna um conjunto diferente de campos padrão para um recurso permissions.

Depois que o servidor processar uma solicitação válida que inclua o parâmetro de consulta fields, ele retornará um código de status HTTP 200 OK com os dados solicitados. Se o parâmetro de consulta de campos 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 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 consulta 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 ver quais campos podem ser retornados para um arquivo, consulte a documentação do recurso files.

Regras de formato dos parâmetros de campo

O formato do valor do parâmetro de solicitação de campos se baseia vagamente na sintaxe do XPath. Veja 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 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 desse caractere curinga pode afetar negativamente o desempenho da solicitação.

Mostrar um exemplo

Solicitação

Neste exemplo, fornecemos o parâmetro do 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 do 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 serão buscados.

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

  • permissions.get com fields=role ou fields=*.
  • files.get com fields=permissions(role) ou fields=permissions/role.
  • files.get com fields=permissions para indicar todos os campos do recurso aninhado.
  • 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).

Mostrar um exemplo

Solicitação

Neste exemplo, fornecemos o parâmetro do 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 do 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"
    }
  ]
}