为资源添加标签
本页面介绍了如何为 BigQuery 资源添加标签。
准备工作
授予为用户提供执行本文档中的每个任务所需权限的 Identity and Access Management (IAM) 角色。执行任务所需的任何权限都列在任务的“所需 IAM 角色”部分中。
为数据集添加标签
在创建 BigQuery 数据集时,您可以使用 bq 命令行工具的 bq mk
命令或调用 datasets.insert
API 方法来为该数据集添加标签。目前,您不能向通过 Google Cloud 控制台创建的数据集添加标签。
本页面介绍如何在创建数据集后向其添加标签。如需详细了解如何在创建数据集时添加标签,请参阅创建数据集。
在创建数据集后添加标签的方法如下:
- 使用 Google Cloud 控制台
- 使用 SQL DDL 语句
- 使用 bq 命令行工具的
bq update
命令 - 调用
datasets.patch
API 方法 - 使用客户端库
向数据集添加标签时,标签不会传播到该数据集中的资源。表或视图不会继承数据集标签。向数据集添加标签后,标签会包含在存储空间结算数据中,但不会包含在与作业相关的结算数据中。
如需详细了解标签的格式,请参阅标签要求。
所需 IAM 角色
如需获得为现有数据集添加标签所需的权限,请让您的管理员为您授予 BigQuery Data Editor (roles/bigquery.dataEditor
) IAM 角色。如需详细了解如何授予角色,请参阅管理对项目、文件夹和组织的访问权限。
此预定义角色可提供 bigquery.datasets.update
权限,该权限是为现有数据集添加标签所必需的。
如需详细了解 BigQuery 中的 IAM 角色和权限,请参阅预定义的角色和权限。
为数据集添加标签
如需在创建数据集后为其添加标签,请执行以下操作:
控制台
在 Google Cloud 控制台中,选择相应的数据集。
在数据集详情页面上,点击标签右侧的铅笔图标。
在修改标签对话框中执行以下操作:
- 点击添加标签。
- 输入键和值。如需应用更多标签,请点击添加标签。每个键只能在每个数据集内使用一次,但您可以在同一项目的不同数据集内使用同一个键。
- 如需更新标签,请修改现有键或值。
- 如需保存更改,请点击更新。
SQL
使用 ALTER SCHEMA SET OPTIONS
DDL 语句在现有数据集上设置标签。设置标签会覆盖数据集中的所有现有标签。以下示例在数据集 mydataset
上设置一个标签:
在 Google Cloud 控制台中,转到 BigQuery 页面。
在查询编辑器中,输入以下语句:
ALTER SCHEMA mydataset SET OPTIONS ( labels = [('sensitivity', 'high')]);
点击
运行。
如需详细了解如何运行查询,请参阅运行交互式查询。
bq
如需为现有数据集添加标签,请发出带 set_label
标志的 bq update
命令。重复使用该标志可添加多个标签。
如果数据集属于非默认项目,请按以下格式将相应项目 ID 添加到数据集:PROJECT_ID:DATASET
。
bq update --set_label KEY:VALUE PROJECT_ID:DATASET
替换以下内容:
KEY:VALUE
:您要添加的标签的键值对。键不得重复。键和值只能包含小写字母、数字字符、下划线和短划线。所有字符必须使用 UTF-8 编码,允许使用国际字符。PROJECT_ID
:您的项目 ID。DATASET
:您要为其添加标签的数据集。
示例:
如需添加标签来跟踪部门,请输入 bq update
命令并将 department
指定为标签键。例如,如要为默认项目中的 mydataset
添加 department:shipping
标签,请输入以下命令:
bq update --set_label department:shipping mydataset
如需为数据集添加多个标签,请重复使用 set_label
标志并为每个标签指定唯一键。例如,如要为默认项目中的 mydataset
添加 department:shipping
标签和 cost_center:logistics
标签,请输入以下命令:
bq update \
--set_label department:shipping \
--set_label cost_center:logistics \
mydataset
API
如需为现有数据集添加标签,请调用 datasets.patch
方法,并填充数据集资源的 labels
属性。
由于 datasets.update
方法会替换整个数据集资源,因此最好使用 datasets.patch
方法。
Go
试用此示例之前,请按照 BigQuery 快速入门:使用客户端库中的 Go 设置说明进行操作。 如需了解详情,请参阅 BigQuery Go API 参考文档。
如需向 BigQuery 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为客户端库设置身份验证。
Java
此示例使用 Java 版 Google HTTP 客户端库向 BigQuery API 发送请求。
试用此示例之前,请按照 BigQuery 快速入门:使用客户端库中的 Java 设置说明进行操作。 如需了解详情,请参阅 BigQuery Java API 参考文档。
如需向 BigQuery 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为客户端库设置身份验证。
Node.js
试用此示例之前,请按照 BigQuery 快速入门:使用客户端库中的 Node.js 设置说明进行操作。 如需了解详情,请参阅 BigQuery Node.js API 参考文档。
如需向 BigQuery 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为客户端库设置身份验证。
Python
试用此示例之前,请按照 BigQuery 快速入门:使用客户端库中的 Python 设置说明进行操作。 如需了解详情,请参阅 BigQuery Python API 参考文档。
如需向 BigQuery 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为客户端库设置身份验证。
为表和视图添加标签
在创建表或视图时向其添加标签的方法如下:
- 使用 bq 命令行工具的
bq mk
命令 - 调用
tables.insert
API 方法
本页面介绍如何向现有表或视图添加标签。如需详细了解如何在创建表或视图时添加标签,请参阅创建表或创建视图。
在创建表或视图后向其添加标签的方法如下:
- 使用 Google Cloud 控制台
- 使用 bq 命令行工具的
bq update
命令 - 调用
tables.patch
API 方法 - 使用客户端库
由于视图被视为表资源,因此您可以使用 tables.patch
方法来修改视图和表。
所需 IAM 角色
如需获得为现有表或视图添加标签所需的权限,请让您的管理员为您授予 BigQuery Data Editor (roles/bigquery.dataEditor
) IAM 角色。如需详细了解如何授予角色,请参阅管理对项目、文件夹和组织的访问权限。
此预定义角色可提供为现有表或视图添加标签所需的权限。如需查看所需的确切权限,请展开所需权限部分:
所需权限
如需为现有表或视图添加标签,您需要拥有以下权限:
-
bigquery.tables.update
-
bigquery.tables.get
如需详细了解 BigQuery 中的 IAM 角色和权限,请参阅预定义的角色和权限。
为表或视图添加标签
如需为现有表或视图添加标签,请执行以下操作:
控制台
在 Google Cloud 控制台中选择表或视图。
点击详情标签页。
点击标签右侧的铅笔图标。
在修改标签对话框中执行以下操作:
- 点击添加标签。
- 输入键和值以添加标签。如需应用更多标签,请点击添加标签。每个键只能在每个数据集内使用一次,但您可以在同一项目的不同数据集内使用同一个键。
- 修改现有键或值以更新标签。
- 点击更新以保存更改。
SQL
使用 ALTER TABLE SET OPTIONS
DDL 语句在现有表上设置标签,或使用 ALTER VIEW SET OPTIONS
DDL 语句 在现有视图上设置标签。设置标签会覆盖表或视图上的所有现有标签。以下示例在表 mytable
上设置两个标签:
在 Google Cloud 控制台中,转到 BigQuery 页面。
在查询编辑器中,输入以下语句:
ALTER TABLE mydataset.mytable SET OPTIONS ( labels = [('department', 'shipping'), ('cost_center', 'logistics')]);
点击
运行。
如需详细了解如何运行查询,请参阅运行交互式查询。
bq
如需为现有表或视图添加标签,请发出带 set_label
标志的 bq update
命令。如需添加多个标签,请重复使用该标志。
如果表或视图属于非默认项目,请按以下格式将相应项目 ID 添加到数据集:project_id:dataset
。
bq update \ --set_label KEY:VALUE \ PROJECT_ID:DATASET.TABLE_OR_VIEW
替换以下内容:
KEY:VALUE
:您要添加的标签的键值对。键不得重复。键和值只能包含小写字母、数字字符、下划线和短划线。所有字符必须使用 UTF-8 编码,允许使用国际字符。PROJECT_ID
:您的项目 ID。DATASET
:包含您要为其添加标签的表或视图的数据集。TABLE_OR_VIEW
:您要为其添加标签的表或视图的名称。
示例:
如需添加表标签来跟踪部门,请输入 bq update
命令并将 department
指定为标签键。例如,如要为默认项目中的 mytable
添加 department:shipping
标签,请输入以下命令:
bq update --set_label department:shipping mydataset.mytable
如需添加视图标签来跟踪部门,请输入 bq update
命令并将 department
指定为标签键。例如,如要为默认项目中的 myview
添加 department:shipping
标签,请输入以下命令:
bq update --set_label department:shipping mydataset.myview
如需为表或视图添加多个标签,请重复使用 set_label
标志并为每个标签指定唯一键。例如,如要为默认项目中的 mytable
添加 department:shipping
标签和 cost_center:logistics
标签,请输入以下命令:
bq update \
--set_label department:shipping \
--set_label cost_center:logistics \
mydataset.mytable
API
如需为现有表或视图添加标签,请调用 tables.patch
方法,并填充表资源的 labels
属性。
由于视图被视为表资源,因此您可以使用 tables.patch
方法来修改视图和表。
由于 tables.update
方法会替换整个数据集资源,因此最好使用 tables.patch
方法。
Go
试用此示例之前,请按照 BigQuery 快速入门:使用客户端库中的 Go 设置说明进行操作。 如需了解详情,请参阅 BigQuery Go API 参考文档。
如需向 BigQuery 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为客户端库设置身份验证。
Java
此示例使用 Java 版 Google HTTP 客户端库向 BigQuery API 发送请求。
试用此示例之前,请按照 BigQuery 快速入门:使用客户端库中的 Java 设置说明进行操作。 如需了解详情,请参阅 BigQuery Java API 参考文档。
如需向 BigQuery 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为客户端库设置身份验证。
Node.js
试用此示例之前,请按照 BigQuery 快速入门:使用客户端库中的 Node.js 设置说明进行操作。 如需了解详情,请参阅 BigQuery Node.js API 参考文档。
如需向 BigQuery 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为客户端库设置身份验证。
Python
试用此示例之前,请按照 BigQuery 快速入门:使用客户端库中的 Python 设置说明进行操作。 如需了解详情,请参阅 BigQuery Python API 参考文档。
如需向 BigQuery 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为客户端库设置身份验证。
为作业添加标签
如需通过命令行向查询作业添加标签,您可以使用 bq 命令行工具的 --label
标志。bp 工具仅支持向查询作业添加标签。
您也可以在通过 API 提交作业时为该作业添加标签,具体做法是调用 jobs.insert
方法并在作业配置中指定 labels
属性。API 支持为任何类型的作业添加标签。
您不能为待处理、正在运行或已完成的作业添加标签或更新标签。
向作业添加标签后,标签会包含在您的结算数据中。
所需 IAM 角色
如需获得为作业添加标签所需的权限,请让您的管理员为您授予 BigQuery User (roles/bigquery.user
) IAM 角色。如需详细了解如何授予角色,请参阅管理对项目、文件夹和组织的访问权限。
此预定义角色可提供 bigquery.jobs.create
权限,该权限是为作业添加标签所必需的。
如需详细了解 BigQuery 中的 IAM 角色和权限,请参阅预定义的角色和权限。
为作业添加标签
如需向作业添加标签,请执行以下操作:
bq
如需为查询作业添加标签,请发出带 --label
标志的 bq query
命令。如需添加多个标签,请重复使用该标志。--nouse_legacy_sql
标志表示您的查询采用 GoogleSQL 语法。
bq query --label KEY:VALUE --nouse_legacy_sql 'QUERY'
请替换以下内容:
KEY:VALUE
:您要添加到查询作业的标签的键值对。键不得重复。键和值只能包含小写字母、数字字符、下划线和短划线。所有字符必须使用 UTF-8 编码,允许使用国际字符。如需为查询作业添加多个标签,请重复使用--label
标志并为每个标签指定唯一键。QUERY
:有效的 GoogleSQL 查询。
示例:
如需为查询作业添加标签,请输入以下命令:
bq query \
--label department:shipping \
--nouse_legacy_sql \
'SELECT
column1, column2
FROM
`mydataset.mytable`'
如需为查询作业添加多个标签,请重复使用 --label
标志并为每个标签指定唯一键。例如,如要为查询作业添加 department:shipping
标签和 cost_center:logistics
标签,请输入以下命令:
bq query \
--label department:shipping \
--label cost_center:logistics \
--nouse_legacy_sql \
'SELECT
column1, column2
FROM
`mydataset.mytable`'
API
如需为作业添加标签,请调用 jobs.insert
方法并填充作业配置的 labels
属性。您可以使用 API 为任何类型的作业添加标签。
将会话中的作业与标签相关联
如果在会话中运行查询,则可以使用 BigQuery 多语句查询为会话中的所有未来查询作业分配标签。
SQL
通过运行以下查询,在会话中设置 @@query_label
系统变量:
SET @@query_label = "KEY:VALUE";
- KEY:VALUE:要分配给会话中所有未来查询的标签的键值对。键不得重复。键和值只能包含小写字母、数字字符、下划线和短划线。所有字符必须使用 UTF-8 编码,允许使用国际字符。
示例:
SET @@query_label = "cost_center:logistics";
API
如需在使用 API 调用运行查询时为会话中的查询作业添加标签,请调用 jobs.insert
方法,并填充 connectionProperties
作业配置的 query_label
属性。
将查询标签与会话相关联并在会话内运行查询后,您就可以收集具有该查询标签的查询的审核日志。如需了解详情,请参阅 BigQuery 的审核日志参考文档。
添加不带值的标签
如果一个标签有键,但值为空,则此标签有时称为标记。请勿将其与标记资源混淆。如需了解详情,请参阅标签和标记。您可以创建一个没有值的新标签,也可以从现有标签键中移除值。
如果您要为资源添加标签,但不需要采用键值格式,则没有值的标签会很有用。比方说,如果一个表包含由多个群组(如支持或开发)使用的测试数据,您可以为该表添加 test_data
标签,以作识别之用。
如需添加没有值的标签,请执行以下操作:
控制台
在 Google Cloud 控制台中,选择相应的资源(数据集、表或视图)。
对于数据集,系统会自动打开“数据集详情”页面。对于表和视图,点击详细信息以打开详情页面。
在详情页面上,点击标签右侧的铅笔图标。
在修改标签对话框中执行以下操作:
- 点击添加标签。
- 输入新键并将值留空。如需应用更多标签,请点击添加标签并重复。
- 如需保存更改,请点击更新。
SQL
如需添加没有值的标签,请使用 ALTER TABLE SET OPTIONS
DDL 语句:
在 Google Cloud 控制台中,转到 BigQuery 页面。
在查询编辑器中,输入以下语句:
ALTER TABLE mydataset.mytable SET OPTIONS ( labels=[("key1", ""), ("key2", "")]);
点击
运行。
如需详细了解如何运行查询,请参阅运行交互式查询。
bq
如需为现有资源添加没有值的标签,请使用带 set_label
标志的 bq update
命令。请指定键并在后面加上英文冒号,但不指定值。
bq update --set_label KEY: RESOURCE_ID
请替换以下内容:
KEY:
:您要使用的标签键。RESOURCE_ID
:有效的数据集、表或视图名称。 如果资源不属于默认项目,请按以下格式添加相应项目 ID:PROJECT_ID:DATASET
。
示例:
如需为 mydataset.mytable
创建 test_data
标签,请输入以下命令。mydataset
属于默认项目。
bq update --set_label test_data: mydataset
API
调用 datasets.patch
方法或 tables.patch
方法,然后添加标签,并将数据集资源或表资源中的标签值设置为空字符串 (""
)。如需从现有标签中移除值,您可以将它们的值替换为空字符串。
由于视图被视为表资源,因此您可以使用 tables.patch
方法修改视图和表。另外,由于 tables.update
方法会替换整个数据集资源,因此最好使用 tables.patch
方法。
后续步骤
- 了解如何针对 BigQuery 资源查看标签。
- 了解如何针对 BigQuery 资源更新标签。
- 了解如何使用标签过滤资源。
- 了解如何针对 BigQuery 资源删除标签。
- 参阅 Resource Manager 文档中的使用标签。