配置对象丰富化

如需为 Cloud Storage 存储桶中的图片和 PDF 文档生成结构化元数据，请创建 特征配置 (FeatureConfig) 资源。您还必须授权对象丰富化服务代理访问您的数据。 配置对象丰富化后， Cloud Storage 会异步评估与您选择的机器 学习模型匹配的对象，并将结果直接作为对象上下文附加到您的对象 。

本页面介绍了如何创建、列出、查看、更新和删除特征配置。此外，本页面还介绍了如何向服务代理授予所需的 Identity and Access Management (IAM) 权限。

完整的工作流包括以下步骤：

  1. 创建特征配置 (FeatureConfig) 资源以定义范围并选择模型。
  2. 授权服务代理访问您的存储桶。
  3. 查看和管理对象上的丰富化元数据。
  4. 使用 BigQuery 中的 SQL 批量分析丰富化。
  5. 随着工作负载的发展，更新或删除特征配置。

如需了解概念详情和支持的用例，请参阅 对象丰富化概览。

准备工作

在配置对象丰富化之前，请完成以下设置步骤：

获取所需的角色

如需获得创建和管理特征配置所需的权限，请让您的管理员为您授予项目的Storage Admin (roles/storage.admin) IAM 角色。如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

此预定义角色包含 创建和管理特征配置所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

如需创建和管理特征配置，需要具备以下权限：

  • storage.featureConfigs.create
  • storage.featureConfigs.list
  • storage.featureConfigs.get
  • storage.featureConfigs.update
  • storage.featureConfigs.delete

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

（可选）准备 Storage Insights 数据集以进行 SQL 分析

如果您计划使用 BigQuery 中的 SQL 查询和分析数百万个对象的丰富化元数据 ，则必须先 存储空间分析。 存储空间分析数据集会自动将对象上下文直接导出到可查询的 BigQuery 表中。

如果您只想使用 Cloud de Confiance 控制台、Google Cloud CLI 或 API 检查单个对象，则可以跳过此步骤。

创建特征配置

特征配置 (FeatureConfig) 指定 Cloud Storage 监控哪些存储桶，以及哪些机器学习模型评估您的对象。在配置中指定确切的存储桶名称；对象丰富化不支持正则表达式或通配符。如果您在创建配置后创建、重新创建（删除并重新创建）或重定位 存储桶，则必须更新特征 配置以包含这些存储桶。如需了解详情，请参阅 配置和范围管理。

您可以使用 Cloud de Confiance 控制台、 Google Cloud CLI 或 JSON API 创建特征配置。

控制台

  1. 在 Cloud de Confiance 控制台中，前往 Cloud Storage 对象丰富化 页面。

    前往“对象丰富化”

  2. 点击创建 。

  3. 在定义来源 步骤中，指定配置名称和目标存储桶：

    1. 在名称 字段中，为特征配置输入具有唯一性的名称。该名称必须包含 1 到 63 个字符，并且只能包含小写字母、数字或连字符。它必须以小写字母开头，且不能以连字符结尾。创建配置后，您无法更改此名称。
    2. 可选：如需帮助识别配置，请在说明 字段中输入说明（最多 256 个字符）。
    3. 如需指定要丰富化的存储桶，请在存储桶名称 字段中输入一个或多个存储桶名称，并用英文逗号或空格分隔。或者，点击浏览，选择一个存储桶，然后 点击 选择。
    4. 点击继续 。

  4. 在选择模型 步骤中，选中要启用的一个或多个 机器学习模型的复选框，然后点击 继续：

    • 图片对象检测 (object-detector)：识别并定位图片中的多个对象。
    • 图片人脸检测 (face-detector)：检测图片中的人脸及其属性。
    • 图片标签 (label-detector)：根据图片内容为图片分配标签。
    • 图片露骨内容检测 (content-safety)：检测成人、暴力或其他敏感内容。
    • PDF 分类 (pdf-classification)：识别文档主题类别。

    如需详细了解每个模型及其输出架构，请参阅 支持的模型和架构。

  5. 在选择处理位置 步骤中，从处理 位置 菜单中选择一个多区域位置（美国 、欧洲 或 亚洲 ），然后点击继续 。

  6. 在授予所需权限 步骤中，选择如何向对象丰富化服务代理授予所需的 IAM 角色：

    • 授予项目范围的权限：自动向服务 代理授予所需的角色（roles/storage.annotationGeneratorService 和 roles/storage.bucketViewer），以处理项目中所有当前及未来的 Cloud Storage 存储桶。选择此选项需要对项目拥有 resourcemanager.projects.setIamPolicy 权限。如果您没有此权限，则无法使用此选项。
    • 请在稍后手动提供授权权限：创建配置 但不立即授予权限。您必须先向服务代理授予权限，然后 Cloud Storage 才能处理对象。

  7. 点击创建 。

    创建特征配置会启动一项长时间运行的操作。操作完成 后， Cloud de Confiance 控制台会打开 配置详情页面。如果您选择了授予项目范围的 权限，则 Cloud de Confiance 控制台会在创建配置后应用 IAM 政策绑定。

