调用PutCname接口为某个存储空间Bucket绑定自定义域名-对象存储(OSS)-阿里云帮助中心

调用PutCname接口为某个存储空间（Bucket）绑定自定义域名。普通Bucket仅支持绑定精确CNAME；Agentic Bucket还支持绑定泛域名CNAME，用于其下BucketSpace的访问。

注意事项

在Agentic Bucket上绑定CNAME（无论精确还是泛域名）时，必须在请求XML中显式传入IsWildCard节点，取值为true或false，不允许缺省或为空。
在Agentic Bucket上，不允许配置以下字段，否则返回400错误（MalformedXML）：AccessPointName、AccessPointNameForObjectProcess、PurgeConfiguration/IsPurgeCdnCache、ClientCaConfiguration（含casCertId、内联证书、删除操作）。普通Bucket保留上述字段的完整功能。
BucketSpace不支持直接绑定CNAME。BucketSpace的公网访问统一通过其所属Agentic Bucket上绑定的泛域名CNAME实现。

权限说明

阿里云账号默认拥有全部权限。阿里云账号下的RAM用户或RAM角色默认没有任何权限，需要阿里云账号或账号管理员通过RAM Policy概述或Bucket Policy授予操作权限。

API	Action	说明
PutCname	oss:PutCname	为Bucket绑定自定义域名。
	yundun-cert:DescribeSSLCertificatePrivateKey	为Bucket绑定自定义域名时，如果绑定证书，则需要这三个操作的权限。
	yundun-cert:DescribeSSLCertificatePublicKeyDetail
	yundun-cert:CreateSSLCertificate

请求语法

POST /?cname&comp=add HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Content-Type: application/xml
Content-Length: 186
Date: GMT Date
Authorization: SignatureValue
<BucketCnameConfiguration>
  <Cname>
    <Domain>example.com</Domain>
  </Cname>
</BucketCnameConfiguration>

说明

PutCname通过请求XML中的IsWildCard节点声明Cname是否为泛域名。对于Agentic Bucket，IsWildCard节点为必填。

请求头

此接口仅包含公共请求头。更多信息，请参见公共HTTP头定义。

请求元素

名称	类型	是否必选	示例值	描述
BucketCnameConfiguration	容器	是	不涉及	Cname配置的容器。父节点：无子节点：Cname
Cname	容器	是	不涉及	Cname信息的容器。父节点：BucketCnameConfiguration 子节点：Domain、IsWildCard和CertificateConfiguration
Domain	字符串	是	example.com	自定义域名。绑定精确CNAME时传入完整域名，例如console.example.com；绑定泛域名CNAME时传入基础域（不含`*.`前缀），例如example.com。父节点：Cname 子节点：无
IsWildCard	布尔值	普通Bucket：否 Agentic Bucket：是	true	是否绑定泛域名CNAME。取值如下： true：绑定泛域名CNAME，Domain传入泛域名基础域。 false：绑定精确CNAME，Domain传入完整域名。在Agentic Bucket上，该节点必选，必须显式传true或false，不允许缺省或为空。普通Bucket该节点可选，默认为false。父节点：Cname 子节点：无
CertificateConfiguration	容器	否	不涉及	证书配置的容器。绑定泛域名CNAME时，证书的CN/SAN需匹配`*.<Domain>`，即需使用通配符证书。父节点：Cname 子节点：CertId、Certificate、PrivateKey、PreviousCertId、Force和DeleteCertificate
CertId	字符串	否	493****-cn-hangzhou	证书ID。父节点：CertificateConfiguration 子节点：无
Certificate	字符串	否	-----BEGIN CERTIFICATE----- MIIDhDCCAmwCCQCFs8ixARsyrDANBgkqhkiG9w0BAQsFADCBgzELMAkGA1UEBhMC **** -----END CERTIFICATE-----	证书公钥。父节点：CertificateConfiguration 子节点：无
PrivateKey	字符串	否	-----BEGIN PRIVATE KEY----- MIIDhDCCAmwCCQCFs8ixARsyrDANBgkqhkiG9w0BAQsFADCBgzELMAkGA1UEBhMC **** -----END PRIVATE KEY-----	证书私钥。父节点：CertificateConfiguration 子节点：无
PreviousCertId	字符串	否	493****-cn-hangzhou	当前证书ID。如果Force值不为true，OSS Server会检查该值与当前证书ID是否匹配，不匹配则报错。重要绑定证书时，如果不填写PreviousCertId，需将Force置为true。父节点：CertificateConfiguration 子节点：无
Force	字符串	否	true	是否强制覆盖证书。取值如下： true：强制覆盖证书。 false：不覆盖证书。父节点：CertificateConfiguration 子节点：无
DeleteCertificate	字符串	否	true	是否删除证书。取值如下： true：删除证书。 false：不删除证书。父节点：CertificateConfiguration 子节点：无

响应头

此接口仅涉及公共响应头。更多信息，请参见公共HTTP头定义。

示例

请求示例

为普通Bucket绑定域名

POST /?cname&comp=add HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Content-Type: application/xml
Content-Length: 186
Date: Thu, 24 Sep 2015 15:39:12 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=host,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
<BucketCnameConfiguration>
  <Cname>
    <Domain>example.com</Domain>
  </Cname>
</BucketCnameConfiguration>

为普通Bucket绑定证书

