自定义文件属性是键值对,用于存储 Google 云端硬盘文件的自定义元数据(例如标记)、其他数据存储区中的 ID、工作流应用之间共享的信息等。例如,您可以为销售部门在第一季度生成的所有文档添加文件属性。
如需添加对所有应用可见的属性,请使用 files
资源的 properties
字段。如需添加仅限于您的应用的属性,请使用 files
资源的 appProperties
字段。
属性还可在搜索表达式中使用。
这是典型属性的结构,可能用于在文件中存储云端硬盘文件的数据库 ID。
Drive API v3
"appProperties": {
"additionalID": "ID",
}
云端硬盘 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 个私有属性。
- 采用 UTF-8 编码的每个属性字符串(包括键和值)不得超过 124 个字节。例如,键为 10 个字符的属性只能有 114 个字符的值。同样,如果某个属性要求值的长度为 100 个字符,则其键的长度最多可为 24 个字符。
如需了解详情,请参阅 files
资源。如需了解 Drive API v2,请参阅 properties
资源。
访问私有自定义文件属性
您只能通过使用 OAuth 2.0 客户端 ID 获取的访问令牌发出的经过身份验证的请求,使用 appProperties
字段检索私有媒体资源。您无法使用 API 密钥检索私有媒体资源。