Para retornar os campos exatos de que você precisa e melhorar o desempenho, use o parâmetro de consulta fields
na chamada de método.
Por padrão, o servidor envia de volta 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 há de 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 saber quais
campos podem ser retornados para um arquivo, consulte a documentação do recurso files
.
Regras de formatação de parâmetros de campo
O formato do valor do parâmetro da solicitação de campos se baseia vagamente na sintaxe 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 campob
que está aninhado no campoa
, 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, colocando expressões entre parênteses "()". Por exemplo,
'permissions(id)'
retorna apenas o ID de permissão de 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 da permissão disponíveis por permissão. O uso desse caractere curinga pode causar impactos negativos no desempenho da solicitação.
Mostrar um exemplo
Solicitação
Neste exemplo, fornecemos o parâmetro de caminho do ID do arquivo e vários campos como parâmetro de consulta na solicitação. A resposta retorna os valores do 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, você pode especificar quais campos do recurso aninhado precisam ser buscados.
Por exemplo, para recuperar o campo role
(recurso aninhado) do recurso permissions
, use uma destas opções:
permissions.get
comfields=role
oufields=*
.files.get
comfields=permissions(role)
oufields=permissions/role
.files.get
comfields=permissions
para implicar todos os campos do recurso aninhado.changes.list
comfields=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 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 do 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" } ] }