命令行

如需创建特征配置，请使用 gcloud alpha storage feature-configs create 命令：

gcloud alpha storage feature-configs create FEATURE_CONFIG_ID \
    --description="DESCRIPTION" \
    --auto-annotate-models=MODELS \
    --auto-annotate-processing-location=PROCESSING_LOCATION \
    --include-bucket-id-regexes=BUCKET_NAME

其中：

  • FEATURE_CONFIG_ID 是特征配置的唯一 ID。必须包含 1 到 63 个字符，以小写字母开头，并且只能包含小写字母、数字或连字符。不能以连字符结尾。
  • DESCRIPTION 是特征配置的可选说明。例如，Scan invoices and receipts。
  • MODELS 是要启用的机器学习模型的逗号分隔列表：face-detector、object-detector、label-detector、content-safety 或 pdf-classification。如需详细了解每个模型及其输出架构，请参阅支持的模型和 架构。
  • PROCESSING_LOCATION 是发生数据处理的多区域处理位置。支持的值为 us、eu 或 asia。
  • BUCKET_NAME 是要在此配置中包含的存储桶的确切名称。您可以指定确切存储桶名称的逗号分隔列表。

JSON API

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

  2. 创建一个包含特征配置设置的 JSON 文件：

    {
  "description": "DESCRIPTION",
  "autoAnnotateConfig": {
    "models": [
      { "name": "MODEL_NAME" }
    ],
    "processingLocation": "PROCESSING_LOCATION"
  },
  "filter": {
    "includedCloudStorageBuckets": {
      "bucketIdRegexes": [
        "BUCKET_NAME"
      ]
    }
  }
}

    其中：

    • DESCRIPTION 是特征配置的可选说明。例如，Scan invoices and receipts。

    • MODEL_NAME 是要启用的机器学习模型的名称：face-detector、object-detector、label-detector、content-safety 或 pdf-classification。如需详细了解每个 模型及其输出架构，请参阅支持的模型和架构。 如需启用多个模型，请向 models 数组添加其他模型对象。

    • PROCESSING_LOCATION 是发生数据处理的多区域处理位置。支持的值为 us、eu 或 asia。

    • BUCKET_NAME 是要在此配置中包含的存储桶的确切名称。例如，my-bucket。 如需包含多个存储桶，请在 bucketIdRegexes 数组中指定其他存储桶名称字符串。

  3. 使用 cURL 向 JSON API 发送 featureConfigs.create 请求：

    curl -X POST --data-binary @JSON_FILE_NAME \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://storage.s3nsapis.fr/v2/projects/PROJECT_ID/locations/global/featureConfigs?featureConfigId=FEATURE_CONFIG_ID"

    其中：

    • JSON_FILE_NAME 是您在上一步中创建的 JSON 文件的路径。例如，config.json。
    • PROJECT_ID 是您的 Cloud de Confiance 项目 ID。例如，my-project。
    • FEATURE_CONFIG_ID 是特征配置的唯一 ID。例如，my-feature-config。必须包含 1 到 63 个字符，以小写字母开头，并且只能包含小写字母、数字或连字符。不能以连字符结尾。

  4. 可选：如需检查创建特征配置的 长时间运行 操作的状态，请使用 cURL 向 JSON API 发送 operations.get 请求：

    curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.s3nsapis.fr/v2/projects/PROJECT_ID/locations/global/operations/OPERATION_ID"

    其中：

    • PROJECT_ID 是您的 Cloud de Confiance 项目 ID。例如，my-project。
    • OPERATION_ID 是在创建响应中返回的操作 ID。

  5. 可选：如需列出所有活跃操作和历史操作，请使用 cURL向 JSON API发送operations.list请求：

    curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.s3nsapis.fr/v2/projects/PROJECT_ID/locations/global/operations"

    其中，PROJECT_ID 是您的 Cloud de Confiance 项目 ID。例如，my-project。

