Cercare file e cartelle

Questa guida spiega come 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 (come 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 del 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.

• operator specifica la condizione per il termine di query.

• values sono 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.

Importante: i seguenti termini di query utilizzano i campi dell'API Drive v3. Alcuni campi delle risorse sono cambiati tra la v2 e la v3. Ad esempio, name sostituisce title. Se utilizzi l'API Drive v2, modifica queste query in modo da utilizzare i campi della v2. Per ulteriori informazioni, vedi Riferimento di confronto tra l'API Drive v2 e v3.

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 una barra rovesciata ("\"), utilizza una barra rovesciata per eseguirne l'escape: name contains 'quinn\'s paper\\essay'.

Nota: questi esempi utilizzano il parametro q non codificato, dove name = 'hello' viene codificato come name+%3d+%27hello%27. Le librerie client gestiscono automaticamente questa codifica.

Cosa interrogare	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 sono 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 abbia il 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 all'interno di una raccolta (ad esempio, l'ID della cartella nella raccolta parents)	'1234567' in parents
File nella cartella dei dati dell'applicazione	'appDataFolder' in parents
File di cui l'utente "[e-mail]" è il proprietario	'[e-mail]' in owners
File per cui l'utente "[e-mail]" ha l'autorizzazione di scrittura	'[e-mail]' in writers
File per cui i membri del gruppo "[e-mail]" hanno l'autorizzazione di scrittura	'[e-mail]' in writers
File per cui l'utente "[e-mail]" ha l'autorizzazione di lettura	'[e-mail]' 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 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 limitare i risultati ai file di tipo image/jpeg. Imposta anche spaces su drive per limitare ulteriormente la ricerca allo spazio Drive. Quando nextPageToken restituisce null, non ci sono altri risultati.

Nota: se utilizzi la versione precedente dell'API Drive v2, puoi trovare esempi di codice su GitHub. Scopri come eseguire la migrazione all'API Drive v3.

Java

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

Visualizza su 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

Visualizza su 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

Visualizza su 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

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

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 all'interno di 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 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 ulteriori informazioni, vedi 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 ulteriori informazioni, vedi Cercare file con un'etichetta o valore di campo specifico.

Cercare tra i corpora

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 esplicitamente il parametro corpora.

Puoi cercare più corpora in una singola query; tuttavia, se i corpora combinati 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, limita il parametro corpora in modo da utilizzare user o drive.

Quando utilizzi il orderBy parametro di query nel 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.

Argomenti correlati

• Cercare i Drive condivisi
• Termini e operatori di query di ricerca
• Tipi MIME supportati per Google Workspace e Google Drive
• Ruoli e autorizzazioni
• Cercare file con un'etichetta o un valore di campo specifico