Questa guida spiega in che modo l'API Google Drive supporta diversi modi per cercare file e cartelle.
Puoi utilizzare il list metodo sulla
files risorsa per restituire tutti o alcuni dei
file e delle cartelle di un utente di Drive. Puoi anche utilizzare il list
metodo per recuperare il fileId richiesto per alcuni metodi delle risorse (ad esempio i
get e update metodi).
Utilizzare il parametro fields
Se vuoi specificare i campi da restituire nella risposta, puoi impostare il
fields parametro
di sistema
con qualsiasi metodo della ris3/} risorsa.files Se ometti il parametro fields, il server restituisce un insieme predefinito di campi specifici per il metodo. Ad esempio, il
list metodo restituisce solo i campi kind, id,
name, mimeType e resourceKey per ogni file. Per restituire campi diversi, vedi Restituire campi specifici.
Ottenere un file per ID
Per ottenere un file, utilizza il get metodo sulla
files risorsa con il fileId parametro di percorso.
Se non conosci l'ID file, puoi elencare tutti i file utilizzando il list
metodo.
Il metodo restituisce il file come istanza di una risorsa files. Se fornisci il parametro alt=media, la risposta include i contenuti del file nel corpo della risposta. Per scaricare un file blob, vedi Scaricare i contenuti dei file blob.
Per riconoscere il rischio di scaricare malware noti o altri
illeciti file, imposta il
acknowledgeAbuse parametro di query su true. Questo campo è applicabile solo quando il parametro alt=media è impostato e l'utente è il proprietario del file o un organizzatore del Drive condiviso in cui si trova il file.
Elencare tutti i file e le cartelle in Il mio Drive
Utilizza il metodo list senza parametri per restituire tutti i file e le cartelle in Il mio Drive dell'utente corrente.
Il seguente comando curl mostra come elencare tutti i file:
curl -X GET \
'https://www.googleapis.com/drive/v3/files' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Accept: application/json'
Sostituisci ACCESS_TOKEN con un token di accesso OAuth 2.0 autorizzato .
Cercare file e cartelle specifici in Il mio Drive
Per cercare un insieme specifico di file o cartelle in Il mio
Drive dell'utente corrente, utilizza il campo della stringa di query q con il metodo list per filtrare i file da restituire combinando
uno o più termini di ricerca.
La sintassi della stringa di query contiene le seguenti tre parti:
query_term operator values
Dove:
query_termè il termine o il campo di query su cui eseguire la ricerca.operatorspecifica la condizione per il termine di query.valuessono i valori specifici che vuoi utilizzare per filtrare i risultati di ricerca.
Ad esempio, la seguente stringa di query filtra la ricerca in modo da restituire solo le cartelle impostando il tipo MIME:
mimeType = 'application/vnd.google-apps.folder'
Per visualizzare tutti i termini di query dei file, vedi Termini di query specifici per i file.
Per visualizzare tutti gli operatori di query che puoi utilizzare per creare una query, vedi Operatori diquery.
Esempi di stringhe di query
La seguente tabella elenca esempi di alcune stringhe di query di base. Il codice effettivo varia a seconda della libreria client che utilizzi per la ricerca.
Devi anche eseguire l'escape dei caratteri speciali nei nomi dei file per assicurarti che la query funzioni correttamente. Ad esempio, se un nome file contiene sia un apostrofo
(') sia un carattere barra rovesciata ("\"), utilizza una barra rovesciata per eseguirne l'escape: name
contains 'quinn\'s paper\\essay'.
| Cosa eseguire la query | Esempio |
|---|---|
Operatore di corrispondenza delle stringhe (contains) |
|
| File che contengono la parola "hello" | fullText contains 'hello' |
| File che contengono la frase esatta "hello world" | fullText contains '"hello world"' |
| File con una query che contiene il carattere "\" (ad esempio "\authors") | fullText contains '\\authors' |
| File con un nome che contiene "budget" | name contains 'budget' |
Operatori di uguaglianza e disuguaglianza (=, !=) |
|
| File con il nome "hello" | name = 'hello' |
| File che sono cartelle | mimeType = 'application/vnd.google-apps.folder' |
| File che non sono cartelle | mimeType != 'application/vnd.google-apps.folder' |
| File aggiunti a Speciali | starred = true |
| File nel Cestino | trashed = true |
| File che non si trovano nel Cestino | trashed = false |
| Scorciatoie che rimandano a un ID file specifico | shortcutDetails.targetId = '1987654321' |
| File che non sono stati condivisi con nessuno o con domini (privati o condivisi con utenti o gruppi specifici) | visibility = 'limited' |
| File accessibili a chiunque disponga del link | visibility = 'anyoneWithLink' |
| File rilevabili pubblicamente sul web | visibility = 'anyoneCanFind' |
Operatori di confronto (>, >=, <, <=) |
|
| File modificati dopo una determinata data (il fuso orario predefinito è UTC) | modifiedTime > '2012-06-04T12:00:00' |
| File creati dopo il 1° gennaio 2023 | createdTime > '2023-01-01T00:00:00' |
| File modificati prima del 1° gennaio 2023 | modifiedTime < '2023-01-01T00:00:00' |
Operatore di appartenenza alla raccolta (in) |
|
File figlio diretti all'interno di una raccolta (ad esempio l'ID cartella nella raccolta parents) |
'1234567' in parents |
| File nella cartella dei dati dell'applicazione | 'appDataFolder' in parents |
| File per i quali l'utente "test@example.org" è il proprietario | 'test@example.org' in owners |
| File per i quali l'utente "test@example.org" ha l'autorizzazione in scrittura | 'test@example.org' in writers |
| File per i quali i membri del gruppo "group@example.org" hanno l'autorizzazione in scrittura | 'group@example.org' in writers |
| File per i quali l'utente "test@example.org" ha l'autorizzazione in lettura | 'test@example.org' in readers |
Operatore di corrispondenza della raccolta (has) |
|
| File con una proprietà di file personalizzata visibile a tutte le app | properties has { key='mass' and value='1.3kg' } |
| File con una proprietà di file personalizzata privata per l'app che effettua la richiesta | appProperties has { key='additionalID' and value='8e8aceg2af2ge72e78' } |
| File con una proprietà di file personalizzata con la chiave "department" (indipendentemente dal valore) | properties has { key='department' } |
Operatori logici (and, or, not) |
|
| File con un nome che contiene le parole "hello" e "goodbye" | name contains 'hello' and name contains 'goodbye' |
| File con un nome che non contiene la parola "hello" | not name contains 'hello' |
| File che contengono il testo "important" e si trovano nel Cestino | fullText contains 'important' and trashed = true |
| File che non contengono la parola "hello" | not fullText contains 'hello' |
| File immagine o video modificati dopo una data specifica | modifiedTime > '2012-06-04T12:00:00' and (mimeType contains 'image/' or mimeType contains 'video/') |
| File condivisi con l'utente autorizzato che contengono "hello" nel nome | sharedWithMe and name contains 'hello' |
| File che sono cartelle o scorciatoie | mimeType = 'application/vnd.google-apps.folder' or mimeType = 'application/vnd.google-apps.shortcut' |
| File con il nome "Project Plan" che non si trovano nel Cestino | name = 'Project Plan' and trashed = false |
| File figlio diretti in una cartella specifica che non si trovano nel Cestino | '1234567' in parents and trashed = false |
Filtrare i risultati di ricerca con una libreria client
Il seguente esempio di codice mostra come utilizzare una libreria client per filtrare i risultati di ricerca in base ai nomi e agli ID dei file JPEG. Questo esempio utilizza il termine di query mimeType per restringere i risultati ai file di tipo image/jpeg. Imposta anche
spaces su drive per restringere ulteriormente la ricerca allo spazio di Drive. Quando nextPageToken restituisce null, non ci sono altri risultati.
Java
Python
Node.js
PHP
Elencare i file in una cartella pubblica
Per cercare o elencare i file in una cartella condivisa pubblicamente (dove l'accesso è impostato su
"Chiunque abbia il link" o "Pubblico sul web"), utilizza il metodo list sulla risorsa files con il parametro di query q impostato per filtrare in base all'ID della cartella nella raccolta parents:
'FOLDER_ID' in parents and trashed = false
Quando elenchi i file in una cartella pubblica, puoi autenticare le richieste utilizzando una
chiave API anziché le credenziali utente OAuth 2.0. Se la cartella si trova in un Drive condiviso, devi anche impostare supportsAllDrives=true e includeItemsFromAllDrives=true nella richiesta.
I seguenti esempi di codice mostrano come elencare i file in una cartella pubblica:
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'
Sostituisci quanto segue:
- FOLDER_ID: l'ID della cartella pubblica.
- API_KEY: la chiave API del tuo progetto.
Cercare in modo ricorsivo file e cartelle discendenti
Il termine di query parents restituisce solo i file e le cartelle figlio diretti che si trovano nella cartella specificata. L'API Drive non fornisce un operatore o un parametro di query per cercare in modo ricorsivo gli alberi delle sottocartelle discendenti in una singola chiamata API.
Per cercare una cartella e tutte le relative sottocartelle e i relativi file discendenti, l'applicazione deve eseguire l'attraversamento dell'albero lato client:
- Esegui una query sui file figlio diretti della cartella di destinazione utilizzando
'FOLDER_ID' in parents and trashed = false. - Identifica le sottocartelle filtrando i risultati in cui
mimeType = 'application/vnd.google-apps.folder'. - Esegui una query ricorsiva o iterativa sull'ID di ogni cartella figlio per recuperarne i contenuti.
I seguenti esempi di codice mostrano come cercare in modo ricorsivo una cartella e i relativi discendenti:
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
Cercare file con proprietà personalizzate
Per cercare file con una proprietà di file personalizzata, utilizza il termine di query di ricerca properties o appProperties con una chiave e un valore. Ad esempio, per cercare una proprietà di file personalizzata privata per l'app che effettua la richiesta chiamata additionalID con un valore di 8e8aceg2af2ge72e78:
appProperties has { key='additionalID' and value='8e8aceg2af2ge72e78' }
Per saperne di più, consulta Aggiungere proprietà di file personalizzate.
Cercare file in base all'etichetta o al valore del campo
Per cercare file con etichette specifiche, utilizza il termine di query di ricerca labels con un ID etichetta specifico.
Per cercare i file a cui è stata applicata un'etichetta specifica:
'labels/LABEL_ID' in labels
Per cercare i file a cui non è stata applicata un'etichetta specifica:
not 'labels/LABEL_ID' in labels
Per cercare i file in base a un valore di campo di etichetta specifico:
labels/LABEL_ID.FIELD_ID = 'VALUE'
In caso di esito positivo, il corpo della risposta contiene tutte le istanze di file che corrispondono alla query. Per saperne di più, consulta Cercare file con un'etichetta o un valore di campo specifico.
Cercare tra le raccolte
Per impostazione predefinita, la raccolta di elementi user è impostata sul parametro di query corpora
quando viene utilizzato il metodo list. Per cercare altre raccolte di elementi, ad esempio quelle condivise con un domain, devi impostare in modo esplicito il parametro corpora.
Puoi cercare più raccolte in una singola query; tuttavia, se le raccolte combinate sono troppo grandi, l'API potrebbe restituire risultati incompleti. Controlla il
incompleteSearch
campo nel corpo della risposta. Se è true, alcuni documenti sono stati omessi. Per risolvere il problema, restringi il parametro corpora in modo da utilizzare user o drive.
Quando utilizzi il
orderBy parametro di query
sul metodo list, evita di utilizzare la chiave createdTime per le query su
raccolte di elementi di grandi dimensioni, in quanto richiede un'elaborazione aggiuntiva e potrebbe causare
timeout o altri problemi. Per l'ordinamento in base all'ora su raccolte di elementi di grandi dimensioni, puoi utilizzare modifiedTime, in quanto è ottimizzato per gestire queste query.
Ad esempio, imposta orderBy su modifiedTime (o modifiedTime desc).
Se ometti il parametro di query orderBy, non esiste un ordinamento predefinito e gli elementi vengono restituiti in modo arbitrario.