Pesquisar arquivos e pastas

Este guia explica como a API Google Drive oferece várias maneiras de pesquisar arquivos e pastas.

Você pode usar o list método no files recurso para retornar todos ou alguns dos arquivos e pastas de um usuário do Drive. Também é possível usar o list método para recuperar o fileId necessário para alguns métodos de recursos, como get e update.

Usar o parâmetro "fields"

Se você quiser especificar os campos a serem retornados na resposta, defina o fields parâmetro do sistema com qualquer método do recurso files. Se você omitir 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 retorna apenas os kind, id, name, mimeType e resourceKey campos para cada arquivo. Para retornar campos diferentes, consulte Retornar campos específicos.

Acessar um arquivo por ID

Para acessar um arquivo, use o get método no files recurso com o fileId parâmetro de caminho. Se você não souber o ID do arquivo, você pode listar todos os arquivos usando o list método.

O método retorna o arquivo como uma instância de um recurso files. Se você fornecer o parâmetro alt=media, a resposta vai incluir o conteúdo do arquivo no corpo da resposta. Para fazer o download de um arquivo blob, consulte Fazer o download do conteúdo de um arquivo blob.

Para reconhecer o risco de fazer o download de malware conhecido ou outros abusivos arquivos, defina o acknowledgeAbuse parâmetro de consulta como true. Esse campo só é aplicável quando o parâmetro alt=media está definido e o usuário é o proprietário do arquivo ou um organizador do drive compartilhado em que o arquivo está localizado.

Listar todos os arquivos e pastas no Meu Drive

Use o método list sem parâmetros para retornar todos os arquivos e pastas no Meu Drive do usuário atual.

O comando curl a seguir mostra como listar todos os arquivos:

curl -X GET \
  'https://www.googleapis.com/drive/v3/files' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Accept: application/json'

Substitua ACCESS_TOKEN por um token de acesso autorizado do OAuth 2.0.

Pesquisar arquivos e pastas específicos no Meu Drive

Para pesquisar um conjunto específico de arquivos ou pastas no Meu Drive do usuário atual, use o campo de string de consulta q com o método list para filtrar os arquivos a serem retornados combinando um ou mais termos de pesquisa.

A sintaxe da string de consulta contém as três partes a seguir:

query_term operator values

Em que:

  • query_term é o termo ou campo de consulta a ser pesquisado.

  • operator especifica a condição do termo de consulta.

  • values são os valores específicos que você quer usar para filtrar os resultados da pesquisa.

Por exemplo, a string de consulta a seguir filtra a pesquisa para retornar apenas pastas definindo o tipo MIME:

mimeType = 'application/vnd.google-apps.folder'

Para conferir todos os termos de consulta de arquivos, consulte Termos de consulta específicos de arquivos.

Para conferir todos os operadores de consulta que podem ser usados para criar uma consulta, consulte Operadores de consulta.

Exemplos de strings de consulta

A tabela a seguir lista exemplos de algumas strings de consulta básicas. O código real difere dependendo da biblioteca de cliente usada para a pesquisa.

