Wyszukiwanie plików i folderów

Z tego przewodnika dowiesz się, jak interfejs Google Drive API obsługuje kilka sposobów wyszukiwania plików i folderów.

Aby zwrócić wszystkie lub niektóre pliki i foldery użytkownika Dysku, możesz użyć metody list w zasobie files. Metody list możesz też użyć do pobrania parametru fileId wymaganego w przypadku niektórych metod zasobów (np. metod get i update).

Używanie parametru fields

Jeśli chcesz określić pola, które mają być zwracane w odpowiedzi, możesz ustawić fields parametr systemowy w dowolnej metodzie zasobu files. Jeśli pominiesz parametr fields, serwer zwróci domyślny zestaw pól właściwy dla danej metody. Na przykład metoda list zwraca tylko pola kind, id, name, mimeType i resourceKey dla każdego pliku. Aby zwrócić inne pola, przeczytaj artykuł Zwracanie określonych pól.

Pobieranie pliku według identyfikatora

Aby pobrać plik, użyj metody get w zasobie files z parametrem ścieżki fileId. Jeśli nie znasz identyfikatora pliku, możesz wyświetlić listę wszystkich plików za pomocą list metody.

Metoda zwraca plik jako instancję zasobu files. Jeśli podasz parametr alt=media, odpowiedź będzie zawierać treść pliku w treści odpowiedzi. Aby pobrać plik blob, przeczytaj artykuł Pobieranie treści pliku blob.

Aby potwierdzić ryzyko pobrania znanego złośliwego oprogramowania lub innych szkodliwych plików, ustaw acknowledgeAbuse parametr zapytania na true. To pole ma zastosowanie tylko wtedy, gdy ustawiony jest parametr alt=media, a użytkownik jest właścicielem pliku lub organizatorem dysku współdzielonego, na którym znajduje się plik.

Wyświetlanie listy wszystkich plików i folderów na Moim dysku

Aby zwrócić wszystkie pliki i foldery na Moim dysku bieżącego użytkownika, użyj metody list bez żadnych parametrów.

To polecenie curl pokazuje, jak wyświetlić listę wszystkich plików:

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

Zastąp ACCESS_TOKEN autoryzowanym tokenem dostępu OAuth 2.0.

Wyszukiwanie określonych plików i folderów na Moim dysku

Aby wyszukać określony zestaw plików lub folderów na Moim dysku bieżącego użytkownika, użyj pola ciągu zapytania q z metodą list, aby filtrować pliki do zwrócenia przez połączenie co najmniej 1 wyszukiwanego hasła.

Składnia ciągu zapytania składa się z tych 3 części:

query_term operator values

Gdzie:

  • query_term to wyszukiwane hasło lub pole.

  • operator określa warunek dla wyszukiwanego hasła.

  • values to konkretne wartości, których chcesz użyć do filtrowania wyników wyszukiwania.

Na przykład ten ciąg zapytania filtruje wyszukiwanie, aby zwracać tylko foldery, ustawiając typ MIME:

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

Aby wyświetlić wszystkie wyszukiwane hasła dotyczące plików, przeczytaj artykuł Wyszukiwane hasła dotyczące plików.

Aby wyświetlić wszystkie operatory zapytań, których możesz użyć do utworzenia zapytania, przeczytaj artykuł Operatory zapytań.

Przykłady ciągów zapytań

W tabeli poniżej znajdziesz przykłady podstawowych ciągów zapytań. Rzeczywisty kod różni się w zależności od biblioteki klienta używanej do wyszukiwania.

