Secret Manager 支援使用實體標記 (ETag) 進行最佳化的並行控制。
在某些情況下，兩個程序同時更新相同資源時可能會互相干擾，後者會覆寫前者的作業。
ETag 可讓程序在對資源採取行動前，先查看資源是否已修改，藉此提供最佳化的並行控制方式。
搭配使用 ETag 與 Secret Manager
下列資源修改要求支援 ETag：
在 secrets.patch 要求中，要求 ETag 會內嵌在 Secret 資料中。所有其他要求都會接受選用的 etag 參數。
如果提供 ETag，且與目前的資源 ETag 相符，要求就會成功；否則會失敗，並傳回 FAILED_PRECONDITION 錯誤和 HTTP 狀態碼 400。如果未提供 ETag，系統會繼續處理要求，而不檢查目前儲存的 ETag 值。
資源 ETag 會在建立資源時產生 (projects.secrets.create、projects.secrets.addVersion)，並針對上述每個修改要求更新。修改要求只會更新所套用資源的 ETag。也就是說，更新密鑰版本不會影響密鑰 ETag，同樣地，更新 ETag 也不會影響密鑰版本。
即使更新不會變更資源的狀態，系統仍會更新資源 ETag。
請見如下範例：
-
使用者 1 嘗試啟用 Secret 版本，但不知道該版本已啟用。系統會處理這項要求，但只會變更版本的 ETag，不會變更其他任何內容。
-
使用者 2 嘗試使用舊 ETag 停用版本。
-
這項作業會失敗，因為系統會辨識較新的 ETag，這表示最近有保留啟用版本的意圖。
即使是看似微小的更新，也會因為 ETag 變更而影響效能。這可確保資料一致性，特別是多位使用者或系統與同一資源互動時。
只要包含資源 (Secret 或 SecretVersion)，回應就會傳回 etag 資源。
使用 ETag 刪除密鑰
本節說明刪除密鑰時如何使用 ETag。如果密鑰已由其他程序修改，刪除作業就會失敗。
gcloud
使用下方的任何指令資料之前，請先替換以下項目：
- SECRET_ID：密鑰的 ID 或密鑰的完整 ID。
- ETAG：密碼的實體標記。ETag 必須包含前後引號。
舉例來說，如果 ETag 值為
"abc"，經過 Shell 逸出處理的值就會是"\"abc\""。
執行下列指令：
Linux、macOS 或 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
使用任何要求資料之前，請先替換以下項目：
- PROJECT_ID：專案 ID。 Google Cloud
- SECRET_ID：密鑰的 ID 或密鑰的完整 ID。
- ETAG：密碼的實體標記。ETag 會指定為網址查詢字串的一部分，且必須經過網址編碼。舉例來說，如果 ETag 值為
"abc"，網址編碼值會是%22abc%22，因為引號字元會編碼為%22。
HTTP 方法和網址：
DELETE https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?etag=ETAG
JSON 要求主體：
{}
如要傳送要求，請選擇以下其中一個選項：
curl
將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：
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
將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：
$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
您應該會收到如下的 JSON 回應：
{}
使用 ETag 更新密鑰
本節說明更新密鑰時如何使用 ETag。如果密鑰已由其他程序修改，更新作業就會失敗。
gcloud
使用下方的任何指令資料之前，請先替換以下項目：
- SECRET_ID：密鑰的 ID 或密鑰的完整 ID。
- KEY：標籤名稱。
- VALUE：對應的標籤值。
- ETAG：密碼的實體標記。ETag 必須包含前後引號。
舉例來說，如果 ETag 值為
"abc"，經過 Shell 逸出處理的值就會是"\"abc\""。
執行下列指令：
Linux、macOS 或 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"
回應會傳回密鑰。
REST
使用任何要求資料之前，請先替換以下項目：
- PROJECT_ID：專案 ID。 Google Cloud
- SECRET_ID：密鑰的 ID 或密鑰的完整 ID。
- ETAG：密碼的實體標記。ETag 會指定為「Secret」的欄位，且必須加上引號。舉例來說，如果 ETag 值為
"abc"，經過 JSON 逸出處理的值就會是{"etag":"\"abc\""}。 - KEY：標籤名稱。
- VALUE：對應的標籤值。
HTTP 方法和網址：
PATCH https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?updateMask=labels
JSON 要求主體：
{"etag":"ETAG", "labels":{"KEY": "VALUE"}}
如要傳送要求，請選擇以下其中一個選項：
curl
將要求主體儲存在名為 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://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?updateMask=labels"
PowerShell
將要求主體儲存在名為 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://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?updateMask=labels" | Select-Object -Expand Content
您應該會收到如下的 JSON 回應：
{
"name": "projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID",
"createTime": "2024-09-04T04:06:00.660420Z",
"labels": {
"KEY": "VALUE"
},
"etag": "\"162145a4f894d5\""
}
使用 ETag 更新密鑰版本
本節說明更新密鑰版本時如何使用 ETag。如果密鑰版本已由其他程序修改，更新作業就會失敗。
以下程式碼範例說明如何使用 ETag 停用密鑰版本。您也可以在其他密鑰變更作業期間指定 ETag，例如啟用已停用的版本或刪除密鑰版本。請參閱 Secret Manager 的程式碼範例。
gcloud
使用下方的任何指令資料之前，請先替換以下項目：
- VERSION_ID：密鑰版本的 ID。
- SECRET_ID：密鑰的 ID 或密鑰的完整 ID。
- ETAG：實體標記。ETag 必須包含前後引號。
舉例來說，如果 ETag 值為
"abc"，經過 Shell 逸出處理的值就會是"\"abc\""。
執行下列指令：
Linux、macOS 或 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"
回應會傳回密鑰。
REST
使用任何要求資料之前，請先替換以下項目：
- PROJECT_ID：專案 ID Google Cloud
- SECRET_ID：密鑰的 ID 或密鑰的完整 ID
- VERSION_ID：密鑰版本的 ID
- ETAG：密鑰版本的實體標記。ETag 會指定為 SecretVersion 的欄位，且必須加上引號。舉例來說，如果 ETag 值為
"abc"，經過 JSON 逸出處理的值就會是{"etag":"\"abc\""}。
HTTP 方法和網址：
POST https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID:disable"
JSON 要求主體：
{"etag":"ETAG"}
如要傳送要求，請選擇以下其中一個選項：
curl
將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：
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
將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：
$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
您應該會收到如下的 JSON 回應：
{
"name": "projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID/versions/VERSION_ID",
"createTime": "2024-09-04T06:41:57.859674Z",
"state": "DISABLED",
"etag": "\"1621457b3c1459\""
}