本文件將說明命名檔案和使用中繼資料 (例如可索引的文字和縮圖) 時的重要考量。如要插入及擷取檔案，請參閱 files 資源。
指定檔案名稱和副檔名
使用 Google Drive API 插入檔案時，應用程式應在標題屬性中指定副檔名。舉例來說，插入 JPEG 檔案的作業應在中繼資料中指定 "name": "cat.jpg" 之類的項目。
後續的 GET 回應可包含唯讀 fileExtension 屬性，並使用 name 屬性中原先指定的擴充功能填入資料。當 Google 雲端硬碟使用者要求下載檔案，或是透過同步處理用戶端下載檔案時，雲端硬碟會根據檔名建立完整檔案名稱 (含副檔名)。如果副檔名遺失，Drive 會嘗試根據檔案的 MIME 類型判斷副檔名。
儲存可索引的文字
雲端硬碟會在辨識檔案類型時，自動為文件建立索引，以利搜尋，包括文字文件、PDF、含文字的圖片和其他常見類型。如果應用程式儲存其他類型的檔案 (例如繪圖、影片和捷徑)，您可以在檔案的 contentHints.indexableText 欄位中提供可建立索引的文字，藉此提高檔案的曝光度。
可建立索引的文字會以 HTML 形式編入索引。如果您儲存可建立索引的文字字串 <section attribute="value1">Here's some text</section>，系統會為「Here's some text」建立索引，但不會為「value1」建立索引。因此，將 XML 儲存為可索引的文字，不如儲存 HTML 來得實用。
指定 indexableText 時，請注意：
contentHints.indexableText的大小限制為 128 KB。- 呈現您預期使用者會搜尋的關鍵字詞和概念。
- 請勿依照重要性排序文字，因為索引器會為您有效率地排序文字。
- 應用程式應在每次儲存時更新可建立索引的文字。
- 確認文字與檔案的內容或中繼資料相關。
這最後一點或許不言自明，但很重要。新增常見搜尋字詞，強制讓檔案顯示在搜尋結果中，並非明智之舉。這可能會讓使用者感到挫折，甚至可能會促使他們刪除檔案。
上傳縮圖
雲端硬碟會自動為許多常見的檔案類型產生縮圖，例如 Google 文件、試算表和簡報。縮圖可協助使用者更輕鬆地辨識雲端硬碟檔案。
如果 Drive 無法為某些檔案類型產生標準縮圖，您可以提供應用程式產生的縮圖圖片。在檔案建立或更新期間，設定 files 資源上的 contentHints.thumbnail 欄位來上傳縮圖。
詳細說明：
- 將
contentHints.thumbnail.image欄位設為網址和檔案名稱安全的 Base64 編碼圖片 (請參閱 RFC 4648 第 5 節)。 - 將
contentHints.thumbnail.mimeType欄位設為縮圖的適當 MIME 類型。
如果雲端硬碟可以從檔案產生縮圖，系統會使用自動產生的縮圖，並忽略您可能上傳的縮圖。如果無法產生縮圖，系統會採用您提供的縮圖。
縮圖應遵循下列規則：
- 可上傳 PNG、GIF 或 JPG 格式。
- 建議寬度為 1600 像素。
- 寬度下限為 220 像素。
- 檔案大小上限為 2 MB。
- 應用程式應在每次儲存時更新這些值。
詳情請參閱 files 資源。
擷取縮圖
您可以擷取雲端硬碟檔案的中繼資料，包括縮圖。縮圖資訊會儲存在 files 資源的 thumbnailLink 欄位中。
傳回特定縮圖
以下程式碼範例顯示 files.get 方法要求，其中包含多個欄位做為查詢參數，用於傳回特定檔案的 thumbnailLink 中繼資料。詳情請參閱「傳回檔案的特定欄位」。
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)