管理对象丰富化

配置对象丰富化后， Cloud Storage 会异步评估符合条件的对象，并将 丰富化元数据直接附加到您存储的对象。

本页面介绍了如何在 Cloud Monitoring 中检查基本上下文元数据、检索 扩展数据载荷、从对象中舍弃丰富化以及监控 处理进度。

获取所需的角色

如需获得查看、检索和舍弃对象丰富化所需的权限，请让您的管理员向您授予存储桶或项目的以下 IAM 角色：

• 查看基本对象丰富化元数据： Storage Object Viewer (roles/storage.objectViewer)
• 检索对象丰富化扩展数据： Storage Object User (roles/storage.objectUser)
• 在对象重写期间舍弃对象丰富化： Storage Object Admin (roles/storage.objectAdmin)

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

这些预定义角色包含 查看、检索和舍弃对象丰富化所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

如需查看、检索和舍弃对象丰富化，您需要具备以下权限：

• 查看基本对象丰富化上下文元数据： storage.objects.get
• 检索对象丰富化扩展数据： storage.objects.viewFullContext
• 在对象重写期间舍弃对象丰富化：
  • storage.objects.get
  • storage.objects.create
  • storage.objects.delete
  • storage.objects.update

您也可以使用自定义角色或其他预定义角色来获取这些权限。

查看对象丰富化

Cloud Storage 会将丰富化元数据作为 Google 管理的 对象上下文直接附加到您的对象，并将其置于 contexts.custom 属性下。每个模型都使用以 google:annotation:为前缀的预留键（例如google:annotation:label-detector-v1或 google:annotation:face-detector-v1）。

Cloud Storage 会将丰富化数据整理为两个层级：

• 上下文元数据：包含上下文键、模型执行状态 (value)、时间戳和 protobuf 类型网址。标准对象 describe 和 get 操作会返回此元数据。
• 扩展数据（预览版）： 包含完整的结构化 JSON 丰富化载荷（最多 128 KiB）。此载荷包含边界多边形坐标、分类置信度分数、面部表情和安全评级等详细信息。

查看基本上下文元数据

如需查看哪些模型处理了对象并查看基本上下文 元数据，请使用 Cloud de Confiance 控制台或 JSON API：

检索扩展数据

如需检索完整的结构化丰富化数据（例如边界框、 边界多边形、 标签或检测到的人脸），请使用 JSON API 调用 viewFullContext 方法 （预览版）。

1. 安装并初始化 gcloud CLI，以便为 Authorization 标头生成访问令牌。

2. 使用 cURL 向 JSON API 发送 viewFullContext 请求，并指定要检查的模型的上下文键：

   curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Accept: application/json" \
     "https://storage.s3nsapis.fr/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME/viewFullContext?contextKey=CONTEXT_KEY"

   其中：

   • BUCKET_NAME 是包含对象的存储桶的名称。例如 my-bucket。
   • OBJECT_NAME 是对象的网址编码名称。 例如 image.jpg。
   • CONTEXT_KEY 是模型上下文键。例如 google:annotation:label-detector-v1。

   响应包含带有完整丰富化载荷的 extendedData 结构：

   {
     "kind": "storage#objectFullContext",
     "type": "CUSTOM",
     "key": "google:annotation:label-detector-v1",
     "value": "SUCCESS",
     "createTime": "2026-09-29T17:20:00.000Z",
     "updateTime": "2026-09-29T17:20:00.000Z",
     "extendedData": {
       "@type": "type.googleapis.com/google.protobuf.Struct",
       "modelName": "label-detector",
       "modelVersion": "v1",
       "labelAnnotationGroup": {
         "labelAnnotations": [
           {
             "description": "Night",
             "knowledgeGraphId": "/m/01d74z",
             "score": 0.92,
             "topicality": 0.19
           }
         ]
       }
     }
   }
   

如需详细了解每个模型的 JSON 架构和字段，请参阅 支持的模型和架构。

舍弃对象丰富化

如果您必须遵守数据保留政策或不再需要丰富化元数据，可以从对象中舍弃这些元数据。

由于 Google 管理以 google: 前缀开头的上下文键，因此您无法使用标准元数据更新方法修改或删除这些键。相反，您可以在对象重写、复制或组合操作期间通过指定 dropContextGroups=custom 参数来舍弃这些键，该参数会舍弃对象上的所有对象上下文。

如需在使用 JSON API 重写对象时舍弃对象上下文（包括对象丰富化） ，请执行以下操作：

1. 安装并初始化 gcloud CLI，以便为 Authorization 标头生成访问令牌。

2. 使用 cURL 通过 POST 重写对象 请求和 dropContextGroups=custom 查询参数调用 JSON API：

   curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Length: 0" \
     "https://storage.s3nsapis.fr/storage/v1/b/SOURCE_BUCKET/o/SOURCE_OBJECT/rewriteTo/b/DESTINATION_BUCKET/o/DESTINATION_OBJECT?dropContextGroups=custom"

   其中：

   • SOURCE_BUCKET 是包含源对象的存储桶的名称。例如 my-source-bucket。
   • SOURCE_OBJECT 是源对象的网址编码名称。例如 image.jpg。
   • DESTINATION_BUCKET 是目标存储桶的名称（可以与源存储桶匹配）。例如 my-source-bucket。
   • DESTINATION_OBJECT 是目标对象的网址编码名称（可以与源对象匹配）。例如 image.jpg。

如需管理和舍弃数以十亿计的对象中的上下文，请参阅 批量管理对象上下文。

监控对象丰富化指标

您可以使用 Cloud Monitoring 跟踪丰富化处理吞吐量、待处理对象和模型 执行计数。 Cloud Storage 会在 gcs_bucket 受监控的资源的 storage.googleapis.com 命名空间下导出以下指标：

指标类型（以 storage.googleapis.com/ 为前缀）	种类和类型	说明和标签
auto_annotate/operations/pending_objects	GAUGE、INT64	存储桶中待丰富化的对象总数。每 300 秒采样一次。
auto_annotate/operations/processed_object_count	DELTA、INT64	在时间窗口内，对象丰富化功能处理的对象总数。每 300 秒采样一次。
auto_annotate/operations/model_count	DELTA、INT64	在时间窗口内，存储桶中执行的模型总数，按 model_name、model_version 和 status（例如 SUCCESS 或 FAILURE）分组。
auto_annotate/operations/request_count	DELTA、INT64	在时间窗口内，进行的 API 调用总数，按 method 和 response_code 分组。
auto_annotate/storage/annotated_objects	GAUGE、INT64	存储桶中已生成丰富化的对象总数的每日快照，按 type 和 data_locations 分组。
auto_annotate/storage/model_outputs	GAUGE、INT64	存储桶中存储的模型输出总数的每日快照，按 model_name、model_version、status、type 和 data_locations 分组。

如需详细了解如何查询指标和设置提醒，请参阅 Cloud Storage 的 Cloud Monitoring 指标 和使用 Metrics Explorer 创建图表。

后续步骤

• 配置对象丰富化。
• 使用 BigQuery 中的 SQL 分析对象丰富化。
• 查看支持的模型和输出架构。
• 阅读对象丰富化概览。
• 查看 featureConfigs JSON API 资源和方法。
• 了解对象上下文。
• 使用 Storage 批量操作批量管理对象。