存储清单介绍

用户可以使用对象存储KS3 的存储清单功能获取存储空间（Bucket）中指定文件（Object）的数量、大小、存储类型、加密状态等信息。相对于GetBucket (ListObjects)接口，在海量文件的列举场景中，建议优先使用存储清单功能。

注意：为避免影响KS3-HDFS服务的正常使用或者引发数据污染的风险，开通了KS3-HDFS服务的Bucket 尽量不要设置为存储清单规则的目标Bucket。

清单文件

清单任务配置完成后，KS3会按清单规则指定的导出周期生成清单文件。清单文件的目录结构如下所示：

destination-Bucket
 └──destination-prefix/
     └──src_bucket/
         └──inventory_name/
             ├──YYYY-MM-DDTHH-MMZ/
             │   ├──manifest.json
             │   └──manifest.checksum
             └──data/
                 ├──inventory-1.csv.gz
                 ├──inventory-2.csv.gz
                 └──inventory-3.csv.gz

目录	说明
destination-prefix/	该目录根据设置的清单报告名前缀生成，如果清单报告名前缀设置为空，将省略该目录。
src_bucket/	该目录根据配置清单报告的源Bucket名称生成。
inventory_name/	该目录根据清单任务的名称生成 。
YYYY-MM-DDTHH-MMZ//	该目录是标准的格林威治时间戳，表示开始扫描Bucket的时间，例如2023-03-31T16-00Z。 该目录下包含了manifest.json和manifest.checksum文件。
data/	该目录下存放了清单文件，清单文件格式为使用GZIP压缩的CSV文件。
文件名称 csv.gz	当导出的源Bucket中Object数量较多时，为方便用户下载和处理数据，程序会自动将清单文件切分成多个CSV压缩文件。CSV压缩文件按照inventoryuuid.csv.gz、inventoryuuid-1.csv.gz、inventoryuuid-2.csv.gz的顺序依次递增。您可以从manifest.json文件中获取CSV文件列表，然后按照以上顺序依次解压CSV文件并读取清单数据。 Object的单条记录信息仅出现在一个清单文件内，不会分布到不同的清单文件。

清单功能生成的具体文件如下：

• manifest文件

manifest文件包含manifest.json 和 manifest.chenksum，详细说明如下：

1. manifest.json：提供了有关清单的元数据和其他基本信息。

{
    "creationTimestamp": "1642994594",
    "destinationBucket": "example-dest-bucket",
    "fileFormat": "CSV",
    "fileSchema": "Bucket, Key, Size, StorageClass, LastModifiedDate, ETag, IsMultipartUploaded, EncryptionStatus",
    "listObjectCount": "12",
    "listStorageSize": "7212835",
    "filterObjectCount": "13",
    "filterStorageSize": "7212835",
    "files": [
            {
            "MD5checksum": "F77449179760C3B13F1E76110F07****",
            "key": "example-dest-bucket/example-inventory/data/a1574226b5e540ee91df356845777c04-1.csv.gz",
            "size": "2046"},
            {
            "MD5checksum": "F77449179760C3B13F1E76110F07****",
            "key": "example-dest-bucket/example-inventory/data/a1574226b5e540ee91df356845777c04-2.csv.gz",
            "size": "2046"}],
    "sourceBucket": "example-src-bucket",
    "version": "2022-12"}

各字段详细说明如下：

