# 设置桶清单-SetBucketInventory #### 功能介绍 桶清单功能可以定期生成桶内对象的元数据信息，通过查看这些信息，可以帮助您更好地了解桶内对象的状态，调用本接口可以配置桶清单功能。有关更多桶清单的介绍和使用限制，请参见[桶清单](https://support.huaweicloud.com/usermanual-obs/obs_03_0084.html)。 #### 接口约束 表1桶清单约束限制 | 限制类型 | 限制内容 | |:---|:---| | 桶版本限制 | 只有OBS 3.0的桶支持配置清单，目标桶无OBS版本限制。关于如何确认桶的版本，请参见[OBS 2.0和OBS 3.0的判断方法](https://support.huaweicloud.com/usermanual-obs/obs_41_0003.html)。 | | 清单数量限制 | 一个桶最多支持10条桶清单。 | | 源桶和目标桶限制 | - 桶清单配置的源桶和目标桶必须归属同一个账号。 - 桶清单配置的源桶和目标桶必须归属同一个区域。 - 桶清单中配置的目标桶不能开启桶服务端加密。 | | 功能限制 | - 只支持生成CSV格式的清单文件。 - 桶清单筛选条件目前仅支持设置为所有对象或指定前缀的对象。 - 同一个桶中多条清单规则的筛选条件不能彼此包含： - 如果已经存在针对桶中所有对象的规则，则无法再创建按对象名前缀筛选的规则。如需创建，要先删除针对所有对象的规则。 - 如果已经存在按对象名前缀筛选的规则，则无法再创建针对桶中所有对象的规则。如需创建，要先删除所有按对象名前缀筛选的规则。 - 如果已经存在某个按对象名前缀筛选的规则（如前缀ab），则无法再创建与其存在包含或被包含关系的规则（如前缀a或前缀abc）。如需创建，要先删除存在包含或被包含关系的规则。 - 桶清单支持统计的对象加密方式目前只支持SSE-KMS。 | | 权限限制 | 清单文件使用OBS系统用户上传到目标桶，目标桶必须给OBS系统用户写权限，即目标桶必须包含一条Principal取值固定为{"Service": "obs"}，授予写权限的桶策略。 | | 其他 | - 暂不对桶清单功能收费，桶清单生成后只按照存储容量计费。 - 不支持联邦用户使用桶清单。 说明： 企业联邦用户是在企业管理系统中创建的用户，账号在IAM控制台创建[身份提供商](https://support.huaweicloud.com/usermanual-iam/iam_08_0000.html)后，企业联邦用户可以登录华为云并根据对应权限使用云服务。 | #### 授权信息 您必须是桶拥有者或拥有设置桶清单的权限，才能调用本接口，建议使用IAM或桶策略进行授权。了解更多OBS授权方式请参见[OBS不同权限控制方式的区别](https://support.huaweicloud.com/perms-cfg-obs/obs_40_0001.html)。 - 如果使用**IAM授权** ，那么请在"角色与策略授权"、"身份策略授权"两种IAM授权方式中选择一种，并配置相应权限： - 如果使用**角色与策略授权** （旧版IAM，即IAM v3接口），需具备**obs:bucket:PutBucketInventoryConfiguration** 权限，授权操作请参见[创建IAM自定义策略](https://support.huaweicloud.com/usermanual-iam/iam_01_0605.html)。 - 如果使用**身份策略授权** （新版IAM，即IAM v5接口），如下表所示，需具备**obs:bucket:putBucketInventoryConfiguration** 权限，授权操作请参见[创建IAM自定义身份策略](https://support.huaweicloud.com/usermanual-iam5/iam_01_0917.html)。 | 授权项 Action | 访问级别 Access Level | 资源类型（\*为必须） Resource Type (\*: required) | [条件键](https://support.huaweicloud.com/api-obs/obs_04_0112.html#ZH-CN_TOPIC_0000002375307974__condition_table) Condition Key | [别名](https://support.huaweicloud.com/iam5_faq/iam_01_1103.html) Alias | 依赖的授权项 Dependencies | |:---|:---|:---|:---|:---|:---| | obs:bucket:putBucketInventoryConfiguration | Write | bucket \* | - [g:EnterpriseProjectId](https://support.huaweicloud.com/usermanual-iam5/iam_01_0934.html#section2) - [g:ResourceTag/\](https://support.huaweicloud.com/usermanual-iam5/iam_01_0934.html#section2) | - | - | | obs:bucket:putBucketInventoryConfiguration | Write | - | - obs:EpochTime - obs:SourceIp - obs:TlsVersion - obs:CustomDomain | - | - | - 如果使用**桶策略** 进行授权，需具备**obs:bucket:PutBucketInventoryConfiguration** 权限，具体操作请参见[自定义创建桶策略](https://support.huaweicloud.com/usermanual-obs/obs_03_0123.html)。 #### URI PUT / #### 调用方法 请参见[如何调用API](https://support.huaweicloud.com/api-obs/obs_04_0006.html)。调用前需要先[计算API签名](https://support.huaweicloud.com/api-obs/obs_04_0009.html)，并将签名添加到请求中。 您还可以使用[API Explorer](https://console.huaweicloud.com/apiexplorer/#/openapi/OBS/doc?api=SetBucketInventory)在线调试接口。 #### 请求消息样式 以下为请求消息样例，请将示例中的*BucketName* 修改为您的桶名，*RegionID* 修改为桶所在的区域ID，可参考[支持区域](https://console.huaweicloud.com/apiexplorer/#/endpoint/OBS)获取区域ID。 ``` PUT /?inventory&id=configuration-id HTTP/1.1 User-Agent: curl/7.29.0 Host: BucketName.obs.RegionID.myhuaweicloud.com Accept: */* Date: GMT Date Authorization: SignatureValue Content-Length: BodyLength Expect: 100-continue configuration-id true inventoryTestPrefix CSV destbucket dest-prefix Daily All Size LastModifiedDate ETag StorageClass IsMultipartUploaded ReplicationStatus EncryptionStatus ``` #### URI参数（URI Parameters） 表2URI参数 | 参数名称 | 参数类型 | 是否必选 | 描述 | |:---|:---|:---|:---| | inventory | String | 是 | **参数解释**： 用于标识API接口与桶清单有关。 **约束限制**： 计算签名时，请在CanonicalizedResource中添加"/*BucketName* /?inventory"，详情参见[签名计算](https://support.huaweicloud.com/api-obs/obs_04_0010.html)。 **取值范围**： inventory **默认取值**： 不涉及 | | id | String | 是 | **参数解释：** 清单配置的id，必须和消息体中的清单配置id一致。 **约束限制：** 不涉及。 **取值范围：** 只能由a-z、A-Z、0-9、-、_和.组成，且长度不超过64字节。 **默认取值：** 不涉及。 | #### 请求头参数（Request headers） 该请求使用公共请求头，具体参见[表3](https://support.huaweicloud.com/api-obs/obs_04_0007.html#ZH-CN_TOPIC_0136436606__table25197309)。 #### 请求体参数（Request body） 在此请求中，需要在请求的消息体中配置桶的清单。清单的配置信息以XML格式上传。具体的配置元素如[表3]。 表3桶清单配置请求体参数 | 名称 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | InventoryConfiguration | 是 | Container | **参数解释：** 清单配置。InventoryConfiguration是Id、IsEnabled、Filter、Destination、Schedule、IncludedObjectVersions以及OptionalFields的父节点。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | Id | 是 | String | **参数解释：** 清单配置的id，必须和请求参数中的清单配置id一致。 父节点：InventoryConfiguration **约束限制：** 不涉及。 **取值范围：** 只能由a-z、A-Z、0-9、-、_和.组成，且长度不超过64字节。 **默认取值：** 不涉及。 | | IsEnabled | 是 | Boolean | **参数解释：** 规则是否启用，如果设置为true，则生成清单，反之不生成。 父节点：InventoryConfiguration **约束限制：** 不涉及。 **取值范围：** true：生成桶清单 false：不生成桶清单。 **默认取值：** 不涉及。 | | Filter | 否 | Container | **参数解释：** 清单过滤器配置，清单只包含符合过滤器规则的对象（只支持按对象名前缀进行过滤），如果没有配置过滤器，则包含所有对象。 父节点：InventoryConfiguration **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | Prefix | 否 | String | **参数解释：** 前缀过滤条件，清单文件中只生成以此前缀开头的对象列表。 父节点：Filter **约束限制：** 不涉及。 **取值范围：** 不超过1024字符。 **默认取值：** 不涉及。 | | Schedule | 是 | Container | **参数解释：** 清单文件的生成周期。 父节点：InventoryConfiguration **约束限制：** **不涉及**。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | Frequency | 是 | String | **参数解释：** 清单文件的生成周期，只支持按天和按周生成清单，第一次配置完桶清单，任务会在一个小时内启动，之后每隔一个周期启动一次。 父节点：Schedule **约束限制：** 不涉及。 **取值范围：** Daily：按天生成清单。 Weekly：按周生成清单。 **默认取值：** 不涉及。 | | Destination | 是 | Container | **参数解释：** 清单的目标配置。 父节点：InventoryConfiguration **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | Format | 是 | String | **参数解释：** 生成的清单文件的格式，现只支持CSV格式。 父节点：Destination **约束限制：** 不涉及。 **取值范围：** CSV：CSV格式。 **默认取值：** 不涉及。 | | Bucket | 是 | String | **参数解释：** 存放清单文件的目标桶的桶名。 父节点：Destination **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | Prefix | 否 | String | **参数解释：** 生成的清单文件对象名会以此前缀开头，如果不配置前缀，则生成的清单文件对象名默认以BucketInventory开头。 父节点：Destination **约束限制：** 不涉及。 **取值范围：** 不包含\\, \*, ?, ", \<, \>, \| 字符，且最长254字符。 **默认取值：** 不涉及。 | | IncludedObjectVersions | 是 | String | **参数解释：** 清单文件中包含对象的多版本配置。 父节点：InventoryConfiguration **约束限制：** **不涉及**。 **取值范围：** - All：清单会包含对象所有的版本，清单中**会增加**版本相关的字段：VersionId、IsLatest、和DeleteMarker。 - Current：清单文件中只会列出当前版本信息，**不会**出现与多版本相关的VersionId、IsLatest、DeleteMarker字段。 **默认取值：** 不涉及。 | | OptionalFields | 否 | Container | **参数解释：** 在此选项中可以添加一些额外的对象元数据字段，生成的清单文件中会包含OptionalFields中配置的字段。 父节点：InventoryConfiguration **约束限制：** 配合Field使用。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | Field | 否 | String | **参数解释：** 可选字段类型，OptionalFields可以包含多个Field元素。添加一些额外的对象元数据字段。 父节点：OptionalFields **约束限制：** 不涉及。 **取值范围：** Size：对象长度 LastModifiedDate：对象的创建时间 ETag：对象的etag StorageClass：对象的存储类别 IsMultipartUploaded：是否多段对象，true或false ReplicationStatus：CRR对象的复制状态 EncryptionStatus：服务端加密方式 BucketKeyStatus：密钥状态，ENABLED或DISABLED UserMeta：自定义元数据 CRC64：数据内容的CRC64 ObjectType：对象类型 **默认取值：** 不涉及。 | #### 响应消息样式 ``` HTTP/1.1 status_code x-obs-request-id: request id x-obs-id-2: id Date: date Content-Length: length ``` #### 响应头 (Response Headers) 该请求的响应消息使用公共响应头，具体请参考[表1](https://support.huaweicloud.com/api-obs/obs_04_0013.html#ZH-CN_TOPIC_0173612084__d0e686)。 #### 响应体 (Response Body) 本接口的响应消息中不携带响应体。 #### 错误响应消息 除了公共的错误码外，此接口还会返回一些其他的错误码。下面列出本接口的一些常见错误，以及可能原因，如[表4]。 表4设置桶清单错误码列表 | 错误码 | 描述 | HTTP状态码 | |:---|:---|:---| | MalformedXML | 清单的XML配置格式错误。 | 400 Bad Request | | InvalidArgument | 无效参数。 | 400 Bad Request | | InventoryCountOverLimit | 配置清单数量超过最大限制。 | 400 Bad Request | | PrefixExistInclusionRelationship | 清单配置中的前缀存在包含关系。 | 400 Bad Request | #### 请求示例 ``` PUT /?inventory&id=test_id HTTP/1.1 User-Agent: curl/7.29.0 Host: examplebucket.obs.cn-north-4.myhuaweicloud.com Accept: */* Date: Tue, 08 Jan 2019 08:17:10 +0000 Authorization: OBS UDSIAMSTUBTEST000001:/e2fqSfzLDb+0M36D4Op/s5KKr0= Content-Length: 600 Expect: 100-continue test_id true inventoryTestPrefix CSV destbucket dest-prefix Daily All Size LastModifiedDate ETag StorageClass IsMultipartUploaded ReplicationStatus EncryptionStatus ``` #### 响应示例 ``` HTTP/1.1 200 OK Server: OBS x-obs-request-id: 000001682C8545B0680893425D60AB83 x-obs-id-2: 32AAAQAAEAABAAAQAAEAABAAAQAAEAABCSIGTuRtBfo7lpHSt0ZknhdDHmllwd/p Date: Tue, 08 Jan 2019 08:12:38 GMT Content-Length: 0 ``` #### 使用SDK调用接口 建议您使用OBS SDK调用接口。SDK对API进行了封装以简化您的开发工作，直接调用SDK接口函数即可访问OBS，无需手动计算签名。 | [Java](https://support.huaweicloud.com/sdk-java-devg-obs/obs_21_0417.html) | [Python](https://support.huaweicloud.com/sdk-python-devg-obs/obs_22_3002.html) | [C](https://support.huaweicloud.com/sdk-c-devg-obs/obs_20_3330.html) | [Go](https://support.huaweicloud.com/sdk-go-devg-obs/obs_23_8010.html) | BrowserJS不支持 | .NET不支持 | Android不支持 | iOS不支持 | PHP不支持 | [Node.js](https://support.huaweicloud.com/sdk-nodejs-devg-obs/obs_29_4001.html) | |---|---|---|---|---|---|---|---|---|---| #### 相关文档 - 了解更多设置桶清单相关介绍，请参见[桶清单](https://support.huaweicloud.com/usermanual-obs/obs_03_0084.html)。 - API操作涉及的计费项参见[计费项](https://support.huaweicloud.com/price-obs/obs_42_0002.html)。