新增自訂檔案屬性

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

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

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

這是一般屬性的結構，可用於儲存雲端硬碟檔案的資料庫 ID。

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

{
  '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 資源。

存取私人自訂檔案屬性

您只能透過驗證的要求 (使用以 OAuth 2.0 用戶端 ID 取得的存取權杖) 使用 appProperties 欄位擷取不公開屬性。您無法使用 API 金鑰擷取不公開屬性。