Aggiorna i bucket di osservabilità

Puoi aggiornare il nome visualizzato, la descrizione o la chiave Cloud Key Management Service di un bucket di osservabilità per riflettere le modifiche organizzative o ruotare le chiavi di crittografia.

Non puoi utilizzare queste operazioni di aggiornamento per risolvere i problemi di conformità. Ad esempio, non puoi utilizzare queste operazioni per modificare la località di un bucket di osservabilità o applicare una chiave Cloud KMS a un bucket che utilizza la crittografia predefinita di Google.

Effetti dell'aggiornamento di una chiave Cloud KMS

L'aggiornamento della chiave Cloud KMS per un bucket di osservabilità non influisce sui dati archiviati. Ciò significa che, prima del completamento dell'aggiornamento, la chiave originale cripta i nuovi dati. Al termine dell'aggiornamento, la chiave aggiornata cripta i nuovi dati.

Puoi continuare ad accedere ai dati archiviati e a visualizzarli a condizione che la chiave Cloud KMS originale rimanga abilitata e che il account di servizio di Google Cloud Observability mantenga le autorizzazioni di criptatore/decriptatore.

Se disabiliti o elimini la chiave Cloud KMS originale, tutti i dati scritti mentre la chiave era attiva diventano immediatamente inaccessibili e illeggibili in modo permanente.

Limitazioni

Si applicano le seguenti limitazioni:

  • Non puoi modificare la località.
  • Non puoi applicare una chiave Cloud KMS a un bucket di osservabilità che utilizza la crittografia predefinita di Google.
  • Il nome visualizzato non deve superare i 100 byte codificati.
  • La descrizione non deve superare i 1000 byte codificati.
  • I dati vengono archiviati per 30 giorni. Puoi omettere il periodo di conservazione o impostarlo su 30.
  • Se aggiorni la chiave Cloud KMS, la località della chiave deve corrispondere esattamente alla località principale del bucket di osservabilità.

Prima di iniziare

Configura il progetto e i ruoli IAM e seleziona l'interfaccia che intendi utilizzare.

Configura il progetto e i ruoli

  1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Google Cloud project.

  3. Enable the Observability API.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  4. Per ottenere le autorizzazioni necessarie per creare bucket di osservabilità, chiedi all'amministratore di concederti il ruolo IAM Editor di osservabilità (roles/observability.editor) sul tuo progetto. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

    Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Configura le interfacce

gcloud

Installa Google Cloud CLI, quindi accedi a gcloud CLI con la tua identità federata. Dopo aver eseguito l'accesso, inizializza Google Cloud CLI eseguendo il comando seguente: 

gcloud init

REST

Per utilizzare gli esempi di API REST in questa pagina in un ambiente di sviluppo locale, utilizzi le credenziali che fornisci a gcloud CLI.

    Installa Google Cloud CLI, quindi accedi a gcloud CLI con la tua identità federata.

Per saperne di più, consulta Autenticati per usare REST nella Google Cloud documentazione sull'autenticazione di.

Configura la chiave Cloud KMS

