搜尋檔案和資料夾

使用 files.list 方法,即可傳回所有或部分雲端硬碟使用者的檔案和資料夾。

您也可以使用 files.list 方法擷取部分資源方法 (例如 files.getfiles.update) 所需的 fileId

在目前使用者的「我的雲端硬碟」中搜尋所有檔案和資料夾

使用 files.list (不含任何參數) 以傳回所有檔案和資料夾。

在目前使用者的「我的雲端硬碟」中搜尋特定檔案或資料夾

如要搜尋一組特定檔案或資料夾,請搭配 files.list 使用查詢字串 q 欄位,透過結合一或多個搜尋字詞來篩選要傳回的檔案。

查詢字串包含以下三個部分:

query_term operator values

在此情況下:

  • query_term 是要搜尋的查詢字詞或欄位。如要查看可用於篩選共用雲端硬碟的查詢字詞,請參閱搜尋字詞和運算子

  • operator 會指定查詢字詞的條件。如要查看每個查詢字詞可與哪些運算子搭配使用,請參閱查詢運算子

  • values 是您要用來篩選搜尋結果的特定值。

例如,下列查詢字串會篩選搜尋,只傳回資料夾:

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

以下範例說明如何使用用戶端程式庫,根據 JPEG 檔案的檔案名稱和 ID 篩選搜尋結果。本範例使用 mimeType 查詢字詞,將結果範圍縮小至 image/jpeg 類型的檔案。這個範例也會將 spaces 設為 drive,進一步將搜尋範圍縮小至 雲端硬碟空間。當 nextPageToken 傳回 null 時,就沒有其他結果。

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, items(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
/**
 * Search file in drive location
 * @return{obj} data file
 * */
async function searchFile() {
  const {GoogleAuth} = require('google-auth-library');
  const {google} = require('googleapis');

  // Get credentials and build service
  // TODO (developer) - Use appropriate auth mechanism for your app
  const auth = new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/drive',
  });
  const service = google.drive({version: 'v3', auth});
  const files = [];
  try {
    const res = await service.files.list({
      q: 'mimeType=\'image/jpeg\'',
      fields: 'nextPageToken, files(id, name)',
      spaces: 'drive',
    });
    Array.prototype.push.apply(files, res.files);
    res.data.files.forEach(function(file) {
      console.log('Found file:', file.name, file.id);
    });
    return res.data.files;
  } catch (err) {
    // TODO(developer) - Handle error
    throw err;
  }
}

PHP

drive/snippets/drive_v3/src/DriveSearchFiles.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;
    }
}

如要將搜尋範圍限制在資料夾,請使用查詢字串,將 MIME 類型設為 q: mimeType = 'application/vnd.google-apps.folder'

如要進一步瞭解 MIME 類型,請參閱「Google Workspace 和 Google 雲端硬碟支援的 MIME 類型」一文。

查詢字串範例

下表列出一些基本的查詢字串。實際程式碼會因用於搜尋的用戶端程式庫而異。

要查詢的內容 範例
名為「hello」的檔案 name = 'hello'
名稱包含「hello」和「goodbye」字詞的檔案 name contains 'hello' and name contains 'goodbye'
名稱不含「hello」一詞的檔案 not name contains 'hello'
屬於 Google 應用程式或資料夾 MIME 類型的資料夾 mimeType = 'application/vnd.google-apps.folder'
非資料夾的檔案 mimeType != 'application/vnd.google-apps.folder'
含有「重要」文字且在垃圾桶中的檔案 fullText contains 'important' and trashed = true
包含「hello」一詞的檔案 fullText contains 'hello'
不包含「hello」一詞的檔案 not fullText contains 'hello'
包含「hello world」完全比對詞組的檔案 fullText contains '"hello world"'
查詢包含「\"」字元的檔案 (例如「\authors」) fullText contains '\\authors'
集合中含有 ID 的檔案,例如 parents 集合 '1234567' in parents
集合中應用程式資料資料夾的檔案 'appDataFolder' in parents
使用者「test@example.org」擁有寫入權限的檔案 'test@example.org' in writers
要讓「group@example.org」群組成員擁有寫入權限的檔案 'group@example.org' in writers
在特定日期之後修改的檔案 modifiedTime > '2012-06-04T12:00:00' // default time zone is UTC
與授權使用者共用 (名稱包含「hello」) 的檔案 sharedWithMe and name contains 'hello'
未與任何人或網域共用的檔案 (僅限私人或與特定使用者/群組共用) visibility = 'limited'
在特定日期後修改的圖片或影片檔案 modifiedTime > '2012-06-04T12:00:00' and (mimeType contains 'image/' or mimeType contains 'video/')

使用自訂檔案屬性搜尋檔案

如要搜尋包含自訂檔案屬性的檔案,請搭配索引鍵和值使用 appProperties 搜尋查詢字詞。舉例來說,如要搜尋名為 additionalID 且值為 8e8aceg2af2ge72e78 的自訂檔案屬性,請執行以下操作:

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

如要進一步瞭解自訂檔案屬性,請參閱「新增自訂檔案屬性」。

搜尋含有特定標籤或欄位值的檔案

如要搜尋有特定標籤的檔案,請使用具有特定標籤 ID 的 labels 搜尋查詢字詞。例如:'labels/LABEL_ID' in labels

如何搜尋沒有特定標籤 ID 的檔案:Not 'labels/LABEL_ID' in labels

您也可以依據特定欄位值搜尋檔案。例如,如要搜尋含有文字值的檔案:labels/LABEL_ID.text_field_id = 'TEXT'

詳情請參閱「搜尋具有特定標籤或欄位值的檔案」。

搜尋語料庫

根據預設,呼叫 files.list 的搜尋會使用 user 語料庫。如要搜尋其他語料庫 (例如與Google Workspace 網域共用的檔案),請使用 corpora 參數。

單一查詢中可能會搜尋多個語料庫,但如果合併的語料庫過大,則可能會傳回不完整的結果。如果 incompleteSearch 結果是 true,表示並非所有文件都會傳回。