更新时间：2026-07-10 GMT+08:00

桶清单

当您的桶中对象数量多达数百万甚至数百亿时，通过列举桶中对象逐一列举对象效率很低且成本高。OBS提供桶清单功能，以定期生成桶内对象的相关信息（如大小、上次修改时间、存储类别）的清单文件，并将清单文件上传到您指定的桶中，方便您管理桶内海量对象。

使用场景

桶清单功能按照一定周期生成桶内对象的相关信息，保存在CSV格式的文件中，并上传到您指定的桶中。

支持对桶中指定前缀的对象生成清单。
生成桶内对象的相关信息包括对象版本、大小、上次修改时间、存储类别、加密状态等。
支持对桶清单加密，加密方式为SSE-KMS方式。
支持设定桶清单的生成频率：每天或每周。
支持将生成的桶清单存储到指定的目标桶，目标桶和源桶可以是同一个桶。

关于源桶和目标桶的概念如下：

源桶：为配置清单的桶，生成的清单文件中包含的是源桶中的对象。
目标桶：生成的清单文件存放到目标桶中，目标桶和源桶必须属于同账号同区域下的桶，且可以是同一个桶。

工作流程

桶清单工作流程如下：

配置桶清单：配置清单存储桶、生成频率、对象版本、对象信息字段等；并配置桶策略，允许OBS向目标桶中上传清单文件。
扫描对象：OBS根据配置的桶清单规则中的筛选条件（如对象前缀、对象版本），定期（每天或每周）扫描桶中所有与桶清单规则匹配的对象。
生成清单文件并存储至目标桶：OBS将扫描结果生成清单文件（全量清单文件），以CSV格式的文件存储在目标桶中。

配置桶清单后，OBS定期扫描生成清单文件的操作在后台执行，不会影响桶的正常使用。

约束与限制

表1 桶清单约束限制
限制类型	限制内容
桶版本限制	只有OBS 3.0的桶支持配置清单，目标桶无OBS版本限制。关于如何确认桶的版本，请参见OBS 2.0和OBS 3.0的判断方法。
清单数量限制	一个桶最多支持10条桶清单。
源桶和目标桶限制	桶清单配置的源桶和目标桶必须归属同一个账号。桶清单配置的源桶和目标桶必须归属同一个区域。桶清单中配置的目标桶不能开启桶服务端加密。
功能限制	只支持生成CSV格式的清单文件。桶清单筛选条件目前仅支持设置为所有对象或指定前缀的对象。同一个桶中多条清单规则的筛选条件不能彼此包含：如果已经存在针对桶中所有对象的规则，则无法再创建按对象名前缀筛选的规则。如需创建，要先删除针对所有对象的规则。如果已经存在按对象名前缀筛选的规则，则无法再创建针对桶中所有对象的规则。如需创建，要先删除所有按对象名前缀筛选的规则。如果已经存在某个按对象名前缀筛选的规则（如前缀ab），则无法再创建与其存在包含或被包含关系的规则（如前缀a或前缀abc）。如需创建，要先删除存在包含或被包含关系的规则。桶清单支持统计的对象加密方式目前只支持SSE-KMS。
权限限制	清单文件使用OBS系统用户上传到目标桶，目标桶必须给OBS系统用户写权限，即目标桶必须包含一条Principal取值固定为{"Service": "obs"}，授予写权限的桶策略，详见为目标桶添加桶策略。
其他	暂不对桶清单功能收费，桶清单生成后只按照存储容量计费。不支持联邦用户使用桶清单。说明：企业联邦用户是在企业管理系统中创建的用户，账号在IAM控制台创建身份提供商后，企业联邦用户可以登录华为云并根据对应权限使用云服务。

费用说明

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

请求费用：生成桶清单文件后上传至目标桶，会产生PUT请求费用；从目标桶下载和读取桶清单文件，会产生GET请求费用。关于请求费用说明，请参见请求费用。
存储费用：生成的桶清单文件被上传至目标桶，会占用目标桶的存储容量，会收取存储费用。关于存储费用说明，请参见存储费用。
公网流出流量费用：通过互联网从目标桶中下载桶清单文件，会产生公网流出流量费用。

通过同区域华为云ECS、CCE、BMS等下载OBS的数据所产生的内网流出流量免费。

为了避免产生不必要的费用开支，建议您及时删除不需要的桶清单文件（手动删除或使用生命周期规则定期删除），如果不再需要桶清单，建议您及时删除配置的桶清单规则。

权限控制

