存储空间分析数据集

存储空间分析数据集功能可帮助您大规模了解、整理和管理数据。您可以选择一个组织，也可以选择一个或多个项目或文件夹，其中包含您要更新元数据的存储分区和对象。系统会将这些项目中包含的存储分区和对象的可查询元数据索引作为 BigQuery 关联数据集提供。

如果您想获取导出到 BigQuery 的 Cloud Storage 资源的分析数据，请使用 Storage Insights 数据集。这些数据分析有助于您进行数据探索、费用优化、强制执行安全措施和实现治理。存储空间分析数据集是一项专属功能，仅通过存储空间智能订阅即可使用。

概览

存储空间分析数据集是组织中一个或多个指定源项目中所有存储分区和对象的元数据的滚动快照。借助数据集提供的信息，您可以更好地了解 Cloud Storage 数据并定期对其进行审核。

如需创建数据集，您需要先在项目中创建数据集配置。您可以选择一个组织，也可以选择一个或多个项目或文件夹，其中包含您要查看元数据的存储分区和对象。数据集配置每天都会生成数据集。数据集配置和数据集都是存储在 Cloud Storage 中的资源。

如需查看数据集，您必须先将数据集关联到 BigQuery。

数据集配置属性

创建数据集配置时，您需要设置数据集的以下属性：

  • 名称：用于引用数据集的名称。名称将用作数据集配置的标识符，在配置创建后便无法更改。名称最多可包含 128 个字符，可使用字母、数字和下划线。名称必须以字母开头。

  • 说明（可选）：数据集的说明。您可以随时修改说明。

  • 数据集范围：包含您要获取元数据的存储分区和对象的组织、项目或文件夹。您可以单独指定项目或文件夹，也可以以 CSV 文件的形式指定，每个项目或文件夹编号单独占一行。您最多可以在一项数据集配置中指定 10,000 个项目或文件夹。

  • 存储分区过滤器（可选）：用于按存储分区名称或地区从数据集中包含和排除特定存储分区的过滤器。

  • 保留期限：数据集捕获和保留数据的天数，包括数据集的创建日期。数据集会每 24 小时更新一次元数据，并且最多可保留 90 天的数据。系统会自动删除在保留期限之外捕获的数据。例如，假设您有一个数据集，创建时间为 2023 年 10 月 1 日，保留期限设置为 30 天。10 月 30 日，数据集将反映过去 30 天（10 月 1 日至 10 月 30 日）的数据。10 月 31 日，数据集将反映 10 月 2 日至 10 月 31 日的数据。您可以随时修改留存期。

  • 位置：存储数据集及其数据的位置。例如 us-central1。位置必须受 BigQuery 支持。我们建议您选择 BigQuery 表的位置（如果有）。

  • 服务代理类型：配置级范围的服务代理或项目级范围的服务代理。

    创建数据集配置后，系统会为您预配服务代理。为了读取数据集，必须向服务代理授予从 Cloud Storage 存储分区读取数据所需的权限。

    项目级服务代理可以访问和写入根据项目中的所有数据集配置生成的数据集。例如，如果您在一个项目中有多种数据集配置，则只需向项目级服务代理授予一次必要权限，即可让其能够读取和写入项目中所有数据集配置的数据集。如需详细了解读取和写入数据集所需的权限，请参阅权限。删除数据集配置后，项目级服务代理不会被删除。

    配置级范围的服务代理只能访问和写入由特定数据集配置生成的数据集。也就是说，如果您有多个数据集配置，则需要向每个配置级范围的服务代理授予必需的权限。删除数据集配置后，配置级范围的服务代理也会被删除。

创建数据集配置后，将数据集关联到 BigQuery。将数据集关联到 BigQuery 会在 BigQuery 中创建一个关联的数据集，以便进行查询。您可以随时关联或解除关联数据集。

如需详细了解您在创建或更新数据集配置时设置的属性，请参阅 JSON API 文档中的 DatasetConfigs 资源。

