新增自訂檔案屬性

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

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

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

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

Drive API v3

"appProperties": {
  "additionalID": "ID",
}

Drive API v2

{
  'key':        'additionalID',
  'value':      'ID',
  'visibility': 'PRIVATE'
}

使用自訂檔案屬性

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

新增或更新自訂檔案屬性

如要新增或更新所有應用程式可見的屬性，請使用 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 v2，請參閱 properties 資源。

存取私有自訂檔案屬性

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