# 设置桶QoS配置-SetBucketQosInfo #### 功能介绍 本接口用于为指定桶配置QoS限制，支持对桶请求的Qps、带宽、并发请求数配置QoS限制。 #### 接口约束 - 当前配置桶QoS为邀测功能，仅对开放的租户使用。 - 当前仅**桶级QoS规则** 支持用户自定义，**租户级** **QoS规则** 可[提交工单](https://console.huaweicloud.com/ticket/?locale=zh-cn#/ticketindex/business?productTypeId=2a129f7ed0b543c6b92d73e2c26aa590&subTypeId=-1&type=2)联系技术人员调整。如果桶没有配置桶级QoS规则，那么该桶最大可使用到账号下集群资源的最大值。 - 桶所属集群的指标如果没有限制，那么桶可配置的对应指标最大为2^63^-1。 - QPS或带宽任一指标超过阈值会触发流控。触发流控时，**请求时延会上升，请求响应中会携带** **头域x-obs-qos-delay-time** ，该头域为请求被流控的时长，单位为ms。上传类请求（[PUT上传](https://support.huaweicloud.com/api-obs/obs_04_0080.html)、[上传段](https://support.huaweicloud.com/api-obs/obs_04_0099.html)等）会返回精确的被流控时长，下载类请求（[下载对象](https://support.huaweicloud.com/api-obs/obs_04_0083.html)等）会返回根据流控程度和文件大小估算出的被流控时长。 - 并发请求数超过阈值会触发流控。触发流控时，请求会**立即失败，返回429**。当QPS或带宽流控时，由于请求时延上升，也会导致并发请求数增加。 #### 授权信息 您必须是桶拥有者或拥有设置桶QoS配置的权限，才能调用本接口，建议使用IAM或桶策略进行授权。了解更多OBS授权方式请参见[OBS不同权限控制方式的区别](https://support.huaweicloud.com/perms-cfg-obs/obs_40_0001.html)。 - 如果使用**IAM授权** ，那么请在"角色与策略授权"、"身份策略授权"两种IAM授权方式中选择一种，并配置相应权限： - 如果使用**角色与策略授权** （旧版IAM，即IAM v3接口），需具备**obs:bucket:PutBucketQosInfo** 权限，授权操作请参见[创建IAM自定义策略](https://support.huaweicloud.com/usermanual-iam/iam_01_0605.html)。 - 如果使用**身份策略授权** （新版IAM，即IAM v5接口），如下表所示，需具备**obs:bucket:putBucketQosInfo** 权限，授权操作请参见[创建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:putBucketQosInfo | 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:putBucketQosInfo | Write | - | - obs:EpochTime - obs:SourceIp - obs:TlsVersion - obs:CustomDomain | - | - | - 如果使用**桶策略** 进行授权，需具备**obs:bucket:PutBucketQosInfo** 权限，具体操作请参见[自定义创建桶策略](https://support.huaweicloud.com/usermanual-obs/obs_03_0123.html)。 #### URI PUT / #### 请求消息样式 以下为请求消息样例，请将示例中的*BucketName* 修改为您的桶名，*RegionID* 修改为桶所在的区域ID，可参考[支持区域](https://console.huaweicloud.com/apiexplorer/#/endpoint/OBS)获取区域ID。 ``` PUT /?x-obs-qosInfo HTTP/1.1 User-Agent: curl/7.29.0 Host: BucketName.obs.RegionID.myhuaweicloud.com Accept: */* Date: GMT Date Authorization: SignatureValue Content-Type: application/xml Content-Length: length extranet 0 1500 1000 1500 512000 512000 512000 intranet 1000 1500 1000 1000 512000 512000 512000 total 1000 2000 2000 2000 1024000 1024000 ``` #### URI参数（URI Parameters） 表1URI参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | x-obs-qosInfo | 是 | String | **参数解释**： 用于标识API接口与桶QoS有关。 **约束限制**： 计算签名时，请在CanonicalizedResource中添加"/*BucketName* /?x-obs-qosInfo"，详情参见[签名计算](https://support.huaweicloud.com/api-obs/obs_04_0010.html)。 **取值范围**： x-obs-qosInfo **默认取值**： 不涉及 | #### 请求头参数（Request headers） 该请求使用公共请求头，具体参见[表3](https://support.huaweicloud.com/api-obs/obs_04_0007.html#ZH-CN_TOPIC_0136436606__table25197309)。 #### 请求体参数（Request body） 配置桶QoS请求需要在消息元素中带上桶QoS配置信息，请求消息体为XML格式。元素的具体含义如[表2]所示。 表2请求体参数 | 参数名称 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | PutBucketQoSRequestBody | 是 | Container | **参数解释：** 桶QoS配置参数的根元素。PutBucketQoSRequestBody是[QoSConfiguration]的父节点。 **约束限制：** 不涉及 **取值范围：** 不涉及 **默认取值：** 不涉及 | | QoSConfiguration | 是 | Container | **参数解释：** 桶QoS配置信息内容。 **约束限制：** 不涉及 **取值范围：** 请详见[QoSConfiguration]。 **默认取值：** 不涉及 | 表3QoSConfiguration | 参数名称 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | QoSRule | 否 | Container | **参数解释：** 桶QoS规则数组。 **约束限制：** 不涉及 **取值范围：** 请详见[QoSRule]。 **默认取值：** 不涉及 | 表4QoSRule | 参数名称 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | NetworkType | 是 | Enum | **参数解释：** 桶QoS限制范围。 **约束限制：** 不允许有重复值。 **取值范围：** - total：总QoS限制 - extranet：公网QoS限制 - intranet：内网QoS限制 **默认取值：** 不涉及 | | ConcurrentRequestLimit | 否 | Integer | **参数解释：** 桶请求并发限制。并发指同一时刻的正在进行的请求数量，单位：次/s。 **约束限制：** - 配置为0表示不限制 - 不小于最小值1000，不超过桶所在集群并发限制。 **取值范围：** 0-9223372036854775807 **默认取值：** 不涉及 | | QpsLimit | 否 | Container | **参数解释：** 桶请求Qps限制规则。 **约束限制：** - 不小于最小1000，不超过桶所在集群Qps限制。 **取值范围：** 请详见[QpsLimit]。 **默认取值：** 不涉及 | | BpsLimit | 否 | Container | **参数解释：** 桶请求带宽限制规则。 **约束限制：** - 不小于最小值512000，不超过桶所在集群Bps限制。 **取值范围：** 请详见[BpsLimit]。 **默认取值：** 不涉及 | 表5QpsLimit | 参数名称 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | Get | 否 | Integer | **参数解释：** 桶下载请求Qps限制，单位：次/s。 **约束限制：** - 配置为0表示不限制 - 不小于最小值1000，不超过桶所在集群下载请求Qps限制 **取值范围：** 0-9223372036854775807 **默认取值：** 不涉及 | | PutPostDelete | 否 | Integer | **参数解释：** 桶上传请求Qps限制，单位：次/s。 **约束限制：** - 配置为0表示不限制 - 不小于最小值1000，不超过桶所在集群上传请求Qps限制 **取值范围：** 0-9223372036854775807 **默认取值：** 不涉及 | | List | 否 | Integer | **参数解释：** 桶列举请求Qps限制，单位：次/s。 **约束限制：** - 配置为0表示不限制 - 不小于最小值1000，不超过桶所在集群列举请求Qps限制 **取值范围：** 0-9223372036854775807 **默认取值：** 不涉及 | | Total | 否 | Integer | **参数解释：** 桶总请求Qps限制，单位：次/s。不包含list请求。 **约束限制：** - 配置为0表示不限制 - 不小于最小值1000，不超过桶所在集群总请求Qps限制 **取值范围：** 0-9223372036854775807 **默认取值：** 不涉及 | 表6BpsLimit | 参数名称 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | Get | 否 | Integer | **参数解释：** 桶下载请求带宽限制，单位：Byte/s。 **约束限制：** - 配置为0表示不限制 - 不小于最小值512000，不超过桶所在集群下载请求带宽限制 **取值范围：** 0-9223372036854775807 **默认取值：** 不涉及 | | PutPost | 否 | Integer | **参数解释：** 桶上传请求带宽限制，单位：Byte/s。 **约束限制：** - 配置为0表示不限制 - 不小于最小值512000，不超过桶所在集群上传请求带宽限制 **取值范围：** 0-9223372036854775807 **默认取值：** 不涉及 | | Total | 否 | Integer | **参数解释：** 桶请求总带宽限制，单位：Byte/s。 **约束限制：** - 配置为0表示不限制 - 不小于最小值512000，不超过桶所在集群总带宽限制 **取值范围：** 0-9223372036854775807 **默认取值：** 不涉及 | #### 响应消息样式 ``` HTTP/1.1 status_code Server: OBS 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) 本接口的响应消息中不携带响应体。 #### 错误响应消息 无特殊错误，所有错误已经包含在[错误码概述](https://support.huaweicloud.com/api-obs/obs_04_0115.html)中。 #### 请求示例1：配置桶总Qos 配置桶总QoS：桶请求总Qps限制为2000，桶请求总带宽限制为1024000。 ``` PUT /?x-obs-qosInfo HTTP/1.1 User-Agent: curl/7.29.0 Host: bucketname.obs.cn-north-4.myhuaweicloud.com Accept: */* Date: Wed, 21 May 2025 08:22:54 +0000 Authorization: OBS UDSIAMSTUBTEST000254:ydH8ffpcbS6YpeOMcEZfn0wE90c= Content-Type: application/xml Content-Length: 628 total 2000 1500 1000 512000 512000 ``` #### 响应示例1 ``` HTTP/1.1 200 OK Server: OBS x-obs-request-id: 00000196F1F037525306DC088DF06BD5 x-obs-id-2: 36AAAQAAEAABSAAgAAEAABAAAQAAEAABAAAaI=AAAAAAAAAAAAAAAAAAAAAAAAAA Date: Wed, 21 May 2025 08:22:54 GMT Content-Length: 0 ``` #### 请求示例2：配置桶总+公网带宽QoS 配置桶公网QoS+内网QoS：桶公网/内网下载请求Qps限制为1000，桶公网/内网下载请求带宽限制为512000。 ``` PUT /?x-obs-qosInfo HTTP/1.1 User-Agent: curl/7.29.0 Host: bucketname.obs.cn-north-4.myhuaweicloud.com Accept: */* Date: Wed, 21 May 2025 08:40:18 +0000 Authorization: OBS UDSIAMSTUBTEST000254:ydH8ffpcbS6YpeOMcEZfn0wE90c= Content-Type: application/xml Content-Length: 1121 extranet 512000 512000 total 0 1000 0 1000 1024000 1024000 ``` #### 响应示例2 ``` HTTP/1.1 200 OK Server: OBS x-obs-request-id: 00000196F20026245306A7D73C891518 x-obs-id-2: 36AAAQAAEAABSAAgAAEAABAAAQAAEAABAAAaI=AAAAAAAAAAAAAAAAAAAAAAAAAA Date: Wed, 21 May 2025 08:40:18 GMT Content-Length: 0 ```