您可以通过桶清单功能，定期获取桶内指定对象的相关信息，并保存到指定的存储桶中。本文介绍桶清单的使用场景及操作步骤。 ## 使用场景您可以通过桶清单功能，定期获取固定存储桶内所有或者指定前缀的对象信息，清单内容包括对象大小、存储类型、最后更新日期、Etag、分片上传状态及加密状态等。如果您需要列举的对象较多，建议您优先使用桶清单功能。 ## 权限说明 * 主账号默认拥有全部权限，IAM 子用户默认没有任何权限。如果您需要使用子账号执行该操作，则需要主账号通过 [IAM 策略](https://www.volcengine.com/docs/6349/102131)或[桶策略](https://www.volcengine.com/docs/6349/102126)为该子账号授予以下权限。 * 设置桶清单：`tos:PutBucketInventory` * 查看桶清单：`tos:GetBucketInventory` * 删除桶清单：`tos:DeleteBucketInventory` * 首次创建桶清单前，您需要通过 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 亿，则生成清单的时间会相应延长。|\ | |:::tip|\ | |如果您需要立即执行扁平桶的清单规则，请参考[其他操作](https://www.volcengine.com/docs/6349/156080?lang=zh&TagIDs=2%2C348#.5YW25LuW5pON5L2c)中的**立即执行桶清单规则**。|\ | ||\ | |:::| |对象数量 |桶清单支持**每日**或者**每周**导出，建议您根据对象数量合理设置导出周期。|\ | ||\ | |* 对象数量 < 100 亿：每日或者每周均可。|\ | |* 对象数量 100 亿 ~ 500 亿：建议每周导出。|\ | |* 对象数量 \> 500 亿：建议指定前缀，分批导出。 | |修改桶清单 |如果您在桶清单执行过程中修改桶清单规则，则新规则既可能在当天的清单中生效，也可能在下一次执行时生效。建议您在修改规则之后使用 T+1 天后生成的清单文件。 | |删除桶清单 |如果您在桶清单任务执行过程中删除了桶清单规则，在清单文件目录下，可能会存在部分已完成的清单结果文件，剩余部分可能不会被继续生成。 | |其他 |* 清单文件导出过程中，可能会占用一定的带宽。如果您的存储桶存在带宽清单的问题，建议您选择其他的存储桶存储清单文件，避免占用源存储桶带宽。|\ | |* 如果源存储桶没有文件，或者设置的清单规则没有匹配到相应的对象，则不会生成清单文件。|\ | |* 导出清单文件的过程中，如果您在存储桶中写入或更新对象，相应信息可能不会保存在清单文件中。|\ | |* 为减少存储容量费用，您可以根据需求删除不需要的清单文件；如果您不再需要定期生成清单文件，您可以直接删除创建的桶清单规则。 | ## 操作步骤 1. 登录[对象存储控制台](https://console.volcengine.com/tos)。 2. 在左侧导航栏，单击**桶列表**。 3. 在顶部导航栏，选择存储桶所属项目。 4. 在**桶列表**页面，单击目标桶名称。 5. 在左侧导航栏，选择**基础设置 \> 桶清单。** 6. 在**桶清单**页面，单击**创建清单**。 7. 在**创建桶清单**页面，设置如下参数。 |**参数** |**说明** | |---|---| |状态 |选择桶清单的状态，可选**开启**和**关闭**。 | |规则名称 |设置规则名称，命名规范如下：|\ | ||\ | |* 长度需为 1～64 个字符。|\ | |* 只能包含数字、短横线（\-）、字母、下划线(_)和英文句号（.）。|\ | |* 只能以数字或字母开头及结尾。 | |目标存储桶 |选择存储清单文件的目标桶。|\ | |:::warning|\ | ||\ | |* 如果设置目标存储桶是公共读（写），会存在清单文件泄漏的风险。|\ | |* 目标存储桶必须和清单文件对应的源存储桶处于同一地域。|\ | |* 归档、冷归档、深度冷归档存储类型的桶不支持作为清单目标桶。|\ | ||\ | |:::| |清单报告前缀 |设置前缀后，清单生成后，您的清单报告将投递至目标存储桶的相应路径下，如果不设置，则默认为 `tos_bucket_inventory`。命名规范如下：|\ | ||\ | |* 支持中文、英文、数字及常见字符。|\ | |* 不支持以正斜线（/）或反斜线（\）开头，不支持使用连续的正斜线（/）。|\ | |* 不支持使用 `..`作为目录名称。|\ | ||\ | |:::tip|\ | |清单文件的格式详情，请参见上文的文件格式。|\ | ||\ | |:::| |报告输出格式 |设置清单报告输出格式，说明如下：|\ | ||\ | |* **压缩**：清单报告压缩为 csv.gz 格式存储到目标桶。|\ | |* **非压缩**：清单报告以 csv 格式存储到目标桶。|\ | ||\ | |默认**报告输出格式**为**压缩**，以减少您的额外存储成本。 | |报告导出周期 |选择报告导出的周期，可选**每周**、**每日**或**一次性**。|\ | |:::tip|\ | ||\ | |* 一次性导出报告默认只执行一次。|\ | |* 如果您选择的对象较多，建议您选择每周导出报告。|\ | ||\ | |:::| |对象版本 |选择需要导出的对象版本，可选**当前版本**或者**所有版本**。|\ | |:::tip|\ | |仅开启了版本控制的存储桶需要选择该参数。|\ | ||\ | |:::| |过滤设置 |选择清单文件的过滤信息，说明如下：|\ | ||\ | |* **按前缀匹配**：设置匹配的前缀，如果不设置则默认生成桶中所有对象的清单。|\ | |* **清单内容信息**：选择清单文件需要导出的信息，支持导出 **Object大小**、**存储类型**、**智能分层：访问层**、**最后更新日期**、**ETag**、**分片上传状态**、**加密状态**、**CRC64**、**复制状态**、**标签、保留模式**和**保留到期时间**。详细说明，请参见 [fileSchema](/docs/6349/156080#fileschema)。|\ | ||\ | |:::tip|\ | |保留模式和保留到期时间处于邀测状态，如需使用，请联系客户经理。|\ | ||\ | |:::| 8. 设置完成后，单击**确定**。 ## 其他操作 * **编辑桶清单规则**：单击目标规则**操作**列的**编辑**，可以修改桶清单规则。 * **删除桶清单规则**：单击目标规则**操作**列的**删除**，在弹出的对话框中单击**删除**，可以删除桶清单规则。 * **立即执行桶清单规则**：单击目标规则**操作**列的**立即执行**，在弹出的对话框中单击**确定**，可以创建即时清单。 :::tip 仅扁平桶（FNS）支持该操作。 ::: * **预览清单规则**：单击目标规则**操作**列的**预览清单**，在弹出的对话框中可以查看清单目录名和清单结果，还可以选择日期对清单进行筛选。单击**查看清单结果**，可以查看**源存储桶**、**目标存储桶**、**对象总数**、**对象总大小**、**清单文件的格式**、**清单文件的版本号**、**清单文件的名称**、**清单文件的大小**，还可以**下载**清单。 ## 常见问题 * [如何确认清单文件是否已生成？](/docs/6349/1799901) * [为什么清单文件很久都没有生成？](/docs/6349/1289649#2ca51210) * [什么原因会影响清单导出速度？](/docs/6349/1289649#8fbc3ce4)