存储空间分析数据集

<0x

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

如果您想深入了解导出到 BigQuery 的 Cloud Storage 资源，请使用存储空间分析数据集。这些数据洞见可帮助您进行数据探索、费用优化、安全措施执行和治理实施。存储空间分析数据集是一项专享功能，仅通过Storage Intelligence订阅提供。

概览

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

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

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

数据集配置属性

创建数据集配置时，您可以设置数据集的这些属性。配置数据集后，您最多可能需要等待 48 小时，才能在 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 表的位置（如果有）。

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

    创建数据集配置会为您预配服务代理。为了读取和写入数据集，必须向服务代理授予所需的权限。

    项目级服务代理可以访问和写入由项目中的所有数据集配置生成的数据集。例如，如果某个项目中有多个数据集配置，那么您只需向项目级服务代理授予所需权限一次，该代理便能够读取和写入项目内所有数据集配置的数据集。删除数据集配置时，不会删除项目范围的服务代理。

    配置范围的服务代理只能访问和写入由特定数据集配置生成的数据集。这意味着，如果您有多个数据集配置，则需要向每个配置范围的服务代理授予必需的权限。删除数据集配置时，系统会删除配置范围的服务代理。

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

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

支持的位置

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

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

元数据的数据集架构

以下各部分介绍了数据集中包含的元数据字段。如需详细了解 BigQuery 列模式，请参阅模式。列模式决定了 BigQuery 存储和查询数据的方式。

存储桶元数据

下表介绍了存储桶元数据字段：

元数据字段 模式 类型 说明
snapshotTime NULLABLE TIMESTAMP snapshotTime 字段以 RFC 3339 格式保存存储桶元数据快照的刷新时间。
name NULLABLE STRING 存储分区的名称。
location NULLABLE STRING 相应存储桶的位置。相应存储桶中对象的对象数据位于此位置内的物理存储空间中。
project NULLABLE INTEGER 相应存储桶所属项目的项目编号。
storageClass NULLABLE STRING 相应存储桶的默认存储类别。
public NULLABLE RECORD 已弃用。此字段用于指明存储桶是否可公开访问。请改用 iamConfiguration。
public.bucketPolicyOnly NULLABLE BOOLEAN 已弃用。此字段是 public 记录的一部分，用于指示是否启用了统一存储桶级访问权限，该权限可防止通过对象级 ACL 授予访问权限。
public.publicAccessPrevention NULLABLE STRING 已弃用。此字段是 public 记录的一部分，用于指明是否禁止公开访问相应存储桶。
autoclass NULLABLE RECORD 存储桶的 Autoclass 配置，启用后，该配置会根据对象的访问方式和时间控制对象的存储类别。
autoclass.enabled NULLABLE BOOLEAN Autoclass 是否处于启用状态。
autoclass.toggleTime NULLABLE TIMESTAMP 上次为此存储桶启用或停用 Autoclass 的时间，采用 RFC 3339 格式。
versioning NULLABLE BOOLEAN 相应存储桶是否已启用版本控制。如需了解详情，请参阅对象版本控制。
lifecycle NULLABLE BOOLEAN 相应存储桶是否具有生命周期配置。如需了解详情，请参阅生命周期管理。
metageneration NULLABLE INTEGER 相应存储桶的元数据生成。
timeCreated NULLABLE TIMESTAMP 相应存储桶的创建时间，采用 RFC 3339 格式。
tags NULLABLE RECORD 已弃用。此字段包含与相应存储桶关联的用户定义的键值对。请改用资源标记。
tags.lastUpdatedTime NULLABLE TIMESTAMP 已弃用。此字段是 tags 记录的一部分，用于指明上次更新标记的时间。
tags.tagMap REPEATED RECORD 已弃用。此字段是 tags 记录的一部分，包含标记键和值的映射。
tags.tagMap.key NULLABLE STRING 已弃用。此字段是 tags.tagMap 记录的一部分，表示标记的键。
tags.tagMap.value NULLABLE STRING 已弃用。此字段是 tags.tagMap 记录的一部分，表示标记的值。
labels REPEATED RECORD 用户提供的分桶标签，以键值对形式表示。
labels.key NULLABLE STRING 单个标签条目。
labels.value NULLABLE STRING 标签的值。
softDeletePolicy NULLABLE OBJECT 存储桶的软删除政策，用于定义存储桶中的对象在被删除后以软删除状态保留的时间段。处于软删除状态的对象无法永久删除，并且在 hardDeleteTime 之前可以恢复。
softDeletePolicy.effectiveTime NULLABLE DATETIME

软删除政策生效的日期时间，采用 RFC 3339 格式。

每当 softDeletePolicy.retentionDurationSeconds 增加时，系统都会更新 softDeletePolicy.effectiveTime。
softDeletePolicy.retentionDurationSeconds NULLABLE LONG 软删除的对象被保留且无法永久删除的时间段（以秒为单位）。该值必须大于或等于 604800（7 天）且小于 7776000（90 天）。该值也可以设置为 0，这会停用软删除政策。
iamConfiguration NULLABLE RECORD 存储桶的 IAM 配置。
iamConfiguration.uniformBucketLevelAccess NULLABLE RECORD 相应存储桶的统一存储桶级访问权限配置。
iamConfiguration.uniformBucketLevelAccess.enabled NULLABLE BOOLEAN 相应存储桶是否使用统一的存储桶级访问权限。
iamConfiguration.publicAccessPrevention NULLABLE STRING 相应存储桶的禁止公开访问状态，为 "inherited" 或 "enforced"。
resourceTags REPEATED RECORD 相应存储桶的标记。如需了解详情，请参阅 Cloud Resource Manager API。
resourceTags.key NULLABLE STRING 资源标记键。
resourceTags.value NULLABLE STRING 资源标记值。
totalSize NULLABLE INTEGER 相应分桶的大小（以字节为单位）。
objectCount NULLABLE INTEGER 相应存储桶中的对象总数。

