Rechercher des fichiers et des dossiers

Ce guide explique comment l'API Google Drive permet de rechercher des fichiers et des dossiers de plusieurs manières.

Vous pouvez utiliser la méthode list sur la ressource files pour renvoyer tout ou partie des fichiers et dossiers d'un utilisateur Drive. La méthode list peut également être utilisée pour récupérer le fileId requis pour certaines méthodes de ressource (telles que les méthodes get et update).

Utiliser le paramètre "fields"

Si vous souhaitez spécifier les champs à renvoyer dans la réponse, vous pouvez définir le fields paramètre système avec n'importe quelle méthode de la res3/} source.files Si vous omettez le paramètre fields, le serveur renvoie un ensemble de champs par défaut spécifique à la méthode. Par exemple, la list méthode ne renvoie que les kind, id, name, mimeType, et resourceKey champs pour chaque fichier. Pour renvoyer d'autres champs, consultez la section Renvoyer des champs spécifiques.

Obtenir un fichier

Pour obtenir un fichier, utilisez la get méthode sur la files ressource avec le fileId paramètre de chemin d'accès. Si vous ne connaissez pas l'ID du fichier, vous pouvez répertorier tous les fichiers à l'aide de la list méthode.

La méthode renvoie le fichier en tant qu'instance d'une ressource files. Si vous fournissez le paramètre alt=media, la réponse inclut le contenu du fichier dans le corps de la réponse. Pour télécharger un fichier blob, consultez la section Télécharger le contenu d'un fichier blob.

Pour reconnaître le risque de télécharger des logiciels malveillants connus ou d'autres abusifs fichiers, définissez le acknowledgeAbuse paramètre de requête sur true. Ce champ ne s'applique que lorsque le paramètre alt=media est défini et que l'utilisateur est le propriétaire du fichier ou l'organisateur du Drive partagé dans lequel le fichier réside.

Rechercher tous les fichiers et dossiers dans le Drive de l'utilisateur actuel

Utilisez la méthode list sans aucun paramètre pour renvoyer tous les fichiers et dossiers.

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

Rechercher des fichiers ou des dossiers spécifiques dans le Drive de l'utilisateur actuel

Pour rechercher un ensemble spécifique de fichiers ou de dossiers, utilisez le champ de chaîne de requête q field avec la list méthode afin de filtrer les fichiers à renvoyer en combinant un ou plusieurs termes de recherche.

La syntaxe de la chaîne de requête contient les trois parties suivantes :

query_term operator values

Où :

• query_term est le terme ou le champ de requête sur lequel effectuer la recherche.

• operator spécifie la condition appliquée au terme de requête.

• values sont les valeurs spécifiques que vous souhaitez utiliser pour filtrer vos résultats de recherche.

Par exemple, la chaîne de requête suivante filtre la recherche pour ne renvoyer que les dossiers en définissant le type MIME :

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

Pour afficher tous les termes de requête de fichier, consultez la section Termes de requête spécifiques aux fichiers.

Pour afficher tous les opérateurs de requête que vous pouvez utiliser pour créer une requête, consultez la section Opérateurs de requête.

Exemples de chaînes de requête

Le tableau suivant présente des exemples de chaînes de requête de base. Le code exact varie selon la bibliothèque cliente que vous utilisez pour votre recherche.

Important : Les termes de requête suivants utilisent des champs de l'API Drive v3. Certains champs de ressources ont changé entre la version 2 et la version 3. Par exemple, name remplace title. Si vous utilisez l'API Drive v2, ajustez ces requêtes pour utiliser les champs de la version 2. Pour en savoir plus, consultez la référence comparative des API Drive v2 et v3.

