添加自定义文件属性

自定义文件属性是用于存储 Google 云端硬盘文件自定义元数据(例如代码)、来自其他数据存储区的 ID、在工作流应用之间共享的信息等键值对。例如,您可以为第一季度销售部门生成的所有文档添加文件属性。

如需添加对所有应用可见的属性,请使用 files 资源的 properties 字段。如需添加仅限您的应用的属性,请使用 files 资源的 appProperties 字段。

属性也可以在搜索表达式中使用。

这是典型属性的结构,可用于在文件中存储云端硬盘文件的数据库 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 脚本中的高级云端硬盘服务为文件添加自定义属性。如需了解详情,请参阅添加自定义属性

获取或列出自定义文件属性

如需查看所有应用可见的属性,请使用 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 字段设置为 null。

PATCH https://www.googleapis.com/drive/v3/files/FILE_ID
{
  "name": null
}

如需查看更改,请调用 files.get 方法来检索文件的 properties 对象。

{
  "properties": {
    "mass": "1.3kg",
    "count": "3"
  }
}

自定义文件属性的限制

自定义属性具有以下限制:

  • 每个文件最多只能包含 100 个自定义属性,所有来源总计。
  • 每个文件最多只能包含 30 项公开资源,所有来源的总和。
  • 任一应用的每个文件最多包含 30 个私有属性。
  • 每个属性字符串(包括键和值)最多 124 个字节,采用 UTF-8 编码。例如,具有长度为 10 个字符的键的属性,其值中只能包含 114 个字符。同样,要求值 100 个字符的属性最多可以为键使用 24 个字符。

如需了解详情,请参阅 files 资源。对于 Drive API v2,请参阅 properties 资源。

访问私有自定义文件属性

您只能通过经过身份验证的请求(使用通过 OAuth 2.0 客户端 ID 获取的访问令牌)通过 appProperties 字段检索私有属性。您无法使用 API 密钥检索私有属性。