标签实例数

本页面介绍了标签。其中介绍了如何创建带有标签的实例、如何添加/更新/移除标签,以及如何在搜索中使用标签。

标签是将相互关联的实例组合在一起的一种简洁方式。例如,您可以根据实例是要用作测试实例还是生产实例来为其添加标签,也可以将您自己的结算代码添加到实例中。您可以使用标签搜索实例或跟踪实例费用。

您所添加的标签始终为键值对形式:

{
 "userLabels": {
    "track": "production",
    "location": "western-division"
    "billing-code": "34802",...
 }

修改标签对 Cloud SQL 实例性能没有影响。

如需了解详情,请参阅“什么是标签?”标签要求

限制

  • 您最多可为每个实例分配 64 个标签。
  • 标签的键和值必须遵循以下限制:

    • 键和值的长度均不能超过 63 个字符。
    • 键和值只能包含小写字母、数字字符、下划线和短划线。允许使用国际字符。
    • 标签键必须以小写字母开头。
    • 标签键不能为空。

创建带有标签的实例

使用 gcloud CLI 或 API 创建新实例时,您可以对该实例应用标签。

gcloud

创建实例时,添加“--labels”标志并后跟以英文逗号分隔的标签键值对列表。您必须使用 Beta 版 create 命令来添加标签。

例如:

gcloud beta sql instances create ... --labels track=production,billing-code=34802

Terraform

创建带有标签的实例时,请使用 Terraform 资源

resource "google_sql_database_instance" "postgres_instance_labels" {
  name             = "postgres-instance-labels"
  region           = "us-central1"
  database_version = "POSTGRES_14"
  settings {
    tier = "db-custom-2-7680"
    user_labels = {
      track        = "production"
      billing-code = 34802
    }
  }
  # set `deletion_protection` to true, will ensure that one cannot accidentally delete this instance by
  # use of Terraform whereas `deletion_protection_enabled` flag protects this instance at the GCP level.
  deletion_protection = false
}

应用更改

如需在 Google Cloud 项目中应用 Terraform 配置,请完成以下部分中的步骤。

准备 Cloud Shell

  1. 启动 Cloud Shell
  2. 设置要在其中应用 Terraform 配置的默认 Google Cloud 项目。

    您只需为每个项目运行一次以下命令,即可在任何目录中运行它。

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    如果您在 Terraform 配置文件中设置显式值,则环境变量会被替换。

准备目录

每个 Terraform 配置文件都必须有自己的目录(也称为“根模块”)。

  1. Cloud Shell 中,创建一个目录,并在该目录中创建一个新文件。文件名必须具有 .tf 扩展名,例如 main.tf。在本教程中,该文件称为 main.tf
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf
  2. 如果您按照教程进行操作,可以在每个部分或步骤中复制示例代码。

    将示例代码复制到新创建的 main.tf 中。

    (可选)从 GitHub 中复制代码。如果端到端解决方案包含 Terraform 代码段,则建议这样做。

  3. 查看和修改要应用到您的环境的示例参数。
  4. 保存更改。
  5. 初始化 Terraform。您只需为每个目录执行一次此操作。
    terraform init

    (可选)如需使用最新的 Google 提供程序版本,请添加 -upgrade 选项:

    terraform init -upgrade

应用更改

  1. 查看配置并验证 Terraform 将创建或更新的资源是否符合您的预期:
    terraform plan

    根据需要更正配置。

  2. 通过运行以下命令并在提示符处输入 yes 来应用 Terraform 配置:
    terraform apply

    等待 Terraform 显示“应用完成!”消息。

  3. 打开您的 Google Cloud 项目以查看结果。在 Google Cloud 控制台的界面中找到资源,以确保 Terraform 已创建或更新它们。

删除更改

如需删除更改,请执行以下操作:

  1. 如需停用删除防护,请在 Terraform 配置文件中将 deletion_protection 参数设置为 false
    deletion_protection =  "false"
  2. 运行以下命令并在提示符处输入 yes,以应用更新后的 Terraform 配置:
    terraform apply
  1. 通过运行以下命令并在提示符处输入 yes,移除之前使用 Terraform 配置应用的资源:

    terraform destroy

curl

在 API 中,在发出添加新实例的“POST”请求期间,将“userLabels”属性加入请求正文以向新实例应用标签。例如,用于创建实例的请求正文具有以下标签:

          "settings": {"tier":"db-custom-2-7680",
                       "userLabels": {"track": "production",
                                      "location": "western-division",
                                      "billing-code": "34802"},
          

为现有实例添加或更新标签

控制台

  1. 转到 Google Cloud 控制台中的“Cloud SQL 实例”页面。

    转到“Cloud SQL 实例”页面

  2. 选中要添加标签的资源旁边的复选框。

  3. 点击右上角的显示信息面板以展开标签列。

  4. 根据需要更新标签或添加新标签。

  5. 保存更改。

gcloud

使用 patch 子命令(Beta 版)为现有实例更新或添加标签:

gcloud beta sql instances patch [INSTANCE_NAME] --update-labels [KEY1]=[VALUE1]...

例如:

gcloud beta sql instances patch my-instance --update-labels track=production,billing-code=34802

如果您提供的标签键已经存在,则该工具将使用新标签值更新现有键。如果您提供新键,则该工具会将新键添加到标签列表中。只有指定的标签会受到影响;命令中未包含的现有标签将保持不变。

rest v1

要添加或更新标签,请使用 PATCH 方法:

在使用任何请求数据之前,请先进行以下替换:

  • project-id:项目 ID
  • instance-id:实例 ID
  • label-name-1:标签名称
  • value-1:label-name-1 的值
  • label-name-2:标签名称
  • value-2:label-name-2 的值

HTTP 方法和网址:

PATCH https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id

请求 JSON 正文:

{
  "settings" :
    {
        "userLabels" :
         {
            "label-name-1" : "value-1",
            "label-name-2" : "value-2"
         }
    }
}

如需发送您的请求,请展开以下选项之一:

您应该收到类似以下内容的 JSON 响应:

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

如果您提供的标签键已经存在,则该工具将使用新标签值更新现有键。如果您提供的是新键,则该工具会将新键添加到标签列表中。只有指定的标签会受到影响;请求中未包含的现有标签将保持不变。

rest v1beta4

要添加或更新标签,请使用 PATCH 方法:

在使用任何请求数据之前,请先进行以下替换:

  • project-id:项目 ID
  • instance-id:实例 ID
  • label-name-1:标签名称
  • value-1:label-name-1 的值
  • label-name-2:标签名称
  • value-2:label-name-2 的值

HTTP 方法和网址:

PATCH https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id

请求 JSON 正文:

{
  "settings" :
    {
        "userLabels" :
         {
            "label-name-1" : "value-1",
            "label-name-2" : "value-2"
         }
    }
}

如需发送您的请求,请展开以下选项之一:

您应该收到类似以下内容的 JSON 响应:

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

如果您提供的标签键已经存在,则该工具将使用新标签值更新现有键。如果您提供的是新键,则该工具会将新键添加到标签列表中。只有指定的标签会受到影响;请求中未包含的现有标签将保持不变。

移除标签

控制台

  1. 转到 Google Cloud 控制台中的“Cloud SQL 实例”页面。

    转到“Cloud SQL 实例”页面

  2. 选中要移除标签的资源旁边的复选框。

  3. 点击显示信息面板以展开标签列。

  4. 点击要移除的所有标签旁边的 X

  5. 保存更改。

gcloud

使用 gcloud CLI 运行带有 --remove-labels 标志的 patch 子命令(Beta 版):

gcloud beta sql instances patch [INSTANCE_NAME] --remove-labels [LABEL1],[LABEL2]

如果您提供的标签名称不存在,此工具不会返回错误。

rest v1

要使用 API 移除标签,请将标签的值设置为 null

在使用任何请求数据之前,请先进行以下替换:

  • project-id:项目 ID
  • instance-id:实例 ID
  • label-name:标签名称

HTTP 方法和网址:

PATCH https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id

请求 JSON 正文:

{
  "settings" :
    {
        "userLabels" :
         {
            "label-name" : null,
         }
    }
}

如需发送您的请求,请展开以下选项之一:

您应该收到类似以下内容的 JSON 响应:

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

rest v1beta4

要使用 API 移除标签,请将标签的值设置为 null

在使用任何请求数据之前,请先进行以下替换:

  • project-id:项目 ID
  • instance-id:实例 ID
  • label-name:标签名称

HTTP 方法和网址:

PATCH https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id

请求 JSON 正文:

{
  "settings" :
    {
        "userLabels" :
         {
            "label-name" : null,
         }
    }
}

如需发送您的请求,请展开以下选项之一:

您应该收到类似以下内容的 JSON 响应:

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

使用标签过滤实例搜索结果

您可以使用 gcloud CLI 或 API 按标签过滤实例列表结果。

gcloud

gcloud 中,发出 list 请求并使用 --filter 标志。如需按标签进行过滤,请使用 labels.[KEY]:[VALUE] 语法。例如,如果要按值为 34802billing-code 标签进行过滤,可以运行以下命令:

gcloud beta sql instances list --filter='labels.billing-code:34802'

如果要按某一标签的存在情况过滤,而不考虑其值为何,可运行以下命令:

gcloud beta sql instances list --filter='labels:billing-code'

如需查看有关 gcloud CLI 中过滤条件语法的完整文档,请参阅 gcloud topic filters 文档

curl

在 API 中,借助使用网址编码的 filter 查询参数发出 list 请求。

gcloud auth login
ACCESS_TOKEN="$(gcloud auth print-access-token)"
curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     -X GET \
     https://www.googleapis.com/sql/v1beta4/projects/[PROJECT_ID]/instances/list?filter=userLabels.[KEY1_NAME]:[KEY1_VALUE]%20userLabels.[KEY2_NAME]:[KEY2_VALUE]

例如:

curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     -X GET \
     https://www.googleapis.com/sql/v1beta4/projects/[PROJECT_ID]/instances/list?filter=userLabels.track:production%20userLabels.billing-code:34802

如果包含的两个标签值之间存在(编码)空格,那么这两个标签值必须均为 true 才能返回实例(AND 运算)。 您也可以明确提供 ANDORNOT 运算符。例如:

curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     -X GET \
     https://www.googleapis.com/sql/v1beta4/projects/[PROJECT_ID]/instances/list?filter=userLabels.track:production%20OR%20userLabels.billing-code:34802

后续步骤