配置桶清单，需要在目标桶中配置桶策略，以允许OBS将生成的清单文件存储至目标桶中。如果通过控制台进行配置，则控制台会自动生成目标桶的桶策略；如果通过REST API进行配置，则需要手动为目标桶配置桶策略。使用API配置桶策略，请参见设置桶策略-SetBucketPolicy。

桶策略的格式如下，修改其中的destbucket为目标桶的桶名。

{
	"Statement": [
		{
			"Effect": "Allow",
			"Sid": "1",
			"Principal": {"Service": "obs"},
			"Resource": ["destbucket/*"],
			"Action": ["PutObject"]
		}
	]
}

清单文件的目录结构

生成的清单文件在目标桶中存储的目录结构如下：

destinationPrefix/sourceBucketName/inventoryId/yyyy-MM-dd'T'HH-mm'Z'/files/UUID_数字.csv

示例：

obj/test-zcy-bucket-002/inventory-861c/2026-06-11T03-04Z/files/0000019EB4A3D9C7B8EA68E19D649A41_1.csv

图1 桶清单文件的存储位置
点击放大

表2 清单文件目录结构参数说明
参数	说明
destinationPrefix	桶清单配置中的“清单文件前缀”，生成的清单文件以此前缀开头，可用于对清单文件进行分类存放。如果没有设置该参数，则默认为BucketInventory。
sourceBucketName	清单文件对应的源桶，可以防止当不同的源桶都配置了相同的目标桶时产生冲突。
inventoryId	桶清单配置中的“清单名称”，可以防止当一个桶的多条清单配置中配置了相同的目标桶时产生冲突。该目录下包含了hive/dt=yyyy-MM-dd-HH-mm/symlink.txt文件，如：hive/dt=2026-06-11-00-00/symlink.txt。
yyyy-MM-dd'T'HH-mm'Z'	生成本次清单文件时开始扫描存储桶的时间和日期。如：2026-06-11T03-04Z 是格林威治时间格式，转换为北京时间，需要加8小时。清单文件中不会包含在此时间之后上传的对象，因此可能会出现清单文件中的文件数量和桶中实际文件数量不一致的情况。该目录下包含了manifest.json文件。
files	固定路径，每个桶清单文件的存放路径均包含此路径。该路径用于将manifest.json文件和清单文件分开存放。
UUID_数字.csv	清单文件的名称。清单文件以.csv格式存放在目标桶中。

清单文件的内容

生成的清单文件包含：.csv格式的清单文件、manifest.json文件和symlink.txt文件。

清单文件中的内容由设置的清单配置而定。以下为生成的.csv格式的清单文件，清单文件中所有可能的字段请参见表3。

图2 清单文件

