Questa pagina è stata tradotta dall'API Cloud Translation.

Utilizzare i tag delle entità per il controllo della contemporaneità ottimistico

Secret Manager supporta l'utilizzo dei tag entità (ETag) per controllo della contemporaneità ottimistico.

In alcuni casi, due processi che aggiornano la stessa risorsa in parallelo possono interferire tra loro, in quanto il secondo processo sovrascrive l'impegno del primo.

Gli ETag forniscono un mezzo per controllo della contemporaneità ottimistico consentendo ai processi di verificare se una risorsa è stata modificata prima di intervenire su di essa.

Utilizzare i tag ETag con Secret Manager

Le seguenti richieste di modifica delle risorse supportano gli ETag:

In una richiesta secrets.patch, l'ETag della richiesta è incorporata nei dati Secret. Tutte le altre richieste accettano un parametro etag facoltativo.

Se viene fornito un ETag e corrisponde all'ETag della risorsa corrente, la richiesta va a buon fine; in caso contrario, non riesce e restituisce un errore FAILED_PRECONDITION e un codice di stato HTTP 400. Se non viene fornito un ETag, la richiesta procede senza controllare il valore ETag attualmente archiviato.

Gli ETag delle risorse vengono generati al momento della creazione della risorsa (projects.secrets.create, projects.secrets.addVersion) e aggiornati per ciascuna delle richieste di modifica elencate sopra. Una richiesta di modifica aggiorna solo l'ETag della risorsa a cui si applica. ovvero l'aggiornamento di una versione del secret non influisce sull'ETag del secret e, analogamente, l'aggiornamento dell'ETag non influisce sulla versione del secret.

Anche quando un aggiornamento non modifica lo stato di una risorsa, aggiorna comunque l'ETag della risorsa.

Considera l'esempio seguente:

L'utente 1 tenta di attivare una versione del secret senza sapere che è già attiva. Il sistema elabora questo elemento, modificando solo l'ETag della versione.
L'utente 2, utilizzando il vecchio ETag, tenta di disattivare la versione.
L'operazione non va a buon fine perché il sistema riconosce l'ETag più recente, che indica un'intenzione più recente di mantenere la versione abilitata.

Anche gli aggiornamenti apparentemente minori sono importanti a causa delle modifiche agli ETag. Ciò garantisce la coerenza dei dati, soprattutto quando più utenti o sistemi interagiscono con la stessa risorsa.

La risorsa etag viene restituita nella risposta ogni volta che viene inclusa una risorsa (Secret o SecretVersion).

Importante:per utilizzare Secret Manager con i carichi di lavoro in esecuzione su Compute Engine o Google Kubernetes Engine, l'istanza o il nodo sottostante deve avere l'ambito OAuth cloud-platform. Per ulteriori informazioni, consulta la sezione Accesso all'API Secret Manager.

Elimina un secret con i tag ETag

Questa sezione descrive l'utilizzo degli ETag durante l'eliminazione di un secret. Se il secret è stato modificato da un altro processo, l'operazione di eliminazione non riesce.

gcloud

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

SECRET_ID: l'ID del secret o l'identificatore completo del secret.
ETAG: il tag di entità del secret. L'ETag deve includere le virgolette che la racchiudono. Ad esempio, se il valore ETag era "abc", il valore con escape della shell sarebbe "\"abc\"".

Esegui questo comando:

Linux, macOS o Cloud Shell

gcloud secrets delete SECRET_ID \
    --etag "ETAG"

Windows (PowerShell)

gcloud secrets delete SECRET_ID `
    --etag "ETAG"

Windows (cmd.exe)

gcloud secrets delete SECRET_ID ^
    --etag "ETAG"

REST

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

PROJECT_ID: l' Google Cloud ID progetto.
SECRET_ID: l'ID del secret o l'identificatore completo del secret.
ETAG: il tag di entità del secret. L'ETag viene specificato come parte della stringa di query dell'URL e deve essere codificato nell'URL. Ad esempio, se il valore ETag è "abc", il valore con codifica URL sarà %22abc%22 perché il carattere virgolette è codificato come %22.

Metodo HTTP e URL:

DELETE https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?etag=ETAG

Corpo JSON della richiesta:

{}

Per inviare la richiesta, scegli una di queste opzioni:

curl

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 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 DELETE \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?etag=ETAG"

PowerShell

Nota: il comando seguente 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 . 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 DELETE `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?etag=ETAG" | Select-Object -Expand Content

Dovresti ricevere una risposta JSON simile alla seguente:

{}

Aggiorna un secret con i tag ETag

Questa sezione descrive l'utilizzo degli ETag durante l'aggiornamento di un secret. Se il secret è stato modificato da un altro processo, l'operazione di aggiornamento non verrà completata.

gcloud

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

