排查 Storage Intelligence 问题

本文档介绍了如何排查与存储空间分析情报、存储空间分析资产清单报告、存储空间分析数据集、对象丰富（预览版）和存储空间批量操作相关的常见问题。

Storage Intelligence 配置错误

以下部分介绍了在为资源配置或管理 Storage Intelligence时可能遇到的错误。

400：存储桶名称无效

问题：请求返回 400 Bad Request，并显示消息 The specified bucket is not valid.

解决方案：请求无效。确保请求满足以下要求：

  • 使用 locations/global。Storage Intelligence 不支持其他位置。
  • 确保 bucket_id_regexes 中的存储桶名称或正则表达式有效。

以下是有效请求的示例：

curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{
      "edition_config": "STANDARD",
      "filter": {
        "included_cloud_storage_buckets": {
          "bucket_id_regexes": [
            "my-bucket-name",
            "prod-data-.*"
          ]
        }
      }
    }' \
    "https://storage./v2/projects/PROJECT_ID/locations/global/intelligenceConfig?updateMask=edition_config,filter"

400：参数无效 - 更新掩码为空

问题：当您发送配置或更新请求时，请求会返回 400 Bad Request，并显示消息 Empty UPDATE_MASK in the request.

解决方案：在请求中提供非空 UPDATE_MASK。UPDATE_MASK 指定 IntelligenceConfig 资源中要更新的 FieldMask 字段的逗号分隔列表（例如 updateMask=edition_config 或 updateMask=edition_config,filter）。

400：更新掩码路径无效

问题：更新配置时，请求返回 400 Bad Request，并显示消息 Invalid UPDATE_MASK paths.

解决方案：验证 UPDATE_MASK 中的每个字段名称是否与 IntelligenceConfig 资源中的有效字段相匹配。

400：字段不可修改

问题：更新配置时，请求返回 400 Bad Request，并显示消息 Invalid UPDATE_MASK: UPDATE_TIME field is not editable.

解决方案：从 UPDATE_MASK 中移除不可修改的系统字段（例如 UPDATE_TIME）。仅指定在 IntelligenceConfig 中定义的可变字段。

400：值无效

问题：请求返回 400 Bad Request，并显示消息 Invalid value at storage_intelligence.edition_config.

解决方案：将 edition_config 设置为支持的值：INHERIT、STANDARD 或 DISABLED。

400：非空过滤条件

问题：请求返回 400 Bad Request，并显示消息 Non-empty filter cannot be specified for INHERIT or DISABLED edition configuration.

解决方案：从请求中移除分桶过滤条件。当 edition_config 设置为 INHERIT 或 DISABLED 时，不支持存储桶过滤条件。

400：过滤条件中的位置或存储桶值为空

问题：请求返回 400 Bad Request，并显示消息 Empty location or bucket values in filter.

解决方案：确保 存储桶过滤条件中的 location 和 bucket 都不是空字符串。

存储空间分析常见问题

本部分介绍了如何解决资产清单报告和数据集的常见问题。

每天生成多个资产清单报告

问题：资产清单报告配置每天生成多个报告文件。

解决方案：对于包含超过 100 万个对象的存储桶，Cloud Storage 会对资产清单报告进行分片，每 100 万个对象生成一个分片。例如，包含 350 万个对象的存储桶会生成 4 个报告分片和一个列出每个分片的清单文件。

资产清单报告未显示在目标存储桶中

问题：资产清单报告未显示在目标存储桶中。

解决方案：如果报告未传送到目标存储桶，请验证以下内容：

  • 确保配置的开始日期已过。如需了解详情，请参阅创建资产清单报告配置。

  • 查看资产清单报告历史记录，以检查是否存在失败及其根本原因。如需查看资产清单报告历史记录，请完成以下步骤：

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

      进入“存储桶”

    2. 在存储桶列表中，点击包含资产清单报告配置的源存储桶的名称。

    3. 在存储桶详细信息页面上，点击库存报告标签页。

    4. 在资产清单报告配置列表中，点击生成您要检查的报告的资产清单报告配置的 UUID。

    5. 在资产清单报告历史记录部分中检查失败情况。将指针悬停在帮助 () 上，即可详细了解失败的原因。

  • 确保向项目级层服务代理授予读取和写入资产清单报告所需的 IAM 角色。如需了解详情，请参阅向服务代理授予所需的角色。

广告资源报告延迟

问题：资产清单报告生成延迟。

解决方案：报告生成时间各不相同。延迟最多 24 小时属于正常情况。

数据集未填充

问题：存储空间分析数据集表仍然为空。

