您可以通过桶清单功能，定期获取桶内指定对象的相关信息，并保存到指定的存储桶中。本文介绍桶清单的使用场景及操作步骤。 ## 使用场景您可以通过桶清单功能，定期获取固定存储桶内所有或者指定前缀的对象信息，清单内容包括对象大小、存储类型、最后更新日期、Etag、分片上传状态及加密状态等。如果您需要列举的对象较多，建议您优先使用桶清单功能。 ## 权限说明 * 首次创建桶清单前，您需要通过 IAM，授予对象存储读取源存储桶所有文件和向目标存储桶写入文件的权限。建议您通过控制台授权，授权成功后，IAM 会自动生成 `TosArchiveTOSInventory` 角色，您可以登录 [IAM 控制台](https://console.volcengine.com/iam/identitymanage/role)查看。 :::warning 如果您因为业务需求设置了桶策略或 IAM 策略，请注意以下生成桶清单相关的 Action 没有被 Deny，否则可能会导致桶清单生成失败： * PutObject * CreateMultipartUpload * UploadPart * CompleteMultipartUpload * HeadObject * ListObjects * SetObjectMeta ::: * `TosArchiveTOSInventory` 角色默认没有访问 KMS 密钥的权限，如果您的存储桶配置了 SSE\-KMS 桶默认加密规则，创建桶清单前，您需要授予该角色 `KMSCryptoUserAccess` 的权限，否则将无法生成桶清单。 ## 清单文件说明 ### 文件格式创建桶清单后，TOS 会按照设置的参数生成对应清单。清单文件的名称如下所示。 ```json destinationPrefix/sourceBucketName/inventoryId/YYYY-MM-DDTHH-MMZ/files/UUID.csv.gz dest_bucket └──destinationPrefix/ └──sourceBucketName/ └──inventoryId/ ├──YYYY-MM-DDTHH-MMZ/ ├──files/ ├──7fd76a1c421391260a481a3405c6****_0.csv.gz ├──7fd76a1c421391260a481a3405c6****_1.csv.gz ├──8s5sda632dwa89s2das3dw9dsa2s****_0.csv.gz .... ├──manifest.json ├──manifest.checksum ``` 参数说明如下。 |**参数** |**说明** | |---|---| |destinationPrefix/ |创建桶清单时设置的报告前缀。如果创建时未设置，则默认为 `tos_bucket_inventory`。 | |sourceBucketName/ |清单文件对应的源存储桶。 | |inventoryId/ |桶清单规则名称。 | |YYYY\-MM\-DDTHH\-MMZ/ |生成清单文件时，开始扫描存储对象的时间信息，UTC 时间，格式为 `YYYY-MM-DDTHH-MMZ`。|\ | |:::tip|\ | ||\ | |* 在该时间之后上传的对象，不会记录在清单文件中。|\ | |* 在 2025\-07\-15 00:00:00 前创建且未修改的桶清单规则，其清单文件的命名格式为 YYYY\-MM\-DDTHH:MMZ，详细介绍，请参见[对象存储桶清单文件名称调整公告](/docs/6349/1567137)。|\ | ||\ | |:::| |files/ |保存对象清单文件的目录，默认为 `files/`。清单文件的格式为 `UUID.csv.gz`，默认为 `.csv.gz` 格式。|\ | |:::tip|\ | ||\ | |* 清单文件的详细说明，请参见[清单文件参数说明](/docs/6349/156080#fileschema)。|\ | |* 如果您导出的对象数据较多，为了便于您处理数据，TOS 会自动将清单文件分隔成多个小文件，文件命名按照 `UUID_0`、`UUID_1`依次递增。|\ | |* 一个 `files` 目录下 UUID 可能不唯一，即可能会出现`UUIDA_0`、`UUIDB_0`、`UUIDB_1`等多个文件。|\ | ||\ | |:::| |manifest.json |保存清单文件元数据及其他信息的文件。详细说明，请参见 [manifest.json](/docs/6349/156080#manifest-json)。 | |manifest.checksum |manifest.json 文件的 MD5 校验信息，例如 `79b1e0cbe3af7fdf127b91af601b****`。 | ### manifest.json `manifest.json` 文件示例及说明如下。 ```json { "creationTimestamp":"1672682400", "sourceBucket":"srctest", "destinationBucket":"destest", "fileFormat":"CSV", "fileSchema":"BucketName,ObjKey,Size,ETag,StorageClass,LastModifiedDate,IsMultipartUploaded,EncryptionStatus", "version":"2022-11-14", "files":[{ "Key":"tos_bucket_inventory/destest/srctest/2023-01-03T02-00Z/files/7fd76a1c421391260a481a3405c6****_0.csv.gz", "Size":619, "MD5checksum":"79b1e0cbe3af7fdf127b91af601b****", "InventoriedRecord":17 }] } ``` |**参数** ||**说明** | |---|---|---| |creationTimestamp ||Unix 时间戳，计量单位为秒，表示开始扫描源存储桶的时间。 | |sourceBucket ||清单文件对应的源存储桶。 | |destinationBucket ||存储清单文件的目的桶。 | |fileFormat ||清单文件的格式，默认为 `CSV`。 | |fileSchema ||清单文件包含的对象信息。详细说明，请参见 [fileSchema](/docs/6349/156080#fileschema)。 | |version ||清单文件的版本号。 | |files |Key |清单文件的完整路径及名称。 | |^^|Size |清单文件大小，单位为 Byte。 | |^^|MD5checksum |清单文件的 MD5 校验信息。 | |^^|InventoriedRecord |清单文件中包含的记录数量。 | ### fileSchema fileSchema 文件示例如下。 ![图片](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/bc9969dadb104eaca0c3d5fca2bb4792~tplv-goo7wpa0wc-image.image =814x) fileSchema 文件不包含参数名称，图中参数名称仅供参考，详细参数说明如下： |**参数** |**是否可选** |**说明** | |---|---|---| |BucketName |必选 |清单文件对应的源存储桶名称。 | |ObjKey |必选 |存储桶中对象的名称。|\ | | |:::tip|\ | | |对象名称采用 URL 编码，您必须解码后方可使用。|\ | | ||\ | | |:::| |VersionId |必选 |对象的版本 ID。|\ | | |:::tip|\ | | |仅当存储桶开启版本控制功能，且创建桶清单时对象版本选择所有版本时，才会导出该信息。|\ | | ||\ | | |:::| |IsLatest |必选 |对象版本是否为最新版本。取值说明如下：|\ | | ||\ | | |* **TRUE**：对象为最新版本|\ | | |* **FALSE**：对象为历史版本。|\ | | ||\ | | |:::tip|\ | | |仅当存储桶开启版本控制功能，且创建桶清单时对象版本选择所有版本时，才会导出该信息。|\ | | ||\ | | |:::| |IsDeleteMarker |必选 |对象版本是否为删除标记。取值说明如下：|\ | | ||\ | | |* **TRUE**：版本为删除标记。|\ | | |* **FALSE**：版本不是删除标记。|\ | | ||\ | | |:::tip|\ | | |仅当存储桶开启版本控制功能，且创建桶清单时对象版本选择所有版本时，才会导出该信息。|\ | | ||\ | | |:::| |Size |可选 |对象大小，单位为字节。 | |ETag |可选 |对象的 ETag。 | |StorageClass |可选 |对象的存储类型。取值说明如下：|\ | | ||\ | | |* **STANDARD**：标准存储。|\ | | |* **IA**：低频访问存储。|\ | | |* **INTELLIGENT_TIERING**：智能分层存储。|\ | | |* **ARCHIVE_FR**：归档闪回存储。|\ | | |* **ARCHIVE**：归档存储。|\ | | |* **COLD_ARCHIVE**：冷归档存储。|\ | | |* **DEEP_COLD_ARCHIVE**：深度冷归档存储。 | |IntelligentTieringAccessTier |可选 |智能分层对象所属的层级。取值说明如下：|\ | | ||\ | | |* **高频访问层**：FREQUENT|\ | | |* **低频访问层**：INFREQUENT|\ | | |* **归档闪回访问层**： ARCHIVEFR | |LastModifiedDate |可选 |对象的最后更新日期，Unix 时间戳格式，计量单位为秒。 | |IsMultipartUploaded |可选 |对象的分片上传状态。取值说明如下：|\ | | ||\ | | |* **TRUE**：是分片上传。|\ | | |* **FALSE**：不是分片上传。 | |EncryptionStatus |可选 |对象的加密状态。取值说明如下：|\ | | ||\ | | |* **TRUE**：已加密。|\ | | |* **FALSE**：未加密。 | |CRC64 |可选 |对象的 CRC64 值，常用于数据一致性的校验。更多信息，请参见[校验数据一致性概述](/docs/6349/136729)。 | |ReplicationStatus |可选 |对象的跨区域复制或同区域复制状态，存在以下情况：|\ | | ||\ | | |* 如果该对象是跨区域复制或同区域复制的源对象，则对象的复制状态取值说明如下：|\ | | | * **COMPLETE**：复制完成。|\ | | | * **PENDING**：等待复制中。|\ | | | * **FAILED**：复制失败。|\ | | ||\ | | |:::tip|\ | | |查看跨区域复制和同区域复制源对象的复制状态功能目前处于邀测状态，如您需要使用该功能，请联系客户经理。|\ | | ||\ | | |:::|\ | | |* 如果该对象是跨区域复制或同区域复制的目标对象，则会显示 **REPLICA**，表示该对象是被复制的对象。|\ | | |* 如果该对象不是跨区域复制或同区域复制的源对象或目标对象，则会显示为空。 | |Tag |可选 |对象标签，格式为 `key1#value1;key2#value2;`。|\ | | |:::tip|\ | | |对象标签 key 和 value 采用 URL 编码，您必须解码后方可使用。|\ | | ||\ | | |:::| |RetentionMode |可选 |对象的保留策略模式，取值说明如下：|\ | | ||\ | | |* **COMPLIANCE**：合规模式。|\ | | |* **NONE**：该对象未设置保留策略。 | |RetainUntilTimestamp |可选 |对象的保留到期时间，Unix 时间戳格式，计量单位为秒， | ## 注意事项 |**限制项** |**说明** | |---|---| |计费 |使用桶清单时，需要收取 API 请求费用和清单文件的存储容量费用。计费详情，请参见[计费概述](/docs/6349/78455)。 | |桶清单数量 |每个存储桶最多可以配置 10 条桶清单。 | |桶清单参数 |* 创建桶清单的源存储桶和保存清单文件的目标存储桶不需要相同，但必须属于相同账号下的相同地域。|\ | |* 桶清单目前仅支持选择所有对象或者指定前缀的对象。|\ | |* 当您在同一存储桶中创建多条清单规则时，每个规则的过滤范围不允许重叠。TOS 会自动校验您的过滤范围，如果范围重叠，您需要先删除或修改之前清单规则的过滤范围，否则会导致创建失败。 | |生成时间 |首次配置桶清单规则，系统会在 24 小时内加载扁平桶的清单规则，48 小时内加载分层桶的清单规则。当桶的对象数量少于 100 亿时，通常在加载规则后的 24 小时内生成清单，如对象数量超过 100 亿，则生成清单的时间会相应延长。 | |对象数量 |桶清单支持**每日**或者**每周**导出，建议您根据对象数量合理设置导出周期。|\ | ||\ | |* 对象数量 < 100 亿：每日或者每周均可。|\ | |* 对象数量 100 亿 ~ 500 亿：建议每周导出。|\ | |* 对象数量 \> 500 亿：建议指定前缀，分批导出。 | |修改桶清单 |如果您在桶清单执行过程中修改桶清单规则，则新规则既可能在当天的清单中生效，也可能在下一次执行时生效。建议您在修改规则之后使用 T+1 天后生成的清单文件。 | |删除桶清单 |如果您在桶清单任务执行过程中删除了桶清单规则，在清单文件目录下，可能会存在部分已完成的清单结果文件，剩余部分可能不会被继续生成。 | |其他 |* 清单文件导出过程中，可能会占用一定的带宽。如果您的存储桶存在带宽清单的问题，建议您选择其他的存储桶存储清单文件，避免占用源存储桶带宽。|\ | |* 如果源存储桶没有文件，或者设置的清单规则没有匹配到相应的对象，则不会生成清单文件。|\ | |* 导出清单文件的过程中，如果您在存储桶中写入或更新对象，相应信息可能不会保存在清单文件中。|\ | |* 为减少存储容量费用，您可以根据需求删除不需要的清单文件；如果您不再需要定期生成清单文件，您可以直接删除创建的桶清单规则。 |