支持的位置

以下 BigQuery 位置支持创建关联的数据集：

  • EU
  • US
  • asia-southeast1
  • europe-west1
  • us-central1
  • us-east1
  • us-east4

元数据的数据集架构

数据集包含以下元数据字段。如需详细了解 BigQuery 列模式，请参阅模式。列模式决定了 BigQuery 如何存储和查询数据。

snapshotTime 字段以 RFC 3339 格式存储存储分区元数据快照刷新的时间。

存储桶元数据

除非另有说明，否则您可以参阅适用于 JSON API 的存储分区资源表示法，详细了解以下存储分区元数据字段。

元数据字段 模式 类型
snapshotTime NULLABLE TIMESTAMP
name NULLABLE STRING
location NULLABLE STRING
project NULLABLE INTEGER
storageClass NULLABLE STRING
versioning NULLABLE BOOLEAN
lifecycle NULLABLE BOOLEAN
metageneration NULLABLE INTEGER
timeCreated NULLABLE TIMESTAMP
public NULLABLE RECORD
public.bucketPolicyOnly NULLABLE BOOLEAN
public.publicAccessPrevention NULLABLE STRING
autoclass NULLABLE RECORD
autoclass.enabled NULLABLE BOOLEAN
autoclass.toggleTime NULLABLE TIMESTAMP
softDeletePolicy NULLABLE OBJECT
softDeletePolicy.effectiveTime NULLABLE DATETIME
softDeletePolicy.retentionDurationSeconds NULLABLE LONG
tags* NULLABLE RECORD
tags.lastUpdatedTime NULLABLE TIMESTAMP
tags.tagMap REPEATED RECORD
tags.tagMap.key NULLABLE STRING
tags.tagMap.value NULLABLE STRING
labels REPEATED RECORD
labels.key NULLABLE STRING
labels.value NULLABLE STRING

* 存储分区的标记。 如需了解详情，请参阅 Cloud Resource Manager API。

对象元数据

除非另有说明，否则您可以参阅适用于 JSON API 的对象资源表示法，详细了解以下对象元数据字段。

元数据字段 模式 类型
snapshotTime NULLABLE TIMESTAMP
bucket NULLABLE STRING
location NULLABLE STRING
componentCount NULLABLE INTEGER
contentDisposition NULLABLE STRING
contentEncoding NULLABLE STRING
contentLanguage NULLABLE STRING
contentType NULLABLE STRING
crc32c NULLABLE INTEGER
customTime NULLABLE TIMESTAMP
etag NULLABLE STRING
eventBasedHold NULLABLE BOOLEAN
generation NULLABLE INTEGER
md5Hash NULLABLE STRING
metageneration NULLABLE INTEGER
name NULLABLE STRING
size NULLABLE INTEGER
storageClass NULLABLE STRING
temporaryHold NULLABLE BOOLEAN
timeCreated NULLABLE TIMESTAMP
timeDeleted NULLABLE TIMESTAMP
updated NULLABLE TIMESTAMP
timeStorageClassUpdated NULLABLE TIMESTAMP
retentionExpirationTime NULLABLE TIMESTAMP
softDeleteTime NULLABLE DATETIME
hardDeleteTime NULLABLE DATETIME
metadata REPEATED RECORD
metadata.key NULLABLE STRING
metadata.value NULLABLE STRING

项目元数据

项目元数据会在关联的数据集中显示为名为 project_attributes_view 的视图：

元数据字段 模式 类型
snapshotTime NULLABLE TIMESTAMP
name NULLABLE STRING
id NULLABLE STRING
number NULLABLE NUMBER

事件和错误的数据集架构

在关联的数据集中，您还可以在 events_view 和 error_attributes_view 视图中查看快照处理事件和错误。如需了解如何排查快照处理错误，请参阅排查数据集错误。

事件日志