SECRET_ID: l'ID del secret o l'identificatore completo del secret.
KEY: il nome dell'etichetta.
VALUE: il valore dell'etichetta corrispondente.
ETAG: il tag di entità del secret. L'ETag deve includere le virgolette che la racchiudono. Ad esempio, se il valore ETag era "abc", il valore con escape della shell sarebbe "\"abc\"".

Esegui questo comando:

Linux, macOS o Cloud Shell

gcloud secrets update SECRET_ID \
    --update-labels "KEY=VALUE" \
    --etag "ETAG"

Windows (PowerShell)

gcloud secrets update SECRET_ID `
    --update-labels "KEY=VALUE" `
    --etag "ETAG"

Windows (cmd.exe)

gcloud secrets update SECRET_ID ^
    --update-labels "KEY=VALUE" ^
    --etag "ETAG"

La risposta restituisce il segreto.

REST

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

PROJECT_ID: l' Google Cloud ID progetto.
SECRET_ID: l'ID del secret o l'identificatore completo del secret.
ETAG: il tag di entità del secret. L'ETag è specificata come campo nel Secret e deve includere le virgolette che lo racchiudono. Ad esempio, se il valore ETag era "abc", il valore con escape JSON sarebbe {"etag":"\"abc\""}.
KEY: il nome dell'etichetta.
VALUE: il valore dell'etichetta corrispondente.

Metodo HTTP e URL:

PATCH https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?updateMask=labels

Corpo JSON della richiesta:

{"etag":"ETAG", "labels":{"KEY": "VALUE"}}

Per inviare la richiesta, scegli una di queste opzioni:

curl

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://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?updateMask=labels"

PowerShell

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://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?updateMask=labels" | Select-Object -Expand Content

Dovresti ricevere una risposta JSON simile alla seguente:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID",
  "createTime": "2024-09-04T04:06:00.660420Z",
  "labels": {
    "KEY": "VALUE"
  },
  "etag": "\"162145a4f894d5\""
}

Aggiorna una versione del secret con ETag

Questa sezione descrive l'utilizzo degli ETag durante l'aggiornamento di una versione del secret. Se la versione del secret è stata modificata da un altro processo, l'operazione di aggiornamento non andrà a buon fine.

L'esempio di codice riportato di seguito descrive la disattivazione di una versione segreta con ETag. Puoi anche specificare gli ETag durante altre operazioni di modifica dei secret, ad esempio quando abiliti le versioni disabilitate o elimini le versioni dei secret. Fai riferimento agli esempi di codice per Secret Manager.

gcloud

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

VERSION_ID: l'ID della versione del secret.
SECRET_ID: l'ID del secret o l'identificatore completo del secret.
ETAG: il tag dell'entità. L'ETag deve includere le virgolette che la racchiudono. Ad esempio, se il valore ETag era "abc", il valore con escape della shell sarebbe "\"abc\"".

Esegui questo comando:

Linux, macOS o Cloud Shell

gcloud secrets versions disable VERSION_ID \
  --secret SECRET_ID \
  --etag "ETAG"

Windows (PowerShell)

gcloud secrets versions disable VERSION_ID `
  --secret SECRET_ID `
  --etag "ETAG"

Windows (cmd.exe)

gcloud secrets versions disable VERSION_ID ^
  --secret SECRET_ID ^
  --etag "ETAG"

La risposta restituisce il segreto.

REST

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

PROJECT_ID: l'ID progetto Google Cloud
SECRET_ID: l'ID del secret o l'identificatore completo del secret
VERSION_ID: l'ID della versione del secret
ETAG: il tag di entità della versione del secret. L'ETag è specificato come campo in SecretVersion e deve includere le virgolette che lo racchiudono. Ad esempio, se il valore ETag era "abc", il valore con escape JSON sarebbe {"etag":"\"abc\""}.

Metodo HTTP e URL:

POST https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID:disable"

Corpo JSON della richiesta:

{"etag":"ETAG"}

Per inviare la richiesta, scegli una di queste opzioni:

curl

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

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID:disable""

PowerShell

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 POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID:disable"" | Select-Object -Expand Content

Dovresti ricevere una risposta JSON simile alla seguente:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID/versions/VERSION_ID",
  "createTime": "2024-09-04T06:41:57.859674Z",
  "state": "DISABLED",
  "etag": "\"1621457b3c1459\""
}

Passaggi successivi

Scopri come configurare le pianificazioni di rotazione per i secret.
Scopri come modificare i secret.
Scopri come configurare le notifiche per un secret.

Utilizzare i tag delle entità per il controllo della contemporaneità ottimistico Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Utilizzare i tag ETag con Secret Manager

Elimina un secret con i tag ETag

gcloud

Linux, macOS o Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

curl

PowerShell

Aggiorna un secret con i tag ETag

gcloud

Linux, macOS o Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

curl

PowerShell

Aggiorna una versione del secret con ETag

gcloud

Linux, macOS o Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

curl

PowerShell

Passaggi successivi

Utilizzare i tag delle entità per il controllo della contemporaneità ottimistico