tencent cloud

对象存储

动态与公告
产品动态
产品公告
产品简介
产品概述
功能概览
应用场景
产品优势
基本概念
地域和访问域名
规格与限制
产品计费
计费概述
计费方式
计费项
免费额度
计费示例
查看和下载账单
欠费说明
常见问题
快速入门
控制台快速入门
COSBrowser 快速入门
用户指南
创建请求
存储桶
对象
数据管理
批量处理
全球加速
监控与告警
运维中心
数据处理
内容审核
智能工具箱
数据工作流
应用集成
工具指南
工具概览
环境安装与配置
COSBrowser 工具
COSCLI 工具
COSCMD 工具
COS Migration 工具
FTP Server 工具
Hadoop 工具
COSDistCp 工具
HDFS TO COS 工具
GooseFS-Lite 工具
在线辅助工具
自助诊断工具
实践教程
概览
访问控制与权限管理
性能优化
使用 AWS S3 SDK 访问 COS
数据容灾备份
域名管理实践
图片处理实践
COS 音视频播放器实践
工作流实践
数据直传
内容审核实践
数据安全
数据校验
大数据实践
COS 成本优化解决方案
在第三方应用中使用 COS
迁移指南
本地数据迁移至 COS
第三方云存储数据迁移至 COS
以 URL 作为源地址的数据迁移至 COS
COS 之间数据迁移
Hadoop 文件系统与 COS 之间的数据迁移
数据湖存储
云原生数据湖
元数据加速
数据加速器 GooseFS
数据处理
数据处理概述
图片处理
媒体处理
内容审核
文件处理
文档处理
故障处理
获取 RequestId 操作指引
通过外网上传文件至 COS 缓慢
访问 COS 时返回403错误码
资源访问异常
POST Object 常见异常
API 文档
简介
公共请求头部
公共响应头部
错误码
请求签名
操作列表
Service 接口
Bucket 接口
Object 接口
批量处理接口
数据处理接口
任务与工作流
内容审核接口
云查毒接口
SDK 文档
SDK 概览
准备工作
Android SDK
C SDK
C++ SDK
.NET(C#) SDK
Flutter SDK
Go SDK
iOS SDK
Java SDK
JavaScript SDK
Node.js SDK
PHP SDK
Python SDK
React Native SDK
小程序 SDK
错误码
鸿蒙(Harmony) SDK
终端 SDK 质量优化
安全与合规
数据容灾
数据安全
访问管理
常见问题
热门问题
一般性问题
计费计量问题
域名合规问题
存储桶配置问题
域名和 CDN 问题
文件操作问题
日志监控问题
权限管理问题
数据处理问题
数据安全问题
预签名 URL 问题
SDK 类问题
工具类问题
API 类问题
服务协议
Service Level Agreement
隐私政策
数据处理和安全协议
联系我们
词汇表
文档对象存储API 文档Bucket 接口 清单（inventory）一次性清单POST Bucket inventory

POST Bucket inventory

PDF
聚焦模式
字号
最后更新时间： 2025-12-09 11:20:25

功能描述

POST Bucket inventory 用于在一个存储桶中创建一个一次性清单任务。通过使用此接口，您能够以更加灵活的方式获取到存储桶中的对象清单，进而更精细化地管理对象。
注意：
您必须在目标存储桶中写入存储桶策略，以供 COS 将清单任务的结果文件写入该存储桶中。
调用该请求时，请确保您有足够的权限对存储桶的清单任务进行操作。存储桶所有者默认拥有该权限，若您无该项权限，请先向存储桶所有者申请该项操作的权限。
如果您指定了清单投递的前缀，COS 后端会自动在您指定的前缀后边加上/。如您指定了Prefix作为前缀，则 COS 后端投递的清单报告路径为Prefix/inventory_report。
在清单任务未完成前，再次重复提交相同 id 的清单任务，或者使用与周期性清单任务相同的 id，服务端会返回重复清单任务的错误。
调用 POST Bucket inventory 创建清单任务后将立即开始执行，每个任务只会执行一次，而不会周期性地重复执行。如需周期性导出清单文件，请使用 PUT Bucket inventory 接口。

请求

请求示例

POST /?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（详情请参见 请求签名 文档）。

请求参数

调用 POST Bucket inventory 需要使用清单任务名称的参数。该参数格式如下：
参数
描述
类型
是否必选
id
清单任务的名称。缺省值：None
合法字符：a-z，A-Z，0-9，-，_，.
注意：清单任务 id 建议不要与周期清单任务 id 相同。同一天内不允许提交重复的 id，否则会返回失败。
String
是

请求头

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

请求体

用户在请求体中使用 XML 语言设置清单任务的具体配置信息，示例如下：
注意：
区别于传统的周期任务形式的清单规则，一次性清单不允许携带 IsEnabled、Schedule 参数。
其余参数与 PUT Bucket inventory 完全一致。
一次性清单报告存储路径与周期性清单一致，详情请参见 清单报告存储路径。
<InventoryConfiguration>
    <Id>inventory-id</Id>
    <Destination>
        <COSBucketDestination>
            <Format>CSV</Format>
            <AccountId>100000000001</AccountId>
            <Bucket>qcs::cos:ap-guangzhou::examplebucket-1250000000</Bucket>
            <Prefix>cos_bucket_inventory</Prefix>
            <Encryption>
                <SSE-COS></SSE-COS>
            </Encryption>
        </COSBucketDestination>
    </Destination>
    <Filter>
        <And>
            <Prefix>myPrefix</Prefix>
            <Tag>
                <Key>string</Key>
                <Value>string</Value>
            </Tag>
        </And>
    </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>

响应

响应头

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

响应体

发起一次性清单任务成功后，会返回 JobId 信息。
<PostInventoryResult>
    <JobId>Dgesgeqzd0dd***==</JobId>
</PostInventoryResult>
具体内容描述如下：
节点名
父节点
描述
类型
PostInventoryResult
无
一次性清单发起成功后的返回。
Container
JobId
PostInventoryResult
一次性清单任务发起成功后，会返回 JobId 信息
String

错误码

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

实际案例

案例：使用特定前缀过滤对象生成一次性清单

请求

该示例向存储桶examplebucket-1250000000中发起一条清单任务。
该清单任务分析存储桶中前缀为 myPrefix，且对象标签含有{age:18}的对象及其所有版本。
分析维度包括 Size，LastModifiedDate，StorageClass，ETag，Tag。
分析结果将以 CSV 格式文件存储在存储桶 inventorybucket-1250000000 中。
假设清单发起时间为2022年11月20日，清单 Manifest 相关文件会发布在目标存储桶以下路径。
cos_bucket_inventory/1250000000/examplebucket/disposable/20221120/manifest.json
cos_bucket_inventory/1250000000/examplebucket/disposable/20221120/manifest.checksum
POST /?inventory&id=disposable 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>disposable</Id>
    <Destination>
        <COSBucketDestination>
            <Format>CSV</Format>
            <AccountId>100000000001</AccountId>
            <Bucket>qcs::cos:ap-guangzhou::inventorybucket-1250000000</Bucket>
            <Prefix>cos_bucket_inventory</Prefix>
        </COSBucketDestination>
    </Destination>
    <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 返回以下响应，表明该清单任务已经成功提交。
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****

<PostInventoryResult>
    <JobId>Dgesgeqzd0dd***==</JobId>
</PostInventoryResult>

上一篇: DELETE Bucket inventory下一篇: PUT Bucket versioning

帮助和支持

本页内容是否解决了您的问题？

填写满意度调查问卷，共创更好文档体验。

文档反馈