表3 清单中列出的对象元数据
元数据	说明
Bucket	执行清单任务的源桶的桶名。
Key	键值，即对象的名称，一个桶里的每个对象拥有唯一的对象键值。清单文件中的对象名采用UTF-8的URL编码，需解码后才能使用。如在图2中： “testfolder%2F”表示对象“testfolder/”，在控制台上表现为文件夹。 “testfolder%2Ftest.txt”表示对象“testfolder/test.txt”，表现为文件夹“testfolder”下的“test.txt”对象。 “test%2D01.txt”表示对象“test-01.txt”。
VersionId	对象的版本ID。仅当清单配置中的“对象版本”为“包含所有版本”时，导出的清单文件中才会有此字段。如果源桶没有开启多版本控制，则该字段显示为空。如果源桶开启了多版本控制，则该字段显示为对象的版本ID。
IsLatest	是否为当前版本对象。仅当清单配置中的“对象版本”为“包含所有版本”时，导出的清单文件中才会有此字段。如果源桶没有开启多版本控制，则该字段显示为“TRUE”。如果源桶开启了多版本控制且对象为最新版本对象，则该字段显示为“TRUE”，如果对象为历史版本对象，则该字段显示为“FALSE”。
IsDeleteMarker	是否为删除标记。在桶开启多版本控制后，如果删除一个对象，OBS将插入一个删除标记来标识对象的最新版本是删除状态。仅当清单配置中的“对象版本”为“包含所有版本”时，导出的清单文件中才会有此字段。如果源桶没有开启多版本控制，则该字段显示为“FALSE”。如果源桶开启了多版本控制且对象为删除标记，则该字段显示为“TRUE”，如果对象不是删除标记，则该字段显示为“FALSE”。
Size	对象大小（以字节为单位）。该参数对应桶清单配置中“清单额外字段”中的“文件大小”参数。
LastModifiedDate	生成清单文件前，对象的最近一次修改日期。如果对象未被修改过，即为对象创建日期。是格林威治时间格式，转换为北京时间，需要加8小时。如：“2026-04-01T07:33:48Z”对应北京时间是“2026年4月1日 15:33:48”。该参数对应桶清单配置中“清单额外字段”中的“上次修改时间”参数。
ETag	ETag是对象内容的唯一标识，可以通过该值识别对象内容是否有变化。比如上传对象时ETag为A，下载对象时ETag为B，则说明对象内容发生了变化。当使用PUT上传时，ETag是对象的MD5哈希值。如果通过多段上传对象，则无论加密方法如何，MD5会拆分ETag，此类情况ETag就不是对象的MD5哈希值。 ETag只反映变化的内容，而不是其元数据。上传的对象或使用拷贝操作创建的对象，通过MD5加密后都有唯一的ETag。该参数对应桶清单配置中“清单额外字段”中的“ETag”参数。
StorageClass	对象的存储类别。取值如下： STANDARD：标准存储 STANDARD_IA：即“WARM”，低频访问存储 GLACIER：即“COLD”，归档存储 DEEP_ARCHIVE：深度归档存储该参数对应桶清单配置中“清单额外字段”中的“存储类别”参数。
IsMultipartUploaded	对象是否是多段上传对象。取值如下： TRUE：对象是多段上传对象。 FALSE：对象不是多段上传对象。该参数对应桶清单配置中“清单额外字段”中的“分段上传”参数。
ReplicationStatus	对象的跨区域复制状态。取值如下： NOREP：对象不是被跨区域复制过来的对象。 REP：对象是被跨区域复制过来的对象。该参数对应桶清单配置中“清单额外字段”中的“复制状态”参数。
EncryptionStatus	对象的加密状态。取值如下： SSE-KMS：对象的加密模式为SSE-KMS。 NOT-SSE：对象没有被加密或加密模式不是SSE-KMS。该参数对应桶清单配置中“清单额外字段”中的“加密状态”参数。
BucketKeyStatus	源桶是否开启存储桶密钥。取值如下： ENABLED：源桶已开启存储桶密钥。 DISABLED：源桶未开启存储桶密钥。该参数对应桶清单配置中“清单额外字段”中的“存储桶密钥状态”参数。
CRC64	对象的CRC64值。按照ECMA-182标准计算的对象的64位无符号数编码的crc64值。crc64是对象内容的唯一标识，可以通过该值识别对象内容是否有变化。如果加密上传对象，crc64计算的是加密前的对象内容。该参数对应桶清单配置中“清单额外字段”中的“CRC64”参数。

当桶内对象很多的时候，单条清单配置可能会生成多个清单文件，生成清单文件需要一定时间。例如，桶内有20万个对象时，生成所有清单文件需要约1.5分钟。在全部清单文件生成完成之后1到2小时会生成一个manifest.json文件，manifest.json文件中包含了该条清单本次生成的所有清单文件的相关信息。

manifest.json文件的存放位置
manifest.json文件在目标桶中存储的位置如下：
```
destinationPrefix/sourceBucketName/inventoryId/yyyy-MM-dd'T'HH-mm'Z'/manifest.json
```
目录结构中的各参数解释，请参见清单文件的目录结构。

示例：
```
obj/test-zcy-bucket-002/inventory-861c/2026-06-11T03-04Z/manifest.json
```
图3 manifest.json文件的存放位置

manifest.json文件内容示例及各字段说明

{
   "sourceBucket": "test-zcy-bucket-002",
   "destinationBucket": "test-zcy-bucket-001",
   "version": "2026-06-11",
   "fileFormat": "CSV",
   "fileSchema": "Bucket,Key,VersionId,IsLatest,IsDeleteMarker,Size,LastModifiedDate,StorageClass,ETag,IsMultipartUploaded,ReplicationStatus,EncryptionStatus,BucketKeyStatus,CRC64",
   "files": [{
      "key": "obj%2Ftest-zcy-bucket-002%2Finventory-861c%2F2026-06-11T03-04Z%2Ffiles%2F0000019EB4A3D9C7B8EA68E19D649A41_1.csv",
      "size": 76782,
      "inventoriedRecord": 376
   }]
}

文件中各字段说明如表4。

表4 manifest文件字段说明
参数	说明
sourceBucket	源桶的桶名称。
destinationBucket	目标桶的桶名称。
version	清单的版本。
fileFormat	清单文件的格式。
fileSchema	清单文件中包含的对象元数据字段，即表3中的元数据。
files	所有清单文件列表。每一个清单文件均包含key、size、inventoriedRecord三个字段。
key	清单文件名称，即清单文件的目录结构，采用UTF-8的URL编码，需解码后才能显示出清单文件的存放路径。例如：“obj%2Ftest-zcy-bucket-002%2Finventory-861c%2F2026-06-11T03-04Z%2Ffiles%2F0000019EB4A3D9C7B8EA68E19D649A41_1.csv”解码后为“obj/test-zcy-bucket-002/inventory-861c/2026-06-11T03-04Z/files/0000019EB4A3D9C7B8EA68E19D649A41_1.csv”。
size	清单文件的大小，以字节为单位。
inventoriedRecord	清单文件中包含的对象记录条数。