Facoltativo. Se prevedi di aggiornare la chiave Cloud KMS utilizzata dal bucket di osservabilità, procedi nel seguente modo:

  1. Abilita l'API Cloud Key Management Service.

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente hai già questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore utilizzo servizi (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

    Abilitare l'API

  2. Crea una chiave e una raccolta di chiavi.

    La località del bucket di osservabilità deve corrispondere alla località della chiave.

  3. Sostituisci PROJECT_ID con l'ID del progetto, quindi esegui il comando seguente:

    gcloud beta observability settings describe \
--location=global --project=PROJECT_ID

    La risposta al comando precedente elenca l'ID del account di servizio di Google Cloud Observability.

  4. Concedi il ruolo Autore crittografia/decrittografia CryptoKey Cloud KMS al account di servizio di Google Cloud Observability.

    gcloud kms keys add-iam-policy-binding \
--project=KMS_PROJECT_ID \
--member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-observability. \
--role=roles/cloudkms.cryptoKeyEncrypterDecrypter \
--location=KMS_KEY_LOCATION \
--keyring=KMS_KEY_RING \
KMS_KEY_NAME

    Prima di eseguire il comando precedente, effettua le seguenti sostituzioni:

    • KMS_PROJECT_ID: l'identificatore alfanumerico univoco, composto dal nome del Google Cloud progetto e da un numero assegnato in modo casuale, del Google Cloud progetto che esegue Cloud KMS. Per informazioni su come ottenere questo identificatore, consulta Identificare i progetti.
    • service-PROJECT_NUMBER: il nome del service account di Google Cloud Observability elencato nel passaggio precedente.
    • KMS_KEY_LOCATION: la regione della chiave Cloud KMS.
    • KMS_KEY_RING: il nome della raccolta di chiavi Cloud KMS.
    • KMS_KEY_NAME: il nome della chiave Cloud KMS. Il formato è il seguente: projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KMS_KEY_RING/cryptoKeys/KEY.

Aggiorna un bucket di osservabilità

REST

Per aggiornare un bucket di osservabilità, invia una richiesta a projects.locations.buckets.patch.

Devi specificare il parametro principale, che identifica il bucket da aggiornare. Questo parametro ha il seguente formato:

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID

I campi nell'espressione precedente hanno i seguenti significati:

Il parametro di query deve specificare un campo updateMask, che identifica i campi da modificare. Ad esempio:

  • Per aggiornare la descrizione, utilizza updateMask=description.
  • Per aggiornare la chiave Cloud KMS e la descrizione, utilizza updateMask=description,cmekSettings.kmsKey.

Il corpo della richiesta è un Bucket oggetto. Devi compilare ogni campo specificato dalla maschera di aggiornamento. Non compilare i campi che non stai aggiornando.

Ad esempio, per aggiornare solo il campo description, puoi utilizzare il seguente oggetto Bucket:

{
    "description": "Updated description for my observability bucket."
}

La risposta è un Operation oggetto. In genere, il completamento di questo metodo richiede meno di un minuto.

In genere, per determinare se un metodo che restituisce un oggetto Operation è completo, esegui il polling dell'oggetto chiamando projects.locations.operations.get finché il campo Operation.done non è impostato su true. Puoi quindi utilizzare altri campi nella struttura Operation per determinare se il metodo è riuscito o meno.

Tuttavia, il metodo patch viene completato rapidamente. Pertanto, un'alternativa è attendere un minuto e poi verificare l'aggiornamento elencando i bucket di osservabilità.

gcloud

Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

  • LOCATION: la località dei bucket di osservabilità. Per elencare tutti i bucket di osservabilità, indipendentemente dalla località, imposta la località su un trattino (-).
  • PROJECT_ID: l'identificatore del progetto.

Esegui il gcloud beta observability buckets list comando:

Linux, macOS o Cloud Shell

gcloud beta observability buckets list \
 --location=LOCATION --project=PROJECT_ID

Windows (PowerShell)

gcloud beta observability buckets list `
 --location=LOCATION --project=PROJECT_ID

Windows (cmd.exe)

gcloud beta observability buckets list ^
 --location=LOCATION --project=PROJECT_ID

La risposta elenca il nome, la descrizione e l'ora di creazione di ogni bucket di osservabilità. Di seguito è riportato un esempio di risposta quando il comando viene eseguito correttamente: 

---
createTime: '2026-01-21T21:39:22.381083860Z'
description: Bucket for storing spans from Cloud Trace.
name: projects/my-project/locations/us/buckets/_Trace

REST

Per elencare i bucket di osservabilità presenti nel tuo progetto e in una località specifica, invia una richiesta all' projects.locations.buckets.list endpoint.

Devi specificare il parametro principale, che ha il seguente formato:

projects/PROJECT_ID/locations/LOCATION

I campi nell'espressione precedente hanno i seguenti significati:

  • PROJECT_ID: l'identificatore del progetto.
  • LOCATION: la località del bucket di osservabilità. Se imposti LOCATION su un trattino, (-), vengono elencati tutti i bucket di osservabilità nel tuo progetto.

La risposta è un array di Bucket oggetti. Per ogni oggetto, il valore del campo name ha il seguente formato:

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID

Ad esempio, quando è stato emesso un comando all'endpoint buckets.list con il parametro principale impostato su projects/my-project/locations/us, la risposta è stata:

{
  "buckets": [
    {
      "name": "projects/my-project/locations/us/buckets/_Trace",
      "description": "Trace Bucket",
      "createTime": "2025-01-01T15:42:30.988919645Z",
      "updateTime": "2025-02-04T15:42:30.988919645Z",
      "retentionDays": 30
    }
  ]
}

Puoi emettere comandi ad altri endpoint dell'API Observability per ottenere ulteriori informazioni sul bucket il cui ID è BUCKET_ID. Ad esempio, puoi elencare i set di dati nel bucket, nonché le visualizzazioni e i link in ogni set di dati. Per un elenco completo degli endpoint dell'API Observability, consulta la documentazione di riferimento dell'API Observability.

Passaggi successivi