解决方案：在关联的 BigQuery 数据集中，检查 error_attributes_view 是否有错误代码。如需了解详情，请参阅排查数据集错误。

查询数据集时“ref”列中的 null 值

问题：在 BigQuery 中查询存储空间分析数据集时，ref 列会返回 null。

解决方案：对于以 / 结尾的对象，数据集中的 ref 列为空。

如果您在 BigQuery 中查询存储空间分析数据集时，ref 列返回 null 值，请验证您是否已授予所需的连接权限和角色，包括对 Cloud Storage 资源的访问权限，如使用 BigQuery 分析对象数据和元数据中所述。

对象丰富化错误

本部分介绍了如何解决在配置、生成或查询对象丰富化时遇到的常见问题。

对象缺少丰富化

问题：配置对象丰富化后，对象上不显示对象丰富化。

解决方案：验证以下内容：

  • 服务代理权限：确保向对象丰富化服务代理授予目标存储桶（或项目）的 roles/storage.annotationGeneratorService 角色以及项目的 roles/storage.bucketViewer 角色。如需查看相关说明，请参阅向服务代理授予权限。
  • 过滤条件和范围配置：确保 FeatureConfig 资源明确包含目标存储桶名称。Cloud Storage 不会自动包含在您创建 FeatureConfig 资源后创建的存储桶。此外，如果您删除并重新创建或重新定位存储桶，则必须更新 FeatureConfig 资源以重新包含该存储桶。
  • 模型前提条件和 Content-Type 元数据：验证对象是否符合已启用模型的内容类型和大小限制。Cloud Storage 会使用对象的 Content-Type 元数据字段来确定资格（对于图片，为 BMP、GIF、ICO、JPEG、PNG、TIFF 或 WEBP；对于 PDF 分类，为 application/pdf）。如果 Content-Type 元数据缺失或不正确，Cloud Storage 将不会处理相应对象，直到您更新其元数据为止。此外，对象丰富化服务会跳过大于 20 MiB 的对象。如需了解详情，请参阅支持的模型和架构。
  • 处理延迟时间：为异步处理预留足够的时间。 对象丰富化服务会异步处理对象。新上传对象的丰富化数据通常会在几个小时内显示。相比之下，回填大型存储桶中的现有对象可能需要数小时或数天。

BigQuery 中未显示对象丰富化

问题：对象丰富化数据出现在 API 中，但未出现在 BigQuery 中。

解决方案：检查以下各项：

  • Storage Insights 数据集配置：验证您是否已为存储桶配置存储空间分析。
  • 每日报告时间表：等待每日数据集更新。 存储空间分析数据集每 24 小时更新一次。因此，新生成的丰富数据最多可能需要 24 小时才会显示在 BigQuery 的 object_contexts_catalog_view 视图中。
  • IAM 权限：确保您有权在 BigQuery 中运行作业和读取数据（例如 roles/bigquery.jobUser 和 roles/bigquery.dataViewer）。如需查询指导，请参阅在 BigQuery 中分析对象丰富化。

检索扩展对象丰富化数据时权限遭拒

问题：检索扩展对象丰富化数据时发生权限错误。

解决方案：您必须拥有对象或存储桶的 storage.objects.viewFullContext 权限才能检索扩展数据，例如边界框坐标或类别置信度得分。Storage Object User (roles/storage.objectUser) 和 Storage Admin (roles/storage.admin) 等角色包含此权限。如需了解详情，请参阅管理对象丰富化。

管理功能配置时权限遭拒

问题：创建、更新或删除 FeatureConfig 时出现权限错误。

解决方案：验证您的账号是否在目标项目上拥有 Storage Admin (roles/storage.admin) 角色或具有必要权限的自定义角色。这些必需权限包括 storage.featureConfigs.create、storage.featureConfigs.update 或 storage.featureConfigs.delete。如需了解特定于方法的权限，请参阅配置对象丰富化和 featureConfigs API 资源。

存储批量操作作业验证错误

本部分介绍了向 storagebatchoperations.googleapis.com 提交批量操作作业请求时发生的验证错误。

400：任务 ID 或资源名称无效

问题：作业创建请求返回 400 Bad Request (INVALID_ARGUMENT) 响应，原因为 JOB_ID_INVALID 或 RESOURCE_NAME_TOO_LONG。

解决方案：验证任务 ID 是否由 1-63 个小写字母数字字符或连字符 ([a-z0-9]([-a-z0-9]*[a-z0-9])?) 组成，以及完整作业资源路径 (projects/PROJECT_ID/locations/LOCATION/jobs/JOB_ID) 是否不超过 200 字节。如果路径超过 200 字节，请缩短任务 ID。如需了解详情，请参阅作业名称。

