文档首页/ 对象存储服务 OBS/ API参考/ 桶API/ 自定义域名/ 设置桶的自定义域名-SetBucketCustomdomain
更新时间：2026-04-15 GMT+08:00
查看PDF
分享

设置桶的自定义域名-SetBucketCustomdomain

功能介绍

调用本接口可为桶设置自定义域名，设置成功之后，用户访问桶的自定义域名就能访问到桶。请确保自定义域名通过DNS能够正确解析到OBS服务。了解更多桶自定义域名相关信息，请参见通过自定义域名访问桶。

接口约束

表1 约束与限制

限制类别

具体限制

桶版本限制

桶版本号为3.0及以上的桶支持配置自定义域名。桶版本号可以在OBS管理控制台上，进入桶概览页后，在“基本信息”中查看。

域名数量限制

每个桶默认最多配置100个自定义域名。

功能限制
  • 一个自定义域名只能配置到一个桶域名上。
  • 暂不支持配置中文域名。
  • 配置的自定义域名后缀目前支持的范围为2~63个英文大小写字母。
  • 按照工信部要求，您配置自定义域名的桶所属区域如果为中国区域，那么需要提前完成ICP备案。
  • 自定义域名通常用于公网访问OBS桶，内网访问OBS建议使用桶默认域名（bucketName.obs.endpoint.myhuaweicloud.com）
说明：

如果使用了加速域名，为防止访问OBS桶中对象变成强制下载，配置自定义域名和加速域名后还需要参考CDN加速场景下访问OBS桶内对象变成强制下载进行处理。

授权信息

您必须是桶拥有者或拥有设置桶的自定义域名的权限，才能调用本接口，建议使用IAM或桶策略进行授权。了解更多OBS授权方式请参见OBS不同权限控制方式的区别。

  • 如果使用IAM授权，那么请在“角色与策略授权”、“身份策略授权”两种IAM授权方式中选择一种，并配置相应权限：
    • 如果使用角色与策略授权（旧版IAM，即IAM v3接口），需具备obs:bucket:PutBucketCustomDomainConfiguration权限，授权操作请参见创建IAM自定义策略。
    • 如果使用身份策略授权（新版IAM，即IAM v5接口），如下表所示，需具备obs:bucket:putBucketCustomDomainConfiguration权限，授权操作请参见创建IAM自定义身份策略。

      授权项

      Action

      访问级别

      Access Level

      资源类型（*为必须）

      Resource Type (*: required)

      条件键

      Condition Key

      别名

      Alias

      依赖的授权项

      Dependencies

      obs:bucket:putBucketCustomDomainConfiguration

      Write

      bucket *

      -

      -

      -
      • obs:EpochTime
      • obs:SourceIp
      • obs:TlsVersion
      • obs:CustomDomain
  • 如果使用桶策略进行授权，需具备obs:bucket:PutBucketCustomDomainConfiguration权限，具体操作请参见自定义创建桶策略。

请求消息样式

绑定自定义域名并且绑定服务端证书请求消息样式： 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
 
PUT /?customdomain=domainname HTTP/1.1
User-Agent: curl/7.29.0
Host: bucketname.obs.cn-north-4.myhuaweicloud.com 
Accept: */*
Date: date
Authorization: authorization string
Content-Length: length
Content-MD5: n58IG6hfM7vqI4K0vnWpog==

<CustomDomainConfiguration> 
    <Name>name</Name> 
    <CertificateId>certificateId</CertificateId> 
    <Certificate>certificate</Certificate> 
    <CertificateChain>certificateChain</CertificateChain> 
    <PrivateKey>privateKey</PrivateKey> 
    <CertificateType>server</CertificateType>
</CustomDomainConfiguration>

绑定自定义域名并且绑定服务端国密证书请求消息样式：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
 
PUT /?customdomain=domainname HTTP/1.1
User-Agent: curl/7.29.0
Host: bucketname.obs.cn-north-4.myhuaweicloud.com 
Accept: */*
Date: date
Authorization: authorization string
Content-Length: length
Content-MD5: n58IG6hfM7vqI4K0vnWpog==

<CustomDomainConfiguration> 
    <Name>name</Name> 
    <CertificateId>certificateId</CertificateId> 
    <Certificate>certificate</Certificate> 
    <CertificateChain>certificateChain</CertificateChain> 
    <PrivateKey>privateKey</PrivateKey> 
    <CertificateType>server_sm</CertificateType>
    <ENCCertificate>encCertificate</ENCCertificate>
    <ENCPrivateKey>encPrivateKey</ENCPrivateKey>
</CustomDomainConfiguration>

绑定客户端CA证书请求消息样式。注意，绑定客户端证书前，需要先绑定服务端证书或者服务端国密证书

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
 
