Google Drive 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
,進一步將搜尋範圍縮小到 雲端硬碟空間。當 nextPageToken
傳回 null
時,就沒有其他結果。
Java
Python
Node.js
PHP
搜尋具有自訂檔案屬性的檔案
如要搜尋含有自訂檔案屬性的檔案,請使用 properties
或含有索引鍵和值的 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
的 corpora
。如要搜尋其他語料庫 (例如與 domain
共用的檔案),請設定 corpora
參數。
在單一查詢中可能會搜尋多個語料庫,但如果合併的主體過大,系統可能會傳回不完整的結果。如果回應主體中的 incompleteSearch
是 true
,則不會傳回所有文件。如果發生這種情況,建議您選擇其他語料庫 (例如 user
或 drive
) 來縮小查詢範圍。