向服务代理授予权限

创建特征配置时，系统会为您的项目预配专用服务代理： Cloud de Confiance service-PROJECT_NUMBER@gcp-sa-autoannotate.s3ns-system.iam.gserviceaccount.com。

如需让此服务代理扫描您的存储桶、读取非结构化对象并附加丰富化元数据，您必须向其授予所需的 IAM 角色。

控制台

如果您在创建特征配置时选择了请在稍后手动提供授权权限 ，或者需要重新应用项目范围的权限，则可以在配置详情页面中授予权限：

  1. 在 Cloud de Confiance 控制台中，前往 Cloud Storage 对象丰富化 页面。

    前往“对象丰富化”

  2. 在配置名称 列中，点击特征配置的名称。

  3. 在操作栏中，点击授予权限 。

  4. 在授予权限 窗格中，点击授予项目范围的权限 。

    此操作会向服务代理授予项目的 Storage Annotation Generator Service (roles/storage.annotationGeneratorService) 和 Storage Bucket Viewer (roles/storage.bucketViewer) 角色。 在 Cloud de Confiance 控制台中授予项目范围的权限需要 对项目拥有 resourcemanager.projects.setIamPolicy 权限。

    如需在各个存储桶（而不是整个项目）上授予 roles/storage.annotationGeneratorService 角色，请使用 Google Cloud CLI。

命令行

  1. 在每个受监控的存储桶上或在项目级层向服务代理授予 Storage Annotation Generator Service (roles/storage.annotationGeneratorService) 角色：

    • 如需在特定 存储桶上授予该角色，请使用 gcloud storage buckets add-iam-policy-binding 命令：

      gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
    --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-autoannotate.s3ns-system.iam.gserviceaccount.com \
    --role=roles/storage.annotationGeneratorService

      其中：

      • BUCKET_NAME 是您要在其中授予权限的存储桶的名称。
      • PROJECT_NUMBER 是您的 Cloud de Confiance 项目编号。

    • 如需在项目中的所有 存储桶中授予该角色，请使用 gcloud projects add-iam-policy-binding 命令：

      gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-autoannotate.s3ns-system.iam.gserviceaccount.com \
    --role=roles/storage.annotationGeneratorService

      其中：

      • PROJECT_ID 是您的 Cloud de Confiance 项目 ID。
      • PROJECT_NUMBER 是您的 Cloud de Confiance 项目编号。

  2. 如需在项目级层授予 Storage Bucket Viewer (roles/storage.bucketViewer) 角色，以便服务代理可以检查存储桶 配置，请使用 gcloud projects add-iam-policy-binding 命令：

    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-autoannotate.s3ns-system.iam.gserviceaccount.com \
    --role=roles/storage.bucketViewer

    其中：

    • PROJECT_ID 是您的 Cloud de Confiance 项目 ID。
    • PROJECT_NUMBER 是您的 Cloud de Confiance 项目编号。

授予角色后，IAM 权限可能需要几分钟才能传播，然后异步处理才会开始。

列出所有特征配置

