您可以通过桶清单功能，定期获取固定存储桶内所有或者指定前缀的对象信息，并保存到指定的存储桶中。清单内容包括对象大小、存储类型、最后更新日期、Etag、分片上传状态及加密状态等。本文介绍桶清单的使用场景及操作步骤。

权限说明

主账号默认拥有全部权限，IAM 子用户默认没有任何权限。如果您需要使用子账号执行该操作，则需要主账号通过 IAM 策略或桶策略为该子账号授予以下权限。

设置桶清单：tos:PutBucketInventory

查看桶清单：tos:GetBucketInventory

删除桶清单：tos:DeleteBucketInventory

首次创建桶清单前，您需要通过 IAM，授予对象存储读取源存储桶所有文件和向目标存储桶写入文件的权限。建议您通过控制台授权，授权成功后，IAM 会自动生成 TosArchiveTOSInventory 角色，您可以登录 IAM 控制台查看。

TosArchiveTOSInventory 角色默认没有访问 KMS 密钥的权限，如果您的存储桶配置了 SSE-KMS 桶默认加密规则，创建桶清单前，您需要授予该角色 KMSCryptoUserAccess 的权限，否则将无法生成桶清单。

注意事项

限制项	说明
桶清单数量	每个存储桶最多可以配置 10 条桶清单。
桶清单参数	创建桶清单的源存储桶和保存清单文件的目标存储桶不需要相同，但必须属于相同账号下的相同地域。桶清单目前仅支持选择所有对象或者指定前缀的对象。当您在同一存储桶中创建多条清单规则时，每个规则的过滤范围不允许重叠。TOS 会自动校验您的过滤范围，如果范围重叠，您需要先删除或修改之前清单规则的过滤范围，否则会导致创建失败。
生成时间	首次配置桶清单规则，系统会在 24 小时内加载扁平桶的清单规则，48 小时内加载分层桶的清单规则。当桶的对象数量少于 100 亿时，通常在加载规则后的 24 小时内生成清单，如对象数量超过 100 亿，则生成清单的时间会相应延长。说明如果您需要立即执行扁平桶的清单规则，请参考其他操作中的立即执行桶清单规则。
对象数量	桶清单支持每日或者每周导出，建议您根据对象数量合理设置导出周期。对象数量 < 100 亿：每日或者每周均可。对象数量 100 亿 ~ 500 亿：建议每周导出。对象数量 > 500 亿：建议指定前缀，分批导出。
修改桶清单	如果您在桶清单执行过程中修改桶清单规则，则新规则既可能在当天的清单中生效，也可能在下一次执行时生效。建议您在修改规则之后使用 T+1 天后生成的清单文件。
删除桶清单	如果您在桶清单任务执行过程中删除了桶清单规则，在清单文件目录下，可能会存在部分已完成的清单结果文件，剩余部分可能不会被继续生成。
其他	清单文件导出过程中，可能会占用一定的带宽。如果您的存储桶存在带宽清单的问题，建议您选择其他的存储桶存储清单文件，避免占用源存储桶带宽。如果源存储桶没有文件，或者设置的清单规则没有匹配到相应的对象，则不会生成清单文件。导出清单文件的过程中，如果您在存储桶中写入或更新对象，相应信息可能不会保存在清单文件中。为减少存储容量费用，您可以根据需求删除不需要的清单文件；如果您不再需要定期生成清单文件，您可以直接删除创建的桶清单规则。

计费说明

桶清单暂不收取功能使用费用，但会产生以下关联费用：

计费项	说明
存储费用	生成的清单报告会占用目标存储桶的存储空间，产生存储容量费用。
API 请求费用	配置和获取清单规则时产生 Put 请求费用和 Get 请求费用。 TOS 写入清单报告到目标存储桶时会产生 Put 请求费用。下载和读取清单报告时，会产生 Get 请求费用。
公网流出流量费用	使用公网 Endpoint 下载和读取清单报告时，会产生公网流出流量费用。

计费项详情，请参见计费概述。

为避免不必要的成本开销，建议及时删除不再需要的清单规则；对于仍需保留的规则，建议通过配置生命周期自动删除过期的清单报告。

操作步骤

登录对象存储控制台。

在左侧导航栏，单击桶列表。

在顶部导航栏，选择存储桶所属项目。

在桶列表页面，单击目标桶名称。

在左侧导航栏，选择基础设置 > 桶清单。