对象元数据

下表介绍了对象元数据字段：

元数据字段 模式 类型 说明
snapshotTime NULLABLE TIMESTAMP snapshotTime 字段以 RFC 3339 格式保存对象元数据快照的刷新时间。
bucket NULLABLE STRING 包含相应对象的存储桶的名称。
location NULLABLE STRING 相应存储桶的位置。相应存储桶中对象的对象数据位于此位置内的物理存储空间中。
componentCount NULLABLE INTEGER 仅针对复合对象返回。复合对象中非复合对象的数量。componentCount 包含用于组合当前对象的任何复合对象中包含的非复合对象。
contentDisposition NULLABLE STRING 对象数据的 Content-Disposition。
contentEncoding NULLABLE STRING 对象数据的 Content-Encoding。
contentLanguage NULLABLE STRING 对象数据的 Content-Language。
contentType NULLABLE STRING 对象数据的 Content-Type。
crc32c NULLABLE INTEGER CRC32c 校验和（如 RFC 4960 附录 B 中所述），使用 base64 以 big-endian 字节顺序编码。
customTime NULLABLE TIMESTAMP 用户指定的对象时间戳，采用 RFC 3339 格式。
etag NULLABLE STRING 对象的 HTTP 1.1 实体标记。
eventBasedHold NULLABLE BOOLEAN 对象是否受基于事件的保全保护。
generation NULLABLE INTEGER 相应对象的内容生成。
md5Hash NULLABLE STRING 数据的 MD5 哈希，使用 base64 编码。对于复合对象，此字段不存在。
metadata REPEATED RECORD 用户提供的元数据，以键值对的形式呈现。
metadata.key NULLABLE STRING 单个元数据条目。
metadata.value NULLABLE STRING 元数据值。
metageneration NULLABLE INTEGER 相应世代的此对象的元数据版本。
name NULLABLE STRING 对象的名称。
size NULLABLE INTEGER 数据的 Content-Length（以字节为单位）。
storageClass NULLABLE STRING 对象的存储类别。
temporaryHold NULLABLE BOOLEAN 相应对象是否受临时冻结约束。
timeCreated NULLABLE TIMESTAMP 对象的创建时间，采用 RFC 3339 格式。
timeDeleted NULLABLE TIMESTAMP 对象的删除时间，采用 RFC 3339 格式。
updated NULLABLE TIMESTAMP 对象元数据的修改时间，采用 RFC 3339 格式。
timeStorageClassUpdated NULLABLE TIMESTAMP 对象的存储类别上次更改的时间。
retentionExpirationTime NULLABLE TIMESTAMP 可以删除对象的最早时间，取决于为对象设置的任何保留配置以及为包含该对象的存储桶设置的任何保留政策。retentionExpirationTime 的值以 RFC 3339 格式提供。
softDeleteTime NULLABLE DATETIME 对象被软删除的时间。仅适用于具有软删除政策的存储分区中的对象。
hardDeleteTime NULLABLE DATETIME 软删除的对象被永久删除且无法再恢复的时间。该值是 softDeleteTime 值与相应存储桶的 softDeletePolicy.retentionDurationSeconds 值之和。仅适用于具有软删除政策的存储分区中的对象。
project NULLABLE INTEGER 相应存储桶所属项目的项目编号。

最新的存储桶和对象元数据快照

关联的数据集通过以下专用视图公开了存储桶和对象元数据的最新快照：

  • bucket_attributes_latest_snapshot_view 可提供 Cloud Storage 存储分区的最新元数据。其结构与 Bucket 元数据架构相匹配。

  • object_attributes_latest_snapshot_view 可为您的 Cloud Storage 对象提供最新的元数据。其结构与对象元数据架构相符。

项目元数据

项目元数据以关联数据集中的视图（名为 project_attributes_view）的形式公开：

元数据字段 模式 类型 说明
snapshotTime NULLABLE TIMESTAMP snapshotTime 字段以 RFC 3339 格式存储项目元数据快照的刷新时间。
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 刷新数据的来源位置。
globalManifest.snapshotTime NULLABLE TIMESTAMP 事件快照的刷新时间，采用 RFC 3339 格式。
eventTime NULLABLE STRING 相应事件发生的时间。
eventCode NULLABLE STRING 与相应条目关联的事件代码。事件代码 1 指的是 manifest.viewName 视图正在刷新，其中包含快照 manifest.snapshotTime 中来源位置 manifest.location 的所有条目。事件代码 2 表示数据集已刷新，其中包含所有来源位置的存储桶和对象条目。此刷新发生在快照 globalManifest.snapshotTime 中。

错误代码

您可以在关联数据集的 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 源项目未配置Storage Intelligence。 源项目 projectErrorRecord.projectNumber 未配置Storage Intelligence。 为源项目 projectErrorRecord.projectNumber 配置Storage Intelligence。如需了解详情，请参阅配置和管理Storage Intelligence。
5 存储桶未配置Storage Intelligence。 存储桶 bucketErrorRecord.bucketName 未配置Storage Intelligence。 为存储桶 bucketErrorRecord.bucketName 配置 Storage Intelligence。如需了解详情，请参阅配置和管理Storage Intelligence。

注意事项

请考虑以下数据集配置：

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

  • 数据集仅在以下 BigQuery 位置中受支持。

后续步骤