PUT /?customdomain=domainname HTTP/1.1
User-Agent: curl/7.29.0
Host: bucketname.obs.cn-north-4.myhuaweicloud.com 
Accept: */*
Date: date
Authorization: authorization string
Content-Length: length
Content-MD5: n58IG6hfM7vqI4K0vnWpog==

<CustomDomainConfiguration> 
    <Name>name</Name> 
    <Certificate>certificate</Certificate> 
    <CertificateType>client</CertificateType>
</CustomDomainConfiguration>

删除证书请求消息样式

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
 
PUT /?customdomain=domainname HTTP/1.1
User-Agent: curl/7.29.0
Host: bucketname.obs.cn-north-4.myhuaweicloud.com 
Accept: */*
Date: date
Authorization: authorization string
Content-Length: length

<CustomDomainConfiguration> 
    <CertificateType>certificateType</CertificateType>
    <DeleteCertificate>true</DeleteCertificate>
</CustomDomainConfiguration>

请求参数

表2 URI参数

参数

是否必选

参数类型

描述

customdomain

是

String

参数解释：

桶的自定义域名。

约束限制：

一个桶最多可以设置100个自定义域名，一个自定义域名只能被一个桶使用。绑定证书时，证书的生效时间为60秒。

取值范围：

长度为0~256的字符串。

默认取值：

不涉及

请求头参数（Request headers）

表3 请求头参数

消息头名称

参数类型

是否必选

描述

Content-MD5

String

否

参数解释：

设置自定义域名证书时，必须要携带此头域，来校验请求消息体内容和发送时是否一致。

按照RFC 1864标准计算出消息体的MD5摘要字符串，即消息体128-bit MD5值经过base64编码后得到的字符串。

示例：n58IG6hfM7vqI4K0vnWpog==

约束限制：

无

取值范围：

无

默认取值：

无

其他公共消息头，具体参见表3。

请求体参数（Request body）

请求体参数为可选，如果请求体参数为空，会覆盖同一自定义域名下已绑定的证书。

表4 请求体参数

参数

是否必选

参数类型

描述

Name

否

String

参数解释：

证书名称。

约束限制：

仅支持输入大写英文字符、小写英文字符、数字、下划线、中划线、英文句点。

取值范围：

长度为3~63的字符串。

默认取值：

不涉及

CertificateId

否

String

参数解释：

证书ID。未携带CertificateId时自动生成证书ID。

约束限制：

如果用户使用CCM服务托管证书，则证书ID必须为CCM上的证书ID。如果用户需要自己运维管理证书，则请求时不需要主动设置证书ID。

取值范围：

由字母和数字组成的长度为16的字符串。

默认取值：

系统自动生成随机16个字符的证书ID。

Certificate

否

String

参数解释：

证书内容，可包含中间证书及根证书。

约束限制：

  • 如果CertificateChain字段传入证书链，则Certificate字段只取证书本身。
  • 回车换行需要使用转义字符\n或者\r\n替换。

取值范围：

长度为0~65536的字符串。

默认取值：

不涉及

CertificateChain

否

String

参数解释：

证书链。可通过Certificate字段传入。

约束限制：

回车换行需要使用转义字符\n或者\r\n替换。

取值范围：

长度为0~8192的字符串。

默认取值：

不涉及

PrivateKey

否

String

参数解释：

证书私钥。

约束限制：

  • 不支持上传带有口令保护的私钥。
  • 回车换行需要使用转义字符\n或者\r\n替换。

取值范围：

长度为0~4096的字符串。

默认取值：

不涉及

CertificateType

否

String

参数解释：

证书类型。

约束限制：

取值大小写敏感。

取值范围：

  • server：服务端证书
  • server_sm：服务端国密证书
  • client：客户端CA证书

默认取值：

server

ENCCertificate

否

String

参数解释：

国密证书的加密证书内容。

约束限制：

回车换行需要使用转义字符\n或者\r\n替换。

取值范围：

长度为0~65536的字符串。

默认取值：

不涉及

ENCPrivateKey

否

String

参数解释：

国密证书的加密私钥。

约束限制：

  • 不支持上传带有口令保护的私钥。
  • 回车换行需要使用转义字符\n或者\r\n替换。

取值范围：

长度为0~4096的字符串。

默认取值：

不涉及

DeleteCertificate

否

String

参数解释：

证书操作类型，是否删除证书。

约束限制：

不涉及

取值范围：

  • false：上传证书操作。
  • true：删除证书操作，删除指定类型的证书。

默认取值：

false

响应消息样式

1
2
3
4
5
6
 
HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: request id
x-obs-id-2:  id
Date: date
Content-Length: 0

响应头 (Response Headers)

该请求的响应消息使用公共响应头，具体请参考表1。

响应体 (Response Body)

本接口的响应消息中不携带响应体。

错误响应消息

无特殊错误，所有错误已经包含在表2中。

请求示例1：绑定自定义域名

绑定自定义域名

1
2
3
4
5
6
7
 
