帮你快速理解、总结文档立即下载
文档中心>API 中心>对象存储>Bucket 接口>清单（inventory）>周期性清单>PUT Bucket inventory

PUT Bucket inventory

最近更新时间：2026-03-27 18:01:35
我的收藏

本页目录：

功能描述

PUT Bucket inventory 用于在存储桶中创建清单任务，您可以对清单任务命名后，使用该请求创建清单任务，详细信息请参见 清单功能概述。
注意：
COS 支持在每个存储桶中创建最多1000条清单任务。
请确保您所使用的账号拥有目标存储桶的写入权限，以供 COS 将清单任务的结果文件写入该存储桶中。
调用该请求时，请确保您有足够的权限对存储桶的清单任务进行操作。存储桶所有者默认拥有该权限，若您无该项权限，请先向存储桶所有者申请该项操作的权限。授权流程请参见 使用方法。
如果您指定了清单投递的前缀，COS 后端会自动在您指定的前缀后边加上/。如您指定了 Prefix 作为前缀，则 COS 后端投递的清单报告路径为 Prefix/inventory_report。


授权说明

授权策略 中 action 设置为 cos:PutBucketInventory 。查看所有 action。

请求

请求示例

PUT /?inventory&id=inventory-configuration-ID HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: GMT Date
Authorization: Auth String
Content-MD5: MD5
说明：
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com，其中 <BucketName-APPID> 为带 APPID 后缀的存储桶名字，例如 examplebucket-1250000000，可参阅 存储桶概览 > 基本信息 和 存储桶概述 > 存储桶命名规范 文档；<Region> 为 COS 的可用地域，可参阅 地域和访问域名 文档。
Authorization: Auth String（详情请参见 请求签名 文档）。

请求参数

调用 PUT Bucket inventory 需要使用清单任务名称的参数。该参数格式如下：
参数
描述
类型
是否必选
id
清单任务的名称。缺省值：None
合法字符：a-z，A-Z，0-9，-，_，.
String
是

请求头

此接口仅使用公共请求头部，详情请参见 公共请求头部 文档。

请求体

用户在请求体中使用 XML 语言设置清单任务的具体配置信息。配置信息包括清单任务分析的对象，分析的频次，分析的维度，分析结果的格式及存储的位置等信息。 
<InventoryConfiguration>
    <Id>list1</Id>
    <IsEnabled>true</IsEnabled>
    <Destination>
        <COSBucketDestination>
            <Format>CSV</Format>
            <AccountId>100000000001</AccountId>
            <Bucket>qcs::cos:ap-guangzhou::examplebucket-1250000000</Bucket>
            <Prefix>list1</Prefix>
            <Encryption>
                <SSE-COS></SSE-COS>
            </Encryption>
        </COSBucketDestination>
    </Destination>
    <Schedule>
        <Frequency>Daily|Weekly|Monthly</Frequency>
        <MonthlyDate></MonthlyDate>
    </Schedule>
    <Filter>
        <Prefix>myPrefix</Prefix>
    </Filter>
    <IncludedObjectVersions>All</IncludedObjectVersions>
    <OptionalFields>
        <Field>Size</Field>
        <Field>LastModifiedDate</Field>
        <Field>ETag</Field>
        <Field>StorageClass</Field>
        <Field>IsMultipartUploaded</Field>
        <Field>ReplicationStatus</Field>
        <Field>Tag</Field>
        <Field>Crc64</Field>
        <Field>x-cos-meta-*</Field>
    </OptionalFields>
