Retornar campos específicos para um arquivo

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

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

Depois que um servidor processar uma solicitação válida que inclua a consulta fields ele retorna um código de status HTTP 200 OK, junto com a solicitação dados. Se o parâmetro de consulta dos campos tiver um erro ou for inválido, o servidor retorna um código de status HTTP 400 Bad Request com um erro informando o que há de errado com a seleção dos 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 dos campos corretos para neste exemplo files.list(fields='files(id,capabilities/canAddChildren)'):

Para determinar os campos que podem ser retornados usando o parâmetro fields, acesse o página de documentação do recurso que você está consultando. Por exemplo, para saber qual campos que 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 dos campos se baseia vagamente em XPath . Veja a seguir as regras de formatação para o parâmetro fields. Todas as elas 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 aninhada recurso.

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

  • Para retornar todos os campos de um objeto, use um asterisco como curinga no campo seleções Por exemplo, 'permissions/permissionDetails/*' seleciona tudo disponíveis por permissão. Observe que o uso de esse caractere curinga pode afetar negativamente o desempenho da solicitação.

Mostrar um exemplo

Solicitação

Neste exemplo, fornecemos o parâmetro de caminho do ID de 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 precisa ser buscado.

Por exemplo, para recuperar o campo role (recurso aninhado) do 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 com fields=permissions para implicar todos os campos do aninhado recurso.
  • 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 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"
    }
  ]
}