标签实例数

MySQL | PostgreSQL | SQL Server

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

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

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

{
 "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

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

您只需为每个项目运行一次以下命令，即可在任何目录中运行它。
```
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
```
如果您在 Terraform 配置文件中设置显式值，则环境变量会被替换。

准备目录

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

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

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

（可选）从 GitHub 中复制代码。如果端到端解决方案包含 Terraform 代码段，则建议这样做。
查看和修改要应用到您的环境的示例参数。
保存更改。
初始化 Terraform。您只需为每个目录执行一次此操作。
```
terraform init
```
（可选）如需使用最新的 Google 提供程序版本，请添加 -upgrade 选项：
```
terraform init -upgrade
```

应用更改

查看配置并验证 Terraform 将创建或更新的资源是否符合您的预期：
```
terraform plan
```
根据需要更正配置。
通过运行以下命令并在提示符处输入 yes 来应用 Terraform 配置：
```
terraform apply
```
等待 Terraform 显示“应用完成！”消息。
打开您的 Google Cloud 项目以查看结果。在 Google Cloud 控制台的界面中找到资源，以确保 Terraform 已创建或更新它们。

删除更改

如需删除更改，请执行以下操作：

如需停用删除防护，请在 Terraform 配置文件中将 deletion_protection 参数设置为 false。
```
deletion_protection =  "false"
```
运行以下命令并在提示符处输入 yes，以应用更新后的 Terraform 配置：
```
terraform apply
```

通过运行以下命令并在提示符处输入 yes，移除之前使用 Terraform 配置应用的资源：
```
terraform destroy
```

curl

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

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

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

控制台

转到 Google Cloud 控制台中的“Cloud SQL 实例”页面。
转到“Cloud SQL 实例”页面
选中要添加标签的资源旁边的复选框。
点击右上角的显示信息面板以展开标签列。
根据需要更新标签或添加新标签。
保存更改。

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"
         }
    }
}

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

curl（Linux、macOS 或 Cloud Shell）

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id"

PowerShell (Windows)

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id" | Select-Object -Expand Content

您应该收到类似以下内容的 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"
         }
    }
}

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

curl（Linux、macOS 或 Cloud Shell）

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id"

PowerShell (Windows)

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id" | Select-Object -Expand Content

您应该收到类似以下内容的 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"
}

移除标签

控制台

转到 Google Cloud 控制台中的“Cloud SQL 实例”页面。
转到“Cloud SQL 实例”页面
选中要移除标签的资源旁边的复选框。
点击显示信息面板以展开标签列。
点击要移除的所有标签旁边的 X。
保存更改。

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,
         }
    }
}

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

curl（Linux、macOS 或 Cloud Shell）

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id"

PowerShell (Windows)

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id" | Select-Object -Expand Content

您应该收到类似以下内容的 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,
         }
    }
}

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

curl（Linux、macOS 或 Cloud Shell）

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id"

PowerShell (Windows)

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id" | Select-Object -Expand Content

您应该收到类似以下内容的 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] 语法。例如，如果要按值为 34802 的 billing-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 运算）。您也可以明确提供 AND、OR、NOT 运算符。例如：

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

后续步骤

了解如何将结算数据导出到 BigQuery。
了解如何使用 gcloud 工具进行过滤。