更新可观测性存储分区

您可以更新可观测性存储桶的显示名称、说明或 Cloud Key Management Service 密钥，以反映组织变更或轮替加密密钥。

您无法使用这些更新操作来解决合规性问题。例如，您无法使用这些操作来更改可观测性存储桶的位置，或将 Cloud KMS 密钥应用于使用 Google 默认加密的存储桶。

更新 Cloud KMS 密钥的影响

更新可观测性存储桶的 Cloud KMS 密钥不会影响存储的数据。也就是说，在更新完成之前，原始密钥会加密新数据。更新完成后，更新后的密钥会加密新数据。

只要 原始 Cloud KMS 密钥保持 启用状态，并且 Google Cloud Observability 服务帐号 保留加密者/解密者权限，您就可以继续访问和查看存储的数据。

如果您停用或销毁原始 Cloud KMS 密钥，则在该密钥处于活动状态时写入的任何数据都会立即变得永久无法访问和读取 。

限制

需要遵循以下限制：

• 您无法修改位置。
• 您无法将 Cloud KMS 密钥应用于使用 Google 默认加密的可观测性存储桶。
• 显示名称不得超过 100 个编码字节。
• 说明不得超过 1000 个编码字节。
• 数据存储时间为 30 天。您可以省略保留期限，也可以将其设置为 30。
• 如果您更新 Cloud KMS 密钥，则密钥的位置必须与可观测性存储桶的父级位置完全一致。

准备工作

配置您的项目和 IAM 角色，然后选择您计划使用的界面。

配置项目和角色

登录您的 Google Cloud 账号。如果您是 Google Cloud的新用户， 请创建一个账号，以评估我们的产品在 实际场景中的表现。新客户还可获享 $300 赠金，用于 运行、测试和部署工作负载。

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

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

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

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

1. 如要获得创建可观测性存储分区所需的权限，请让您的管理员为您授予项目的 Observability Editor (roles/observability.editor) IAM 角色。如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

   您也可以通过自定义 角色或其他预定义 角色来获取所需的权限。

配置界面

gcloud

在 Google Cloud 控制台中，激活 Cloud Shell。

激活 Cloud Shell

Google Cloud Cloud Shell 会话随即会在控制台的底部启动，并显示命令行提示符。Cloud Shell 是一个已安装 Google Cloud CLI 且已为当前项目设置值的 Shell 环境 。该会话可能需要几秒钟来完成初始化。

REST

如需在本地开发环境中使用本页面上的 REST API 示例，请使用您提供给 gcloud CLI 的 凭证。

安装 Google Cloud CLI。

如果您使用的是外部身份提供方 (IdP)，则必须先 使用联合身份登录 gcloud CLI。

如需了解详情，请参阅 身份验证文档中的使用 REST 时进行身份验证 Google Cloud 。

配置 Cloud KMS 密钥

可选。如果您计划更新可观测性存储桶使用的 Cloud KMS 密钥，请执行以下操作：

1. 启用 Cloud Key Management Service API。

   启用 API 所需的角色

   如需启用 API，您需要拥有 serviceusage.services.enable 权限。如果您 创建了项目，则可能已通过 所有者角色 (roles/owner) 拥有此权限。否则，您可以通过 Service Usage Admin 角色 (roles/serviceusage.serviceUsageAdmin) 获取此权限。 了解如何授予角色。

   启用 API

2. 创建密钥环和密钥。

   可观测性存储桶的位置必须与密钥的位置一致。

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:[e-mail] \
   --role=roles/cloudkms.cryptoKeyEncrypterDecrypter \
   --location=KMS_KEY_LOCATION \
   --keyring=KMS_KEY_RING \
   KMS_KEY_NAME
   

   在运行上述命令之前，请进行以下替换：

   • KMS_PROJECT_ID：运行 Cloud KMS 的 Google Cloud 项目的唯一字母数字 标识符，由 Google Cloud 项目名称和随机分配的编号组成。 如需了解如何获取此标识符，请参阅 标识项目。
   • 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。

更新可观测性存储桶

REST

如需更新可观测性存储桶，请向 projects.locations.buckets.patch发送请求。

您必须指定 parent 参数，该参数用于标识要更新的存储桶。此参数的格式如下：

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID

上述表达式中的字段具有以下含义：

• PROJECT_ID：项目的标识符。
• LOCATION：可观测性存储桶的位置。
• BUCKET_ID：可观测性存储桶的 ID。例如，此 ID 可能是 _Trace。

查询参数必须指定 updateMask 字段，该字段用于标识要修改的字段。例如：

• 如需更新说明，请使用 updateMask=description。
• 如需更新 Cloud KMS 密钥和说明，请使用 updateMask=description,cmekSettings.kmsKey。

请求正文是一个 Bucket 对象。您必须填充更新掩码指定的所有字段。请勿填充您未更新的字段。

例如，如需仅更新 description 字段，您可以使用以下 Bucket 对象：

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

响应是一个 Operation 对象。 通常，此方法需要不到一分钟的时间即可完成。

通常，如需确定返回 Operation 对象 的方法是否已完成，您需要通过调用 projects.locations.operations.get 来轮询该对象，直到 Operation.done 字段设置为 true。然后，您可以使用 Operation 结构中的其他字段来确定该方法是成功还是失败。

不过，patch 方法会快速完成。因此，另一种方法是等待一分钟，然后通过列出可观测性存储分区来验证更新。

gcloud

注意：您必须使用 gcloud CLI 563.0.0 版或更高版本。

在使用下面的命令数据之前， 请先进行以下替换：

• LOCATION：可观测性存储分区的位置。如需列出所有可观测性存储分区， 无论其位置如何，请将位置设置为连字符 (-)。
• PROJECT_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

响应会列出每个可观测性存储分区的名称、说明和创建时间。 以下是命令成功时的响应示例：

---
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 端点发送请求。

您必须指定 parent 参数，该参数的格式如下：

projects/PROJECT_ID/locations/LOCATION

上述表达式中的字段具有以下含义：

• PROJECT_ID：项目的标识符。
• LOCATION：可观测性存储桶的位置。 如果您将 LOCATION 设置为连字符 (-)，则会列出项目中的所有可观测性存储分区 。

响应是一个 Bucket对象数组。对于每个对象，name 字段的值的格式如下：

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID

例如，当向 buckets.list 端点发出命令且 parent 参数设置为 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 参考文档。

后续步骤

• 查看和分析遥测数据
• 为可观测性存储分区设置默认值：为可观测性存储分区配置 默认存储位置和默认 客户管理的加密密钥 (CMEK)。