symlink.txt文件记录了桶清单文件的路径，用于在大数据场景下业务快速找到所有桶清单。Apache Hive兼容OBS桶清单功能产生的symlink.txt文件，Hive能够自动查找到symlink.txt文件和symlink.txt文件中记录的清单文件，其中symlink.txt文件按照对象名的字典序排序。

symlink.txt文件的存放位置
symlink.txt文件在目标桶中存储的位置如下：
```
destinationPrefix/sourceBucketName/inventoryId/hive/dt=yyyy-MM-dd-HH-mm/symlink.txt
```
目录结构中的各参数解释，请参见清单文件的目录结构。

示例：
```
obj/test-zcy-bucket-002/inventory-861c/hive/dt=2026-06-11-00-00/symlink.txt
```
图4 symlink.txt文件的存放位置
symlink.txt文件内容示例及各字段说明
```
obs://test-zcy-bucket-001/obj/test-zcy-bucket-002/inventory-861c/2026-06-11T03-04Z/files/0000019EB4A3D9C7B8EA68E19D649A41_1.csv
```
文件中“test-zcy-bucket-001”为桶清单文件存放的目标桶名称，其他字段说明请参见如清单文件的目录结构。

注意事项

在生成桶清单的过程中，如果您对源桶中的对象进行操作，这可能会导致最终生成的桶清单文件中的对象数量和源桶中实际的对象数量不一致。这是由于对象的最后修改时间如果在manifest.json文件中version字段显示的时间之后，该对象将不会被统计进桶清单文件中。

使用建议

权限最小化：通过REST API配置桶清单前，手动为目标桶配置桶策略时，遵循权限最小化原则，仅配置所需的上传对象权限（PutObject），请勿配置其他更大或更多权限。
性能建议：配置桶清单存储桶时，建议您选择业务流量较小的桶，因为如果选择业务流量较高的桶，可能会由于将大量桶清单文件上传至桶中而产生带宽竞争，从而影响业务访问。
节省成本：桶清单支持按天或周生成清单文件。对于桶中文件数量很多（如：数百万或数百亿）时，建议配置按周生成清单文件；同时为桶配置生命周期规则，自动删除超过指定天数（如：30天或60天）的桶清单文件以节约存储成本。
监控告警：建议您配置目标桶的存储容量监控告警，并定期查看目标桶的存储容量，防止清单文件无限制增长导致存储费用激增。
修改桶清单配置：修改桶清单配置会影响下游清单文件数据分析，建议您提前规划并通知所有关键流程人员，避免产生不可控的影响。

使用方式

OBS支持通过管理控制台、API、SDK方式配置桶清单，不支持使用OBS Browser+、obsutil方式配置桶清单。

使用OBS控制台

在OBS管理控制台左侧导航栏选择“桶列表”。
在桶列表中，单击待操作的桶，进入“对象”页面。
在左侧导航栏，单击“数据管理>桶清单”进入“桶清单”页面。
单击“创建”，系统弹出“创建桶清单”对话框。

设置“清单配置”相关参数。

图5 清单配置

