Pesquisar arquivos e pastas

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

Use o método list no recurso files para retornar todos ou alguns dos arquivos e pastas de um usuário do Drive. O método list também pode ser usado 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 parâmetro do sistema fields 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 método list retorna apenas os campos kind, id, name, mimeType e resourceKey de cada arquivo. Para retornar campos diferentes, consulte Retornar campos específicos.

Acessar um arquivo

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

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

Para reconhecer o risco de baixar malware conhecido ou outros arquivos abusivos, defina o parâmetro de consulta acknowledgeAbuse 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á.

Pesquisar todos os arquivos e pastas no Meu Drive do usuário atual

Use o método list sem parâmetros para retornar todos os arquivos e pastas.

GET https://www.googleapis.com/drive/v3/files

Pesquisar arquivos ou pastas específicos no Meu Drive do usuário atual

Para pesquisar um conjunto específico de arquivos ou pastas, use o campo q da string de consulta 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:

q: 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 string de consulta

A tabela a seguir lista exemplos de algumas strings de consulta básicas. O código real varia de acordo com a biblioteca de cliente usada na pesquisa.

Também é necessário escapar caracteres especiais nos nomes dos 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 você quer consultar Exemplo
Arquivos com o nome "hello" name = 'hello'
Arquivos com um nome que contenha 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 "importante" e estão na lixeira fullText contains 'important' and trashed = true
Arquivos que contêm a palavra "hello" fullText contains 'hello'
Arquivos que não têm a palavra "hello" not 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 que são pastas mimeType = 'application/vnd.google-apps.folder'
Arquivos que não são pastas mimeType != 'application/vnd.google-apps.folder'
Arquivos modificados após uma determinada data (o fuso horário padrão é UTC) modifiedTime > '2012-06-04T12:00:00'
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 marcados com estrela starred = true
Arquivos em uma coleção (por exemplo, o ID da pasta na coleção parents) '1234567' in parents
Arquivos em uma pasta de dados do aplicativo em uma coleção '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 compartilhados com o usuário autorizado que têm "olá" no nome sharedWithMe and name contains 'hello'
Arquivos com uma propriedade 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 não foram compartilhados com ninguém ou domínios (apenas particulares ou compartilhados com usuários ou grupos específicos) visibility = 'limited'

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 por nomes de arquivos e IDs de arquivos JPEG. Este 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, items(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
/**
 * Search file in drive location
 * @return{obj} data file
 * */
async function searchFile() {
  const {GoogleAuth} = require('google-auth-library');
  const {google} = require('googleapis');

  // Get credentials and build service
  // TODO (developer) - Use appropriate auth mechanism for your app
  const auth = new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/drive',
  });
  const service = google.drive({version: 'v3', auth});
  const files = [];
  try {
    const res = await service.files.list({
      q: 'mimeType=\'image/jpeg\'',
      fields: 'nextPageToken, files(id, name)',
      spaces: 'drive',
    });
    Array.prototype.push.apply(files, res.files);
    res.data.files.forEach(function(file) {
      console.log('Found file:', file.name, file.id);
    });
    return res.data.files;
  } catch (err) {
    // TODO(developer) - Handle error
    throw err;
  }
}

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;
    }
}

Pesquisar arquivos com uma propriedade personalizada

Para pesquisar arquivos com uma propriedade personalizada, use o termo de consulta properties ou appProperties com uma chave e um valor. Por exemplo, para pesquisar uma propriedade de arquivo personalizada particular 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 com um marcador ou valor de campo específico

Para pesquisar arquivos com rótulos específicos, use o termo de consulta labels com um ID de rótulo específico. Por exemplo, 'labels/LABEL_ID' in labels. Se a solicitação for bem-sucedida, o corpo da resposta vai conter todas as instâncias de arquivo em que o rótulo foi aplicado.

Para pesquisar arquivos sem um ID de marcador específico: Not 'labels/LABEL_ID' in labels.

Também é possível pesquisar arquivos com base em valores de campo específicos. Por exemplo, para pesquisar arquivos com um valor de texto: labels/LABEL_ID.text_field_id ='TEXT'.

Para mais informações, consulte Pesquisar arquivos com um rótulo ou valor de campo específico.

Pesquisar nos corpora

As pesquisas que chamam o método list usam o corpora de user por padrão. Para pesquisar outros corpora, como arquivos compartilhados com um domain, defina o parâmetro corpora.

É possível pesquisar vários corpus em uma única consulta, mas resultados incompletos podem ser retornados se o corpus combinado for muito grande. Se incompleteSearch for true no corpo da resposta, significa que nem todos os documentos foram retornados. Se isso acontecer, refine a consulta escolhendo um corpus diferente, como user ou drive.