在桶清单页面，单击创建清单。

在创建桶清单页面，设置如下参数。

参数	说明
状态	选择桶清单的状态，可选开启和关闭。
规则名称	设置规则名称，命名规范如下：长度需为 1～64 个字符。只能包含数字、短横线（-）、字母、下划线（_）和英文句号（.）。只能以数字或字母开头及结尾。
目标存储桶	选择存储清单文件的目标桶。注意如果设置目标存储桶是公共读（写），会存在清单文件泄漏的风险。目标存储桶必须和清单文件对应的源存储桶处于同一地域。归档、冷归档、深度冷归档存储类型的桶不支持作为清单目标桶。
清单报告前缀	设置前缀后，清单生成后，您的清单报告将投递至目标存储桶的相应路径下，默认为 tos_bucket_inventory。命名规范如下：支持中文、英文、数字及常见字符。不支持以正斜线（/）或反斜线（\）开头，不支持使用连续的正斜线（/）。不支持使用 .. 作为目录名称。
报告输出格式	设置清单报告输出格式，说明如下：压缩（默认）：清单报告输出格式默认压缩为 csv.gz ，以减少您的额外存储成本。。非压缩：清单报告以 csv 格式存储到目标桶。
报告导出周期	选择报告导出的周期，可选每周、每日或一次性。说明一次性导出报告默认只执行一次。如果您选择的对象较多，建议您选择每周导出报告。
对象版本	选择需要导出的对象版本，可选当前版本或者所有版本。说明仅开启了版本控制的存储桶需要选择该参数。
过滤设置	选择清单文件的过滤信息，说明如下：按前缀匹配：设置匹配的前缀，如果不设置则默认生成桶中所有对象的清单。条件过滤：设置条件进行过滤，支持设置对象大小、创建时间、修改时间、筛选标签、存储类型、对象类型相关条件。清单内容信息：选择清单文件需要导出的信息，支持导出 Object 大小、存储类型、智能分层：访问层、最后更新日期、ETag、分片上传状态、加密状态、CRC64、复制状态、标签、保留模式、保留到期时间。详细说明，请参见 fileSchema。说明最后访问时间处于邀测状态，如需使用，请联系客户经理。输出自定义头部：设置清单结果文件的自定义元数据头部。仅支持配置以 x-tos-meta- 开头的访问头部，可增删多条。例如输入source，则完整头部为 x-tos-meta-source。

设置完成后，单击确定即可按报告导出周期生成清单。

清单文件说明

文件名称

创建桶清单后，TOS 会按照设置的参数生成对应清单。清单文件的名称如下所示。

参数说明如下。

参数	说明
destinationPrefix/	创建桶清单时设置的报告前缀。如果创建时未设置，则默认为 tos_bucket_inventory。
sourceBucketName/	清单文件对应的源存储桶。
inventoryId/	桶清单规则名称。
YYYY-MM-DDTHH-MMZ/	生成清单文件时，开始扫描存储对象的时间信息，UTC 时间，格式为 YYYY-MM-DDTHH-MMZ。说明在该时间之后上传的对象，不会记录在清单文件中。在 2025-07-15 00:00:00 前创建且未修改的桶清单规则，其清单文件的命名格式为 YYYY-MM-DDTHH:MMZ，详细介绍，请参见对象存储桶清单文件名称调整公告。
files/	保存对象清单文件的目录，默认为 files/。清单文件的格式为 UUID.csv.gz，默认为 .csv.gz 格式。说明清单文件的详细说明，请参见清单文件参数说明。如果您导出的对象数据较多，为了便于您处理数据，TOS 会自动将清单文件分隔成多个小文件，文件命名按照 UUID_0、UUID_1依次递增。一个 files 目录下 UUID 可能不唯一，即可能会出现UUIDA_0、UUIDB_0、UUIDB_1等多个文件。
manifest.json	保存清单文件元数据及其他信息的文件。详细说明，请参见 manifest.json。
manifest.checksum	manifest.json 文件的 MD5 校验信息，例如 79b1e0cbe3af7fdf127b91af601b****。

manifest.json

manifest.json 文件示例及说明如下。

