本文件說明命名檔案及使用中繼資料 (例如可建立索引的文字和縮圖) 的重要注意事項。如要插入及擷取檔案,請參閱 files
資源。
指定檔案名稱和副檔名
使用 Google Drive API 插入檔案時,應用程式應在標題屬性中指定副檔名。舉例來說,插入 JPEG 檔案的作業,應在中繼資料中指定類似 "name": "cat.jpg"
的內容。
後續的 GET
回應可包含唯讀 fileExtension
屬性,其中填入原本在 name
屬性中指定的擴充功能。當 Google 雲端硬碟使用者要求下載檔案,或透過同步處理用戶端下載檔案時,雲端硬碟會根據標題建立完整檔案名稱 (含擴充功能)。在缺少副檔名的情況下,雲端硬碟會嘗試根據檔案的 MIME 類型判斷副檔名。
儲存可建立索引的文字
雲端硬碟在識別檔案類型 (包括文字文件、PDF、含有文字的圖片及其他常見類型) 時,會自動為文件建立索引以供搜尋。如果應用程式會儲存其他類型的檔案 (例如繪圖、影片和捷徑),您可以在檔案的 contentHints.indexableText
欄位中提供可建立索引的文字,藉此提高曝光度。
可建立索引的文字會以 HTML 的形式建立索引。如果您儲存可建立索引的文字字串 <section attribute="value1">Here's some text</section>
,則「以下是一些文字」會編入索引,但「value1」不會。因此,將 XML 儲存為可建立索引的文字並不像儲存 HTML 一樣實用。
指定 indexableText
時,也請注意以下幾點:
contentHints.indexableText
的大小上限為 128 KB。- 找出您希望使用者搜尋的重要詞彙和概念。
- 請勿嘗試按照重要性排序文字,因為索引器會更有效率。
- 應用程式應在每次儲存時更新可建立索引的文字。
- 確認文字與檔案內容或中繼資料相關。
這個重點可能很顯而易見,卻很重要。我們不建議新增常用搜尋字詞,強制檔案顯示在搜尋結果中。這可能會讓使用者感到不便,甚至促使他們刪除檔案。
上傳縮圖
雲端硬碟會自動產生 Google 文件、試算表和簡報等多種常見檔案類型的縮圖。縮圖可協助使用者輕鬆找到雲端硬碟檔案。
對於 Google 雲端硬碟無法產生標準縮圖的檔案類型,您可以提供應用程式產生的縮圖。在建立或更新檔案期間,透過設定 files
資源的 contentHints.thumbnail
欄位來上傳縮圖。
詳細說明:
- 將
contentHints.thumbnail.image
欄位設為網址和檔案名稱安全採用 Base64 編碼的圖片 (請參閱 RFC 4648 第 5 節)。 - 將
contentHints.thumbnail.mimeType
欄位設為縮圖的適當 MIME 類型。
如果 Google 雲端硬碟可以從檔案產生縮圖,則會使用自動產生的縮圖,並忽略所有已上傳的檔案。如果系統無法產生縮圖,就會使用您提供的縮圖。
縮圖必須遵守下列規則:
- 可使用 PNG、GIF 或 JPG 格式上傳。
- 建議寬度為 1600 像素。
- 寬度不得少於 220 像素。
- 檔案大小上限為 2 MB。
- 每次儲存時,應用程式應該會更新這些值。
詳情請參閱 files
資源。
擷取縮圖
您可以擷取雲端硬碟檔案的中繼資料 (包括縮圖)。
縮圖資訊位於 files
資源的 thumbnailLink
欄位中。
傳回特定縮圖
下列程式碼範例說明如何以多個欄位做為查詢參數,傳回特定檔案的 thumbnailLink
中繼資料的 files.get
方法要求。詳情請參閱「傳回檔案的特定欄位」。
GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=id,name,mimeType,thumbnailLink
將 FILE_ID 替換為您要尋找的檔案 fileId
。
如果可以,該要求會將短期網址傳回至檔案縮圖。這類連結通常會持續幾小時。只有在要求權限的應用程式可以存取檔案內容時,系統才會填入這個欄位。如果檔案並未公開共用,則必須使用憑證要求擷取 thumbnailLink
中傳回的網址。
傳回縮圖清單
下列程式碼範例顯示的是 files.list
方法要求,其中含有多個欄位做為查詢參數,藉此傳回檔案清單的 thumbnailLink
中繼資料。詳情請參閱「搜尋檔案與資料夾」。
GET https://www.googleapis.com/drive/v3/files/?fields=files(id,name,mimeType,thumbnailLink)
如要將搜尋結果限制為特定檔案類型,請套用查詢字串以設定 MIME 類型。舉例來說,下列程式碼範例說明如何將清單限制為 Google 試算表檔案。如要進一步瞭解 MIME 類型,請參閱 Google Workspace 和 Google 雲端硬碟支援的 MIME 類型。
GET https://www.googleapis.com/drive/v3/files/q=mimeType='application/vnd.google-apps.spreadsheet'&fields=files(id,name,mimeType,thumbnailLink)