如需列出项目中的所有特征配置，请完成以下步骤：

控制台

  1. 在 Cloud de Confiance 控制台中，前往 Cloud Storage 对象丰富化 页面。

    前往“对象丰富化”

    配置 标签页会列出项目中的所有特征配置，包括其已启用的模型、处理位置、范围、存储桶过滤条件、创建日期和上次更新日期。

  2. 可选：如需过滤列表，请在过滤条件 字段中输入属性名称或值。

命令行

使用 gcloud alpha storage feature-configs list 命令：

gcloud alpha storage feature-configs list

JSON API

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

  2. 使用 cURL 向 JSON API 发送 featureConfigs.list 请求：

    curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Accept: application/json" \
  "https://storage.s3nsapis.fr/v2/projects/PROJECT_ID/locations/global/featureConfigs"

    其中，PROJECT_ID 是您的 Cloud de Confiance 项目 ID。例如，my-project。

查看特征配置详情

如需检查特定特征配置的模型、目标存储桶和处理位置，请完成以下步骤：

控制台

  1. 在 Cloud de Confiance 控制台中，前往 Cloud Storage 对象丰富化 页面。

    前往“对象丰富化”

  2. 在配置名称 列中，点击要检查的特征配置的名称。

    配置详情页面会显示配置名称、说明、范围、包含的存储桶、处理位置、已启用的模型、创建日期和上次更新日期。

命令行

使用 gcloud alpha storage feature-configs describe 命令：

gcloud alpha storage feature-configs describe FEATURE_CONFIG_ID

将 FEATURE_CONFIG_ID 替换为特征配置的 ID。

JSON API

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

  2. 使用 cURL 向 JSON API 发送 featureConfigs.get 请求：

    curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Accept: application/json" \
  "https://storage.s3nsapis.fr/v2/projects/PROJECT_ID/locations/global/featureConfigs/FEATURE_CONFIG_ID"

    其中：

    • PROJECT_ID 是您的 Cloud de Confiance 项目 ID。例如，my-project。
    • FEATURE_CONFIG_ID 是特征配置的 ID。例如，my-feature-config。

更新特征配置

您可以更新现有特征配置，以添加或移除机器学习模型、更改目标存储桶、修改处理位置或更新说明。

控制台

  1. 在 Cloud de Confiance 控制台中，前往 Cloud Storage 对象丰富化 页面。

    前往“对象丰富化”

  2. 在配置名称 列中，点击要更新的特征配置的名称。

  3. 在配置详情页面上，更新要更改的设置：

    • 如需更新说明，请点击 配置说明 旁边的 修改配置 说明。在修改说明 窗格中，更新说明 字段中的文本，然后点击保存 。
    • 如需更新存储桶范围，请点击 修改配置范围 旁边的 配置范围。在定义范围 步骤中，在存储桶名称 字段中添加或移除目标存储桶，然后点击继续 。在授予所需权限 步骤中，为服务代理选择一个权限选项，然后点击保存 。
    • 如需更新处理位置，请点击 修改配置 处理位置 旁边的 处理位置。在修改 处理位置 窗格中，从处理位置 菜单中选择一个多区域位置（美国、 欧洲 或 亚洲 ），然后 点击 保存 。
    • 如需更新已启用的模型，请点击 修改已启用配置的 模型 旁边的 已启用的模型 。在修改模型 窗格中，选中或取消选中要更新的模型的复选框，然后点击保存 。

命令行

使用 gcloud alpha storage feature-configs update 命令更新 说明、模型、处理位置或存储桶过滤条件：

gcloud alpha storage feature-configs update FEATURE_CONFIG_ID \
    --description="DESCRIPTION" \
    --auto-annotate-models=MODELS \
    --auto-annotate-processing-location=PROCESSING_LOCATION \
    --include-bucket-id-regexes=BUCKET_NAME

