Cómo buscar archivos y carpetas

En esta guía, se explica cómo la API de Google Drive admite varias formas de buscar archivos y carpetas.

Puedes usar el list método en el files recurso para mostrar todos o algunos de los archivos y carpetas de un usuario de Drive. También puedes usar el list método para recuperar el fileId que se requiere para algunos métodos de recursos (como los get y update métodos).

Usa el parámetro fields

Si deseas especificar los campos que se mostrarán en la respuesta, puedes configurar el fields parámetro del sistema con cualquier método del recurso files. Si omites el parámetro fields, el servidor muestra un conjunto predeterminado de campos específicos del método. Por ejemplo, el list método solo muestra los campos kind, id, name, mimeType, y resourceKey para cada archivo. Para mostrar diferentes campos, consulta Cómo mostrar campos específicos.

Obtén un archivo por su ID

Para obtener un archivo, usa el get método en el files recurso con el fileId parámetro de ruta de acceso. Si no conoces el ID del archivo, puedes enumerar todos los archivos con el list método.

El método muestra el archivo como una instancia de un recurso files. Si proporcionas el parámetro alt=media, la respuesta incluirá el contenido del archivo en el cuerpo de la respuesta. Para descargar un archivo blob, consulta Cómo descargar el contenido de un archivo blob.

Para reconocer el riesgo de descargar software malicioso conocido o cualquier otro abusivo archivo, configura el acknowledgeAbuse parámetro de consulta como true. Este campo solo se aplica cuando se configura el parámetro alt=media y el usuario es el propietario del archivo o un organizador de la unidad compartida en la que reside el archivo.

Enumera todos los archivos y carpetas en Mi unidad

Usa el método list sin parámetros para mostrar todos los archivos y carpetas en Mi unidad del usuario actual.

El siguiente comando curl muestra cómo enumerar todos los archivos:

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

Reemplaza ACCESS_TOKEN por un token de acceso de OAuth 2.0 autorizado .

Busca archivos y carpetas específicos en Mi unidad

Para buscar un conjunto específico de archivos o carpetas en Mi unidad del usuario actual, usa el campo de cadena de consulta q con el método list para filtrar los archivos que se mostrarán combinando uno o más términos de búsqueda.

La sintaxis de la cadena de consulta contiene las siguientes tres partes:

query_term operator values

Donde:

  • query_term es el término o campo de consulta en el que se buscará.

  • operator especifica la condición para el término de consulta.

  • values son los valores específicos que deseas usar para filtrar los resultados de la búsqueda.

Por ejemplo, la siguiente cadena de consulta filtra la búsqueda para mostrar solo las carpetas configurando el tipo de MIME:

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

Para ver todos los términos de consulta de archivos, consulta Términos de consulta específicos de archivos.

Para ver todos los operadores de consulta que puedes usar para crear una consulta, consulta Operadores deconsulta.

Ejemplos de cadenas de consulta

En la siguiente tabla, se enumeran ejemplos de algunas cadenas de consulta básicas. El código real difiere según la biblioteca cliente que uses para tu búsqueda.

También debes escapar los caracteres especiales en los nombres de los archivos para asegurarte de que la consulta funcione correctamente. Por ejemplo, si un nombre de archivo contiene un apóstrofe (') y un carácter de barra inversa ("\"), usa una barra inversa para escaparlos: name contains 'quinn\'s paper\\essay'.

Qué consultar Ejemplo
Operador de coincidencia de cadenas (contains)
Archivos que contienen la palabra "hello" fullText contains 'hello'
Archivos que contienen la frase exacta "hello world" fullText contains '"hello world"'
Archivos con una consulta que contiene el carácter "\" (por ejemplo, "\authors") fullText contains '\\authors'
Archivos con un nombre que contiene "budget" name contains 'budget'
Operadores de igualdad y desigualdad (=, !=)
Archivos con el nombre "hello" name = 'hello'
Archivos que son carpetas mimeType = 'application/vnd.google-apps.folder'
Archivos que no son carpetas mimeType != 'application/vnd.google-apps.folder'
Archivos destacados starred = true
Archivos en la papelera trashed = true
Archivos que no están en la papelera trashed = false
Accesos directos que apuntan a un ID de archivo específico shortcutDetails.targetId = '1987654321'
Archivos que no se compartieron con nadie ni con dominios (privados o compartidos con usuarios o grupos específicos) visibility = 'limited'
Archivos accesibles para cualquier persona que tenga el vínculo visibility = 'anyoneWithLink'
Archivos que se pueden descubrir públicamente en la Web visibility = 'anyoneCanFind'
Operadores de comparación (>, >=, <, <=)
Archivos modificados después de una fecha determinada (la zona horaria predeterminada es UTC) modifiedTime > '2012-06-04T12:00:00'
Archivos creados después del 1 de enero de 2023 createdTime > '2023-01-01T00:00:00'
Archivos modificados antes del 1 de enero de 2023 modifiedTime < '2023-01-01T00:00:00'
Operador de pertenencia a la colección (in)
Archivos dentro de una colección (por ejemplo, el ID de carpeta en la colección parents) '1234567' in parents
Archivos en la carpeta de datos de la aplicación 'appDataFolder' in parents
Archivos para los que el usuario "test@example.org" es el propietario 'test@example.org' in owners
Archivos para los que el usuario "test@example.org" tiene permiso de escritura 'test@example.org' in writers
Archivos para los que los miembros del grupo "group@example.org" tienen permiso de escritura 'group@example.org' in writers
Archivos para los que el usuario "test@example.org" tiene permiso de lectura 'test@example.org' in readers
Operador de coincidencia de colección (has)
Archivos con una propiedad de archivo personalizada visible para todas las apps properties has { key='mass' and value='1.3kg' }
Archivos con una propiedad de archivo personalizada privada para la app que realiza la solicitud appProperties has { key='additionalID' and value='8e8aceg2af2ge72e78' }
Archivos que tienen una propiedad de archivo personalizada con la clave "department" (independientemente del valor) properties has { key='department' }
Operadores lógicos (and, or, not)
Archivos con un nombre que contiene las palabras "hello" y "goodbye" name contains 'hello' and name contains 'goodbye'
Archivos con un nombre que no contiene la palabra "hello" not name contains 'hello'
Archivos que contienen el texto "important" y están en la papelera fullText contains 'important' and trashed = true
Archivos que no contienen la palabra "hello" not fullText contains 'hello'
Archivos de imagen o video modificados después de una fecha específica modifiedTime > '2012-06-04T12:00:00' and (mimeType contains 'image/' or mimeType contains 'video/')
Archivos compartidos con el usuario autorizado que tienen "hello" en el nombre sharedWithMe and name contains 'hello'
Archivos que son carpetas o accesos directos mimeType = 'application/vnd.google-apps.folder' or mimeType = 'application/vnd.google-apps.shortcut'
Archivos con el nombre "Project Plan" que no están en la papelera name = 'Project Plan' and trashed = false
Archivos en una carpeta específica que no están en la papelera '1234567' in parents and trashed = false

Filtra los resultados de la búsqueda con una biblioteca cliente

En la siguiente muestra de código, se muestra cómo usar una biblioteca cliente para filtrar los resultados de la búsqueda a los nombres de archivo y los IDs de los archivos JPEG. En este ejemplo, se usa el término de consulta mimeType para limitar los resultados a los archivos de tipo image/jpeg. También se establece spaces en drive para limitar aún más la búsqueda al espacio de Drive. Cuando nextPageToken muestra null, no hay más 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;
    }
}