400：职位描述超出限制

问题：作业创建请求返回 400 Bad Request (INVALID_ARGUMENT) 响应，原因 DESCRIPTION_TOO_LONG。

解决方案：确保作业说明不超过 1,024 字节。如果超出此限制，请缩短文本。如需了解详情，请参阅作业说明。

400：作业来源配置缺失或无效

问题：作业创建请求返回 400 Bad Request (INVALID_ARGUMENT) 响应，原因如下：

  • SOURCE_NOT_SPECIFIED
  • BUCKET_LIST_EMPTY
  • TOO_MANY_BUCKETS
  • MULTI_BUCKET_NOT_SUPPORTED
  • BUCKET_NAME_REQUIRED
  • OBJECT_CONFIGURATION_REQUIRED

解决方案：确保您的作业指定了有效的来源配置（bucket_list 或 project_source），并且每个存储桶都定义了对象选择方法。如需了解详情，请参阅创建和管理批量操作作业。

400：存储桶或对象名称无效

问题：作业创建请求返回 400 Bad Request (INVALID_ARGUMENT) 响应，原因为 BUCKET_NAME_INVALID 或 OBJECT_NAME_INVALID。

解决方案：确保所有存储桶和对象名称都符合 Cloud Storage 命名要求。如需了解详情，请参阅存储桶命名准则和对象命名准则。

400：项目来源配置错误

问题：作业创建请求返回 400 Bad Request (INVALID_ARGUMENT) 响应，原因如下：

  • PROJECT_SOURCE_PROJECT_INVALID
  • PROJECT_SOURCE_DRY_RUN_FIELDS_EXCLUSIVE
  • PROJECT_SOURCE_DRY_RUN_ID_INVALID

解决方案：验证您的项目来源配置是否符合格式和字段排他性要求。如果您指定试运行任务 ID，请省略所有其他 project_source 参数。如需了解详情，请参阅使用高级过滤条件创建作业。

400：转换参数冲突或缺失

问题：作业创建请求返回 400 Bad Request (INVALID_ARGUMENT) 响应，原因如下：

  • TRANSFORMATION_NOT_SPECIFIED
  • REWRITE_OBJECT_MISSING_PARAMETERS
  • PUT_OBJECT_HOLD_MISSING_PARAMETERS
  • PUT_METADATA_MISSING_PARAMETERS

解决方案：指定一种转换类型，并提供所有必需参数。如果配置对象保留，请验证是否已在存储桶上启用对象锁定，以及时间戳是否使用 RFC 3339 UTC 格式。如需详细了解不同转换的参数要求，请参阅服务类型。

400：对象前缀重叠或重复

问题：作业创建请求返回 400 Bad Request (INVALID_ARGUMENT) 响应，原因代码为 OBJECT_PREFIX_OVERLAP 或 DUPLICATE_OBJECT_PREFIX。

解决方案：移除重复的前缀，并确保 included_object_prefixes 中的任何前缀都不是列表中其他条目的前缀。如需了解详情，请参阅对象前缀。

400：清单文件格式和访问权限问题

问题：作业创建请求返回 400 Bad Request (INVALID_ARGUMENT) 响应，原因为 MANIFEST_LOCATION_REQUIRED 或 MANIFEST_LOCATION_INVALID，或者作业无法读取清单。

