本文將說明檔案命名和處理中繼資料 (例如可建立索引的文字和縮圖) 時的重要注意事項。如要插入及擷取檔案，請參閱 files 資源。
中繼資料總覽
在 Google 雲端硬碟 API 中，files 資源代表中繼資料。與中繼資料是子物件的 API 不同，Drive API 會將整個 files 資源視為中繼資料。您可以透過 資源的 get 或 list 方法，直接存取中繼資料。files
根據預設，get 和 list 方法只會傳回部分欄位。如要擷取特定資料，您必須在要求中定義 fields system 參數。如果省略，伺服器會傳回方法專屬的預設欄位子集。舉例來說，list 方法只會傳回每個檔案的 kind、id、name、mimeType 和 resourceKey 欄位。如要傳回不同欄位，請參閱「傳回特定欄位」。
此外，使用者在檔案中的角色也會影響中繼資料的顯示。permissions 資源不會決定使用者對檔案或資料夾可執行的動作。而是包含布林值 capabilities 欄位集合的 files 資源。Google 雲端硬碟 API 會從與檔案或資料夾相關聯的 permissions 資源衍生這些 capabilities。詳情請參閱「瞭解檔案功能」。
Drive API 提供兩種受限的中繼資料範圍：drive.metadata 和 drive.metadata.readonly。drive.metadata 範圍可讓您查看及管理檔案中繼資料，而 drive.metadata.readonly 範圍則為唯讀。兩者都嚴格禁止存取檔案內容。詳情請參閱「選擇 Google Drive API 範圍」。
最後，請務必驗證權限和範圍的邏輯。舉例來說，使用者可能擁有檔案的完整權限，但如果應用程式只有 drive.metadata.readonly 範圍，Drive API 會封鎖修改或下載檔案的嘗試。
指定檔案名稱和副檔名
使用 Google Drive API 插入檔案時，應用程式應在 name 屬性中指定副檔名。舉例來說，插入 JPEG 檔案的操作應在中繼資料中指定類似 "name": "cat.jpg" 的內容。
後續的 GET 回應可以包含唯讀的 fileExtension 屬性，其中填入 name 屬性中原先指定的擴充功能。當 Google 雲端硬碟使用者要求下載檔案，或透過同步處理用戶端下載檔案時，雲端硬碟會根據名稱建立完整檔案名稱 (含副檔名)。如果缺少副檔名，雲端硬碟會嘗試根據檔案的 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 文件、試算表和簡報。縮圖可協助使用者更輕鬆地辨識雲端硬碟檔案。
如果 Google 雲端硬碟無法為檔案類型產生標準縮圖，您可以提供應用程式產生的縮圖。建立或更新檔案時，請在 files 資源上設定 contentHints.thumbnail 欄位，上傳縮圖。
詳細說明：
- 將
contentHints.thumbnail.image欄位設為網址和檔案名稱安全 Base64 編碼圖片 (請參閱 RFC 4648 第 5 節)。 - 將
contentHints.thumbnail.mimeType欄位設為縮圖的適當 MIME 類型。
如果雲端硬碟可以從檔案產生縮圖，就會使用自動產生的縮圖，並忽略您上傳的縮圖。如果無法產生縮圖，就會使用你提供的縮圖。
縮圖應符合下列規則：
- 可上傳 PNG、GIF 或 JPG 格式的檔案。
- 建議寬度為 1600 像素。
- 寬度下限為 220 像素。
- 檔案大小上限為 2 MB。
- 應用程式每次儲存時，都應更新這些值。
詳情請參閱 files 資源。
擷取縮圖
您可以擷取雲端硬碟檔案的中繼資料，包括縮圖。縮圖資訊位於 files 資源的 thumbnailLink 欄位。
傳回特定縮圖
下列程式碼範例顯示 get 方法要求，其中包含多個欄位做為查詢參數，可傳回特定檔案的 thumbnailLink 中繼資料。詳情請參閱傳回檔案的特定欄位。
GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=id,name,mimeType,thumbnailLink
將 FILE_ID 替換為要尋找的檔案 fileId。
如果有的話，要求會傳回檔案縮圖的短期網址。
連結通常會在數小時後失效。只有在要求應用程式可以存取檔案內容時，這個欄位才會填入資料。如果檔案未公開分享，則必須使用已驗證的要求，擷取 thumbnailLink 中傳回的網址。
傳回縮圖清單
下列程式碼範例顯示 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)