新增自訂檔案屬性

自訂檔案屬性是鍵/值組合，用於儲存 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 中的進階 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.0 的相關資訊，請參閱 properties 資源。

存取私人自訂檔案屬性

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