字段名称	描述	示例
creationTimestamp	时间戳，显示开始扫描源Bucket的时间 单位：ms	1680071580356
destinationBucket	存储清单文件的目标Bucket	example-dest-bucket
fileFormat	清单文件的格式	CSV
fileSchema	清单文件包含的字段	Bucket, Key, Size, StorageClass, LastModifiedDate, ETag, IsMultipartUploaded, EncryptionStatus
listObjectCount	扫描文件的数量	12
listStorageSize	扫描文件的总大小 单位：Byte	7212835
filterObjectCount	符合要求被过滤的文件数量	12
filterStorageSize	符合要求被过滤的文件总大小 单位：Byte	7212835
files	包含清单文件的文件名完整路径、大小、MD5值。如果存在多个清单文件，则包含多个清单文件信息组	“MD5checksum”: “F77449179760C3B13F1E76110F07****” “key”: “destbucket/example-inventory4/data/a1574226-b5e5-40ee-91df356845777c04.csv.gz” “size”: “2046”
sourceBucket	配置清单规则的源Bucket	example-src-bucket
version	清单功能版本号	2022-12

2. manifest.checksum：包含manifest.json文件的MD5值，例如：F77449179760C3B13F1E76110F07****。

• 清单报告

用户配置一项清单任务后，KS3 将根据配置定时扫描用户存储桶内指定的对象，并输出一份清单报告，清单报告支持 CSV 、Parquet、ORC格式文件。目前 KS3 清单报告中支持记录以下信息：

字段名称	说明
Bucket	执行清单任务的源Bucket名称
Key	Bucket中Object的名称。使用CSV文件时，Object名称使用URL编码，需要解码后进行查看
Size	Object大小
StorageClass	Object的存储类型
LastModifiedDate	Object的最后修改时间
ETag	Object的ETag，Object生成时会创建相应的ETag，用于标识一个Object的内容 通过简单上传创建的Object，ETag值是其内容的MD5值 通过其他方式创建的Object，ETag值是基于一定计算规则生成的唯一值，但不是其内容的MD5值
IsMultipartUploaded	Object是否通过分片上传生成。如果是，则该字段值为True，否则为False
EncryptionStatus	Object是否已加密。若Object已加密，则该字段值为True，否则为False

注意事项

开通说明

• 需通过控制台指引，跳转至授权服务页进行授权，如果没有进行授权，日志文件无法投递成功。

带宽流量说明

• 在清单文件列表导出到目标Bucket的过程中，可能会占用一定的带宽。如果存放清单文件列表的目标Bucket与配置清单任务的源Bucket相同，且源Bucket存在流量较大带宽紧张的情况，为保障较快的清单文件列表导出速度，建议新建一个目标Bucket用于存放清单文件。

配置建议说明

• 当文件数量小于100亿时，可根据自己的业务需要，设置清单规则。
• 当文件数量大于100亿时，建议以prefix维度设置清单规则。

清理清单文件说明

• 在删除清单规则前，KS3会根据清单规则中的设置，仅一次或以周为周期导出清单文件。为避免导出不必要的清单文件，可以及时删除不再需要的清单规则。对于已导出且不再需要的存量清单文件，也可以及时清理。

特殊情况说明

• 如果源Bucket没有任何文件，或清单任务设置的prefix没有匹配到任何文件，则不会生成清单文件。

• 导出清单文件的过程中，由于Object的创建、删除或覆盖等操作，可能会导致最终输出的清单列表中不一定包含所有的Object。最后修改时间早于manifest.json文件中creationTimestamp字段显示时间的Object会出现在清单文件中，最后修改时间晚于creationTimestamp字段显示时间的Object可能不会出现在清单文件中。

约束与限制

• 对于单个Bucket，通过KS3管理控制台最多可配置10条清单规则。

• 配置清单的源Bucket与存放清单文件的目标Bucket可以相同也可以不同，但是必须属于同一账号下的相同地域。

• 因ID/id为KS3保留字段，除通过API进行清单操作(Put/Get/Delete/List)时，请勿使用该字段作为业务参数。

计费说明

• 使用Bucket清单功能会产生一定的费用，包含：

  • 存储清单功能费用：以清单列出文件数量进行计费
  • API请求费用和清单文件存储费用

• 在删除清单规则前，KS3会按照清单规则持续生成清单文件，会产生一定的存储费用。为避免产生不必要的费用，请及时清理不再需要的清单文件。