Istanze di etichette

MySQL   |  PostgreSQL   |  SQL Server

Questa pagina spiega le etichette. Descrive come creare un'istanza con le etichette, come aggiungere, aggiornare e rimuovere le etichette e come utilizzarle nelle ricerche.

Le etichette sono un modo semplice per raggruppare istanze correlate o associate tra loro. Ad esempio, puoi etichettare le istanze in base al fatto che le utilizzi per i test o in produzione oppure puoi aggiungere il tuo codice di fatturazione a un'istanza. Puoi utilizzare le etichette per cercare le istanze o per monitorare gli addebiti delle istanze.

Le etichette vengono sempre aggiunte come coppie chiave/valore:

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

La modifica delle etichette non influisce sulle prestazioni dell'istanza Cloud SQL.

Per saperne di più, consulta Che cosa sono le etichette? e Requisiti per le etichette.

Limitazioni

• Puoi assegnare fino a 64 etichette a ogni istanza.

• Le chiavi e i valori delle etichette devono rispettare le seguenti limitazioni:

  • Le chiavi e i valori non possono essere più lunghi di 63 caratteri ciascuno.
  • Le chiavi e i valori possono contenere solo lettere minuscole, caratteri numerici, trattini bassi e trattini. Sono consentiti caratteri internazionali.
  • Le chiavi delle etichette devono iniziare con una lettera minuscola.
  • Le chiavi delle etichette non possono essere vuote.

Creare istanze con etichette

Quando crei una nuova istanza utilizzando gcloud CLI o l'API, puoi applicare le etichette all'istanza.

gcloud

Quando crei l'istanza, includi il flag `--labels`, seguito da un elenco separato da virgole di coppie chiave-valore di etichette. Per includere le etichette, devi utilizzare la versione beta del comando create.

Ad esempio:

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

Terraform

Quando crei un'istanza con un'etichetta, utilizza una risorsa 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
}

Applica le modifiche

Per applicare la configurazione Terraform in un progetto Google Cloud, completa i passaggi nelle seguenti sezioni.

Prepara Cloud Shell

1. Avvia Cloud Shell.

2. Imposta il progetto Google Cloud predefinito in cui vuoi applicare le configurazioni Terraform.

   Devi eseguire questo comando una sola volta per progetto e puoi farlo in qualsiasi directory.

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   Le variabili di ambiente vengono sostituite se imposti valori espliciti nel file di configurazione Terraform.

Prepara la directory

Ogni file di configurazione di Terraform deve avere una propria directory (chiamata anche modulo principale).

1. In Cloud Shell, crea una directory e un nuovo file al suo interno. Il nome file deve avere l'estensione .tf, ad esempio main.tf. In questo tutorial, il file è denominato main.tf.

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. Se stai seguendo un tutorial, puoi copiare il codice campione in ogni sezione o passaggio.

   Copia il codice campione nel file main.tf appena creato.

   Se vuoi, copia il codice da GitHub. Questa opzione è consigliata quando lo snippet Terraform fa parte di una soluzione end-to-end.

3. Esamina e modifica i parametri di esempio da applicare al tuo ambiente.
4. Salva le modifiche.
5. Inizializza Terraform. Devi eseguire questa operazione una sola volta per directory.

   terraform init

   Se vuoi, per utilizzare la versione più recente del provider Google, includi l'opzione -upgrade:

   terraform init -upgrade

Applica le modifiche

1. Rivedi la configurazione e verifica che le risorse che Terraform sta per creare o aggiornare corrispondano alle tue aspettative:

   terraform plan

   Apporta le correzioni necessarie alla configurazione.

2. Applica la configurazione di Terraform eseguendo il seguente comando e inserendo yes al prompt:

   terraform apply

   Attendi che Terraform mostri il messaggio "Applicazione completata".

3. Apri il tuo progetto Google Cloud per visualizzare i risultati. Nella console Google Cloud, vai alle risorse nell'interfaccia utente per assicurarti che Terraform le abbia create o aggiornate.

Nota: in genere i sample di Terraform presuppongono che le API richieste siano attivate nel progetto Google Cloud.

Elimina le modifiche

Per eliminare le modifiche, procedi nel seguente modo:

1. Per disattivare la protezione dall'eliminazione, imposta l'argomento deletion_protection su false nel file di configurazione Terraform.

   deletion_protection =  "false"

2. Applica la configurazione Terraform aggiornata eseguendo il seguente comando e inserendo yes al prompt:

   terraform apply

3. Rimuovi le risorse applicate in precedenza con la configurazione Terraform eseguendo il seguente comando e inserendo yes al prompt:

   terraform destroy

curl

Nell'API, durante la richiesta "POST" per aggiungere una nuova istanza, aggiungi la proprietà "userLabels" nel corpo della richiesta per applicare le etichette alla nuova istanza. Ad esempio, il corpo della richiesta per la creazione di un'istanza contiene le seguenti etichette:

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

Aggiungere o aggiornare le etichette di un'istanza esistente

console

1. Vai alla pagina Istanze Cloud SQL nella console Google Cloud.

   Vai alla pagina Istanze Cloud SQL

2. Seleziona le caselle di controllo accanto alle risorse da etichettare.

3. Fai clic su Mostra riquadro Informazioni nell'angolo in alto a destra per espandere la colonna delle etichette.

4. Aggiorna o aggiungi nuove etichette come preferisci.

5. Salva le modifiche.

gcloud

Utilizza il sottocomando patch (versione beta) per aggiornare o aggiungere etichette a un'istanza esistente:

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

Ad esempio:

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

Se fornisci una chiave di etichetta esistente, lo strumento aggiorna la chiave esistente con il nuovo valore dell'etichetta. Se fornisci una nuova chiave, lo strumento la aggiunge all'elenco delle etichette. Sono interessate solo le etichette specificate; le etichette esistenti non incluse nel comando rimangono invariate.