POST /?cname&comp=add HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Content-Type: application/xml
Content-Length: 186
Date: Thu, 24 Sep 2015 15:39:12 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=host,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
<BucketCnameConfiguration>
  <Cname>
    <Domain>example.com</Domain>
    <CertificateConfiguration>
      <CertId>493****-cn-hangzhou</CertId>
      <Certificate>-----BEGIN CERTIFICATE----- MIIDhDCCAmwCCQCFs8ixARsyrDANBgkqhkiG9w0BAQsFADCBgzELMAkGA1UEBhMC **** -----END CERTIFICATE-----</Certificate>
      <PrivateKey>-----BEGIN PRIVATE KEY----- MIIDhDCCAmwCCQCFs8ixARsyrDANBgkqhkiG9w0BAQsFADCBgzELMAkGA1UEBhMC **** -----END PRIVATE KEY-----</PrivateKey>
      <PreviousCertId>493****-cn-hangzhou</PreviousCertId>
      <Force>true</Force>
    </CertificateConfiguration>
  </Cname>
</BucketCnameConfiguration>

为普通Bucket解绑证书

如果您不希望该域名继续使用该证书，可以执行解绑证书的操作。

POST /?cname&comp=add HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Content-Type: application/xml
Content-Length: 186
Date: Thu, 24 Sep 2015 15:39:12 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=host,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
<BucketCnameConfiguration>
  <Cname>
    <Domain>example.com</Domain>
      <CertificateConfiguration>
      <DeleteCertificate>True</DeleteCertificate>
    </CertificateConfiguration>
  </Cname>
</BucketCnameConfiguration>

为Agentic Bucket绑定泛域名CNAME（附带泛域名证书）

POST /?cname&comp=add HTTP/1.1
Host: myab-$uid-$region-ab-apsr.oss-cn-hangzhou.aliyuncs.com
Content-Type: application/xml
Content-Length: 186
Date: Thu, 17 Apr 2025 15:39:12 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=host,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
<BucketCnameConfiguration>
  <Cname>
    <Domain>example.com</Domain>
    <IsWildCard>true</IsWildCard>
    <CertificateConfiguration>
      <Certificate>-----BEGIN CERTIFICATE----- MIIDhDCCAmwCCQCFs8ixARsyrDANBgkqhkiG9w0BAQsFADCBgzELMAkGA1UEBhMC **** -----END CERTIFICATE-----</Certificate>
      <PrivateKey>-----BEGIN PRIVATE KEY----- MIIDhDCCAmwCCQCFs8ixARsyrDANBgkqhkiG9w0BAQsFADCBgzELMAkGA1UEBhMC **** -----END PRIVATE KEY-----</PrivateKey>
    </CertificateConfiguration>
  </Cname>
</BucketCnameConfiguration>

为Agentic Bucket绑定精确CNAME

POST /?cname&comp=add HTTP/1.1
Host: myab-$uid-$region-ab-apsr.oss-cn-hangzhou.aliyuncs.com
Content-Type: application/xml
Content-Length: 186
Date: Thu, 17 Apr 2025 15:39:12 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=host,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
<BucketCnameConfiguration>
  <Cname>
    <Domain>console.example.com</Domain>
    <IsWildCard>false</IsWildCard>
  </Cname>
</BucketCnameConfiguration>

返回示例

content-length: 0
x-oss-console-auth: success
server: AliyunOSS
x-oss-server-time: 980
connection: keep-alive
x-oss-request-id: 5C1B138A109F4E405B2D
date: Wed, 15 Sep 2021 03:33:37 GMT

SDK

本接口对应的各语言SDK如下：

命令行工具ossutil

PutCname接口所对应的ossutil命令，请参见put-cname。

错误码

错误码	HTTP状态码	描述
InvalidArgument	400	返回此错误的可能原因如下： Cname格式错误，您可以在返回XML中查看具体错误字段和原因。 Agentic Bucket上`IsWildCard`节点缺失或值为空。泛域名基础域校验不通过，例如标签数超过上限、层级不足、高危TLD组合等。
MalformedXML	400	Agentic Bucket上配置了不支持的字段（AccessPointName、AccessPointNameForObjectProcess、PurgeConfiguration/IsPurgeCdnCache、ClientCaConfiguration），或请求Body格式不合法。
CnameCertificateMismatch	400	证书与CNAME域名不匹配。绑定泛域名CNAME时，需使用CN/SAN匹配`*.<Domain>`的通配符证书。
NeedVerifyDomainOwnership	403	未验证域名所有权。验证域名所有权的步骤说明如下：调用CreateCnameToken接口创建域名所有权验证所需的CnameToken。在Agentic Bucket上创建泛域名基础域的Token时，需指定`wildcard=true`。在您的域名服务商处添加TXT记录。例如，您需要为自定义域名`example.com`添加TXT记录。添加记录时，记录类型选择TXT、主机记录需填写`_dnsauth.example`、记录值填写步骤1返回的CnameToken，其他参数保留默认配置。具体步骤，请参见手动添加Cname记录。说明添加的TXT记录需等待几分钟后生效。调用PutCname接口绑定自定义域名。
CnameDenied	403	域名已被占用。
CnameIsForbidden	403	该域名为OSS内部保留域名，无法绑定。
CnameIsRisk	403	该域名为存在较高风险，无法绑定。
NoSuchCnameInRecord	404	域名未备案。关于备案域名的具体步骤，请参见什么是阿里云域名服务。
ConflictCname	409	泛域名基础域已绑定到同一UID下的另一个Agentic Bucket。需先在原Agentic Bucket上解绑该泛域名CNAME，再重新绑定。
CnameAlreadyExists	409	返回此错误的可能原因如下：该域名已绑定至当前账号下的另一个Bucket。问题现象：返回错误信息中的CnameType为CNAME_OSS。该域名是图片处理域名。问题现象：返回错误信息中的CnameType为CNAME_IMG。针对以上问题，您需要解除域名绑定。具体步骤，请参见解除域名绑定。
MethodNotAllowed	405	目标Bucket类型未开通CNAME能力。