创建和发布标签

本文档介绍如何使用 Google 云端硬盘 Labels API 创建和发布标签。

创建标签

如需创建标签，请对 labels 资源使用 create 方法。标签可以选择性地包含一个或多个 Field 对象。

您还必须指定：

  • LabelType 对象。

  • 通过 Properties 对象获取的标签 title。

  • useAdminAccess 查询参数设置为 true，以使用用户的管理员凭据。在允许访问之前，服务器会验证用户是否拥有所需的管理分类标签管理员权限。

以下代码示例展示了如何使用 create 方法创建具有指定标题的标准管理员标签，以及包含两个 Choice 对象的 SelectionOptions Field。

Python

label_body = {
    'labelType': 'ADMIN',
    'properties': {
        'title': 'TITLE'
    },
    'fields': [{
        'properties': {
            'displayName': 'DISPLAY_NAME'
        },
        'selectionOptions': {
            'listOptions': {},
            'choices': [{
                'properties': {
                    'displayName': 'CHOICE_1'
                }
            }, {
                'properties': {
                    'displayName': 'CHOICE_2'
                }
            }]
        }
    }]
}
response = service.labels().create(
    body=label_body, useAdminAccess=True).execute()

Node.js

var label = {
  'labelType': 'ADMIN',
  'properties': {
    'title': 'TITLE'
  },
  'fields': [{
    'properties': {
      'displayName': 'DISPLAY_NAME'
    },
    'selectionOptions': {
      'listOptions': {},
      'choices': [{
        'properties': {
          'displayName': 'CHOICE_1'
        }
      }, {
        'properties': {
          'displayName': 'CHOICE_2'
        }
      }]
    }
  }]
};

service.labels.create({
  requestBody: label,
  useAdminAccess: true
}, (err, res) => {
  if (err) return console.error('The API returned an error: ' + err);
  console.log(res);
});

替换以下内容：

  • TITLE：标签的标题。
  • DISPLAY_NAME：字段的显示名称。
  • CHOICE_1：SelectionOptions 字段中的第一个选项。
  • CHOICE_2：SelectionOptions 字段中的第二个选项。

标签是在 UNPUBLISHED_DRAFT State 中创建的。标签必须为 PUBLISHED，才能向用户显示并用于文件。如需了解详情，请参阅标签生命周期。

标签数量限制

创建和应用标签时，存在以下限制：

  • 标准标签：150
  • 每个标签的字段数：10

使用标签中的字段

下表介绍了您可以添加到标签中的字段类型、用户与这些字段的互动方式，以及这些字段的格式注意事项和限制：

Field Type 用户可执行的操作 格式注意事项和限制
SelectionOptions 从列表中选择一个或多个选项 支持的选项数量上限为 200
文件最多可有 10 个选项（在 ListOptions 中配置）
IntegerOptions 输入数值 仅支持整数
DateOptions 选择日历日期 （可选）DateFormat 可设置为“长格式：Month DD, YYYY”或“短格式：MM/DD/YY”
TextOptions 在文本框中输入文字 支持的字符数上限为 100
UserOptions 从 Google Workspace 通讯录中选择一个或多个用户。 根据 ListOptions 中的配置，一个文件的用户条目数上限为 10

发布标签

借助 Drive Labels API，您可以在标签草稿完成后发布该草稿。然后，用户就可以看到该标签，并将其应用于文件。

如需发布标签，请对 labels 资源使用 publish 方法，并指定：

  • 表示每个标签的 labels 资源。它包含资源 name 和 id，后者是标签的全局唯一标识符。

  • useAdminAccess 查询参数设置为 true，以使用用户的管理员凭据。在允许访问之前，服务器会验证用户是否拥有所需的管理分类标签管理员权限。

以下代码示例展示了如何使用标签的 id 来识别和发布正确的标签。

Python

service.labels().publish(
    name='labels/ID',
    body={
        'useAdminAccess': True
    }
).execute()

Node.js

service.labels.publish({
  name: 'labels/ID',
  requestBody: {
    useAdminAccess: true
  }
}, (err, res) => {
  if (err) return console.error('The API returned an error: ' + err);
  console.log(res);
});

将 ID 替换为要发布的标签的 ID。

标签发布后，该标签会移至 PUBLISHED State，并且标签的修订版本 ID 会递增。然后，用户就可以看到该标签并将其应用于文件。如需了解详情，请参阅标签生命周期。

发布标签时的限制

在准备发布标签时，请注意以下限制：

  • 标签一经发布，便无法返回到原始草稿状态。如需了解详情，请参阅标签生命周期。

  • 发布标签会创建新发布的修订版本。所有之前的草稿修订版本均会被删除。系统会保留之前发布的修订版本，但会根据需要自动删除这些版本。

  • 发布后，您将无法再进行某些更改。一般来说，这意味着任何会使与标签相关的现有元数据失效或触发新限制的更改都会被拒绝。例如，标签发布后，不允许对标签进行以下更改：

    • 标签会被直接删除。（必须先停用，然后才能删除。）
    • Field.FieldType 已更改。
    • 对 Field 验证选项的更新会拒绝之前接受的内容。
    • 减少了条目数上限。