Nach Dateien und Ordnern suchen

In dieser Anleitung wird erläutert, wie Sie mit der Google Drive API auf verschiedene Arten nach Dateien und Ordnern suchen können.

Mit der Methode list für die files Ressource können Sie alle oder einige der Dateien und Ordner eines Drive-Nutzers zurückgeben. Sie können mit der list Methode auch die fileId abrufen, die für einige Ressourcenmethoden erforderlich ist (z. B. die get und update Methoden).

Parameter „fields“ verwenden

Wenn Sie die Felder angeben möchten, die in der Antwort zurückgegeben werden sollen, können Sie den fields System parameter mit einer beliebigen Methode der files Ressource festlegen. Wenn Sie den Parameter fields weglassen, gibt der Server eine Standardgruppe von Feldern zurück, die für die Methode spezifisch sind. Die Methode list gibt beispielsweise nur die Felder kind, id, name, mimeType und resourceKey für jede Datei zurück. Informationen zum Zurückgeben anderer Felder finden Sie unter Bestimmte Felder zurückgeben.

Datei nach ID abrufen

Verwenden Sie die get Methode für die files Ressource mit dem fileId Pfad-Parameter, um eine Datei abzurufen. Wenn Sie die Datei-ID nicht kennen, können Sie alle Dateien auflisten mit der list Methode.

Die Methode gibt die Datei als Instanz einer Ressource files zurück. Wenn Sie den Parameter alt=media angeben, enthält die Antwort den Dateiinhalt im Antworttext. Informationen zum Herunterladen einer Blob-Datei finden Sie unter Blob-Dateiinhalt herunterladen.

Setzen Sie den acknowledgeAbuse Abfrageparameter auf true, um das Risiko des Herunterladens bekannter Malware oder anderer missbräuchlicher Dateien zu bestätigen. Dieses Feld ist nur anwendbar, wenn der Parameter alt=media festgelegt ist und der Nutzer entweder der Eigentümer der Datei oder ein Organisator der geteilten Ablage ist, in der sich die Datei befindet.

Alle Dateien und Ordner in „Meine Ablage“ auflisten

Verwenden Sie die Methode list ohne Parameter, um alle Dateien und Ordner in „Meine Ablage“ des aktuellen Nutzers zurückzugeben.

Der folgende curl-Befehl zeigt, wie Sie alle Dateien auflisten:

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

Ersetzen Sie ACCESS_TOKEN durch ein autorisiertes OAuth 2.0-Zugriffstoken.

Nach bestimmten Dateien und Ordnern in „Meine Ablage“ suchen

Wenn Sie nach einer bestimmten Gruppe von Dateien oder Ordnern in „Meine Ablage“ des aktuellen Nutzers suchen möchten, verwenden Sie das Abfragestringfeld q mit der list Methode, um die zurückzugebenden Dateien zu filtern, indem Sie einen oder mehrere Suchbegriffe kombinieren.

Die Abfragestringsyntax enthält die folgenden drei Teile:

query_term operator values

Wobei:

  • query_term ist der Suchbegriff oder das Feld, nach dem gesucht werden soll.

  • operator gibt die Bedingung für den Suchbegriff an.

  • values sind die spezifischen Werte, mit denen Sie Ihre Suchergebnisse filtern möchten.

Mit dem folgenden Abfragestring wird die Suche beispielsweise so gefiltert, dass nur Ordner zurückgegeben werden, indem der MIME-Typfestgelegt wird:

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

Alle Abfragebegriffe für Dateien finden Sie unter Dateispezifische Abfragebegriffe.

Alle Abfrageoperatoren, die Sie zum Erstellen einer Abfrage verwenden können, finden Sie unter Query operators.

Beispiele für Abfragestrings

In der folgenden Tabelle sind Beispiele für einige grundlegende Abfragestrings aufgeführt. Der tatsächliche Code hängt von der Clientbibliothek ab, die Sie für Ihre Suche verwenden.