您可以在关联的数据集中的 events_view 视图中查看事件日志：

列名 模式 类型 说明
manifest.snapshotTime NULLABLE TIMESTAMP 事件快照刷新的时间（采用 RFC 3339 格式）。
manifest.viewName NULLABLE STRING 已刷新的视图的名称。
manifest.location NULLABLE STRING 刷新的数据的来源位置。
eventTime NULLABLE STRING 事件发生的时间。
eventCode NULLABLE STRING 与相应条目关联的事件代码。事件代码 1 是指 manifest.viewName 视图会刷新，其中包含快照 manifest.snapshotTime 中来源位置 manifest.location 的所有条目。

错误代码

您可以在关联数据集中的 error_attributes_view 视图中查看错误代码：

列名 模式 类型 说明
errorCode NULLABLE INTEGER 与此条目关联的错误代码。如需查看有效值列表以及相应解决方法，请参阅排查数据集错误。
errorSource NULLABLE STRING 错误的来源。有效值：CONFIGURATION_PREPROCESSING。
errorTime NULLABLE TIMESTAMP 错误发生的时间。
sourceGcsLocation NULLABLE STRING 错误的来源 Cloud Storage 位置。对于项目，此字段为 null，因为项目没有位置信息。
bucketErrorRecord.bucketName NULLABLE STRING 与错误相关的存储分区的名称。您可以使用这些信息来调试存储分区错误。
bucketErrorRecord.serviceAccount NULLABLE STRING 需要有权从存储分区提取对象的服务账号。您可以使用这些信息来调试存储分区错误。
projectErrorRecord.projectNumber NULLABLE INTEGER 与错误相关的项目的编号。您可以使用这些信息调试项目错误。
projectErrorRecord.organizationName NULLABLE STRING 项目必须属于的组织的编号，否则我们将无法处理。值 0 表示数据集不在组织中。您可以使用这些信息调试项目错误。

排查数据集错误

如需了解如何排查记录到关联数据集中 error_attributes_view 视图中的快照处理错误，请参阅下表：

错误代码 错误用例 错误消息 问题排查
1 源项目不属于组织 源项目 projectErrorRecord.projectNumber 不属于组织 projectErrorRecord.organizationName。 将源项目 projectErrorRecord.projectNumber 添加到组织 projectErrorRecord.organizationName。如需了解如何在组织之间迁移项目，请参阅在组织之间迁移项目。
2 存储分区授权错误 无法为存储分区 bucketErrorRecord.bucketName 提取对象，因为权限被拒。 向服务账号 bucketErrorRecord.serviceAccount 授予 Identity and Access Management (IAM) 权限，以允许对存储分区 bucketErrorRecord.bucketName 提取对象。如需了解详情，请参阅向服务代理授予所需权限。
3 目标项目不属于组织 目标项目 projectErrorRecord.projectNumber 不属于组织 projectErrorRecord.organizationName。 将目标项目 projectErrorRecord.projectNumber 添加到组织 projectErrorRecord.organizationName。如需了解如何在组织之间迁移项目，请参阅在组织之间迁移项目。
4 来源项目未配置存储空间分析情报。 来源项目 projectErrorRecord.projectNumber 未配置存储空间分析情报。 为源项目 projectErrorRecord.projectNumber 配置存储空间分析情报。如需了解详情，请参阅配置和管理存储空间智能。
5 存储分区未配置存储空间分析情报。 存储分区 bucketErrorRecord.bucketName 未配置存储空间分析情报。 为存储分区 bucketErrorRecord.bucketName 配置存储空间分析情报。如需了解详情，请参阅配置和管理存储空间智能。

注意事项

请考虑以下数据集配置：

  • 当您重命名启用了分层命名空间的存储分区中的文件夹时，该存储分区中的对象名称也会更新。被关联数据集提取后，这些对象快照会被视为关联数据集中的新条目。

  • 只有以下 BigQuery 位置支持数据集。

后续步骤