Retornar campos específicos para um arquivo

Para retornar os campos exatos necessários e melhorar a performance, 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 do 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 informando o que há de errado com a seleção de campos. Por exemplo, files.list(fields='files(id,capabilities,canAddChildren)') produz 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 você pode retornar usando o parâmetro fields, visite 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 do parâmetro de campo

O formato do valor do parâmetro de 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 campo b que está 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 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 de permissão disponíveis por permissão. O uso desse caractere curinga pode causar impactos negativos no desempenho da solicitação.

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

{
  "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 ou fields=*.
• files.get com fields=permissions(role) ou fields=permissions/role.
• files.get por fields=permissions para implicar 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).

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

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