Enumera los archivos de una carpeta pública

Para buscar o enumerar archivos en una carpeta compartida públicamente (en la que el acceso se establece en "Cualquier persona que tenga el vínculo" o "Público en la Web"), usa el list método en el recurso files con el parámetro de consulta q configurado para filtrar por el ID de la carpeta en la colección parents:

'FOLDER_ID' in parents and trashed = false

Cuando enumeres archivos en una carpeta pública, puedes autenticar las solicitudes con una clave de API en lugar de credenciales de usuario de OAuth 2.0. Si la carpeta se encuentra dentro de una unidad compartida, también debes establecer supportsAllDrives=true y includeItemsFromAllDrives=true en la solicitud.

En los siguientes ejemplos de código, se muestra cómo enumerar archivos en una carpeta 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'

Reemplaza lo siguiente:

Busca archivos con propiedades personalizadas

Para buscar archivos con una propiedad de archivo personalizada, usa el término de búsqueda properties o appProperties con una clave y un valor. Por ejemplo, para buscar una propiedad de archivo personalizada que sea privada para la app que realiza la solicitud llamada additionalID con un valor de 8e8aceg2af2ge72e78:

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

Para obtener más información, consulta Agrega propiedades de archivo personalizadas.

Busca archivos por etiqueta o valor de campo

Para buscar archivos con etiquetas específicas, usa el término de búsqueda labels con un ID de etiqueta específico.

Para buscar archivos a los que se les aplicó una etiqueta específica, haz lo siguiente:

'labels/LABEL_ID' in labels

Para buscar archivos a los que no se les aplicó una etiqueta específica, haz lo siguiente:

not 'labels/LABEL_ID' in labels

Para buscar archivos según un valor de campo de etiqueta específico, haz lo siguiente:

labels/LABEL_ID.FIELD_ID = 'VALUE'

Si se ejecuta correctamente, el cuerpo de la respuesta contiene todas las instancias de archivo que coinciden con la consulta. Para obtener más información, consulta Busca archivos con una etiqueta o un valor de campo específicos.

Busca en todos los corpus

De forma predeterminada, la colección de elementos user se establece en el parámetro de consulta corpora cuando se usa el método list. Para buscar otras colecciones de elementos, como las que se comparten con un domain, debes establecer el parámetro corpora de forma explícita.

Puedes buscar varios corpus en una sola consulta. Sin embargo, si el corpus combinado es demasiado grande, la API podría mostrar resultados incompletos. Consulta el incompleteSearch campo en el cuerpo de la respuesta. Si es true, se omitieron algunos documentos. Para resolver este problema, limita el corpora para usar user o drive.

Cuando uses el orderBy parámetro de consulta en el método list, evita usar la clave createdTime para las consultas en colecciones de elementos grandes, ya que requiere procesamiento adicional y puede provocar tiempos de espera agotados o problemas. Para la clasificación relacionada con el tiempo en colecciones de elementos grandes, puedes usar modifiedTime en su lugar, ya que está optimizado para controlar estas consultas. Por ejemplo, establece orderBy en modifiedTime (o modifiedTime desc).

Si omites el parámetro de consulta orderBy, no hay un orden de clasificación predeterminado y los elementos se muestran de forma arbitraria.