标签是一种汇集相互关联的资源的简洁方法。例如,通常的做法是为用于生产、预演或开发的资源分别添加标签,以便您可以在必要时轻松搜索属于每个开发阶段的资源。您的标签可能会显示 vmrole:webserver
、environment:production
、location:west
等内容。您所添加的标签始终为键值对形式:
{
"labels": {
"vmrole": "webserver",
"environment": "production",
"location": "west",...
}
}
将标签应用于以下任何资源:
- 虚拟机实例
- 转发规则
- 图片
- 永久性磁盘
- 永久性磁盘快照
- Cloud Storage 存储分区
- 静态外部 IP 地址(测试版)
- VPN 隧道(测试版)
为资源添加标签后,您可以利用嵌套过滤等功能,对添加标签的资源进行更精确的搜索。
准备工作
- 如果您要使用本指南中的命令行示例,请执行以下操作:
- 安装或更新到 gcloud 命令行工具的最新版本。
- 设置默认区域和可用区。
- 如果您要使用本指南中的 API 示例,请设置 API 访问权限。
- 阅读永久性磁盘文档。
- 阅读映像文档。
限制
您最多可为每个资源分配 64 个标签。
标签格式
标签键和值必须符合以下正则表达式要求:
- 键和值的长度均不能超过 63 个字符。
- 键和值只能包含以下内容:
- 小写字母
- 数字字符
- 下划线
- 连字符
- 允许使用国际字符。
- 标签键必须以小写字母开头。
- 标签键不能为空。
创建具有标签的资源
在创建新资源时,您可以向该资源应用标签。
Console
在 Google Cloud Console 中,转到创建实例页面。
在标签下,点击添加标签。
继续执行创建过程。
gcloud
创建资源时,请包含 --labels
标志,后跟英文逗号分隔的标签键值对列表。例如:
gcloud compute instances create ... --labels webserver=backend,media=images
创建映像和磁盘时,相同的标志也适用。
API
在 API 中,在发出添加新资源的 POST
请求期间,在请求正文中添加 labels
属性以将标签应用于新资源。例如,用于创建虚拟机实例的请求正文具有以下标签:
body = {
"name": "[INSTANCE_NAME]",
"machineType": "zones/[ZONE]/machineTypes/[MACHINE_TYPE]",
...,
"labels": [{
"key": "webserver",
"value": "backend"
},
{
"key": "media",
"value": "images"
}]
}
创建映像和磁盘时,也可以应用相同属性。
向现有资源添加或更新标签
您可以在资源上添加标签或更新现有标签。
控制台
gcloud
通过 gcloud
命令行工具,使用带有 --add-labels
标志的 update
子命令来添加或更改标签。例如,如需向磁盘添加标签,请使用 gcloud compute disks update [DISK] --add-labels
子命令:
gcloud compute disks update example-disk --add-labels backend=webserver,media=images
如果您提供的标签键已存在,该工具将使用新的标签值来更新现有键。如果您提供新键,则该工具将向标签列表添加新键。
对于实例、快照和映像,请使用 gcloud compute instances
、gcloud compute snapshots
或 gcloud compute images
命令。
API
要添加或更新标签,请使用最新的指纹和要应用的完整标签列表对相应资源的 setLabels
方法发出 POST
请求。
与元数据和标记类似,如果资源当前具有您想要保留的标签,则除了您要添加的任何新标签,还必须在请求中包含这些标签。
例如,以下代码段向实例的 setLabels
方法发出请求。您也可以向磁盘、快照或映像 的 setLabels
方法发出请求:
Request
POST https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f/instances/example-instance/setLabels
{
"labels": {
"environment": "test",
"an-existing-tag": ""
},
"labelFingerprint": "42WmSpB8rSM="
}
同样,可在创建资源时通过指定 labels
对象向资源添加标签。
获取 API 请求的标签指纹
在 API 中更新或添加标签时,您需要提供请求的最新标签指纹,以防止与其他请求发生冲突。只有 API 请求需要该指纹,Cloud Console 和 gcloud
工具不需要指纹。
要获取最新的标签指纹以便您发出请求,请对各个资源执行 GET
请求。例如,以下代码段获取实例的 labelsFingerprint
。您可以对磁盘、快照或映像发出类似请求。
查找 labelFingerprint
属性:
Request
GET https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f/instances/example-instance
200 OK { "kind": "compute#instance", "id": "4392196237934605253", "creationTimestamp": "2015-09-15T14:05:16.475-07:00", "zone": "https://content.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f", "status": "RUNNING", ... "labels": { "environment": "test" }, "labelFingerprint": "p1ty_9HoBk0=" }
移除标签
控制台
gcloud
使用 gcloud
命令行工具,运行带有 --remove-labels
标志的 update
命令。提供一组要移除的标签键。例如:
gcloud compute disks update example-disk --remove-labels backend,media
对于快照和映像,请使用 gcloud compute snapshots
或 gcloud compute images
集合。
API
在 API 中,向实例、磁盘和快照等相应 API 资源的 setLabels
方法发出 POST
请求。
提供当前的 labelsFingerprint
和一个空的标签列表以移除所有标签,或提供您要保留的标签列表(去掉您要移除的标签)。例如:
Request
POST https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f/instances/example-instance/setLabels
{
"labels": { },
"labelFingerprint": "42WmSpB8rSM="
}
使用标签过滤搜索
您可以搜索资源并按标签过滤结果。
控制台
gcloud
在 gcloud
中,发出 list
请求并使用 --filter
标志。要按标签进行过滤,请使用语法 labels.key=[VALUE]
。例如,如果要按键为 env
、值为 dev
的标签进行过滤,您可以运行以下命令:
gcloud compute instances list --filter labels.env=dev
如需查看有关 gcloud
工具中的过滤器语法的完整文档,请参阅 gcloud topic filters
文档。
API
在 API 中,借助使用网址编码的 filter
查询参数发出列表请求。例如,要基于键为 env
、值为 dev
的标签进行过滤,请发出以下 GET
请求:
GET https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/list?filter=labels.env+eq+dev
如需了解详情,请参阅 Compute Engine API 参考文档中的 filter
文档。
实例标签和网络标记之间的关系
过去,标签和标记是相关的。例如,如果您已向虚拟机实例添加一个 webserver:test
标签,Compute Engine 就会自动向该实例添加一个 webserver
标记。
现在,标签和标记是分开的。如果您在实例上创建标签,Compute Engine 不会为该实例创建标记。如果需要在实例上创建标记,必须手动进行创建。
要了解如何创建标记,请参阅网络标记页面。