解决方案：验证清单 URI 是否为有效的 CSV 路径 (gs://<bucket_name>/<path>/<object_name>.csv)，以及存储批量操作服务代理是否对清单存储桶具有 roles/storage.objectViewer 角色。如需详细了解 CSV 格式和架构要求，请参阅清单。

400：存储空间分析数据集发现错误

问题：使用存储空间分析数据集进行对象发现会返回 400 Bad Request（INVALID_ARGUMENT 或 FAILED_PRECONDITION）响应，原因如下：

  • BUCKET_DISCOVERY_SNAPSHOT_TOO_OLD
  • TARGET_LOCATIONS_REQUIRED_FOR_SNAPSHOT_TIME
  • BUCKET_DISCOVERY_TOO_MANY_BUCKETS

解决方案：验证 snapshot_time 是否在过去 48 小时内，为存储桶指定 target_locations，并确保发现查询匹配的存储桶不超过 1,000 个。如需了解详情，请参阅使用存储空间分析数据集创建清单。

400：在启用了 Autoclass 的存储桶上，存储类别转换失败

问题：作业创建请求返回 400 Bad Request (FAILED_PRECONDITION) 响应，原因为 AUTOCLASS_STORAGE_CLASS_TRANSFORMATION_UNSUPPORTED。

解决方案：您无法在启用了 Autoclass 的存储桶上运行存储类别转换。请定位到未启用 Autoclass 的存储桶，或移除存储类别转换。如需了解详情，请参阅 Autoclass 限制。

400：在启用统一存储桶级访问权限的存储桶上，对象 ACL 更新失败

问题：作业创建请求返回 400 Bad Request (FAILED_PRECONDITION) 响应，原因是 UBLA_OBJECT_ACL_UPDATE_UNSUPPORTED。

解决方案：您无法在启用了统一存储桶级访问权限的存储桶上更新对象 ACL。请改为在存储桶或项目级层使用 IAM 角色管理访问权限。如需了解详情，请参阅统一存储桶级访问权限。

存储批量操作运行时和执行问题

本部分介绍了在批量操作作业异步执行期间发生的问题。

403：执行期间出现权限错误

问题：批量作业在执行期间失败，并显示 403 Forbidden (PERMISSION_DENIED)。

解决方案：向存储批量操作服务代理 (service-PROJECT_NUMBER@gcp-sa-storagebatchoperations.) 授予您的转换类型所需的 IAM 角色。如需了解详情，请参阅向服务代理授予权限。

对象重写期间的 CMEK 加密错误

问题：由于 Cloud KMS 密钥状态或权限错误，对象重写失败，并显示 400 Bad Request 或 403 Forbidden。

解决方案：验证 Cloud KMS 密钥是否为 Enabled 且与目标存储桶位于同一区域，以及服务代理是否具有 roles/cloudkms.cryptoKeyEncrypterDecrypter 角色。如需了解详情，请参阅服务类型：重写对象。

error_summaries 中的失败次数较高

问题：批量作业完成，但 counters.failed_object_count 不为零，且 error_summaries 中包含错误代码（例如 404 NOT_FOUND、412 FAILED_PRECONDITION 或 403 PERMISSION_DENIED）。

解决方案：运行带有 --location 标志的 gcloud storage batch-operations jobs describe（例如 gcloud storage batch-operations jobs describe JOB_ID --location=LOCATION），以查看汇总的错误细分，并查看 Cloud Logging 以获取每个对象的错误日志。如需了解详情，请参阅获取作业详细信息。

存储批量操作作业因快照已超过两天而失败

问题：创建基于 CEL 过滤器的存储批量操作作业时，作业创建失败。出错提示指出快照时间早于两天。

解决方案：为防止对过时的对象状态执行操作，存储批量操作会自动使作业创建失败。如果所选快照的创建时间超过两天，则会发生此故障。请选择以下任一方法来解决此问题：

  • 使用清单文件：在 BigQuery 中手动查询数据集。将结果导出到 CSV 清单文件，并将该文件上传到 Cloud Storage 存储桶。然后，您可以使用清单方法创建批量操作作业，以避免两天的时间限制。
  • 检查数据集配置：验证您的数据集配置是否处于有效状态，且未被暂停。确认数据集快照已成功运行。如需了解如何验证配置，请参阅查看数据集配置。
  • 使用目标位置和快照时间替换：指定 --target-snapshot-time 标志，通过明确选择 RFC 3339 格式的快照来绕过两天过时故障。指定 --target-locations 标志，以将操作限制为快照所在的地理位置。您可以使用这些替换设置来解决导致自动全局快照无法更新的同步延迟问题。因此，您可以手动定位到较新的区域级快照。如需了解命令语法，请参阅使用高级过滤器创建作业。

基于 CEL 过滤器的存储批量操作作业在新订阅的项目中失败

问题：在新订阅的项目上运行基于 CEL 过滤条件的存储批量操作作业失败，因为系统找不到有效的快照。

解决方案：启用 Storage Intelligence 订阅后，您必须等待 24 小时才能运行基于 CEL 过滤器的存储批量操作作业。此延迟可让系统执行初始元数据快照并确定起始快照时间。

基于 CEL 过滤器的存储批量操作作业失败并显示权限错误或抛出运行时错误

问题：基于 CEL 过滤器的存储批量操作作业在执行期间失败或返回运行时权限错误。

解决方案：存储批量操作会使用您的用户凭证来处理对象。如果您对目标存储桶和对象没有必要的 IAM Reader 或 Writer 权限，则作业会失败。如果您的 CEL 过滤条件选择的资源是您无权访问的资源，就会出现此问题。确认您的账号对作业范围内的所有存储桶和对象具有 Storage Admin (roles/storage.admin)、Storage Object Admin (roles/storage.objectAdmin) 或同等角色。如需了解如何授予角色，请参阅使用 IAM 权限。

监控和日志分析

如需详细了解如何在 Cloud Logging 中检查每个对象的执行失败情况和错误载荷，请参阅查看存储批量操作日志。

Storage Intelligence Advisor 问题

本部分提供有关如何解决使用 Storage Intelligence 顾问时遇到的常见问题的指南。

Storage Intelligence Advisor 权限遭拒错误

问题：访问 Storage Intelligence Advisor 时收到 Permission denied 错误，并且图表和指标为空或显示权限错误。

解决方案：如果您没有具备查看 Storage Intelligence Advisor 所需权限的 IAM 角色，就会出现此问题。请让管理员为您授予您要查看的项目、文件夹或组织的 Storage Admin (roles/storage.admin) 角色。如需查看所需权限的列表，请参阅所需角色。

权限不足，无法查看受影响的项目

问题：当您在组织或文件夹级层查看发现结果时，“检测到发现结果的项目”面板会在项目旁边显示一条警告指示器，其中包含消息 You've insufficient permission to access this project。

解决方案：如果您拥有在组织级或文件夹级查看 Storage Intelligence 顾问的权限，但缺少相应特定项目的必需 IAM 权限，则会发生此问题。请让项目管理员为您授予受影响项目的 Storage Admin (roles/storage.admin) 角色。

Storage Intelligence Advisor 为空或缺少数据

问题：Storage Intelligence Advisor 网页加载后，概览部分（根据所选资源，标记为项目概览、文件夹概览或组织概览）或主要发现结果部分中的图表和指标为空，或者数据已过时。

解决方案：出现此问题的原因如下：

  • 数据处理延迟时间：Storage Intelligence 指标和分析结果依赖于存储空间用量的每日快照和分析。数据可能需要 24 到 48 小时才会显示在 Storage Intelligence Advisor 中。此类延迟通常发生在您创建新存储桶后，或您首次查看 Storage Intelligence Advisor 时。如果您希望看到近期活动数据，请等待 48 小时，然后再次查看。
  • 无存储资源：如果所选项目、文件夹或组织在所选时间段内不包含任何存储桶或对象，则 Storage Intelligence Advisor 为空。选择包含存储资源的其他项目、文件夹或组织。
  • 时间过滤条件不正确：时间过滤条件设置的范围没有发生任何存储活动。将时间过滤条件调整为包含存储活动的时间范围。

发现结果未显示在 Storage Intelligence Advisor 中

问题：您希望根据近期的存储活动在热门发现部分中看到发现结果，但该部分为空。

解决方案：如果 Storage Intelligence 智能助理未针对所选时间段生成任何发现结果，就会出现此问题。未发现结果可能是由于以下原因造成的：

  • 未发现匹配的模式：最新分析周期未检测到与发现结果模式相符的存储行为。
  • 数据处理延迟：调查结果依赖于存储空间指标，而这些指标需要 24 到 48 小时才能处理完毕。在下一个处理周期完成后，系统会显示过去 24 小时内发生的事件的发现结果。

使用 VPC Service Controls 时出现的问题

问题：当您尝试从 VPC Service Controls 服务边界内的项目访问 Storage Intelligence Advisor 时，收到“访问遭拒”或权限错误。

解决方案：如果 VPC Service Controls 未正确配置，无法在您的项目、 Google Cloud 控制台和 Storage Intelligence 资源之间进行通信，就会出现此问题。如需解决此问题，请查看以下要求：

  • 受限服务：验证服务边界是否限制了 Cloud Storage API (storage.googleapis.com) 和存储空间分析 (storageinsights.googleapis.com) API。如需了解详情，请参阅列出和描述服务参数。
  • 边界配置：验证您用于查看 Storage Intelligence 顾问的项目是否与您监控的项目位于同一服务边界内。如果它们位于不同的边界内，您必须配置入站流量和出站流量规则或使用边界桥。
  • 从边界外部进行访问：如果您从边界外部的网络访问 Google Cloud 控制台，则必须创建入站规则或访问权限级别，其中包含您的用户账号和您正在使用的公共 IP 地址范围。
  • 共享 VPC：如果您使用共享 VPC，请验证该项目是否与您的服务项目位于同一服务边界内。如需了解详情，请参阅共享 VPC。
  • 审核日志：使用违规分析器检查审核日志中是否存在 VPC Service Controls 违规情况。违规分析器可帮助诊断违规行为并找出原因，例如 RESOURCES_NOT_IN_SAME_SERVICE_PERIMETER 错误。

后续步骤