Você também precisa fazer o escape de caracteres especiais nos nomes de arquivos para garantir que a consulta funcione corretamente. Por exemplo, se um nome de arquivo contiver um apóstrofo (') e uma barra invertida ("\"), use uma barra invertida para fazer o escape deles: name contains 'quinn\'s paper\\essay'.

O que consultar Exemplo
Operador de correspondência de string (contains)
Arquivos que contêm a palavra "hello" fullText contains 'hello'
Arquivos que contêm a frase exata "hello world" fullText contains '"hello world"'
Arquivos com uma consulta que contém o caractere "\" (por exemplo, "\authors") fullText contains '\\authors'
Arquivos com um nome que contém "budget" name contains 'budget'
Operadores de igualdade e desigualdade (=, !=)
Arquivos com o nome "hello" name = 'hello'
Arquivos que são pastas mimeType = 'application/vnd.google-apps.folder'
Arquivos que não são pastas mimeType != 'application/vnd.google-apps.folder'
Arquivos com estrela starred = true
Arquivos na lixeira trashed = true
Arquivos que não estão na lixeira trashed = false
Atalhos que apontam para um ID de arquivo específico shortcutDetails.targetId = '1987654321'
Arquivos que não foram compartilhados com ninguém ou domínios (particulares ou compartilhados com usuários ou grupos específicos) visibility = 'limited'
Arquivos que podem ser acessados por qualquer pessoa com o link visibility = 'anyoneWithLink'
Arquivos que podem ser descobertos publicamente na Web visibility = 'anyoneCanFind'
Operadores de comparação (>, >=, <, <=)
Arquivos modificados após uma determinada data (o fuso horário padrão é UTC) modifiedTime > '2012-06-04T12:00:00'
Arquivos criados após 1º de janeiro de 2023 createdTime > '2023-01-01T00:00:00'
Arquivos modificados antes de 1º de janeiro de 2023 modifiedTime < '2023-01-01T00:00:00'
Operador de associação de coleção (in)
Arquivos em uma coleção (por exemplo, o ID da pasta na coleção parents) '1234567' in parents
Arquivos na pasta de dados do aplicativo 'appDataFolder' in parents
Arquivos em que o usuário "test@example.org" é o proprietário 'test@example.org' in owners
Arquivos em que o usuário "test@example.org" tem permissão de gravação 'test@example.org' in writers
Arquivos em que os membros do grupo "group@example.org" têm permissão de gravação 'group@example.org' in writers
Arquivos em que o usuário "test@example.org" tem permissão de leitura 'test@example.org' in readers
Operador de correspondência de coleção (has)
Arquivos com uma propriedade de arquivo personalizada visível para todos os apps properties has { key='mass' and value='1.3kg' }
Arquivos com uma propriedade de arquivo personalizada privada para o app solicitante appProperties has { key='additionalID' and value='8e8aceg2af2ge72e78' }
Arquivos que têm uma propriedade de arquivo personalizada com a chave "department" (independente do valor) properties has { key='department' }
Operadores lógicos (and, or, not)
Arquivos com um nome que contém as palavras "hello" e "goodbye" name contains 'hello' and name contains 'goodbye'
Arquivos com um nome que não contém a palavra "hello" not name contains 'hello'
Arquivos que contêm o texto "important" e estão na lixeira fullText contains 'important' and trashed = true
Arquivos que não contêm a palavra "hello" not fullText contains 'hello'
Arquivos de imagem ou vídeo modificados após uma data específica modifiedTime > '2012-06-04T12:00:00' and (mimeType contains 'image/' or mimeType contains 'video/')
Arquivos compartilhados com o usuário autorizado que têm "hello" no nome sharedWithMe and name contains 'hello'
Arquivos que são pastas ou atalhos mimeType = 'application/vnd.google-apps.folder' or mimeType = 'application/vnd.google-apps.shortcut'
Arquivos com o nome "Project Plan" que não estão na lixeira name = 'Project Plan' and trashed = false
Arquivos em uma pasta específica que não estão na lixeira '1234567' in parents and trashed = false

Filtrar resultados da pesquisa com uma biblioteca de cliente

O exemplo de código a seguir mostra como usar uma biblioteca de cliente para filtrar os resultados da pesquisa para nomes de arquivos e IDs de arquivos JPEG. Esse exemplo usa o termo de consulta mimeType para restringir os resultados a arquivos do tipo image/jpeg. Ele também define spaces como drive para restringir ainda mais a pesquisa ao espaço do Drive. Quando nextPageToken retorna null, não há mais resultados.

Java

drive/snippets/drive_v3/src/main/java/SearchFile.java
import com.google.api.client.http.HttpRequestInitializer;
import com.google.api.client.http.javanet.NetHttpTransport;
import com.google.api.client.json.gson.GsonFactory;
import com.google.api.services.drive.Drive;
import com.google.api.services.drive.DriveScopes;
import com.google.api.services.drive.model.File;
import com.google.api.services.drive.model.FileList;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;
import java.io.IOException;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;

/* Class to demonstrate use-case of search files. */
public class SearchFile {

  /**
   * Search for specific set of files.
   *
   * @return search result list.
   * @throws IOException if service account credentials file not found.
   */
  public static List<File> searchFile() throws IOException {
           /*Load pre-authorized user credentials from the environment.
           TODO(developer) - See https://developers.google.com/identity for
           guides on implementing OAuth2 for your application.*/
    GoogleCredentials credentials = GoogleCredentials.getApplicationDefault()
        .createScoped(Arrays.asList(DriveScopes.DRIVE_FILE));
    HttpRequestInitializer requestInitializer = new HttpCredentialsAdapter(
        credentials);

    // Build a new authorized API client service.
    Drive service = new Drive.Builder(new NetHttpTransport(),
        GsonFactory.getDefaultInstance(),
        requestInitializer)
        .setApplicationName("Drive samples")
        .build();

    List<File> files = new ArrayList<File>();

    String pageToken = null;
    do {
      FileList result = service.files().list()
          .setQ("mimeType='image/jpeg'")
          .setSpaces("drive")
          .setFields("nextPageToken, files(id, title)")
          .setPageToken(pageToken)
          .execute();
      for (File file : result.getFiles()) {
        System.out.printf("Found file: %s (%s)\n",
            file.getName(), file.getId());
      }

      files.addAll(result.getFiles());

      pageToken = result.getNextPageToken();
    } while (pageToken != null);

    return files;
  }
}

Python

drive/snippets/drive-v3/file_snippet/search_file.py
import google.auth
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError


def search_file():
  """Search file in drive location

  Load pre-authorized user credentials from the environment.
  TODO(developer) - See https://developers.google.com/identity
  for guides on implementing OAuth2 for the application.
  """
  creds, _ = google.auth.default()

  try:
    # create drive api client
    service = build("drive", "v3", credentials=creds)
    files = []
    page_token = None
    while True:
      # pylint: disable=maybe-no-member
      response = (
          service.files()
          .list(
              q="mimeType='image/jpeg'",
              spaces="drive",
              fields="nextPageToken, files(id, name)",
              pageToken=page_token,
          )
          .execute()
      )
      for file in response.get("files", []):
        # Process change
        print(f'Found file: {file.get("name")}, {file.get("id")}')
      files.extend(response.get("files", []))
      page_token = response.get("nextPageToken", None)
      if page_token is None:
        break

  except HttpError as error:
    print(f"An error occurred: {error}")
    files = None

  return files


if __name__ == "__main__":
  search_file()

Node.js

drive/snippets/drive_v3/file_snippets/search_file.js
import {GoogleAuth} from 'google-auth-library';
import {google} from 'googleapis';

/**
 * Searches for files in Google Drive.
 * @return {Promise<object[]>} A list of files.
 */
async function searchFile() {
  // Authenticate with Google and get an authorized client.
  // TODO (developer): Use an appropriate auth mechanism for your app.
  const auth = new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/drive',
  });

  // Create a new Drive API client (v3).
  const service = google.drive({version: 'v3', auth});

  // Search for files with the specified query.
  const result = await service.files.list({
    q: "mimeType='image/jpeg'",
    fields: 'nextPageToken, files(id, name)',
    spaces: 'drive',
  });

  // Print the name and ID of each found file.
  (result.data.files ?? []).forEach((file) => {
    console.log('Found file:', file.name, file.id);
  });

  return result.data.files ?? [];
}

