什么是清单
清单是一种帮助用户管理存储桶中对象的功能，可以有计划地取代对象存储同步 List API 操作。对象存储（Cloud Object Storage，COS）可根据用户的清单任务配置，每天、每周或每月定时扫描用户存储桶内指定的对象或拥有相同对象前缀的对象，并输出一份清单报告，以 CSV 格式的文件存储到用户指定的存储桶中。也支持发起一次性清单任务，立刻产出一份清单报告。文件中会列出存储的对象及其对应的元数据，并根据用户的配置信息，记录用户所需的对象属性信息。
您可以使用清单功能实现包括但不限于以下基本用途：
审核并报告对象的复制和加密状态。
简化并加快业务工作流和大数据作业。
注意：
用户可以在一个存储桶中配置多个清单任务，清单任务执行过程中并不会直接读取对象内容，仅扫描对象元数据等属性信息。
目前暂不支持金融云地域。
如需通过子账号设置清单，请确保子账号已被主账号授予
cos:PutBucketInventory 和 cos:PutObject 操作权限。清单参数
用户配置一项清单任务后，COS 将根据配置定时扫描用户存储桶内指定的对象，并输出一份清单报告，清单报告支持 CSV 格式文件。目前 COS 清单报告中支持记录以下信息：
清单信息 | 描述 |
AppID | 账号的 ID |
Bucket | 执行清单任务的存储桶名称 |
fileFormat | 文件格式 |
listObjectCount | |
listStorageSize | 列出的对象大小 |
filterObjectCount | 筛选的对象数量 |
filterStorageSize | 筛选的对象大小 |
Key | 存储桶中的对象文件名称。使用 CSV 文件格式时，对象文件名称采用 URL 编码形式，必须解码然后才能使用 |
VersionId | 对象版本 ID。在存储桶上启用版本控制后，COS 会为添加到存储桶的对象指定版本号。如果列表仅针对对象的当前版本，则不包含此字段 |
IsLatest | 如果对象的版本为最新，则设置为 True。如果列表仅针对对象的当前版本，则不包含此字段 |
IsDeleteMarker | 如果对象是删除标记，则设置为 True。如果列表仅针对对象的当前版本，则不包含此字段 |
Size | 对象大小（以字节 Byte 为单位） |
LastModifiedDate | 对象的最近修改日期（以日期较晚者为准） |
ETag | 实体标签是对象的哈希。ETag 仅反映对对象的内容的更改，而不反映对对象的元数据的更改。ETag 可能是也可能不是对象数据的 MD5 摘要。是与不是取决于对象的创建方式和加密方式 |
StorageClass | 用于存储对象的存储类，有关更多信息，请参见 存储类型 |
IsMultipartUploaded | 如果对象以分块上传形式上传，则设置为 True，有关更多信息，请参见 分块上传 |
Replicationstatus | 用于标记对象复制中源端文件和副本文件的状态。源端文件标记：PENDING（待复制）、COMPLETED（复制完成）、FAILED（复制失败）；副本文件标记：REPLICA（已完成复制，生成副本文件）。有关更多信息，请参见 复制行为说明 |
Tag | 对象的标签 |
Crc64 | 对象的CRC64信息。 |
x-cos-meta-* | 对象的自定义元数据信息，例如 x-cos-meta-testheader。清单会将相应的对象元数据输出，若对象不包含该元数据，则为空。 |
周期性清单和一次性清单
清单支持两种类型：周期性清单和一次性清单。
周期性清单：支持用户设置好清单规则后，按月、按周或按天产出清单报告。其中，按月需要指定产出的日期（支持设置1～28日），按周的情况下，规则是周几配置的后续则继续按照周几产出。
一次性清单：发起一次性清单任务，产出一次报告。当前 COS 不支持对一次性清单任务进行记录查询，因此请注意保存好发起任务的规则 id、清单存储路径等信息，方便后续查找清单报告。
如何配置清单
在配置清单前，您需要了解两个概念：
源存储桶：想要开通清单功能的存储桶。
包含清单中所列出的对象。
包含清单的配置。
目标存储桶：存储清单的存储桶。
包含清单列表文件。
包含 Manifest 文件，描述清单列表文件的位置。
配置清单主要分为以下步骤：
指定源存储桶中待分析的对象信息
您需要告知 COS 您需要分析哪一些对象信息。因此，在配置清单功能时，需要在源存储桶中配置以下信息：
选择对象版本：列出所有对象版本或者仅列出当前版本。若您选择了列出所有对象版本，则 COS 将会把您同名对象的所有历史版本均列入清单报告中，仅选择当前版本，则 COS 仅会记录您的最新版本对象。
配置所需分析的对象属性：您需要告知 COS 需要将对象属性中的哪些信息记录到清单报告中，目前支持的对象属性包括账号 ID，源存储桶名称，对象文件名称，对象版本 ID、是否最新版本、是否删除标记，对象大小，对象最新修改日期，ETag，对象的存储类，跨地域复制标记以及是否属于分块上传文件。
配置清单报告的存储信息
您需要告知 COS 按照何种频率导出清单报告，清单报告要存储至哪个存储桶中，并决定是否需要对清单报告进行加密，需要配置信息如下：
选择清单导出频率：每日或者每周。您可以通过此配置告知 COS 应该按照何种频率执行清单功能。
选择清单加密：不加密或者 SSE-COS。如您选择了 SSE-COS 加密，我们将会对生成的清单报告进行加密。
配置清单的输出位置：您需要指定清单报告需要存储的存储桶。
注意：
目标存储桶必须和源存储桶位于同一地域，两者可以是同一存储桶。
使用方法
通过控制台配置清单
添加定时清单
1. 登录 对象存储控制台。
2. 在左侧导航栏中，单击存储桶列表。
3. 单击进入想要开通清单功能的存储桶（源存储桶）。
4. 在左侧导航栏中，选择基础配置 > 清单设置，单击添加清单。
5. 在配置页面您可以进行以下配置：
5.1 基础信息
规则状态：是否开启当前清单规则。您可以选择开启/关闭清单。
清单名称：输入您的清单名称。
目标存储桶：是指存储清单的存储桶，初始默认目标存储桶即源存储桶，目标存储桶必须与源存储桶处于同一地域。
清单报告前缀（选填）：输入为目标存储桶选择的前缀，可对公共位置的清单文件进行分组，初始为默认值。
清单报告生成路径：是指清单报告的生成路径。
5.2 筛选条件
文件范围：选择清单对象的范围，可选择整个存储桶或者部分相同前缀的文件。例如选择存储桶中 folder 路径下的 doc 路径的所有文件，则指定文件前缀为
folder/doc。对象版本：选择清单要包含对象的所有版本还是仅当前版本。如不选择，默认只保留当前版本。
筛选标签（选填）：通过筛选将标签相同的对象列入清单。若不填写，默认不筛选。
筛选时间（选填）：通过筛选将修改时间为某时间点后或某时间段内的对象列入清单。若不设置，默认不筛选。
筛选存储类型（选填）：通过筛选将指定存储类型（如有）的对象列入清单，关于存储类型的介绍，请参见 存储类型概述。若不设置，默认不筛选。
输出自定义头部（选填）：如需清单报告中包含对象的自定义头部，可填入需输出的自定义头部，仅支持输出 x-cos-meta-* 头部。若不填写，则默认不输出自定义头部。
清单信息：选择清单报告需要包含的对象的相应信息，可选项有：大小、存储类型、ETag、存储桶复制状态、分块上传状态、最新更新日期、标签、CRC64。若不选择，默认全选。
说明：
ETag（实体标签）是对象的哈希，ETag 仅反映对对象内容的更改，而不反映对其元数据的更改。ETag 不一定是对象数据的 MD5 摘要，这取决于对象的创建方式和加密方式。
生成的清单内容默认包含 Appid、Bucket、Key、LastModifiedTime 字段内容。
如果存储桶已开启版本控制，则生成的清单内容会增加 VersionId、IsLatest、IsDeleteMarker 字段内容。
5.3 输出格式
输出格式：输出清单文件格式为使用 GZIP 压缩的 CSV 文件。
生成周期：支持按照每日/每周/每月进行生成，默认每日生成。清单的具体生成时间取决于数据量大小，配置说明如下：
每日：例如当天下午15点添加了清单，通常最晚于次日的6点生成清单文件并投递至目标存储桶。
每周：默认以7天为周期生成清单。例如9月1日开启清单，第一份清单会在9月2日生成，之后会在 9月9日、 9月16日、9月23日…，以7天为周期生成清单。
每月：可指定每月1号-28号任意一天生成清单。清单生成逻辑如下：
若创建清单的当前日<指定日，将会在当前月的指定日期生成。
例如，9月8日开启清单，并指定每月25号生成，第一份清单会在9月25日生成，之后会在10月25日、11月25日、12月25日…，以月为周期生成清单。
若创建清单的当前日>=指定日，将会在下个月的指定日期生成。
例如，9月8日开启清单，并指定每月3号生成，第一份清单会在10月3日生成，之后会在11月3日、12月3日…，以月为周期生成清单。
清单加密：选择清单是否需要服务端加密，您可选择：
不加密：不加密清单，此项为默认项。
SSE-COS：使用 COS 托管密钥的服务端加密来加密报告，有关更多信息，请参见对象存储开发者指南中的 SSE-COS 加密。
访问授权：默认关闭。开启访问授权后，即可进行下一步操作。
5.4 信息确认
5.5 对存储桶的清单配置信息进行确认。如需修改，单击上一步即可。
6. 确认配置信息无误后，单击确定即可。此后 COS 将按照所设周期自动生成清单文件并投递到您所设置的目标存储桶。
说明：
7. 创建成功后，清单将投递至指定路径，即5.1的清单报告生成路径。更多请参见 清单报告存储路径。
生成即时清单
说明：
如果希望立即执行已创建的清单规则，可选择生成即时清单。
1. 登录 对象存储控制台。
2. 在左侧导航栏中，单击存储桶列表，然后单击进入已创建清单规则的存储桶（源存储桶）。
3. 单击左侧基础配置 > 清单设置，找到对应的清单规则，并单击右侧的更多 > 立即执行，即可快速生成清单。
4. 创建成功后，即时清单将投递至指定路径，即当前定时清单规则已配置的清单报告生成路径。
预览清单
1. 登录 对象存储控制台。
2. 在左侧导航栏中，单击存储桶列表，然后单击进入已创建清单规则的存储桶（源存储桶）。
3. 单击左侧 基础配置 > 清单设置，找到对应的清单规则，并单击 更多 > 预览清单 快捷查看清单结果。
4. 预览清单页面会展示当前规则下生成的所有清单，包括定时清单和即时清单。您可以一键前往清单目录和查看清单结果，并支持筛选日期、清单类型。
注意：
发起清单任务后，清单结果会逐步更新，待清单目录下的 manifest.json 文件生成之后，清单结果才会完全生成。
5. 日期选择完成后，在清单目录名一列，单击某个目录会快捷跳转至该目录，您可查看生成的清单内容。更多说明请参见 清单报告存储路径。
6. 若需要直接查看清单结果，在操作一列单击查看清单结果，即可看到您配置的筛选条件下的对象总数和大小。更多详细清单信息，支持点击下载进行解压查看。
7. 下载后的 CSV 文件对应的字段名称可在 manifest.json 文件的“fileSchema”中查看，更多字段含义和描述请参见 清单参数。
通过 API 配置清单
使用 API 为指定存储桶开启清单功能时，请参考以下步骤：
1. 创建 COS 角色。
2. COS 角色绑定权限。
3. 开启清单功能。
1. 创建 COS 角色
{"version": "2.0","statement": [{"action": "name/sts:AssumeRole","effect": "allow","principal": {"service": "cos.cloud.tencent.com"}}]}
2. COS 角色绑定权限
角色权限绑定权限，具体接口信息参见 AttachRolePolicy。
其中，policyName 为：QcloudCOSFullAccess，roleName 为第1步中的 COS_QcsRole，也可以使用创建 roleName 时返回的 roleID。
3. 开启清单功能
存放清单文件的目标存储桶和源存储桶需要在同一地域，调用接口，开启清单功能，具体接口信息如下：
周期性清单
配置周期性清单：PUT Bucket inventory
查看周期性清单规则：GET Bucket Inventory
删除周期性清单规则：DELETE Bucket Inventory
列出周期性清单规则：LIST Bucket Inventory
发起一次性清单任务： POST Bucket Inventory
清单报告存储路径
清单报告及相关的 Manifest 相关文件会发布在目标存储桶中，其中清单报告会发布在以下路径：
destination-prefix/appid/source-bucket/config-ID/Manifest 相关文件会发布在目标存储桶以下路径：
destination-prefix/appid/source-bucket/config-ID/YYYYMMDD/manifest.jsondestination-prefix/appid/source-bucket/config-ID/YYYYMMDD/manifest.checksum注意：
发起清单任务后，清单结果会逐步更新，待清单目录下的 manifest.json 文件生成之后，清单结果才会完全生成。
路径中所代表的含义如下：
destination-prefix：是用户在配置清单时设置的“目标前缀”，可用于对目标存储桶中的公共位置的所有清单报告进行分组。
source-bucket：是清单报告对应的源存储桶名称，加入这个文件夹是为了避免在多个源存储桶将各自清单报告发送至同一目标存储桶时可能造成的冲突。
config-ID：是用户在配置清单时设置的“清单名称”，当同一源存储桶设置多个清单报告并将其发送至同一目标存储桶时，可以用 config-ID 区分不同的清单报告。
YYYYMMDD：时间戳，包含生成清单报告时开始存储桶扫描的时间和日期。
manifest.json：指 Manifest 文件。
manifest.checksum：指 manifest.json 文件内容的 MD5。
其中，Manifest 相关文件总共包含两份文件 manifest.json 和 manifest.checksum。
说明：
有关 Manifest 文件的介绍如下：
manifest.json 和 manifest.checksum 都属于 Manifest 文件，manifest.json 描述清单报告的位置，manifest.checksum 是作为 manifest.json 文件内容的 MD5。每次交付新的清单报告时，均会带有一组新的 Manifest 文件。
manifest.json 包含的每个 Manifest 均提供了有关清单的元数据和其他基本信息，这些信息包括：
源存储桶名称。
目标存储桶名称。
清单版本。
时间戳，包含生成清单报告时开始扫描存储桶的日期与时间。
清单文件的格式与架构。
目标存储桶中清单报告的对象键，大小及 md5Checksum。
以下是 CSV 格式清单的 manifest.json 文件中的 Manifest 示例：
{"sourceAppid": "1250000000","sourceBucket": "example-source-bucket","destinationAppid": "1250000000","destinationBucket": "example-inventory-destination-bucket","fileFormat": "CSV","listObjectCount": "13","listStorageSize": "7212835","filterObjectCount": "13","filterStorageSize": "7212835","fileSchema": "Appid, Bucket, Key, Size, LastModifiedDate, ETag, StorageClass, IsMultipartUploaded, ReplicationStatus","files": [{"key": "cos_bucket_inventory/1250000000/examplebucket/inventory01/04d73d9debc73d9f0bf85af461abde6c.csv.gz","size": "502","md5Checksum": "7d40288a09c25b302ad6cb5fced54f35"}]}
清单一致性
COS 的清单报告提供了新对象和覆盖的 PUT 的最终一致性，并提供了 DELETE 的最终一致性，因此清单报告中可能不包含最近添加或删除的对象。例如，COS 在执行用户配置的清单任务的过程中时，用户执行了上传或删除对象的操作，则这些操作的结果可能不被反映在清单报告中。