</InventoryConfiguration>
具体的节点描述如下：
节点名
父节点
描述
类型
是否必选
InventoryConfiguration
无
包含清单的配置参数
Container
是
Id
InventoryConfiguration
清单的名称，与请求参数中的 id 对应
String
是
IsEnabled
InventoryConfiguration
清单是否启用的标识：
如果设置为 true，清单功能将生效
如果设置为 false，将不生成任何清单
Boolean
是
IncludedObjectVersions
InventoryConfiguration
是否在清单中包含对象版本：
如果设置为 All，清单中将会包含所有对象版本，并在清单中增加 VersionId，IsLatest，DeleteMarker 这几个字段
如果设置为 Current，则清单中不包含对象版本信息
String
是
Filter
InventoryConfiguration
筛选待分析对象。清单功能将分析符合 Filter 中设置的前缀的对象
Container
否
And
Filter
筛选待分析对象时，如果同时需要前缀与对象标签条件，需要用 And 包装
Container
否
Prefix
And
需要分析的对象的前缀
String
否
Tag
And
筛选待分析对象时，可以用对象标签（支持多个）作为过滤条件
Container
否
Period
Filter
需要分析的对象的创建时间范围
Container
否
StartTime
Period
需要分析的对象创建的起始时间，参数为秒级时间戳，如1568688761
String
否
EndTime
Period
需要分析的对象创建的结束时间，参数为秒级时间戳，如1568688762
String
否
OptionalFields
InventoryConfiguration
设置清单结果中应包含的分析项目
Container
否
Field
OptionalFields
清单结果中可选包含的分析项目名称，可选字段包括：Size，LastModifiedDate，StorageClass，ETag，IsMultipartUploaded，ReplicationStatus，Tag，Crc64，x-cos-meta-*
注意，如果筛选条件里使用了对象标签，在这里也必须添加 Tag
此外，也支持用户填写x-cos-meta-*形式的自定义头部，如x-cos-meta-testheader。清单会将相应的对象元数据输出，若对象不包含该元数据，则为空。
String
否
Schedule
InventoryConfiguration
配置清单任务周期
Container
是
Frequency
Schedule
清单任务周期，可选项为按日、按周或按月，枚举值：Daily、Weekly、Monthly。其中，按月需要指定清单产出的日期
String
是
MonthlyDate
Schedule
如果清单任务周期选择了按月，需要明确指定清单产出的日期。支持填入 1～28 范围内的整数
Integer
否
Destination
InventoryConfiguration
描述存放清单结果的信息
Container
是
COSBucketDestination
Destination
清单结果导出后存放的存储桶信息
Container
是
Bucket
COSBucketDestination
清单分析结果的存储桶名
String
是
AccountId
COSBucketDestination
存储桶的所有者 UIN（主账号），例如100000000001。可在 账号信息 中查看
String
否
Prefix
COSBucketDestination
清单分析结果的前缀
String
否
Format
COSBucketDestination
清单分析结果的文件形式，可选项为 CSV 格式
String
是
Encryption
COSBucketDestination
为清单结果提供服务端加密的选项
Container
否
SSE-COS
Encryption
COS 托管密钥的加密方式，无需填充
Container
否

响应

响应头

此接口仅返回公共响应头部，详情请参见 公共响应头部 文档。

响应体

该请求的响应体返回为空。

错误码

此接口遵循统一的错误响应和错误码，详情请参见 错误码 文档。

实际案例

案例一：添加指定了对象前缀的清单任务

请求

该示例向存储桶 examplebucket-1250000000中添加一条名为 list1的清单任务。
该清单任务分析存储桶中前缀为 myPrefix 的对象及其所有版本。
分析频次为每天一次。
分析维度包括 Size ， LastModifiedDate， StorageClass，ETag，IsMultipartUploaded， ReplicationStatus。
分析结果将以 CSV 格式文件存储在存储桶 examplebucket-1250000000中，文件添加前缀 list1且用 SSE-COS 加密。
PUT /?inventory&id=list1 HTTP/1.1
Date: Mon, 28 Aug 2018 02:53:38 GMT
Authorization: q-sign-algorithm=sha1&q-ak=************************************&q-sign-time=1503888878;1503889238&q-key-time=1503888878;1503889238&q-header-list=host&q-url-param-list=inventory&q-signature=****************************************
Content-MD5: AAq9nzrpsz5LJ4UEe1f6Q==
Host: examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com
Content-Length: 1024

<?xml version = "1.0" encoding = "UTF-8">
<InventoryConfiguration xmlns = "http://....">
    <Id>list1</Id>
    <IsEnabled>true</IsEnabled>
    <Destination>
        <COSBucketDestination>
            <Format>CSV</Format>
            <AccountId>100000000001</AccountId>
            <Bucket>qcs::cos:ap-guangzhou::examplebucket-1250000000</Bucket>
            <Prefix>list1</Prefix>
            <Encryption>
                <SSE-COS></SSE-COS>
            </Encryption>
        </COSBucketDestination>
    </Destination>
    <Schedule>
        <Frequency>Daily</Frequency>
    </Schedule>
    <Filter>
        <Prefix>myPrefix</Prefix>
        <Period>
            <StartTime>1568688761</StartTime>
            <EndTime>1568688762</EndTime>
        </Period>
    </Filter>
    <IncludedObjectVersions>All</IncludedObjectVersions>
    <OptionalFields>
        <Field>Size</Field>
        <Field>LastModifiedDate</Field>
        <Field>ETag</Field>
        <Field>StorageClass</Field>
        <Field>IsMultipartUploaded</Field>
        <Field>ReplicationStatus</Field>
    </OptionalFields>
</InventoryConfiguration>

响应

上述请求后，COS 返回以下响应，表明该清单任务 list1已经成功设置完毕。
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 0
Date: Mon, 28 Aug 2018 02:53:38 GMT
Server: tencent-cos
x-cos-request-id: NTlhMzg1ZWVfMjQ4OGY3MGFfMWE1NF8****

案例二：添加指定了对象前缀和对象标签的清单任务

