新增自訂檔案屬性

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

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

屬性也可用於搜尋運算式

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

Drive API v3

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

Drive API 第 2 版

{
  '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 第 2 版,請參閱 properties 資源。

存取私人自訂檔案屬性

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