Sie müssen auch Sonderzeichen in Ihren Dateinamen mit Escapezeichen versehen, damit die Abfrage korrekt funktioniert. Wenn ein Dateiname beispielsweise sowohl ein Apostroph (') als auch einen umgekehrten Schrägstrich ("\") enthält, verwenden Sie einen umgekehrten Schrägstrich, um sie mit Escapezeichen zu versehen: name contains 'quinn\'s paper\\essay'.

Was soll abgefragt werden? Beispiel
Operator für Stringübereinstimmung (contains)
Dateien, die das Wort „hello“ enthalten fullText contains 'hello'
Dateien, die die genaue Phrase „hello world“ enthalten fullText contains '"hello world"'
Dateien mit einer Abfrage, die das Zeichen „\“ enthält (z. B. „\authors“) fullText contains '\\authors'
Dateien mit einem Namen, der „budget“ enthält name contains 'budget'
Gleichheits- und Ungleichheitsoperatoren (=, !=)
Dateien mit dem Namen „hello“ name = 'hello'
Dateien, die Ordner sind mimeType = 'application/vnd.google-apps.folder'
Dateien, die keine Ordner sind mimeType != 'application/vnd.google-apps.folder'
Dateien, die mit einem Sternchen markiert sind starred = true
Dateien, die sich im Papierkorb befinden trashed = true
Dateien, die sich nicht im Papierkorb befinden trashed = false
Verknüpfungen, die auf eine bestimmte Datei-ID verweisen shortcutDetails.targetId = '1987654321'
Dateien, die für niemanden oder keine Domains freigegeben wurden (privat oder für bestimmte Nutzer oder Gruppen freigegeben) visibility = 'limited'
Dateien, auf die jeder mit dem Link zugreifen kann visibility = 'anyoneWithLink'
Dateien, die im Web öffentlich auffindbar sind visibility = 'anyoneCanFind'
Vergleichsoperatoren (>, >=, <, <=)
Dateien, die nach einem bestimmten Datum geändert wurden (Standardzeitzone ist UTC) modifiedTime > '2012-06-04T12:00:00'
Dateien, die nach dem 1. Januar 2023 erstellt wurden createdTime > '2023-01-01T00:00:00'
Dateien, die vor dem 1. Januar 2023 geändert wurden modifiedTime < '2023-01-01T00:00:00'
Operator für die Mitgliedschaft in einer Sammlung (in)
Dateien in einer Sammlung (z. B. die Ordner-ID in der Sammlung parents) '1234567' in parents
Dateien im Ordner für Anwendungsdaten 'appDataFolder' in parents
Dateien, deren Eigentümer der Nutzer „test@example.org“ ist 'test@example.org' in owners
Dateien, für die der Nutzer „test@example.org“ Schreibberechtigungen hat 'test@example.org' in writers
Dateien, für die Mitglieder der Gruppe „group@example.org“ Schreibberechtigungen haben 'group@example.org' in writers
Dateien, für die der Nutzer „test@example.org“ Leseberechtigungen hat 'test@example.org' in readers
Operator für die Übereinstimmung mit einer Sammlung (has)
Dateien mit einer benutzerdefinierten Dateieigenschaft, die für alle Apps sichtbar ist properties has { key='mass' and value='1.3kg' }
Dateien mit einer benutzerdefinierten Dateieigenschaft, die für die anfragende App privat ist appProperties has { key='additionalID' and value='8e8aceg2af2ge72e78' }
Dateien mit einer benutzerdefinierten Dateieigenschaft mit dem Schlüssel „department“ (unabhängig vom Wert) properties has { key='department' }
Logische Operatoren (and, or, not)
Dateien mit einem Namen, der die Wörter „hello“ und „goodbye“ enthält name contains 'hello' and name contains 'goodbye'
Dateien mit einem Namen, der das Wort „hello“ nicht enthält not name contains 'hello'
Dateien, die den Text „important“ enthalten und sich im Papierkorb befinden fullText contains 'important' and trashed = true
Dateien, die das Wort „hello“ nicht enthalten not fullText contains 'hello'
Bild- oder Videodateien, die nach einem bestimmten Datum geändert wurden modifiedTime > '2012-06-04T12:00:00' and (mimeType contains 'image/' or mimeType contains 'video/')
Dateien, die für den autorisierten Nutzer freigegeben wurden und „hello“ im Namen enthalten sharedWithMe and name contains 'hello'
Dateien, die Ordner oder Verknüpfungen sind mimeType = 'application/vnd.google-apps.folder' or mimeType = 'application/vnd.google-apps.shortcut'
Dateien mit dem Namen „Project Plan“, die sich nicht im Papierkorb befinden name = 'Project Plan' and trashed = false
Dateien in einem bestimmten Ordner, die sich nicht im Papierkorb befinden '1234567' in parents and trashed = false

Suchergebnisse mit einer Clientbibliothek filtern

Das folgende Codebeispiel zeigt, wie Sie mit einer Clientbibliothek Suchergebnisse nach Dateinamen und IDs von JPEG-Dateien filtern. In diesem Beispiel wird der Abfragebegriff mimeType verwendet, um die Ergebnisse auf Dateien vom Typ image/jpeg zu beschränken. Außerdem wird spaces auf drive gesetzt, um die Suche weiter auf den Drive Speicherplatz zu beschränken. Wenn nextPageToken null zurückgibt, sind keine weiteren Ergebnisse vorhanden.

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

Dateien in einem öffentlichen Ordner auflisten

Wenn Sie in einem öffentlich freigegebenen Ordner nach Dateien suchen oder diese auflisten möchten (wobei der Zugriff auf „Jeder mit dem Link“ oder „Öffentlich im Web“ festgelegt ist), verwenden Sie die Methode list für die Ressource files mit dem Abfrage parameter q, der so festgelegt ist, dass nach der ID des Ordners in der Sammlung parents gefiltert wird:

'FOLDER_ID' in parents and trashed = false

Wenn Sie Dateien in einem öffentlichen Ordner auflisten, können Sie Anfragen mit einem API-Schlüssel anstelle von OAuth 2.0 Nutzeranmeldedaten authentifizieren. Wenn sich der Ordner in einer geteilten Ablage befindet, müssen Sie in der Anfrage auch supportsAllDrives=true und includeItemsFromAllDrives=true festlegen.

Die folgenden Codebeispiele zeigen, wie Sie Dateien in einem öffentlichen Ordner auflisten:

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'

Ersetzen Sie Folgendes:

  • FOLDER_ID: Die ID des öffentlichen Ordners.
  • API_KEY: Der API Schlüssel Ihres Projekts.

Nach Dateien mit benutzerdefinierten Eigenschaften suchen

Wenn Sie nach Dateien mit einer benutzerdefinierten Dateieigenschaft suchen möchten, verwenden Sie entweder den Suchbegriff properties oder appProperties mit einem Schlüssel und einem Wert. Beispiel: So suchen Sie nach einer benutzerdefinierten Dateieigenschaft, die für die anfragende App privat ist und den Namen additionalID mit dem Wert 8e8aceg2af2ge72e78 hat:

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

Weitere Informationen finden Sie unter Benutzerdefinierte Datei eigenschaften hinzufügen.

Nach Dateien anhand von Label- oder Feldwerten suchen

Wenn Sie nach Dateien mit bestimmten Labels suchen möchten, verwenden Sie den Suchbegriff labels mit einer bestimmten Label-ID.

So suchen Sie nach Dateien, auf die ein bestimmtes Label angewendet wurde:

'labels/LABEL_ID' in labels

So suchen Sie nach Dateien, auf die kein bestimmtes Label angewendet wurde:

not 'labels/LABEL_ID' in labels

So suchen Sie nach Dateien anhand eines bestimmten Label-Feldwerts:

labels/LABEL_ID.FIELD_ID = 'VALUE'

Wenn der Vorgang erfolgreich ist, enthält der Antworttext alle Dateiinstanzen, die der Abfrage entsprechen. Weitere Informationen finden Sie unter Nach Dateien mit einem bestimmten Label oder Feldwert suchen.

Corpora durchsuchen

Standardmäßig ist die user Elementsammlung für den corpora Abfrageparameter festgelegt, wenn die list Methode verwendet wird. Wenn Sie in anderen Elementsammlungen suchen möchten, z. B. in solchen, die für eine domain freigegeben wurden, müssen Sie den Parameter corpora explizit festlegen.

Sie können mehrere Corpora in einer einzigen Abfrage durchsuchen. Wenn die kombinierten Corpora jedoch zu groß sind, gibt die API möglicherweise unvollständige Ergebnisse zurück. Prüfen Sie das incompleteSearch Feld im Antworttext. Wenn es true ist, wurden einige Dokumente ausgelassen. Um dieses Problem zu beheben, beschränken Sie corpora auf user oder drive.

Wenn Sie den orderBy Abfrage parameter für die list Methode verwenden, sollten Sie den createdTime Schlüssel für Abfragen in großen Elementsammlungen vermeiden, da dies zusätzliche Verarbeitung erfordert und zu Zeitüberschreitungen oder anderen Problemen führen kann. Für die zeitbezogene Sortierung in großen Elementsammlungen können Sie stattdessen modifiedTime verwenden, da es für die Verarbeitung dieser Abfragen optimiert ist. Setzen Sie orderBy beispielsweise auf modifiedTime (oder modifiedTime desc).

Wenn Sie den Abfrageparameter orderBy weglassen, gibt es keine Standardsortierreihenfolge und die Elemente werden willkürlich zurückgegeben.