搜尋檔案和資料夾

Google 雲端硬碟 API 支援多種檔案和資料夾搜尋方式。

您可以使用 files.list 方法，傳回雲端硬碟使用者的所有或部分檔案和資料夾。files.list 方法也可以用來擷取部分資源方法 (例如 files.get 和 files.update) 所需的 fileId。

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

使用不含任何參數的 files.list 方法，即可傳回所有檔案和資料夾。

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

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

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

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

query_term operator values

在此情況下：

  • query_term 是搜尋的查詢字詞或欄位。

  • operator 會指定查詢字詞的條件。

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

如要查看可用於篩選檔案和資料夾的查詢字詞和運算子，請參閱「搜尋查詢字詞和運算子」。

例如，下列查詢字串會設定 MIME 類型，讓搜尋結果只傳回資料夾：

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

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

查詢字串範例

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

您也必須在檔案名稱中逸出特殊字元，確保查詢能正常運作。舉例來說，如果檔案名稱同時包含撇號 (') 和反斜線 ("\") 字元，請使用反斜線逸出：name contains 'quinn\'s paper\\essay'。

要查詢的內容 範例
檔案名稱為「hello」 name = 'hello'
檔案名稱含有「hello」和「goodbye」字詞 name contains 'hello' and name contains 'goodbye'
檔案名稱不含「hello」字詞 not name contains 'hello'
垃圾桶中含有「重要」文字的檔案 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'
資料夾檔案 mimeType = 'application/vnd.google-apps.folder'
非資料夾的檔案 mimeType != 'application/vnd.google-apps.folder'
在指定日期之後修改的檔案 (預設時區為世界標準時間) modifiedTime > '2012-06-04T12:00:00'
在特定日期之後修改的圖片或影片檔案 modifiedTime > '2012-06-04T12:00:00' and (mimeType contains 'image/' or mimeType contains 'video/')
已加星號的檔案 starred = true
集合中的檔案 (例如 parents 集合中的資料夾 ID) '1234567' in parents
集合中應用程式資料資料夾中的檔案 'appDataFolder' in parents
使用者「test@example.org」擁有的檔案 'test@example.org' in owners
使用者「test@example.org」具有寫入權限的檔案 'test@example.org' in writers
檔案的「group@example.org」群組成員具備寫入權限 'group@example.org' in writers
與授權使用者共用的檔案，檔案名稱中含有「hello」 sharedWithMe and name contains 'hello'
所有應用程式都能看到自訂檔案屬性的檔案 properties has { key='mass' and value='1.3kg' }
檔案具有自訂檔案屬性，且該屬性僅供要求應用程式使用 appProperties has { key='additionalID' and value='8e8aceg2af2ge72e78' }
未與任何人或網域共用的檔案 (僅限私人檔案，或與特定使用者或群組共用的檔案) visibility = 'limited'

使用用戶端程式庫篩選搜尋結果

以下程式碼範例示範如何使用用戶端程式庫，將搜尋結果篩選為 JPEG 檔案的檔案名稱和 ID。此範例使用 mimeType 查詢字詞，將結果縮小至 image/jpeg 類型的檔案。並將 spaces 設為 drive，進一步將搜尋範圍縮小到 Google 雲端硬碟空間。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;
    }
}

搜尋含有自訂檔案屬性的檔案

如要搜尋含有自訂檔案屬性的檔案，請使用 properties 或 appProperties 搜尋查詢字詞，並附上鍵和值。舉例來說，如要搜尋僅供要求應用程式 additionalID 使用的自訂檔案屬性，且值為 8e8aceg2af2ge72e78：

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

詳情請參閱「新增自訂檔案屬性」。

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

如要搜尋特定標籤的檔案，請使用 labels 搜尋查詢字詞，並加上特定標籤 ID。例如：'labels/LABEL_ID' in labels。如果成功，回應主體會包含已套用標籤的所有檔案例項。

如要搜尋沒有特定標籤 ID 的檔案，請使用 Not 'labels/LABEL_ID' in labels。

您也可以根據特定欄位值搜尋檔案。例如，如要搜尋含有文字值的檔案，請輸入 labels/LABEL_ID.text_field_id ='TEXT'。

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

搜尋語料庫

根據預設，呼叫 files.list 的搜尋會使用 user 的 corpora。如要搜尋其他語料庫 (例如透過 domain 共用的檔案)，請設定 corpora 參數。

單一查詢可搜尋多個語料庫，但如果合併的語料庫過大，可能會傳回不完整的結果。如果回應主體中的 incompleteSearch 為 true，則不會傳回所有文件。如果發生這種情況，請選擇其他語料庫 (例如 user 或 drive) 來縮小查詢範圍。