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. Vous pouvez également utiliser la list
méthode pour récupérer le fileId requis pour certaines méthodes de ressource (telles que les
get et update méthodes).
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 par ID
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 un organisateur du Drive partagé dans lequel le fichier réside.
Répertorier tous les fichiers et dossiers dans Mon Drive
Utilisez la méthode list sans aucun paramètre pour renvoyer tous les fichiers et dossiers dans Mon Drive de l'utilisateur actuel.
La commande curl suivante montre comment répertorier tous les fichiers :
curl -X GET \
'https://www.googleapis.com/drive/v3/files' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Accept: application/json'
Remplacez ACCESS_TOKEN par un jeton d'accès OAuth 2.0 autorisé .
Rechercher des fichiers et des dossiers spécifiques dans Mon Drive
Pour rechercher un ensemble spécifique de fichiers ou de dossiers dans Mon
Drive de l'utilisateur actuel, utilisez le champ de chaîne de requête q avec la méthode list pour 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_termest le terme ou le champ de requête sur lequel effectuer la recherche.operatorspécifie la condition appliquée au terme de requête.valuessont 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 :
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.
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'.
| É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 suivis | 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' |
| Fichiers accessibles à toute personne disposant du lien | visibility = 'anyoneWithLink' |
| Fichiers publiquement détectables sur le Web | visibility = 'anyoneCanFind' |
Opérateurs de comparaison (>, >=, <, <=) |
|
| Fichiers modifiés après une date donnée (fuseau horaire par défaut : 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 enfants directs dans une collection (par exemple, l'ID de dossier dans la collection parents) |
'1234567' in parents |
| Fichiers dans le dossier de données de l'application | 'appDataFolder' in parents |
| Fichiers dont l'utilisateur "test@example.org" est le propriétaire | 'test@example.org' in owners |
| Fichiers pour lesquels l'utilisateur "test@example.org" dispose de l'autorisation d'écriture | 'test@example.org' in writers |
| Fichiers pour lesquels les membres du groupe "group@example.org" disposent de l'autorisation d'écriture | 'group@example.org' in writers |
| Fichiers pour lesquels l'utilisateur "test@example.org" dispose de l'autorisation de lecture | 'test@example.org' 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 avec une propriété de fichier personnalisée dont la clé est "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 qui ne contiennent 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é et 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 |
| Fichiers enfants directs dans un dossier spécifique qui ne sont pas dans la corbeille | '1234567' in parents 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.
Java
Python
Node.js
PHP
Répertorier les fichiers dans un dossier public
Pour rechercher ou répertorier des fichiers dans un dossier partagé publiquement (où l'accès est défini sur
"Toute personne disposant du lien" ou "Public sur le Web"), utilisez la list méthode sur la ressource files avec le paramètre de requête q défini pour filtrer par l'ID du dossier dans la collection parents :
'FOLDER_ID' in parents and trashed = false
Lorsque vous répertoriez des fichiers dans un dossier public, vous pouvez authentifier les requêtes à l'aide d'une
clé API au lieu d'identifiants utilisateur OAuth 2.0. Si le dossier se trouve dans un Drive partagé, vous devez également définir supportsAllDrives=true et includeItemsFromAllDrives=true dans la requête.
Les exemples de code suivants montrent comment répertorier des fichiers dans un dossier public :
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'
Remplacez les éléments suivants :
- FOLDER_ID : ID du dossier public.
- API_KEY : clé API de votre projet.
Rechercher de manière récursive des dossiers et des fichiers descendants
Le terme de requête parents ne renvoie que les fichiers et dossiers enfants directs situés dans le dossier spécifié. L'API Drive ne fournit pas d'opérateur ni de paramètre de requête permettant de rechercher de manière récursive des arborescences de sous-dossiers descendants en un seul appel d'API.
Pour rechercher un dossier et tous ses sous-dossiers et fichiers descendants, votre application doit effectuer une traversée d'arborescence côté client :
- Interrogez les enfants directs du dossier cible à l'aide de
'FOLDER_ID' in parents and trashed = false. - Identifiez les sous-dossiers en filtrant les résultats où
mimeType = 'application/vnd.google-apps.folder'. - Interrogez de manière récursive ou itérative l'ID de chaque dossier enfant pour récupérer son contenu.
Les exemples de code suivants montrent comment rechercher de manière récursive un dossier et ses descendants :
Node.js
/**
* Recursively searches a folder and all descendant subfolders for files.
* @param {string} folderId The ID of the starting folder.
* @param {Object} authClient An authorized OAuth 2.0 client.
* @return {Promise<Array>} The list of all descendant files.
*/
async function searchFolderRecursively(folderId, authClient) {
const {google} = require('googleapis');
const service = google.drive({version: 'v3', auth: authClient});
const allFiles = [];
const foldersToSearch = [folderId];
try {
while (foldersToSearch.length > 0) {
const currentFolderId = foldersToSearch.pop();
let pageToken = null;
do {
const response = await service.files.list({
q: `'${currentFolderId}' in parents and trashed = false`,
fields: 'nextPageToken, files(id, name, mimeType)',
pageSize: 1000,
supportsAllDrives: true,
includeItemsFromAllDrives: true,
pageToken: pageToken,
});
const files = response.data.files || [];
for (const file of files) {
if (file.mimeType === 'application/vnd.google-apps.folder') {
foldersToSearch.push(file.id);
} else {
allFiles.push(file);
}
}
pageToken = response.data.nextPageToken;
} while (pageToken);
}
return allFiles;
} catch (err) {
// TODO(developer): Handle error
console.error(err);
throw err;
}
}
Python
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError
def search_folder_recursively(folder_id, creds):
"""Recursively searches a folder and all descendant subfolders for
files.
Args:
folder_id: The ID of the starting folder.
creds: An authorized OAuth 2.0 credentials object.
Returns:
A list of all descendant file resources.
"""
service = build("drive", "v3", credentials=creds)
all_files = []
folders_to_search = [folder_id]
try:
while folders_to_search:
current_folder_id = folders_to_search.pop()
page_token = None
while True:
response = (
service.files()
.list(
q=f"'{current_folder_id}' in parents and trashed = false",
fields="nextPageToken, files(id, name, mimeType)",
pageSize=1000,
supportsAllDrives=True,
includeItemsFromAllDrives=True,
pageToken=page_token,
)
.execute()
)
for item in response.get("files", []):
if (
item.get("mimeType")
== "application/vnd.google-apps.folder"
):
folders_to_search.append(item.get("id"))
else:
all_files.append(item)
page_token = response.get("nextPageToken")
if not page_token:
break
return all_files
except HttpError as error:
# TODO(developer): Handle error
print(f"An error occurred: {error}")
return None
Rechercher des fichiers avec des propriétés personnalisées
Pour rechercher des fichiers avec une propriété de fichier personnalisée, utilisez le terme de requête de recherche 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 par libellé ou valeur de champ
Pour rechercher des fichiers avec des libellés spécifiques, utilisez le terme de requête de recherche labels avec un ID de libellé spécifique.
Pour rechercher des fichiers auxquels un libellé spécifique a été appliqué :
'labels/LABEL_ID' in labels
Pour rechercher des fichiers auxquels un libellé spécifique n'a pas été appliqué :
not 'labels/LABEL_ID' in labels
Pour rechercher des fichiers en fonction d'une valeur de champ de libellé spécifique :
labels/LABEL_ID.FIELD_ID = 'VALUE'
Si la requête aboutit, le corps de la réponse contient toutes les instances de fichier qui correspondent à la requête. Pour en savoir plus, consultez la section Rechercher des fichiers avec un libellé ou une valeur de champ spécifique.
Rechercher dans plusieurs 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 en une seule requête. Toutefois, si le corpus combiné est trop volumineux, l'API peut renvoyer des résultats incomplets. Vérifiez le
incompleteSearch
champ dans le corps de la réponse. S'il est défini sur 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, définissez orderBy sur modifiedTime (ou modifiedTime desc).
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.