ラベルのインスタンス

MySQL   |  PostgreSQL   |  SQL Server

このページでは、ラベルについて説明します。ここで説明するのは、ラベルを使用してインスタンスを作成する方法、ラベルを追加、更新、削除する方法、検索でラベルを使用する方法です。

ラベルは互いに関連するインスタンスを簡単にグループ化するための方法です。たとえば、テストまたは本番環境のいずれで使用するかに応じてインスタンスにラベルを付けたり、インスタンスに独自の請求コードを追加したりできます。ラベルを使用して、インスタンスを検索したり、インスタンスの料金を追跡することもできます。

ラベルは Key-Value ペアで追加します。

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

ラベルを変更しても、Cloud SQL インスタンスのパフォーマンスに影響はありません。

詳細については、ラベルとはとラベルの要件をご覧ください。

制限事項

• 各インスタンスには最大 64 個のラベルを割り当てることができます。

• ラベルのキーと値には次の制限があります。

  • キーと値は、それぞれ 63 文字以下にする必要があります。
  • キーと値に使用できるのは、小文字、数字、アンダースコア、ダッシュだけです。国際文字も使用できます。
  • ラベルキーは小文字で始める必要があります。
  • ラベルキーは空にできません。

ラベル付きインスタンスを作成する

gcloud CLI または API を使用して新しいインスタンスを作成すると、インスタンスにラベルを適用できます。

gcloud

インスタンスを作成するときに、--labels フラグを指定し、それに続けてラベルの Key-Value ペアをカンマ区切りのリストとして指定します。ラベルを含めるには、create コマンドのベータ版を使用する必要があります。

例:

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
    }
  }
  # 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 プロジェクトを設定します。

   このコマンドは、プロジェクトごとに 1 回だけ実行する必要があります。これは任意のディレクトリで実行できます。

   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 を初期化します。これは、ディレクトリごとに 1 回だけ行います。

   terraform init

   最新バージョンの Google プロバイダを使用する場合は、-upgrade オプションを使用します。

   terraform init -upgrade

変更を適用する

1. 構成を確認して、Terraform が作成または更新するリソースが想定どおりであることを確認します。

   terraform plan

   必要に応じて構成を修正します。

2. 次のコマンドを実行します。プロンプトで「yes」と入力して、Terraform 構成を適用します。

   terraform apply

   Terraform に「Apply complete!」というメッセージが表示されるまで待ちます。

3. Google Cloud プロジェクトを開いて結果を表示します。Google Cloud コンソールの UI でリソースに移動して、Terraform によって作成または更新されたことを確認します。

注: Terraform のサンプルでは通常、必要な API が Google Cloud プロジェクトで有効になっていることを前提としています。

変更を削除する

変更を削除するには、次の手順を行います。

1. 削除の保護を無効にするには、Terraform 構成ファイルで deletion_protection 引数を false に設定します。

   deletion_protection =  "false"

2. 次のコマンドを実行します。プロンプトで「yes」と入力して、更新された Terraform 構成を適用します。

   terraform apply

3. 次のコマンドを実行しています。プロンプトで「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 サブコマンド（ベータ版）を使用して、既存のインスタンスでラベルを更新または追加します。

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: ラベル名-1 の値
• label-name-2: ラベル名
• value-2: ラベル名-2 の値

HTTP メソッドと URL:

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": "[e-mail]",
  "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: ラベル名-1 の値
• label-name-2: ラベル名
• value-2: ラベル名-2 の値

HTTP メソッドと URL:

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）

注: 次のコマンドは、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/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": "[e-mail]",
  "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 サブコマンド（ベータ版）を実行します。

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

存在しないラベル名を指定しても、エラーは返されません。

rest v1

API を使用してラベルを削除するには、ラベルの値を null に設定します。

リクエストのデータを使用する前に、次のように置き換えます。

• project-id: プロジェクト ID
• instance-id: インスタンス ID
• label-name: ラベル名

HTTP メソッドと URL:

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

リクエストの本文（JSON）:

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

リクエストを送信するには、次のいずれかのオプションを開きます。

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": "[e-mail]",
  "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 メソッドと URL:

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

リクエストの本文（JSON）:

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

リクエストを送信するには、次のいずれかのオプションを開きます。

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/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": "[e-mail]",
  "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 で list リクエストを作成し、URL エンコードされた 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

（エンコードされた）スペースで連結された 2 つのラベル値がフィルタに含まれている場合、両方のラベルがともに 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 ツールを使用したフィルタリングについて学習します。