Pesquisar arquivos e pastas

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

É possível usar o list método no files recurso 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 o get método e o update) método.

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.

Receber um arquivo

Para receber 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 baixar um arquivo blob, consulte Baixar conteúdo de arquivo blob.

Para reconhecer o risco de baixar 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 reside.

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 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:

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 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'.

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. 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.

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

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()

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
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 de arquivo personalizada

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

Para pesquisar arquivos com marcadores específicos, use o termo de consulta de pesquisa labels com um ID de marcador específico. Por exemplo: 'labels/LABEL_ID' in labels. Se for bem-sucedido, o corpo da resposta vai conter todas as instâncias de arquivo em que o marcador está 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 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 as 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, ?orderBy=modifiedTime.

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

Temas relacionados

• Pesquisar drives compartilhados
• Termos e operadores de consulta de pesquisa
• Tipos MIME compatíveis com o Google Workspace e o Google Drive
• Papéis e permissões
• Pesquisar arquivos com um rótulo ou valor de campo específico