Nach Dateien und Ordnern suchen

In dieser Anleitung wird beschrieben, 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. Sie können die list Methode auch verwenden, um die fileId abzurufen, 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.

Wenn Sie das Risiko des Herunterladens bekannter Malware oder anderer missbräuchlicher Dateien bestätigen möchten, setzen Sie den acknowledgeAbuse Abfrageparameter auf true. 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 in „Meine Ablage“ des aktuellen Nutzers nach einer bestimmten Gruppe von Dateien oder Ordnern suchen möchten, verwenden Sie das Feld q für den Abfragestring mit der Methode list, 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 so gefiltert, dass nur Ordner zurückgegeben werden, indem der MIME-Typfestgelegt wird:

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

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

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

Beispiele für Abfragestrings

Die folgende Tabelle enthält Beispiele für einige grundlegende Abfragestrings. Der tatsächliche Code hängt von der Clientbibliothek ab, die Sie für die 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'.

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 Suchbegriff 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.

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

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()

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
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 (Zugriff auf „Jeder mit dem Link“ oder „Öffentlich im Web“ gesetzt), verwenden Sie die list Methode für die files Ressource mit dem q Abfrage parameter, der so festgelegt ist, dass nach der Ordner-ID in der parents Sammlung 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:

/**
 * 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 -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'

Untergeordnete Ordner und Dateien rekursiv durchsuchen

Der Suchbegriff parents gibt nur direkte untergeordnete Dateien und Ordner zurück, die sich im angegebenen Ordner befinden. Die Drive API bietet keinen Abfrageoperator oder Parameter, um untergeordnete Unterordnerstrukturen in einem einzigen API-Aufruf rekursiv zu durchsuchen.

Wenn Sie einen Ordner und alle seine untergeordneten Unterordner und Dateien durchsuchen möchten, muss Ihre Anwendung die Baumstruktur auf Clientseite durchlaufen:

1. Fragen Sie direkte untergeordnete Elemente des Zielordners mit 'FOLDER_ID' in parents and trashed = false ab.
2. Identifizieren Sie Unterordner, indem Sie die Ergebnisse filtern, bei denen mimeType = 'application/vnd.google-apps.folder'.
3. Fragen Sie rekursiv oder iterativ die ID jedes untergeordneten Ordners ab, um seinen Inhalt abzurufen.

Die folgenden Codebeispiele zeigen, wie Sie einen Ordner und seine untergeordneten Elemente rekursiv durchsuchen:

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

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

Nach Dateien mit benutzerdefinierten Eigenschaften suchen

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

Wenn Sie nach Dateien mit bestimmten Labels suchen möchten, verwenden Sie den Suchanfragebegriff 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'

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

In mehreren Corpora suchen

Standardmäßig ist die user Elementsammlung für den corpora Suchparameter 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 in einer einzigen Abfrage in mehreren Corpora suchen. 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. 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.

Weitere Informationen

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