PHP

drive/snippets/drive_v3/src/DriveSearchFiles.php
<?php
use Google\Client;
use Google\Service\Drive;
function searchFiles()
{
    try {
        $client = new Client();
        $client->useApplicationDefaultCredentials();
        $client->addScope(Drive::DRIVE);
        $driveService = new Drive($client);
        $files = array();
        $pageToken = null;
        do {
            $response = $driveService->files->listFiles(array(
                'q' => "mimeType='image/jpeg'",
                'spaces' => 'drive',
                'pageToken' => $pageToken,
                'fields' => 'nextPageToken, files(id, name)',
            ));
            foreach ($response->files as $file) {
                printf("Found file: %s (%s)\n", $file->name, $file->id);
            }
            array_push($files, $response->files);

            $pageToken = $response->pageToken;
        } while ($pageToken != null);
        return $files;
    } catch(Exception $e) {
       echo "Error Message: ".$e;
    }
}

Listar arquivos em uma pasta pública

Para pesquisar ou listar arquivos em uma pasta compartilhada publicamente (em que o acesso está definido como "Qualquer pessoa com o link" ou "Público na Web"), use o método list no recurso files com o parâmetro de consulta q query definido para filtrar pelo ID da pasta na coleção parents:

'FOLDER_ID' in parents and trashed = false

