为资源添加标签
本页面介绍了如何为 BigQuery 资���添加标签。
准备工作
授予为用户提供执行本文档中的每个任务所需权限的 Identity and Access Management (IAM) 角色。执行任务所需的任何权限都列在任务的“所需 IAM 角色”部分中。
为数据集添加标签
在创建 BigQuery 数据集时,您可以使用 bq 命令行工具的 bq mk 命令或调用 datasets.insert API 方法来为该数据集添加标签。您不能向使用 Google Cloud 控制台创建的数据集添加标签。
本页面介绍如何在创建数据集后向其添加标签。如需详细了解如何在创建数据集时添加标签,请参阅创建数据集。
向数据集添加标签时,标签不会传播到该数据集中的资源。表或视图不会继承数据集标签。向数据集添加标签后,标签会包含在存储空间结算数据中,但不会包含在与作业相关的结算数据中。
如需详细了解标签的格式,请参阅标签要求。
所需 IAM 角色
如需获得为现有数据集添加标签所需的权限,请让您的管理员为您授予 BigQuery Data Owner (roles/bigquery.dataOwner) 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 进行身份验证,请设置应用默认凭证。如需了解详情,请参阅为客户端库设置身份验证。
为表和视图添加标签
本页面介绍如何向现有表或视图添加标签。如需详细了解如何在创建表或视图时添加标签,请参阅创建表或创建视图。
由于视图被视为表资源,因此您可以使用 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 命令。如需添加多个标签,请重复使用该标志。该标志表示您的查询采用 GoogleSQL 语法。
bq query --label KEY:VALUE 'QUERY'
请替换以下内容:
KEY:VALUE:您要添加到查询作业的标签的键值对。键不得重复。键和值只能包含小写字母、数字字符、下划线和短划线。所有字符必须使用 UTF-8 编码,允许使用国际字符。如需为查询作业添加多个标签,请重复使用--label标志并为每个标签指定唯一键。QUERY:有效的 GoogleSQL 查询。
示例:
如需为查询作业添加标签,请输入以下命令:
bq query \
--label department:shipping \
\
'SELECT
column1, column2
FROM
`mydataset.mytable`'
如需为查询作业添加多个标签,请重复使用 --label 标志并为每个标签指定唯一键。例如,如要为查询作业添加 department:shipping 标签和 cost_center:logistics 标签,请输入以下命令:
bq query \
--label department:shipping \
--label cost_center:logistics \
\
'SELECT
column1, column2
FROM
`mydataset.mytable`'
API
如需为作业添加标签,请调用 jobs.insert 方法并填充作业配置的 labels 属性。您可以使用 API 为任何类型的作业添加标签。
Python
试用此示例之前,请按照 BigQuery 快速入门:使用客户端库中的 Python 设置说明进行操作。 如需了解详情,请参阅 BigQuery Python API 参考文档。
如需向 BigQuery 进行身份验证,请设置应用默认凭证。如需了解详情,请参阅为客户端库设置身份验证。
将会话中的作业与标签相关联
如果在会话中运行查询,则可以使用 BigQuery 多语句查询为会话中的所有未来查询作业分配标签。
SQL
通过运行以下查询,在会话中设置 @@query_label 系统变量:
SET @@query_label = "KEY:VALUE";
- KEY:VALUE:要分配给会话中所有未来查询的标签的键值对。 您还可以添加多个键值对,并用英文逗号分隔(例如
SET @@query_label = "key1:value1,key2:value2")。键必须是唯一的。键和值只能包含小写字母、数字字符、下划线和短划线。所有字符必须使用 UTF-8 编码,允许使用国际字符。
示例:
SET @@query_label = "cost_center:logistics";
API
如需在使用 API 调用运行查询时为会话中的查询作业添加标签,请调用 jobs.insert 方法,并填充 connectionProperties 作业配置的 query_label 属性。
将查询标签与会话相关联并在会话内运行查询后,您就可以收集具有该查询标签的查询的审核日志。如需了解详情,请参阅 BigQuery 的审核日志参考文档。
为预留添加标签
为预留添加标签后,标签会包含在您的结算数据中。您可以使用这些标签来过滤 Cloud Billing 数据中的分析槽归因 SKU。
分析槽归因 SKU 仅��录槽使用情况。它不会记录 BigQuery Reservation API SKU 的费用。不支持将预留标签作为 BigQuery Reservation API SKU 的过滤条件。
如需详细了解如何在结算数据中使用标签,请参阅使用过滤条件优化数据。
所需 IAM 角色
如需获得为预留添加标签所需的权限,请让您的管理员为您授予管理项目的 BigQuery Resource Editor (roles/bigquery.resourceEditor) IAM 角色。如需详细了解如何授予角色,请参阅管理对项目、文件夹和组织的访问权限。
此预定义角色包含为预留添加标签所需的 bigquery.reservations.update 权限。
为预留添加标签
如需为预留添加标签,请执行以下操作:
控制台
在 Google Cloud 控制台中,前往 BigQuery 页面。
在导航菜单中,点击容量管理。
点击槽预留标签页。
找到要更新的预留。
展开 操作选项。
点击修改。
如需展开高级设置部分,请点击 展开箭头。
点击添加标签。
输入键值对。如需应用更多标签,请点击添加标签。
点击保存。
SQL
如需为预留添加标签,请使用 ALTER RESERVATION SET OPTIONS DDL 语句。设置标签会覆盖预留中的任何现有标签。以下示例对预留 myreservation 设置一个标签:
在 Google Cloud 控制台中,前往 BigQuery 页面。
在查询编辑器中,输入以下语句:
ALTER RESERVATION myreservation SET OPTIONS ( labels = [('sensitivity', 'high')]);
点击 运行。
如需详细了解如何运行查询,请参阅运行交互式查询。
bq
如需为预留添加标签,请发出带有 set_label 标志和 --reservation 标志的 bq update 命令。如需添加多个标签,请重复使用 set_label 标志。
bq update --set_label KEY:VALUE --location LOCATION --reservation RESERVATION_NAME
替换以下内容:
KEY:VALUE:您要为预留添加的标签的键值对。键不得重复。键和值只能包含小写字母、数字字符、下划线和短划线。所有字符必须使用 UTF-8 编码,允许使用国际字符。如需为预留添加多个标签,请重复使用--set_label标志并为每个标签指定唯一键。LOCATION:预留的位置。location标志不能位于命令的末尾,否则会返回FATAL Flags positioning错误。RESERVATION_NAME:预留的名称。
添加不带值的标签
如果一个标签有键,但值为空,则此标签有时称为标记。请勿将其与标记资源混淆。如需了解详情,请参阅标签和标记。您可以创建一个没有值的新标签,也可以从现有标签键中移除值。
如果您要为资源添加标签,但不需要采用键值格式,则没有值的标签会很有用。比方说,如果一个表包含由多个群组(如支持或开发)使用的测试数据,您可以为该表添加 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 方法。