Drive Labels API 概览

标签是您定义的元数据，可帮助用户整理、查找 Google 云端硬盘中的文件并为其应用政策。Drive Labels API 是一个 RESTful API，可通过将元数据附加到云端硬盘文件来支持业务流程。此 API 的常见用途如下：

将内容分类以遵循信息治理策略 - 创建标签来标识需要特殊处理的敏感内容或数据。例如，您可以创建一个名为“敏感”且带有“绝密”、“机密”和“公开”标记的带标记的标签（具有以不同颜色标识的选项值标签）。
将政策应用于云端硬盘中的内容 - 创建标签以在其整个生命周期中管理云端硬盘内容，并确保其遵循组织的记录保留做法。例如，使用标签来管理数据泄露政策 (DLP)，即“敏感性”标签设置为“绝密”的文件无法下载到计算机上。
挑选和查找文件 - 创建标签，以便组织中的用户根据标签及其字段查找内容，从而提升公司内容的可搜索性。例如，您的组织中的人员可以使用云端硬盘搜索选项查找在特定日期之前等待签名的所有合同。

下面列出了 Drive Labels API 中使用的常用术语：

标签

放在云端硬盘文件中的结构化元数据。云端硬盘用户可以为文件分配标签并设置标签字段值。标签由以下部分组成：

标签名称: 标签的资源名称。标签 ID 是标签名称的一部分。根据请求，该名称采用 labels/{id} 或 labels/{id}@{revisionId} 形式。如需了解详情，请参阅下文的标签修订版本。
标签 ID: 标签的全局唯一标识符。ID 是标签名称的一部分，但与名称不同的是，修订版本之间是一致的。

标签有两种样式：

标记标签

具有 SelectionOptions 字段类型的标签，其中包含可以进行颜色编码以指示重要性的选择。可以通过 Choice 的 Properties 设置 badgeConfig 来完成此操作。

云端硬盘会显示每个文件所选选项的颜色，以便用户清楚地了解文件的状态、分类等。例如，“敏感度”标记标签的“绝密”选项可能会显示为红色。您一次只能使用一个标记标签。

标准标签

包含零个或零个以上字段类型的标签。标准标签可能具有标签标题（如“Project Moonshoot”），并指示与项目相关的所有文件。标准标签还可以具有多个结构化字段。例如，标题为“合同”的标签可能包含“公司”、“截止日期”、“状态”和“签署者”字段。每个字段均为特定类型（文本、日期、选择或用户）。

字段

标签的单个可设置组件。一个标签可以有零个或零个以上的关联字段。

字段类型: 与字段相关联的值的数据类型。可配置为文本、整数、日期、用户或选择。如果您使用 ListOptions 配置该字段，则可以使用多个值设置用户和选择字段。所选类型会影响适用于云端硬盘内容的有效值以及可用的搜索查询选项。

选择

用户可以在 SelectionOptions 字段中选择几个选项之一。

标签类型

所有标签都包含一个 LabelType。标签有 2 种：

管理

如需创建和修改管理员拥有的标签，您必须是拥有管理标签权限的帐号管理员。

管理员可以与任何用户共享管理员标签，以授予该用户查看这些标签并将其应用于云端硬盘内容的权限。如需修改或读取云端硬盘内容上的标签值，您需要以下权限：

修改 - 用户必须修改相应的权限级别，才能修改与指定标签相关的云端硬盘内容元数据：
- 云端硬盘内容：EDITOR
- 标签：APPLIER
读取 - 用户要读取或搜索与给定标签相关的云端硬盘内容元数据，必须具有适当的权限级别：
- 云端硬盘内容：READER
- 标签：READER

Shared

非管理员用户可以创建共享标签，以供其他人应用于云端硬盘内容。团队可以创建和整理自己的标签以供团队使用，而无需管理员。

标签分类

当前可供用户用来应用云端硬盘文件的标签字段。也称为标签架构。

标签分类示例：

灵敏度 - 红色、橙色、黄色、绿色
状态 - 尚未开始、草稿、审核中、最终
内容类型 - 合同、设计文档、模型
部门 - 营销、财务、人力资源、销售

标签生命周期

标签会经历创建、发布、更新等生命周期。当标签完成整个生命周期后，其标签修订版本会增加。如需了解详情，请参阅下文的标签生命周期。

标签修订版本

标签的实例。每当创建、更新、发布或弃用标签时，标签修订版本都会递增。

修订版本草稿: 标签当前草稿实例的修订版本号。您可以对标签进行多项更新，每次更新都会递增其草稿修订版本号，而不会影响已发布的修订版本。通过创建草稿标签，您可以在发布之前测试标签更新。
已发布修订版本: 已发布版本的修订版本的编号。已发布的标签是用户当前可用的标签实例。

标签生命周期

标签、字段和选项会在其整个生命周期中经历特定的状态。此外，标签可能有不同的修订版本。下图显示了标签生命周期（包括修订）：

创建标签 (create()) - 创建标签并将其作为 revision_id=1 存储在数据库中。该标签的状态为 UNPUBLISHED_DRAFT。在此状态下：
- 用户无法查看标签
- 用户无法将此标签应用于云端硬盘内容。
（可选）更新标签、字段或选项 (delta()) - 每次更新（甚至在发布之前）都存储在数据库中，并且标签的修订版本数递增。
发布标签 (publish()) - 标签状态为 PUBLISHED，用户可以应用标签。发布标签后，修订版本也会随之增加。
（可选）更新标签、字段或选项 (delta()) - 更新标签、字段或选项，并将其作为草稿标签存储在数据库中。该标签的状态为 PUBLISHED，其值为 hasUnpublishedChanges=true，表示存在草稿更改，但用户看不到这些更改。每次更新都会递增标签的修订版本。
（可选）发布标签 (publish()) - 发布最新草稿（如果有）。该标签的状态为 PUBLISHED，用户可以应用该标签。发布标签会递增其版本。
停用标签 (disable()) - 标签的状态为 DISABLED，但用户可以通过 API 应用标签。但是，已停用的标签不会显示在界面中，除非已配置为显示。弃用标签会增加其修订版本。
启用标签 (enable()) - 此标签会返回 PUBLISHED 状态，用户可以应用该标签。发布标签后，修订版本也会随之增加。
删除标签 (delete()) - 标签状态为 DELETED，因此无法应用。已删除的标签最终会被完全清除。

需要强调的是，每次更新标签都会递增标签的修订版本。此外，如果标签已发布，则在 n 次更新后再次发布，表示其已发布的修订版本号为修订版本 + n + 1 个连续更新数量。

后续步骤

如需了解如何使用 Google Workspace API 进行开发，包括处理身份验证和授权，请参阅 Workspace 开发者使用入门。
如需了解如何配置和运行简单的 Labels API 应用，请参阅快速入门概览。