管理对象丰富化

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

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

获取所需的角色

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

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

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

所需权限

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

  • 查看基本对象丰富化上下文元数据：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）。此载荷包含边界多边形坐标、分类置信度分数、面部表情和安全评分等详细信息。

查看基本上下文元数据

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

控制台

  1. 在 Google Cloud 控制台中，转到 Cloud Storage 存储桶页面。

    进入“存储桶”

  2. 在存储桶列表中，点击您要检查的对象所在的存储桶的名称。

    在对象表中，自定义上下文列会为处理过对象的每个模型（内容安全、人脸检测器、标签检测器、对象检测器或 PDF 分类）显示一个条状标签。

  3. 如需检查单个对象，请点击该对象的名称。

  4. 在对象详情页面上，前往自定义上下文字段。如果该字段有多个条状标签，请点击 展开该行。

  5. 将指针悬停在模型条状标签上或点击模型条状标签，即可查看其基本上下文元数据：

    • 上下文键：预留的模型键，例如 google:annotation:label-detector-v1。
    • 上下文值：模型执行状态（SUCCESS 或 FAILURE）。
    • 创建时间和上次修改时间：Cloud Storage 创建和上次更新丰富功能的时间戳。
    • 查看配置中心：打开对象丰富化页面。在存储桶的对象表中查看条状标签时，您还可以点击过滤上下文，以按该上下文过滤存储桶中的对象。

JSON API

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

  2. 使用 cURL 向 JSON API 发送包含 projection=full 查询参数的 Objects: get 请求：

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

    其中：

    • BUCKET_NAME 是包含对象的存储分区的名称。例如 my-bucket。
    • OBJECT_NAME 是对象的网址编码名称。例如 image.jpg。

    响应会返回 contexts.custom 结构：

    {
  "kind": "storage#object",
  "id": "my-bucket/image.jpg/1700000000000000",
  "name": "image.jpg",
  "bucket": "my-bucket",
  "contexts": {
    "custom": {
      "google:annotation:label-detector-v1": {
        "value": "SUCCESS",
        "createTime": "2026-09-29T17:20:00.000Z",
        "updateTime": "2026-09-29T17:20:00.000Z",
        "extendedDataTypeUrl": "type.googleapis.com/google.protobuf.Struct"
      }
    }
  }
}

    value 字段指示对象的模型执行状态，例如 SUCCESS 或 FAILURE。

检索扩展数据

如需检索完整的结构化丰富数据（例如边界框、边界多边形、标签或检测到的人脸），请使用 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./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 rewrite Object 请求和 dropContextGroups=custom 查询参数调用 JSON API：

    curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Length: 0" \
  "https://storage./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 创建图表。

后续步骤