PUT /?customdomain=obs.ccc.com HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.cn-north-4.myhuaweicloud.com 
Accept: */*
Date: Mon, 14 Jan 2019 08:31:36 +0000
Authorization: OBS UDSIAMSTUBTEST000094:u2kJF4kENs6KlIDcAZpAKSKPtnc=
Content-Length: 0

响应示例1

1
2
3
4
5
6
 
HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: 000001697692CC5380E9D272E6D8F830
x-obs-id-2: 32AAAQAAEAABSAAgAAEAABAAAQAAEAABCSsfu2GXj9gScHhFnrrTPY2cFOEZuvta
Date: Wed, 13 Mar 2019 10:22:05 GMT
Content-Length: 0

请求示例2：绑定自定义域名

绑定自定义域名并且绑定服务端证书请求示例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
 
PUT /?customdomain=obs.ccc.com HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.cn-north-4.myhuaweicloud.com 
Accept: */*
Date: Mon, 14 Jan 2019 08:31:36 +0000
Authorization: OBS UDSIAMSTUBTEST000094:u2kJF4kENs6KlIDcAZpAKSKPtnc=
Content-Length: 314
Content-MD5: n58IG6hfM7vqI4K0vnWpog==

<CustomDomainConfiguration> 
    <Name>exampleCertName</Name> 
    <CertificateId>exampleCertificateId</CertificateId> 
    <Certificate>exampleCertificate</Certificate> 
    <CertificateChain>exampleCertificateChain</CertificateChain> 
    <PrivateKey>examplePrivateKey</PrivateKey> 
    <CertificateType>server</CertificateType>
</CustomDomainConfiguration>

响应示例2

1
2
3
4
5
6
 
HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: 000001697692CC5380E9D272E6D8F830
x-obs-id-2: 32AAAQAAEAABSAAgAAEAABAAAQAAEAABCSsfu2GXj9gScHhFnrrTPY2cFOEZuvta
Date: Wed, 13 Mar 2019 10:22:05 GMT
Content-Length: 0

请求示例3：绑定自定义域名并且绑定服务端国密证书

绑定自定义域名并且绑定服务端国密证书请求示例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
 
PUT /?customdomain=obs.ccc.com HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.cn-north-4.myhuaweicloud.com 
Accept: */*
Date: Mon, 14 Jan 2019 08:31:36 +0000
Authorization: OBS UDSIAMSTUBTEST000094:u2kJF4kENs6KlIDcAZpAKSKPtnc=
Content-Length: 314
Content-MD5: n58IG6hfM7vqI4K0vnWpog==

<CustomDomainConfiguration> 
    <Name>exampleCertName</Name> 
    <CertificateId>exampleCertificateId</CertificateId> 
    <Certificate>exampleCertificate</Certificate> 
    <CertificateChain>exampleCertificateChain</CertificateChain> 
    <PrivateKey>examplePrivateKey</PrivateKey> 
    <CertificateType>server_sm</CertificateType>
    <ENCCertificate>encCertificate</ENCCertificate>
    <ENCPrivateKey>encPrivateKey</ENCPrivateKey> 
</CustomDomainConfiguration>

请求示例4：绑定客户端CA证书

绑定客户端CA证书请求示例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
 
PUT /?customdomain=obs.ccc.com HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.cn-north-4.myhuaweicloud.com 
Accept: */*
Date: Mon, 14 Jan 2019 08:31:36 +0000
Authorization: OBS UDSIAMSTUBTEST000094:u2kJF4kENs6KlIDcAZpAKSKPtnc=
Content-Length: 314
Content-MD5: n58IG6hfM7vqI4K0vnWpog==

<CustomDomainConfiguration> 
    <Name>exampleCertName</Name> 
    <Certificate>exampleCertificate</Certificate> 
    <CertificateType>client</CertificateType>
</CustomDomainConfiguration>

请求示例5：删除证书

删除证书请求示例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
 
PUT /?customdomain=obs.ccc.com HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.cn-north-4.myhuaweicloud.com 
Accept: */*
Date: Mon, 14 Jan 2019 08:31:36 +0000
Authorization: OBS UDSIAMSTUBTEST000094:u2kJF4kENs6KlIDcAZpAKSKPtnc=
Content-Length: 314

<CustomDomainConfiguration> 
    <CertificateType>exampleCertificateType</CertificateType>
    <DeleteCertificate>true</DeleteCertificate>
</CustomDomainConfiguration>

使用SDK调用接口

建议您使用OBS SDK调用接口。SDK对API进行了封装以简化您的开发工作，直接调用SDK接口函数即可访问OBS，无需手动计算签名。

Java暂不支持

Python

C

Go

BrowserJS暂不支持

.NET暂不支持

Android暂不支持

iOS暂不支持

PHP暂不支持

Node.js暂不支持

相关文档

父主题： 自定义域名

相关文档