rest v1

Per aggiungere o aggiornare le etichette, utilizza il metodo PATCH:

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

• project-id: l'ID progetto
• instance-id: l'ID istanza
• label-name-1: un nome di etichetta
• value-1: il valore di nome-etichetta-1
• label-name-2: un nome di etichetta
• value-2: il valore di nome-etichetta-2

Metodo HTTP e URL:

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

Corpo JSON della richiesta:

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

Per inviare la richiesta, espandi una di queste opzioni:

curl (Linux, macOS o Cloud Shell)

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che ti consente di accedere automaticamente all'interfaccia a riga di comando gcloud. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

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)

Nota: il comando seguente presuppone che tu abbia eseguito l'accesso alla CLI gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login . Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

$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

Dovresti ricevere una risposta JSON simile alla seguente:

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

Se fornisci una chiave di etichetta esistente, lo strumento aggiorna la chiave esistente con il nuovo valore dell'etichetta. Se fornisci una nuova chiave, lo strumento la aggiunge all'elenco delle etichette. Sono interessate solo le etichette specificate; le etichette esistenti non incluse nella richiesta rimangono invariate.

rest v1beta4

Per aggiungere o aggiornare le etichette, utilizza il metodo PATCH:

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

• project-id: l'ID progetto
• instance-id: l'ID istanza
• label-name-1: un nome di etichetta
• value-1: il valore di nome-etichetta-1
• label-name-2: un nome di etichetta
• value-2: il valore di nome-etichetta-2

Metodo HTTP e URL:

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

Corpo JSON della richiesta:

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

Per inviare la richiesta, espandi una di queste opzioni:

curl (Linux, macOS o Cloud Shell)

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che ti consente di accedere automaticamente all'interfaccia a riga di comando gcloud. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

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)

Nota: il comando seguente presuppone che tu abbia eseguito l'accesso alla CLI gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login . Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

$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

Dovresti ricevere una risposta JSON simile alla seguente:

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

Se fornisci una chiave di etichetta esistente, lo strumento aggiorna la chiave esistente con il nuovo valore dell'etichetta. Se fornisci una nuova chiave, lo strumento la aggiunge all'elenco delle etichette. Sono interessate solo le etichette specificate; le etichette esistenti non incluse nella richiesta rimangono invariate.

Rimuovere un'etichetta

console

1. Vai alla pagina Istanze Cloud SQL nella console Google Cloud.

   Vai alla pagina Istanze Cloud SQL

2. Seleziona le caselle di controllo accanto alle risorse per le quali vuoi rimuovere le etichette.

3. Fai clic su Mostra riquadro informazioni per espandere la colonna delle etichette.

4. Fai clic su X accanto a tutte le etichette che vuoi rimuovere.

5. Salva le modifiche.

gcloud

Utilizzando l'interfaccia a riga di comando gcloud, esegui il sottocomando patch (versione beta) con il flag --remove-labels:

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

Se fornisci il nome di un'etichetta che non esiste, non viene restituito alcun errore.

rest v1

Per rimuovere un'etichetta utilizzando l'API, imposta il relativo valore su null:

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

• project-id: l'ID progetto
• instance-id: l'ID istanza
• label-name: il nome dell'etichetta

Metodo HTTP e URL:

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

Corpo JSON della richiesta:

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

Per inviare la richiesta, espandi una di queste opzioni:

curl (Linux, macOS o Cloud Shell)

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che ti consente di accedere automaticamente all'interfaccia a riga di comando gcloud. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

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)

Nota: il comando seguente presuppone che tu abbia eseguito l'accesso alla CLI gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login . Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

$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

Dovresti ricevere una risposta JSON simile alla seguente:

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

Per rimuovere un'etichetta utilizzando l'API, imposta il relativo valore su null:

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

• project-id: l'ID progetto
• instance-id: l'ID istanza
• label-name: il nome dell'etichetta

Metodo HTTP e URL:

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

Corpo JSON della richiesta:

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

Per inviare la richiesta, espandi una di queste opzioni:

curl (Linux, macOS o Cloud Shell)

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che ti consente di accedere automaticamente all'interfaccia a riga di comando gcloud. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

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)

Nota: il comando seguente presuppone che tu abbia eseguito l'accesso alla CLI gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login . Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

$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

Dovresti ricevere una risposta JSON simile alla seguente:

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

Filtrare le ricerche delle istanze utilizzando le etichette

Puoi filtrare i risultati dell'elenco di istanze per etichetta utilizzando gcloud CLI o l'API.

gcloud

In gcloud, effettua una richiesta list e utilizza il flag --filter. Per filtrare in base alle etichette, utilizza la sintassi labels.[KEY]:[VALUE]. Ad esempio, se volevi applicare un filtro a un'etichetta billing-code con un valore 34802, potevi eseguire questo comando:

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

Se vuoi filtrare in base all'esistenza di un'etichetta, indipendentemente dal relativo valore:

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

Per la documentazione completa sulla sintassi dei filtri nella gcloud CLI, consulta la documentazione di gcloud topic filters.

curl

Nell'API, effettua una richiesta di elenco con un parametro di query filter codificato per l'URL:

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]

Ad esempio:

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

Quando due valori dell'etichetta sono inclusi con uno spazio (codificato) tra di loro, entrambi devono essere veri affinché venga restituita un'istanza (un'operazione AND). Puoi anche fornire esplicitamente gli operatori AND, OR e NOT. Ad esempio:

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

Passaggi successivi

• Scopri di più sull'esportazione dei dati di fatturazione in BigQuery.
• Scopri di più sull'applicazione di filtri utilizzando lo strumento gcloud.