Nach Dateien und Ordnern suchen

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

Mit der list Methode für die files Ressource können Sie alle oder einige Dateien und Ordner eines Drive-Nutzers zurückgeben. Die list Methode kann auch verwendet werden, um die fileId abzurufen, die für einige Ressourcenmethoden erforderlich ist, z. B. die get Methode und die update) Methode.

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 abrufen

Verwenden Sie die get Methode für die files Ressource mit dem fileId Pfadparameter, 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 files-Ressource zurück. Wenn Sie den Abfrageparameter alt=media angeben, enthält die Antwort den Dateiinhalt im Antworttext. Informationen zum Herunterladen oder Exportieren der Datei finden Sie unter Dateien herunterladen und exportieren.

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.

Nach allen Dateien und Ordnern in der Ablage des aktuellen Nutzers suchen

Verwenden Sie die Methode list ohne Parameter, um alle Dateien und Ordner zurückzugeben.

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

Nach bestimmten Dateien oder Ordnern in der Meine Ablage des aktuellen Nutzers suchen

Wenn Sie nach einer bestimmten Gruppe von Dateien oder Ordnern suchen möchten, verwenden Sie das Feld q für den Abfragestring mit der list Methode, um die zurückzugebenden Dateien zu filtern, indem Sie einen oder mehrere Suchbegriffe kombinieren.

Die Syntax des Abfragestrings 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 gefiltert, um nur Ordner zurückzugeben, indem der MIME-Typfestgelegt wird:

q: 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 die Suche verwenden.

Wichtig: Die folgenden Abfragebegriffe verwenden Felder aus der Drive API v3. Einige Ressourcenfelder haben sich zwischen Version 2 und 3 geändert. Beispielsweise ersetzt name das Feld title. Wenn Sie die Drive API v2 verwenden, passen Sie diese Abfragen an, um die Felder der Version 2 zu verwenden. Weitere Informationen finden Sie in der Vergleichsreferenz für die Drive API v2 und v3.

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

Hinweis: In diesen Beispielen wird der nicht codierte q Parameter verwendet, wobei name = 'hello' als codiert wird name+%3d+%27hello%27. Clientbibliotheken verarbeiten diese Codierung automatisch.

Was Sie abfragen möchten	Beispiel
Dateien mit dem Namen „hello“	name = 'hello'
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“ enthalten	fullText contains 'hello'
Dateien, die das Wort „hello“ nicht enthalten	not fullText contains 'hello'
Dateien, die die genaue Wortgruppe „hello world“ enthalten	fullText contains '"hello world"'
Dateien mit einer Abfrage, die das Zeichen „\“ enthält (z. B. „\authors“)	fullText contains '\\authors'
Dateien, die Ordner sind	mimeType = 'application/vnd.google-apps.folder'
Dateien, die keine Ordner sind	mimeType != 'application/vnd.google-apps.folder'
Dateien, die nach einem bestimmten Datum geändert wurden (Standardzeitzone ist UTC)	modifiedTime > '2012-06-04T12:00:00'
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/')
Markierte Dateien	starred = true
Dateien in einer Sammlung (z. B. die Ordner-ID in der Sammlung parents)	'1234567' in parents
Dateien in einem Ordner mit Anwendungsdaten in einer Sammlung	'appDataFolder' in parents
Dateien, deren Eigentümer der Nutzer „[e-mail]“ ist	'[e-mail]' in owners
Dateien, für die der Nutzer „[e-mail]“ Schreibberechtigung hat	'[e-mail]' in writers
Dateien, für die Mitglieder der Gruppe „[e-mail]“ Schreibberechtigung haben	'[e-mail]' in writers
Dateien, die für den autorisierten Nutzer freigegeben wurden und „hello“ im Namen enthalten	sharedWithMe and name contains 'hello'
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, die für keine Nutzer oder Domains freigegeben wurden (nur privat oder für bestimmte Nutzer oder Gruppen freigegeben)	visibility = 'limited'

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.

Hinweis: Wenn Sie die ältere Drive API v2 verwenden, finden Sie Codebeispiele auf GitHub. Informationen zur Migration zur Drive API v3.

Java

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

Auf GitHub ansehen

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

Auf GitHub ansehen

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

Auf GitHub ansehen

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

Auf GitHub ansehen

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

Nach Dateien mit einer benutzerdefinierten Dateieigenschaft suchen

Wenn Sie nach Dateien mit einer benutzerdefinierten Dateieigenschaft suchen möchten, verwenden Sie entweder den Suchabfragebegriff 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 mit einem bestimmten Label oder Feldwert suchen

Wenn Sie nach Dateien mit bestimmten Labels suchen möchten, verwenden Sie den Suchabfragebegriff labels mit einer bestimmten Label-ID. Beispiel: 'labels/LABEL_ID' in labels. Bei Erfolg enthält der Antworttext alle Dateiinstanzen, auf die das Label angewendet wurde.

So suchen Sie nach Dateien ohne eine bestimmte Label-ID: Not 'labels/LABEL_ID' in labels.

Sie können auch nach Dateien anhand bestimmter Feldwerte suchen. Beispiel: So suchen Sie nach Dateien mit einem Textwert: labels/LABEL_ID.text_field_id ='TEXT'.

Weitere Informationen finden Sie unter Nach Dateien mit einem bestimmten Label oder Feld wert 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 Sammlungen, 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 Abfrageparameter für die list Methode verwenden, sollten Sie den createdTime Schlüssel nicht für Abfragen in großen Elementsammlungen verwenden, 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. Beispiel: ?orderBy=modifiedTime.

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

Weitere Informationen

• Nach geteilten Ablagen suchen
• Suchabfragebegriffe und -operatoren
• Unterstützte MIME-Typen in Google Workspace und Google Drive
• Rollen und Berechtigungen
• Nach Dateien mit einem bestimmten Label oder Feldwert suchen