Vous devez également échapper les caractères spéciaux dans les noms de fichiers pour que la requête fonctionne correctement. Par exemple, si un nom de fichier contient à la fois une apostrophe (') et une barre oblique inverse ("\"), utilisez une barre oblique inverse pour les échapper : name contains 'quinn\'s paper\\essay'.

Remarque : Ces exemples utilisent le paramètre q non encodé, où name = 'hello' est encodé sous la forme name+%3d+%27hello%27. Les bibliothèques clientes gèrent automatiquement cet encodage.

Éléments à interroger	Exemple
Opérateur de correspondance de chaîne (contains)
Fichiers contenant le mot "hello"	fullText contains 'hello'
Fichiers contenant l'expression exacte "hello world"	fullText contains '"hello world"'
Fichiers avec une requête contenant le caractère "\" (par exemple, "\authors")	fullText contains '\\authors'
Fichiers dont le nom contient "budget"	name contains 'budget'
Opérateurs d'égalité et d'inégalité (=, !=)
Fichiers nommés "hello"	name = 'hello'
Fichiers qui sont des dossiers	mimeType = 'application/vnd.google-apps.folder'
Fichiers qui ne sont pas des dossiers	mimeType != 'application/vnd.google-apps.folder'
Fichiers ajoutés aux favoris	starred = true
Fichiers dans la corbeille	trashed = true
Fichiers qui ne sont pas dans la corbeille	trashed = false
Raccourcis qui pointent vers un ID de fichier spécifique	shortcutDetails.targetId = '1987654321'
Fichiers qui n'ont été partagés avec personne ni aucun domaine (privés ou partagés avec des utilisateurs ou des groupes spécifiques)	visibility = 'limited'
Opérateurs de comparaison (>, >=, <, <=)
Fichiers modifiés après une date donnée (le fuseau horaire par défaut est UTC)	modifiedTime > '2012-06-04T12:00:00'
Fichiers créés après le 1er janvier 2023	createdTime > '2023-01-01T00:00:00'
Fichiers modifiés avant le 1er janvier 2023	modifiedTime < '2023-01-01T00:00:00'
Opérateur d'appartenance à une collection (in)
Fichiers d'une collection (par exemple, l'ID de dossier dans la collection parents)	'1234567' in parents
Fichiers du dossier de données de l'application	'appDataFolder' in parents
Fichiers dont l'utilisateur "[e-mail]" est le propriétaire	'[e-mail]' in owners
Fichiers pour lesquels l'utilisateur "[e-mail]" dispose d'une autorisation d'écriture	'[e-mail]' in writers
Fichiers pour lesquels les membres du groupe "[e-mail]" disposent d'une autorisation d'écriture	'[e-mail]' in writers
Fichiers pour lesquels l'utilisateur "[e-mail]" dispose d'une autorisation de lecture	'[e-mail]' in readers
Opérateur de correspondance de collection (has)
Fichiers avec une propriété de fichier personnalisée visible par toutes les applications	properties has { key='mass' and value='1.3kg' }
Fichiers avec une propriété de fichier personnalisée privée pour l'application à l'origine de la requête	appProperties has { key='additionalID' and value='8e8aceg2af2ge72e78' }
Fichiers ayant une propriété de fichier personnalisée avec la clé "department" (quelle que soit la valeur)	properties has { key='department' }
Opérateurs logiques (and, or, not)
Fichiers dont le nom contient les mots "hello" et "goodbye"	name contains 'hello' and name contains 'goodbye'
Fichiers dont le nom ne contient pas le mot "hello"	not name contains 'hello'
Fichiers contenant le texte "important" et se trouvant dans la corbeille	fullText contains 'important' and trashed = true
Fichiers ne contenant pas le mot "hello"	not fullText contains 'hello'
Fichiers image ou vidéo modifiés après une date spécifique	modifiedTime > '2012-06-04T12:00:00' and (mimeType contains 'image/' or mimeType contains 'video/')
Fichiers partagés avec l'utilisateur autorisé dont le nom contient "hello"	sharedWithMe and name contains 'hello'
Fichiers qui sont des dossiers ou des raccourcis	mimeType = 'application/vnd.google-apps.folder' or mimeType = 'application/vnd.google-apps.shortcut'
Fichiers nommés "Project Plan" qui ne sont pas dans la corbeille	name = 'Project Plan' and trashed = false

