Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

為項目加上標籤

MySQL | PostgreSQL | SQL Server

本頁面說明標籤。本文說明如何建立含有標籤的執行個體、如何新增、更新及移除標籤，以及如何在搜尋中使用標籤。

標籤是將彼此相關或關聯的執行個體分組在一起的一種簡便方式。例如，您可以根據使用執行個體作為測試還是實際工作環境來為執行個體加上標籤，也可以將自己的帳單代碼新增至執行個體。您可以使用標籤來搜尋執行個體，或追蹤執行個體費用。

請將標籤一律新增為鍵/值組合：

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

修改標籤不會影響 Cloud SQL 執行個體效能。

詳情請參閱「什麼是標籤？」和「標籤規定」。

限制

每個執行個體最多可指派 50 個使用者定義的標籤。雖然Google Cloud 資源最多支援 64 個標籤，但 Cloud SQL 會保留最多 14 個標籤，用於基礎備份快照的內部系統和帳單中繼資料。
如果現有執行個體已有超過 50 個使用者定義的標籤，您就無法新增標籤，且如果使用者和系統標籤加總超過 64 個，自動或隨選備份可能會失敗。為避免備份失敗，請將每個執行個體的使用者定義標籤減少至 50 個以下。
標籤的鍵值必須符合下列限制：
- 每個鍵和值的長度不得超過 63 個字元。
- 鍵和值只能包含小寫英文字母、數字字元、底線和破折號。允許使用國際字元。
- 標籤鍵的開頭必須是小寫英文字母。
- 標籤鍵不得留空。

使用標籤建立執行個體

使用 gcloud CLI 或 API 建立新的執行個體時，您可以為執行個體套用標籤。

gcloud

建立執行個體時，請加入 `--labels` 旗標，並加上以半形逗號分隔的標籤鍵/值組合清單。您必須使用建立指令的 Beta 版，才能加入標籤。

例如：

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

Terraform

使用標籤建立執行個體時，請使用 Terraform 資源：

resource "google_sql_database_instance" "default" {
  name             = "sqlserver-instance-labels"
  region           = "us-central1"
  database_version = "SQLSERVER_2019_STANDARD"
  root_password    = "INSERT-PASSWORD-HERE"
  settings {
    tier = "db-custom-2-7680"
    user_labels = {
      track        = "production"
      billing-code = 34802
    }
  }
}

套用變更

如要在 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 顯示「Apply complete!」訊息。
開啟 Google Cloud 專案即可查看結果。在 Google Cloud 控制台中，前往 UI 中的資源，確認 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 執行個體頁面
選取您想加上標籤的資源旁邊的核取方塊。
按一下右上角的 [Show Info Panel] (顯示資訊面板)，展開標籤欄。
視需求更新或新增標籤。
儲存變更。

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 執行個體頁面
找出您要移除標籤的資源，然後勾選旁邊的核取方塊。
按一下 [Show info panel] (顯示資訊面板) 來展開標籤欄。
找出您要移除的所有標籤，然後按一下旁邊的 [X]。
儲存變更。

gcloud

使用 gcloud CLI 執行 patch 子指令 (Beta 版)，並搭配 --remove-labels 旗標：

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

如果您提供的標籤名稱不存在，系統不會傳回錯誤。

REST 第 1 版

如要使用 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 查詢參數提出清單要求：

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 工具篩選。

為項目加上標籤 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

限制

使用標籤建立執行個體

gcloud

Terraform

套用變更

準備 Cloud Shell

準備目錄

套用變更

刪除變更

curl

在現有執行個體上新增或更新標籤

主控台

gcloud

rest v1

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

REST v1beta4

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

移除標籤

主控台

gcloud

REST 第 1 版

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

REST v1beta4

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

使用標籤篩選執行個體搜尋結果

gcloud

curl

後續步驟

為項目加上標籤