表5 清单配置参数说明
参数	描述
清单名称	桶清单的名称。清单名称相关规则如下：只能由大写或小写的英文字母、数字、英文句号（.）、下划线（_）和连字符（-）组成。长度范围为1到64位。
筛选条件	桶清单筛选条件，OBS会为源桶中指定前缀的对象生成清单。对象名前缀规则： *不能包括\:?"<>\|特殊字符。不能以/开头。不能两个/相邻。输入的前缀必须为对象在桶中除桶名外的绝对路径，有如下几种情况：如果不输入，表示对桶中所有对象生成清单。如果输入的前缀不带“/”，表示匹配桶根目录下的对象。如果输入的前缀带“/”，表示匹配桶中对应文件夹下的对象。如：输入“testfolder/”，表示匹配桶中testfolder文件夹下的对象。输入“testfolder/test”，表示匹配桶中testfolder文件夹下名称以“test”开头的对象。同一个桶中多条清单规则的筛选条件不能彼此包含。**主要有以下几种情况：如果已针对桶中所有对象配置了一条桶清单规则，那么将不能再配置第二条桶清单规则。如果已针对指定前缀对象配置了一条桶清单规则，那么将不能再配置第二条针对所有对象的桶清单规则。如果已针对指定前缀（如：test）对象配置了一条桶清单规则，那么将不能再配置第二条针对指定前缀（如：te或test01）的桶清单规则。
清单存储桶	存储桶清单文件的桶（目标桶）。只能选择与源桶在同账号同区域下的桶。清单存储桶不能开启桶密码安全中心。
清单文件前缀	清单文件的存储路径前缀。清单文件生成后，将存储至清单存储桶的以下路径：清单文件前缀/源桶名/清单名称/日期时间/files/ 如不配置此参数，上述路径的一级目录“清单文件前缀”将由系统自动生成并命名为“BucketInventory”，此时清单文件将存储在清单存储桶的以下路径：BucketInventory/源桶名/清单名称/日期时间/files/。 *清单文件前缀不能以英文句号（.）或斜杠（/）开头或结尾，不能包含以下字符 : \:?"<>\|。** 输入示例：输入“obj”，清单文件将存储至以下路径：obj/源桶名/清单名称/日期时间/files/ 输入“obj/list”，清单文件将存储至以下路径：obj/list/源桶名/清单名称/日期时间/files/
生成频率	设定桶清单的生成频率。可选择每天或每周生成一次。源桶中文件数量很多（如：数百亿）时，建议选择每周生成一次桶清单文件，以此来降低成本。
清单状态	设置桶清单配置的状态。开启：表示按照相关设置生成桶清单。关闭：表示不生成桶清单。关闭桶清单后，已生成的桶清单仍然保留在目标桶中；重新开启桶清单后，将新生成桶清单，且不影响已生成的桶清单。

单击“下一步”，进入“报表配置”页面并设置相关参数。

图6 报表配置

设置“报表格式”相关参数。

表6 报表配置参数说明
参数	描述
清单格式	支持生成CSV格式的桶清单文件。
对象版本	桶清单文件中对象的版本，可以设置为“仅限当前版本”和“包含所有版本”。仅限当前版本：桶清单文件中仅包含当前版本对象的清单。包含所有版本：桶清单文件中包含当前版本和历史版本对象的清单。
清单额外字段	选择希望导出的对象信息，即桶清单文件中包含的对象信息。支持的字段有：文件大小：对象的大小，以“字节”为单位。上次修改时间：生成清单文件前，对象的最近一次修改日期。如果对象未被修改过，即为对象创建日期。是格林威治时间格式，转换为北京时间，需要加8小时。如：“2026-04-01T07:33:48Z”对应北京时间是“2026年4月1日 15:33:48”。存储类别：对象的存储类别。 STANDARD：标准存储 STANDARD_IA：即“WARM”，低频访问存储 GLACIER：即“COLD”，归档存储 DEEP_ARCHIVE：深度归档存储 ETag：ETag是对象内容的唯一标识，可以通过该值识别对象内容是否有变化。比如上传对象时ETag为A，下载对象时ETag为B，则说明对象内容发生了变化。当使用PUT上传时，ETag是对象的MD5哈希值。如果通过多段上传对象，则无论加密方法如何，MD5会拆分ETag，此类情况ETag就不是对象的MD5哈希值。 ETag只反映变化的内容，而不是其元数据。上传的对象或使用拷贝操作创建的对象，通过MD5加密后都有唯一的ETag。分段上传：对象是否是多段上传对象。 TRUE：对象采用了多段上传。 FALSE：对象没有采用多段上传。复制状态：对象的跨区域复制状态。 NOREP：对象没有被跨区域复制。 REP：对象被跨区域复制。加密状态：对象的加密状态。 SSE-KMS：对象的加密模式为SSE-KMS。 NOT-SSE：对象没有被加密或加密模式不是SSE-KMS。存储桶密钥：源桶的存储桶密钥状态。 DISABLED：源桶没有开启存储桶密钥。 ENABLED：源桶开启了存储桶密钥。 CRC64：按照ECMA-182标准计算的对象的64位无符号数编码的crc64值。crc64是对象内容的唯一标识，可以通过该值识别对象内容是否有变化。如果加密上传对象，crc64计算的是加密前的对象内容。

单击“下一步”，确认桶策略。

OBS将在桶清单存储桶上创建桶策略，以允许其将清单文件存入该桶。

如果桶清单存储桶中已存在该桶策略，则会使用已有的，而不会创建新的桶策略。
单击“确定”。

首次配置桶清单后，系统将在1小时内启动清单任务，生成桶清单文件；在之后的周期内，系统会按配置的生成频率定期生成桶清单文件。