管理檔案中繼資料

本文件涵蓋為檔案命名及處理 例如可建立索引的文字和縮圖如要插入及擷取檔案,請參閱 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>,接著是「提供一些 文字」已建立索引,但「值_1」則並非如此因此,請將 XML 儲存為可建立索引的 XML 文字不如儲存 HTML

指定 indexableText 時,請注意:

  • contentHints.indexableText 的大小上限為 128 KB。
  • 呈現您預期使用者會搜尋的關鍵字詞和概念。
  • 不要嘗試按照重要性排序文字,因為索引器會這麼做 讓您更有效率地
  • 應用程式應在每次儲存時更新可建立索引的文字。
  • 確認文字與檔案的內容或中繼資料相關。

最後一個要點聽起來可能看似明顯,卻很重要。但我們不建議 新增常用搜尋字詞,強制讓檔案顯示在搜尋結果中。這個 不僅會讓使用者感到困擾,甚至可能激勵使用者刪除檔案。

上傳縮圖

雲端硬碟會自動產生許多常見檔案的縮圖 例如 Google 文件、試算表和簡報 縮圖有助於使用者識別雲端硬碟檔案。

適用於雲端硬碟無法產生標準縮圖的檔案類型 ,您可以提供應用程式產生的縮圖。過程中 檔案建立或更新時,如要上傳縮圖,請設定 files 資源的 contentHints.thumbnail 欄位。

詳細說明:

  • contentHints.thumbnail.image 欄位設為安全的網址和檔案名稱 Base64 編碼圖片 (請參閱 RFC 4648 章節) 5)。
  • contentHints.thumbnail.mimeType 欄位設為適當的 MIME 類型 。

如果雲端硬碟可以從檔案產生縮圖,就會使用 並忽略您已上傳的任何影片。如果無法 並根據您提供的圖片來產生縮圖。

縮圖需遵守下列規則:

  • 可上傳 PNG、GIF 或 JPG 格式。
  • 建議寬度為 1600 像素。
  • 寬度下限為 220 像素。
  • 檔案大小上限為 2 MB。
  • 每次儲存時,應用程式應更新這些欄位。
,瞭解如何調查及移除這項存取權。

詳情請參閱 files 資源。

擷取縮圖

您可以擷取雲端硬碟檔案的中繼資料 (包括縮圖)。 縮圖資訊會儲存在thumbnailLink files 資源。

傳回特定縮圖

以下程式碼範例顯示 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)