请求

该示例向存储桶examplebucket-1250000000中添加一条名为 list2的清单任务。
该清单任务分析存储桶中前缀为 myPrefix ，且有对象标签含有{age:18}的对象及其所有版本。
分析频次为每天一次。
分析维度包括 Size ，LastModifiedDate，StorageClass，ETag，Tag。
分析结果将以 CSV 格式文件存储在存储桶 inventorybucket-1250000000 中。
PUT /?inventory&id=list2 HTTP/1.1
Date: Mon, 28 Aug 2018 02:53:38 GMT
Authorization: q-sign-algorithm=sha1&q-ak=************************************&q-sign-time=1503888878;1503889238&q-key-time=1503888878;1503889238&q-header-list=host&q-url-param-list=inventory&q-signature=****************************************
Content-MD5: AAq9nzrpsz5LJ4UEe1f6Q==
Host: examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com
Content-Length: 1024

<?xml version = "1.0" encoding = "UTF-8">
<InventoryConfiguration xmlns = "http://....">
    <Id>list2</Id>
    <IsEnabled>true</IsEnabled>
    <Destination>
        <COSBucketDestination>
            <Format>CSV</Format>
            <AccountId>100000000001</AccountId>
            <Bucket>qcs::cos:ap-guangzhou::inventorybucket-1250000000</Bucket>
        </COSBucketDestination>
    </Destination>
    <Schedule>
        <Frequency>Daily</Frequency>
    </Schedule>
    <Filter>
        <And>
            <Prefix>myPrefix</Prefix>
            <Tag>
                <Key>age</Key>
                <Value>18</Value>
            </Tag>
        </And>
    </Filter>
    <IncludedObjectVersions>All</IncludedObjectVersions>
    <OptionalFields>
        <Field>Size</Field>
        <Field>LastModifiedDate</Field>
        <Field>StorageClass</Field>
        <Field>ETag</Field>
        <Field>Tag</Field>
    </OptionalFields>
</InventoryConfiguration>

响应

上述请求后，COS 返回以下响应，表明该清单任务 list2已经成功设置完毕。
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 0
Date: Mon, 28 Aug 2018 02:53:38 GMT
Server: tencent-cos
x-cos-request-id: NTlhMzg1ZWVfMjQ4OGY3MGFfMWE1NF8****

案例三：清单支持输出对象的自定义头部

请求

该示例向存储桶examplebucket-1250000000中添加一条名为 list3的清单任务。
该清单任务分析存储桶中前缀为 myPrefix ，且有对象标签含有{age:18}的对象及其所有版本。
分析频次为每天一次。
分析维度包括 Size ， LastModifiedDate， StorageClass，ETag，Tag，x-cos-meta-myheader。
分析结果将以 CSV 格式文件存储在存储桶 inventorybucket-1250000000 中。
PUT /?inventory&id=list2 HTTP/1.1
Date: Mon, 28 Aug 2018 02:53:38 GMT
Authorization: q-sign-algorithm=sha1&q-ak=************************************&q-sign-time=1503888878;1503889238&q-key-time=1503888878;1503889238&q-header-list=host&q-url-param-list=inventory&q-signature=****************************************
Content-MD5: AAq9nzrpsz5LJ4UEe1f6Q==
Host: examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com
Content-Length: 1024

<?xml version = "1.0" encoding = "UTF-8">
<InventoryConfiguration xmlns = "http://....">
    <Id>list2</Id>
    <IsEnabled>true</IsEnabled>
    <Destination>
        <COSBucketDestination>
            <Format>CSV</Format>
            <AccountId>100000000001</AccountId>
            <Bucket>qcs::cos:ap-guangzhou::inventorybucket-1250000000</Bucket>
        </COSBucketDestination>
    </Destination>
    <Schedule>
        <Frequency>Daily</Frequency>
    </Schedule>
    <Filter>
        <And>
            <Prefix>myPrefix</Prefix>
            <Tag>
                <Key>age</Key>
                <Value>18</Value>
            </Tag>
        </And>
    </Filter>
    <IncludedObjectVersions>All</IncludedObjectVersions>
    <OptionalFields>
        <Field>Size</Field>
        <Field>LastModifiedDate</Field>
        <Field>StorageClass</Field>
        <Field>ETag</Field>
        <Field>Tag</Field>
        <Field>Crc64</Field>
        <Field>x-cos-meta-myheader</Field>
    </OptionalFields>
</InventoryConfiguration>

响应

上述请求后，COS 返回以下响应，表明该清单任务 list3已经成功设置完毕。
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 0
Date: Mon, 28 Aug 2018 02:53:38 GMT
Server: tencent-cos
x-cos-request-id: NTlhMzg1ZWVfMjQ4OGY3MGFfMWE1NF8****

中国站