参数			说明
creationTimestamp			Unix 时间戳，计量单位为秒，表示开始扫描源存储桶的时间。
sourceBucket			清单文件对应的源存储桶。
destinationBucket			存储清单文件的目的桶。
fileFormat			清单文件的格式，默认为 CSV。
fileSchema			清单文件包含的对象信息。详细说明，请参见 fileSchema。
version			清单文件的版本号。
files	Key	清单文件的完整路径及名称。
		Size	清单文件大小，单位为 Byte。
		MD5checksum	清单文件的 MD5 校验信息。
		InventoriedRecord	清单文件中包含的记录数量。

fileSchema

fileSchema 文件示例如下。

fileSchema 文件不包含参数名称，图中参数名称仅供参考，详细参数说明如下：

参数	是否可选	说明
BucketName	必选	清单文件对应的源存储桶名称。
ObjKey	必选	存储桶中对象的名称。说明对象名称采用 URL 编码，您必须解码后方可使用。
VersionId	必选	对象的版本 ID。说明仅当存储桶开启版本控制功能，且创建桶清单时对象版本选择所有版本时，才会导出该信息。
IsLatest	必选	对象版本是否为最新版本。取值说明如下： TRUE：对象为最新版本 FALSE：对象为历史版本。说明仅当存储桶开启版本控制功能，且创建桶清单时对象版本选择所有版本时，才会导出该信息。
IsDeleteMarker	必选	对象版本是否为删除标记。取值说明如下： TRUE：版本为删除标记。 FALSE：版本不是删除标记。说明仅当存储桶开启版本控制功能，且创建桶清单时对象版本选择所有版本时，才会导出该信息。
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 值，常用于数据一致性的校验。更多信息，请参见校验数据一致性概述。
ReplicationStatus	可选	对象的跨区域复制或同区域复制状态，存在以下情况：如果该对象是跨区域复制或同区域复制的源对象，则对象的复制状态取值说明如下： COMPLETE：复制完成。 PENDING：等待复制中。 FAILED：复制失败。说明查看跨区域复制和同区域复制源对象的复制状态功能目前处于邀测状态，如您需要使用该功能，请联系客户经理。如果该对象是跨区域复制或同区域复制的目标对象，则会显示 REPLICA，表示该对象是被复制的对象。如果该对象不是跨区域复制或同区域复制的源对象或目标对象，则会显示为空。
Tag	可选	对象标签，格式为 key1#value1;key2#value2;。说明对象标签 key 和 value 采用 URL 编码，您必须解码后方可使用。
RetentionMode	可选	对象的保留策略模式，取值说明如下： COMPLIANCE：合规模式。 NONE：该对象未设置保留策略。
RetainUntilTimestamp	可选	对象的保留到期时间，Unix 时间戳格式，计量单位为秒。
LastAccessTime	可选	对象的最后访问时间。说明 LastAccessTime 处于邀测状态，如需使用，请联系客户经理。只有开启访问跟踪功能，才会更新对象的最后访问时间。使用最后访问时间前，请先在生命周期页面开启访问跟踪，详细操作请参见开启访问跟踪。 TOS 默认从开启访问跟踪的当天开始计算对象的最后访问时间，两次访问同一个对象的间隔时间不少于 24 小时，才会更新该对象的最后访问时间。例如在 1 月 1 日 8:00 下载对象，则记录对象访问时间为 1 月 1 日 8:00，则在 1 月 2 日 8:00 前的下载请求均不再更新访问时间，直到 1 月 2 日 8:00 后再下载才会更新访问时间。详细介绍，请参见哪些操作会更新 Object 的 LastAccessTime？。对象最后访问时间无法保证绝对准确。如果服务端处于繁忙状态，部分对象被访问后可能不会更新最后访问时间，因此请勿将该字段作为数据清理的判断依据。

其他操作

编辑桶清单规则：单击目标规则操作列的编辑，可以修改桶清单规则。

删除桶清单规则：单击目标规则操作列的删除，在弹出的对话框中单击删除，可以删除桶清单规则。

立即执行桶清单规则：单击目标规则操作列的立即执行，在弹出的对话框中单击确定，可以创建即时清单。

预览清单规则：单击目标规则操作列的预览清单，在弹出的对话框中可以查看清单目录名和清单结果，还可以选择日期对清单进行筛选。单击查看清单结果，可以查看源存储桶、目标存储桶、对象总数、对象总大小、清单文件的格式、清单文件的版本号、清单文件的名称、清单文件的大小，还可以下载清单。

常见问题

如何确认清单文件是否已生成？

为什么清单文件很久都没有生成？

什么原因会影响清单导出速度？

对象存储