新增自訂檔案屬性

自訂檔案屬性是鍵/值組合，用於儲存 Google 雲端硬碟檔案的自訂中繼資料 (例如標記)、其他資料儲存庫的 ID、工作流程應用程式之間共用的資訊等。舉例來說，您可以為銷售部門在第 1 季產生的所有文件新增檔案屬性。

如要新增所有應用程式都能看到的屬性，請使用 files 資源的 properties 欄位。如要新增僅限應用程式使用的屬性，請使用 files 資源的 appProperties 欄位。

屬性也可以用於搜尋運算式。

這是典型的屬性結構，可用於在檔案中儲存 Google 雲端硬碟檔案的資料庫 ID。

使用自訂檔案屬性

本節說明如何執行一些與自訂檔案屬性相關的工作，這些工作會影響所有應用程式。

新增或更新自訂檔案屬性

如要新增或更新所有應用程式可見的屬性，請使用 files.update 方法設定 files 資源的 properties 欄位。

PATCH https://www.googleapis.com/drive/v3/files/FILE_ID

{
  "properties": {
    "name": "wrench",
    "mass": "1.3kg",
    "count": "3"
  }
}

您也可以使用 Google Apps Script 中的進階雲端硬碟服務，將自訂屬性新增至檔案。詳情請參閱「新增自訂屬性」。

取得或列出自訂檔案屬性

如要查看所有應用程式可見的屬性，請使用 files.get 方法擷取檔案的自訂檔案屬性。

GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=properties

回應包含 properties 物件，其中含有鍵/值組合的集合。

{
  "properties": {
    "name": "wrench",
    "mass": "1.3kg",
    "count": "3"
  }
}

刪除自訂檔案屬性

如要刪除所有應用程式可見的屬性值，請使用 files.update 方法，將 files 資源的 properties 欄位設為空值。

PATCH https://www.googleapis.com/drive/v3/files/FILE_ID

{
  "name": null
}

如要查看變更，請呼叫 files.get 方法，擷取檔案的 properties 物件。

{
  "properties": {
    "mass": "1.3kg",
    "count": "3"
  }
}

自訂檔案屬性的限制

自訂屬性有以下限制：

• 每個檔案最多可有 100 個自訂屬性，總計來自所有來源。
• 每個檔案最多 30 個公開屬性，總計來自所有來源。
• 每個應用程式的檔案最多可有 30 個私有屬性。
• 以 UTF-8 編碼時，每個屬性字串 (包括鍵和值) 最多 124 個位元組。舉例來說，如果屬性的鍵長度為 10 個字元，值就只能有 114 個字元。同樣地，如果屬性的值需要 100 個字元，則鍵最多可使用 24 個字元。

詳情請參閱 files 資源。如要瞭解 Drive API 第 2 版，請參閱 properties 資源。

存取私人自訂檔案屬性

您只能透過經過驗證的要求，使用 appProperties 欄位擷取私人資源，且該要求必須使用透過 OAuth 2.0 用戶端 ID 取得的存取權杖。您無法使用 API 金鑰擷取私人資源。