Filtrer les résultats de recherche avec une bibliothèque cliente

L'exemple de code suivant montre comment utiliser une bibliothèque cliente pour filtrer les résultats de recherche en fonction des noms de fichiers et des ID de fichiers JPEG. Cet exemple utilise le terme de requête mimeType pour limiter les résultats aux fichiers de type image/jpeg. Il définit également spaces sur drive pour limiter davantage la recherche à l'espace Drive Drive. Lorsque nextPageToken renvoie null, il n'y a plus de résultats.

Remarque : Si vous utilisez l'ancienne API Drive v2, vous trouverez des exemples de code sur GitHub. Découvrez comment migrer vers l'API Drive v3.

Java

drive/snippets/drive_v3/src/main/java/SearchFile.java

Afficher sur GitHub

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

Afficher sur GitHub

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

Afficher sur GitHub

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

Afficher sur GitHub

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

Rechercher des fichiers avec une propriété de fichier personnalisée

Pour rechercher des fichiers avec une propriété de fichier personnalisée, utilisez le terme de requête properties ou appProperties avec une clé et une valeur. Par exemple, pour rechercher une propriété de fichier personnalisée privée pour l'application à l'origine de la requête appelée additionalID avec la valeur 8e8aceg2af2ge72e78 :

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

Pour en savoir plus, consultez la section Ajouter des propriétés de fichier personnalisées.

Rechercher des fichiers avec un libellé ou une valeur de champ spécifiques

Pour rechercher des fichiers avec des libellés spécifiques, utilisez le terme de requête labels avec un ID de libellé spécifique. Par exemple : 'labels/LABEL_ID' in labels. Si la requête aboutit, le corps de la réponse contient toutes les instances de fichier auxquelles le libellé est appliqué.

Pour rechercher des fichiers sans ID de libellé spécifique : Not 'labels/LABEL_ID' in labels.

Vous pouvez également rechercher des fichiers en fonction de valeurs de champ spécifiques. Par exemple, pour rechercher des fichiers avec une valeur de texte : labels/LABEL_ID.text_field_id ='TEXT'.

Pour en savoir plus, consultez la section Rechercher des fichiers avec un libellé ou une valeur de champ spécifiques.

Rechercher dans les corpus

Par défaut, la collection d'éléments user est définie sur le paramètre de requête corpora lorsque la méthode list est utilisée. Pour rechercher d'autres collections d'éléments, telles que celles partagées avec un domain, vous devez définir explicitement le paramètre corpora.

Vous pouvez effectuer une recherche dans plusieurs corpus dans une seule requête. Toutefois, si les corpus combinés sont trop volumineux, l'API peut renvoyer des résultats incomplets. Vérifiez le incompleteSearch champ dans le corps de la réponse. Si la valeur est true, certains documents ont été omis. Pour résoudre ce problème, limitez le corpora à user ou drive.

Lorsque vous utilisez le orderBy paramètre de requête sur la méthode list, évitez d'utiliser la clé createdTime pour les requêtes sur les grandes collections d'éléments, car cela nécessite un traitement supplémentaire et peut entraîner des délais d'attente ou d'autres problèmes. Pour le tri temporel sur les grandes collections d'éléments, vous pouvez utiliser modifiedTime à la place, car il est optimisé pour gérer ces requêtes. Par exemple, ?orderBy=modifiedTime.

Si vous omettez le paramètre de requête orderBy, il n'y a pas d'ordre de tri par défaut et les éléments sont renvoyés de manière arbitraire.

Articles associés

• Rechercher des Drive partagés
• Termes de requête et opérateurs de recherche
• Types MIME compatibles avec Google Workspace et Google Drive
• Rôles et autorisations
• Rechercher des fichiers avec un libellé ou une valeur de champ spécifiques