本文件說明命名檔案及使用中繼資料 (例如可建立索引的文字和縮圖) 的重要注意事項。如要插入及擷取檔案，請參閱 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)