Aby zapytanie działało prawidłowo, musisz też użyć znaków specjalnych w nazwach plików. Jeśli na przykład nazwa pliku zawiera zarówno apostrof (') jak i ukośnik odwrotny ("\"), użyj ukośnika odwrotnego, aby je pominąć: name contains 'quinn\'s paper\\essay'.

Co chcesz wyszukać Przykład
Operator dopasowania ciągu (contains)
Pliki zawierające słowo „hello” fullText contains 'hello'
Pliki zawierające dokładnie wyrażenie „hello world” fullText contains '"hello world"'
Pliki z zapytaniem zawierającym znak „\” (np. „\authors”) fullText contains '\\authors'
Pliki, których nazwa zawiera „budget” name contains 'budget'
Operatory równości i nierówności (=, !=)
Pliki o nazwie „hello” name = 'hello'
Pliki, które są folderami mimeType = 'application/vnd.google-apps.folder'
Pliki, które nie są folderami mimeType != 'application/vnd.google-apps.folder'
Pliki oznaczone gwiazdką starred = true
Pliki w koszu trashed = true
Pliki, które nie są w koszu trashed = false
Skróty wskazujące konkretny identyfikator pliku shortcutDetails.targetId = '1987654321'
Pliki, które nie zostały udostępnione nikomu ani żadnej domenie (prywatne lub udostępnione konkretnym użytkownikom lub grupom) visibility = 'limited'
Pliki, które są dostępne dla każdej osoby mającej link visibility = 'anyoneWithLink'
Pliki, które można publicznie znaleźć w internecie visibility = 'anyoneCanFind'
Operatory porównania (>, >=, <, <=)
Pliki zmodyfikowane po określonej dacie (domyślna strefa czasowa to UTC) modifiedTime > '2012-06-04T12:00:00'
Pliki utworzone po 1 stycznia 2023 r. createdTime > '2023-01-01T00:00:00'
Pliki zmodyfikowane przed 1 stycznia 2023 r. modifiedTime < '2023-01-01T00:00:00'
Operator przynależności do kolekcji (in)
Pliki będące bezpośrednimi elementami podrzędnymi w kolekcji (np. identyfikator folderu w kolekcji parents) '1234567' in parents
Pliki w folderze danych aplikacji 'appDataFolder' in parents
Pliki, których właścicielem jest użytkownik „test@example.org” 'test@example.org' in owners
Pliki, do których użytkownik „test@example.org” ma uprawnienia do zapisu 'test@example.org' in writers
Pliki, do których członkowie grupy „group@example.org” mają uprawnienia do zapisu 'group@example.org' in writers
Pliki, do których użytkownik „test@example.org” ma uprawnienia do odczytu 'test@example.org' in readers
Operator dopasowania kolekcji (has)
Pliki z niestandardową właściwością pliku widoczną dla wszystkich aplikacji properties has { key='mass' and value='1.3kg' }
Pliki z niestandardową właściwością pliku prywatną dla aplikacji wysyłającej żądanie appProperties has { key='additionalID' and value='8e8aceg2af2ge72e78' }
Pliki, które mają niestandardową właściwość pliku z kluczem „department” (niezależnie od wartości) properties has { key='department' }
Operatory logiczne (and, or, not)
Pliki, których nazwa zawiera słowa „hello” i „goodbye” name contains 'hello' and name contains 'goodbye'
Pliki, których nazwa nie zawiera słowa „hello” not name contains 'hello'
Pliki, które zawierają tekst „important” i są w koszu fullText contains 'important' and trashed = true
Pliki, które nie zawierają słowa „hello” not fullText contains 'hello'
Pliki graficzne lub wideo zmodyfikowane po określonej dacie modifiedTime > '2012-06-04T12:00:00' and (mimeType contains 'image/' or mimeType contains 'video/')
Pliki udostępnione autoryzowanemu użytkownikowi, których nazwa zawiera „hello” sharedWithMe and name contains 'hello'
Pliki, które są folderami lub skrótami mimeType = 'application/vnd.google-apps.folder' or mimeType = 'application/vnd.google-apps.shortcut'
Pliki o nazwie „Project Plan”, które nie są w koszu name = 'Project Plan' and trashed = false
Pliki będące bezpośrednimi elementami podrzędnymi w określonym folderze, które nie są w koszu '1234567' in parents and trashed = false

Filtrowanie wyników wyszukiwania za pomocą biblioteki klienta

Ten przykładowy kod pokazuje, jak użyć biblioteki klienta do filtrowania wyników wyszukiwania według nazw plików i identyfikatorów plików JPEG. Ten przykład używa wyszukiwanego hasła mimeType, aby zawęzić wyniki do plików typu image/jpeg. Ustawia też spaces na drive, aby dodatkowo zawęzić wyszukiwanie do miejsca na Dysku Dysku. Gdy nextPageToken zwraca null, nie ma więcej wyników.

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

Wyświetlanie listy plików w folderze publicznym

Aby wyszukać lub wyświetlić listę plików w folderze udostępnionym publicznie (gdzie dostęp jest ustawiony na "Każda osoba mająca link" lub "Publiczny w internecie"), użyj metody list w zasobie files z parametrem zapytania q ustawionym na filtrowanie według identyfikatora folderu w kolekcji parents:

'FOLDER_ID' in parents and trashed = false

Podczas wyświetlania listy plików w folderze publicznym możesz uwierzytelniać żądania za pomocą klucza interfejsu API zamiast danych logowania użytkownika OAuth 2.0. Jeśli folder znajduje się na dysku współdzielonym, musisz też ustawić w żądaniu supportsAllDrives=true i includeItemsFromAllDrives=true.

Te przykłady kodu pokazują, jak wyświetlić listę plików w folderze publicznym:

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'

Zastąp te elementy:

Wyszukiwane hasło parents zwraca tylko pliki i foldery będące bezpośrednimi elementami podrzędnymi w określonym folderze. Interfejs Drive API nie udostępnia operatora zapytania ani parametru, który umożliwiałby rekursywne przeszukiwanie drzew podfolderów potomnych w jednym wywołaniu interfejsu API.

Aby przeszukać folder i wszystkie jego podfoldery i pliki potomne, aplikacja musi wykonać przechodzenie po drzewie po stronie klienta:

  1. Wyszukaj bezpośrednie elementy podrzędne folderu docelowego za pomocą zapytania 'FOLDER_ID' in parents and trashed = false.
  2. Zidentyfikuj podfoldery, filtrując wyniki, w których mimeType = 'application/vnd.google-apps.folder'.
  3. Rekursywnie lub iteracyjnie wysyłaj zapytania o identyfikator każdego folderu podrzędnego, aby pobrać jego zawartość.

Te przykłady kodu pokazują, jak rekursywnie przeszukać folder i jego elementy potomne:

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

Wyszukiwanie plików z właściwościami niestandardowymi

Aby wyszukać pliki z niestandardową właściwością pliku, użyj wyszukiwanego hasła properties lub appProperties z kluczem i wartością. Aby na przykład wyszukać niestandardową właściwość pliku prywatną dla aplikacji wysyłającej żądanie o nazwie additionalID z wartością 8e8aceg2af2ge72e78:

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

Więcej informacji znajdziesz w artykule Dodawanie niestandardowych właściwości pliku.

Wyszukiwanie plików według etykiety lub wartości pola

Aby wyszukać pliki z określonymi etykietami, użyj wyszukiwanego hasła labels z konkretnym identyfikatorem etykiety.

Aby wyszukać pliki, do których zastosowano określoną etykietę:

'labels/LABEL_ID' in labels

Aby wyszukać pliki, do których nie zastosowano określonej etykiety:

not 'labels/LABEL_ID' in labels

Aby wyszukać pliki na podstawie określonej wartości pola etykiety:

labels/LABEL_ID.FIELD_ID = 'VALUE'

W przypadku powodzenia treść odpowiedzi zawiera wszystkie instancje plików pasujące do zapytania. Więcej informacji znajdziesz w artykule Wyszukiwanie plików z określoną etykietą lub wartością pola.

Wyszukiwanie w zbiorach tekstów

Domyślnie, gdy używana jest metoda list, w parametrze zapytania corpora ustawiana jest kolekcja elementów user. Aby przeszukać inne kolekcje elementów, np. te udostępnione w domain, musisz jawnie ustawić parametr corpora.

W jednym zapytaniu możesz przeszukać wiele zbiorów tekstów. Jeśli jednak połączone zbiory tekstów są zbyt duże, interfejs API może zwrócić niepełne wyniki. Sprawdź pole incompleteSearch w treści odpowiedzi. Jeśli ma wartość true, oznacza to, że pominięto niektóre dokumenty. Aby rozwiązać ten problem, zawęź parametr corpora, aby używać user lub drive.

Gdy używasz parametru zapytania orderBy w metodzie list, unikaj używania klucza createdTime w przypadku zapytań dotyczących dużych kolekcji elementów, ponieważ wymaga to dodatkowego przetwarzania i może spowodować przekroczenie limitu czasu lub inne problemy. W przypadku sortowania według czasu w dużych kolekcjach elementów możesz użyć zamiast tego parametru modifiedTime, ponieważ jest on zoptymalizowany pod kątem obsługi tych zapytań. Na przykład ustaw orderBy na modifiedTime (lub modifiedTime desc).

Jeśli pominiesz parametr zapytania orderBy, nie będzie domyślnej kolejności sortowania, a elementy będą zwracane w dowolnej kolejności.