新增自訂檔案屬性

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

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

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

這是一般屬性的結構，可用於儲存雲端硬碟檔案的資料庫 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 中的進階 Drive 服務，在檔案中新增自訂屬性。詳情請參閱「新增自訂屬性」。

取得或列出自訂檔案屬性

如要查看所有應用程式可見的屬性，請使用 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 金鑰擷取不公開屬性。