更新可觀測性 bucket

您可以更新可觀測性值區的顯示名稱、說明或 Cloud Key Management Service 金鑰，以反映機構異動或輪替加密金鑰。

您無法使用這些更新作業解決法規遵循問題。舉例來說，您無法使用這些作業變更可觀測性值區的位置，或將 Cloud KMS 金鑰套用至使用 Google 預設加密的值區。

更新 Cloud KMS 金鑰的影響

更新可觀測性 bucket 的 Cloud KMS 金鑰不會影響儲存的資料。也就是說，在更新完成前，原始金鑰會加密新資料。更新完成後，系統會使用更新後的金鑰加密新資料。

只要原始 Cloud KMS 金鑰維持啟用狀態，且 Google Cloud Observability 服務帳戶保留加密者/解密者權限，您就能繼續存取及查看儲存的資料。

如果您停用或刪除原始 Cloud KMS 金鑰，在該金鑰有效期間寫入的所有資料，都會立即永久無法存取和讀取。

限制

相關限制如下：

  • 你無法修改位置。
  • 如果可觀測性值區使用 Google 預設加密，您就無法套用 Cloud KMS 金鑰。
  • 顯示名稱不得超過 100 個編碼位元組。
  • 說明不得超過 1000 個編碼位元組。
  • 資料會保存 30 天。您可以省略保留期限，或將其設為 30。
  • 如果更新 Cloud KMS 金鑰，金鑰位置必須與可觀測性 bucket 的父項位置完全相符。

事前準備

設定專案和 IAM 角色，然後選取要使用的介面。

設定專案和角色

  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. 如要取得建立可觀測性 bucket 所需的權限，請要求管理員授予您專案的「可觀測性編輯者」 (roles/observability.editor) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

    您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

設定介面

gcloud

安裝 Google Cloud CLI，然後 使用聯合身分登入 gcloud CLI。登入後，執行下列指令來初始化 Google Cloud CLI：

gcloud init

REST

如要在本機開發環境中使用本頁的 REST API 範例，請使用您提供給 gcloud CLI 的憑證。

    安裝 Google Cloud CLI，然後 使用聯合身分登入 gcloud CLI。

詳情請參閱 Google Cloud 驗證說明文件中的「使用 REST 進行驗證」。

設定 Cloud KMS 金鑰

選用。如果您打算更新可觀測性值區使用的 Cloud KMS 金鑰，請按照下列步驟操作：

  1. 啟用 Cloud Key Management Service API。

    啟用 API 時所需的角色

    如要啟用 API，您必須具備 serviceusage.services.enable 權限。如果您建立了專案，可能已透過「擁有者」角色 (roles/owner) 取得這項權限。否則，您可以透過「服務使用情形管理員」角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

    啟用 API

  2. 建立金鑰環和金鑰。

    可觀測性 bucket 的位置必須與金鑰位置相符。

  3. 將 PROJECT_ID 替換為專案 ID，然後執行下列指令：

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

    上述指令的回應會列出 Google Cloud Observability 服務帳戶的 ID。

  4. 將 Cloud KMS CryptoKey Encrypter/Decrypter 角色授予 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

    執行上述指令前，請先進行下列替換：

    • KMS_PROJECT_ID：由專案名稱和隨機指派的數字組成的唯一英數字元 ID，用於執行 Cloud KMS 的專案。 Google Cloud Google Cloud 如要瞭解如何取得這個 ID，請參閱「識別專案」。
    • service-PROJECT_NUMBER：上一個步驟中列出的 Google Cloud Observability 服務帳戶名稱。
    • KMS_KEY_LOCATION：Cloud KMS 金鑰的區域。
    • KMS_KEY_RING：Cloud KMS 金鑰環的名稱。
    • KMS_KEY_NAME： Cloud KMS 金鑰的名稱。格式如下： projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KMS_KEY_RING/cryptoKeys/KEY。

更新可觀測性 bucket

REST

如要更新可觀測性 bucket，請傳送要求至 projects.locations.buckets.patch。

您必須指定父項參數，用來識別要更新的值區。這個參數的格式如下：

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID

上述運算式中的欄位具有下列意義：

  • PROJECT_ID：專案的 ID。
  • LOCATION：可觀測性 bucket 的位置。
  • BUCKET_ID：可觀測性 Bucket 的 ID。舉例來說，這個 ID 可能是 _Trace。

查詢參數必須指定 updateMask 欄位，用來識別要修改的欄位。例如：

  • 如要更新說明，請使用 updateMask=description。
  • 如要更新 Cloud KMS 金鑰和說明，請使用 updateMask=description,cmekSettings.kmsKey。

要求主體是 Bucket 物件。您必須填入更新遮罩指定的所有欄位。請勿填寫您未更新的欄位。

舉例來說，如要只更新 description 欄位，可以使用下列 Bucket 物件：

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

回應為 Operation 物件。 這項方法通常會在 1 分鐘內完成。

一般來說，如要判斷傳回 Operation 物件的方法是否完成，請呼叫 projects.locations.operations.get 輪詢物件，直到 Operation.done 欄位設為 true 為止。接著，您可以使用 Operation 結構中的其他欄位，判斷方法是否成功。

不過，patch 方法很快就會完成。因此，替代做法是等待一分鐘，然後列出可觀測性值區，驗證更新是否成功。

gcloud

使用下方的任何指令資料之前，請先替換以下項目：

  • LOCATION：可觀測性 bucket 的位置。如要列出所有可觀測性值區，不論位置為何，請將位置設為連字號 (-)。
  • PROJECT_ID：專案的 ID。

執行 gcloud beta observability buckets list 指令：

Linux、macOS 或 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

回應會列出每個可觀測性 bucket 的名稱、說明和建立時間。以下是指令成功時的回應範例： 

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

REST

如要列出專案和特定位置中的可觀測性值區，請將要求傳送至 projects.locations.buckets.list 端點。

您必須指定父項參數，格式如下：

projects/PROJECT_ID/locations/LOCATION

上一個運算式中的欄位具有下列意義：

  • PROJECT_ID：專案的 ID。
  • LOCATION：可觀測性 bucket 的位置。 如果將 LOCATION 設為連字號 (-)，系統會列出專案中的所有可觀測性值區。

回應是 Bucket 物件的陣列。每個物件的 name 欄位值格式如下：

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID

舉例來說，如果向 buckets.list 端點發出指令，並將父項參數設為 projects/my-project/locations/us，則回應如下：

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

您可以對其他 Observability API 端點發出指令，進一步瞭解 ID 為 BUCKET_ID 的值區。舉例來說，您可以列出該值區中的資料集，以及每個資料集的檢視畫面和連結。如需 Observability API 端點的完整清單，請參閱 Observability API 參考文件。

後續步驟