替换以下内容：

  • FEATURE_CONFIG_ID：您要更新的特征配置的 ID。
  • DESCRIPTION：特征配置的可选说明。例如，Scan invoices and receipts。
  • MODELS：要启用的机器学习模型的逗号分隔列表：face-detector、object-detector、label-detector、content-safety 或 pdf-classification。
  • PROCESSING_LOCATION：发生数据处理的多区域处理位置。有效值为 us、eu 或 asia。
  • BUCKET_NAME：要扫描的确切存储桶名称的逗号分隔列表。对象丰富化不支持通配符或正则表达式。如果您创建、重新创建或重定位存储桶，则必须更新此列表以包含这些存储桶。

JSON API

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

  2. 创建一个包含要更新的设置的 JSON 文件。 例如，如需更新说明、已启用的模型和目标存储桶：

    {
  "description": "DESCRIPTION",
  "autoAnnotateConfig": {
    "models": [
      { "name": "MODEL_NAME" }
    ],
    "processingLocation": "PROCESSING_LOCATION"
  },
  "filter": {
    "includedCloudStorageBuckets": {
      "bucketIdRegexes": [
        "BUCKET_NAME"
      ]
    }
  }
}

    其中：

    • DESCRIPTION 是特征配置的可选说明。例如，Scan invoices and receipts。

    • MODEL_NAME 是要包含的机器学习模型：face-detector、object-detector、label-detector、content-safety 或 pdf-classification。如需详细了解每个 模型及其输出架构，请参阅支持的模型和架构。如需启用多个模型，请向 models 数组添加其他模型对象。

    • PROCESSING_LOCATION 是发生数据处理的多区域处理位置。有效值为 us、eu 或 asia。

    • BUCKET_NAME 是要包含在扫描中的存储桶的确切名称。例如，my-bucket。 对象丰富化不支持正则表达式或通配符。如果您创建、重新创建或重定位存储桶，则必须更新此列表以包含这些存储桶。如需包含多个存储桶，请在 bucketIdRegexes 数组中指定其他存储桶名称字符串。

  3. 使用 cURL 向 JSON API 发送 featureConfigs.patch 请求：

    curl -X PATCH --data-binary @JSON_FILE_NAME \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  "https://storage.s3nsapis.fr/v2/projects/PROJECT_ID/locations/global/featureConfigs/FEATURE_CONFIG_ID?updateMask=UPDATE_MASK"

    其中：

    • JSON_FILE_NAME 是您在第 2 步中创建的 JSON 请求文件的本地路径。例如，update.json。
    • PROJECT_ID 是您的 Cloud de Confiance 项目 ID。例如，my-project。
    • FEATURE_CONFIG_ID 是要更新的特征配置的 ID。例如，my-feature-config。
    • UPDATE_MASK 是您要更新的字段的逗号分隔列表，例如 description,filter 或 autoAnnotateConfig.models。如需了解语法规则，请参阅 FieldMask。

删除特征配置

删除特征配置会阻止 Cloud Storage 为匹配的存储桶生成新的丰富化。删除配置不会删除已附加到存储对象的现有丰富化。

如需删除特征配置，请完成以下步骤：

控制台

  1. 在 Cloud de Confiance 控制台中，前往 Cloud Storage 对象丰富化 页面。

    前往“对象丰富化”

  2. 在配置名称 列中，点击要删除的特征 配置的名称，然后点击 删除 。

  3. 在确认对话框中，点击确认 。

命令行

使用 gcloud alpha storage feature-configs delete 命令：

gcloud alpha storage feature-configs delete FEATURE_CONFIG_ID

将 FEATURE_CONFIG_ID 替换为特征配置的 ID。

JSON API

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

  2. 使用 cURL 向 JSON API 发送 featureConfigs.delete 请求：

    curl -X DELETE \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Accept: application/json" \
  "https://storage.s3nsapis.fr/v2/projects/PROJECT_ID/locations/global/featureConfigs/FEATURE_CONFIG_ID"

    其中：

    • PROJECT_ID 是您的 Cloud de Confiance 项目 ID。例如，my-project。
    • FEATURE_CONFIG_ID 是要删除的特征配置的 ID。例如，my-feature-config。

后续步骤