Ao listar arquivos em uma pasta pública, é possível autenticar solicitações usando uma chave de API em vez de credenciais de usuário do OAuth 2.0. Se a pasta estiver localizada em um drive compartilhado, você também precisará definir supportsAllDrives=true e includeItemsFromAllDrives=true na solicitação.

Os exemplos de código a seguir mostram como listar arquivos em uma pasta pública:

Node.js

/**
 * List files in a public folder using an API key.
 * @param {string} folderId The ID of the public folder.
 * @param {string} apiKey Your Google Cloud API key.
 * @return {Promise<Array>} The list of files.
 */
async function listPublicFolder(folderId, apiKey) {
  const {google} = require('googleapis');
  const service = google.drive({version: 'v3', auth: apiKey});

  try {
    const response = await service.files.list({
      q: `'${folderId}' in parents and trashed = false`,
      fields: 'nextPageToken, files(id, name, mimeType)',
      supportsAllDrives: true,
      includeItemsFromAllDrives: true,
    });
    const files = response.data.files;
    console.log('Files:');
    for (const file of files) {
      console.log(`${file.name} (${file.id})`);
    }
    return files;
  } catch (err) {
    // TODO(developer): Handle error
    console.error(err);
  }
}

curl

curl -G \
  'https://www.googleapis.com/drive/v3/files' \
  --data-urlencode "q='FOLDER_ID' in parents and trashed = false" \
  --data-urlencode 'supportsAllDrives=true' \
  --data-urlencode 'includeItemsFromAllDrives=true' \
  --data-urlencode 'fields=nextPageToken,files(id,name,mimeType)' \
  --data-urlencode 'key=API_KEY' \
  -H 'Accept: application/json'

Substitua:

Pesquisar arquivos com propriedades personalizadas

Para pesquisar arquivos com uma propriedade de arquivo personalizada, use o termo de consulta properties ou appProperties com uma chave e um valor. Por exemplo, para pesquisar uma propriedade de arquivo personalizada que seja privada para o app solicitante chamado additionalID com um valor de 8e8aceg2af2ge72e78:

appProperties has { key='additionalID' and value='8e8aceg2af2ge72e78' }

Para mais informações, consulte Adicionar propriedades de arquivo personalizadas.

Pesquisar arquivos por rótulo ou valor de campo

Para pesquisar arquivos com rótulos específicos, use o termo de consulta labels com um ID de rótulo específico.

Para pesquisar arquivos que têm um rótulo específico aplicado:

'labels/LABEL_ID' in labels

Para pesquisar arquivos que não têm um rótulo específico aplicado:

not 'labels/LABEL_ID' in labels

Para pesquisar arquivos com base em um valor de campo de rótulo específico:

labels/LABEL_ID.FIELD_ID = 'VALUE'

Se a solicitação for bem-sucedida, o corpo da resposta vai conter todas as instâncias de arquivo que correspondem à consulta. Para mais informações, consulte Pesquisar arquivos com um rótulo ou valor de campo.

Pesquisar em todos os corpora

Por padrão, a coleção de itens user é definida no parâmetro de consulta corpora quando o método list é usado. Para pesquisar outras coleções de itens, como aquelas compartilhadas com um domain, defina explicitamente o parâmetro corpora.

É possível pesquisar vários corpora em uma única consulta. No entanto, se os corpora combinados forem muito grandes, a API poderá retornar resultados incompletos. Verifique o incompleteSearch campo no corpo da resposta. Se for true, alguns documentos foram omitidos. Para resolver isso, restrinja o corpora para usar user ou drive.

Ao usar o orderBy parâmetro de consulta no método list, evite usar a chave createdTime para consultas em coleções de itens grandes, porque ela exige processamento adicional e pode resultar em tempos limite ou outros problemas. Para classificação relacionada ao tempo em coleções de itens grandes, use modifiedTime, já que ele é otimizado para processar essas consultas. Por exemplo, defina orderBy como modifiedTime (ou modifiedTime desc).

Se você omitir o parâmetro de consulta orderBy, não haverá uma ordem de classificação padrão, e os itens serão retornados arbitrariamente.