调用PutCname接口为某个存储空间（Bucket）绑定自定义域名。
权限说明
阿里云账号默认拥有全部权限。阿里云账号下的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>请求头
此接口仅包含公共请求头。更多信息，请参见公共请求头（Common Request Headers）。
请求元素
名称 | 类型 | 是否必选 | 示例值 | 描述 |
BucketCnameConfiguration | 容器 | 是 | 不涉及 | Cname配置的容器。 父节点：无 子节点：Cname |
Cname | 容器 | 是 | 不涉及 | Cname信息的容器。 父节点：BucketCnameConfiguration 子节点：Domain |
Domain | 字符串 | 是 | example.com | 自定义域名。 父节点：Cname 子节点：无 |
CertificateConfiguration | 容器 | 否 | 不涉及 | 证书配置的容器。 父节点：Cname 子节点：CertId、Certificate、PrivateKey、PreviousCertId、Force和DeleteCertificate |
CertId | 字符串 | 否 | 493****-cn-hangzhou | 证书ID。 父节点：CertificateConfiguration 子节点：无 |
Certificate | 字符串 | 否 | -----BEGIN CERTIFICATE----- MIIDhDCCAmwCCQCFs8ixARsyrDANBgkqhkiG9w0BAQsFADCBgzELMAkGA1UEBhMC **** -----END CERTIFICATE----- | 证书公钥。 父节点：CertificateConfiguration 子节点：无 |
PrivateKey | 字符串 | 否 | -----BEGIN CERTIFICATE----- MIIDhDCCAmwCCQCFs8ixARsyrDANBgkqhkiG9w0BAQsFADCBgzELMAkGA1UEBhMC **** -----END CERTIFICATE----- | 证书私钥。 父节点：CertificateConfiguration 子节点：无 |
PreviousCertId | 字符串 | 否 | 493****-cn-hangzhou | 当前证书ID。如果Force值不为true，OSS Server会检查该值与当前证书ID是否匹配，不匹配则报错。 重要 绑定证书时，如果不填写PreviousCertId，需将Force置为true。 父节点：CertificateConfiguration 子节点：无 |
Force | 字符串 | 否 | true | 是否强制覆盖证书。取值如下：
父节点：CertificateConfiguration 子节点：无 |
DeleteCertificate | 字符串 | 否 | true | 是否删除证书。取值如下：
父节点：CertificateConfiguration 子节点：无 |
响应头
此接口仅涉及公共响应头。更多信息，请参见公共响应头（Common Response Headers）。
示例
请求示例
绑定域名
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>绑定证书
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 CERTIFICATE----- MIIDhDCCAmwCCQCFs8ixARsyrDANBgkqhkiG9w0BAQsFADCBgzELMAkGA1UEBhMC **** -----END CERTIFICATE-----</PrivateKey> <PreviousCertId>493****-cn-hangzhou</PreviousCertId> <Force>true</Force> </CertificateConfiguration> </Cname> </BucketCnameConfiguration>解绑证书
如果您不希望该域名继续使用该证书，可以执行解绑证书的操作。
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>
返回示例
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如下：
Java
Python V2
Go V2
Node.js
PHP V2
命令行工具ossutil
PutCname接口所对应的ossutil命令，请参见put-cname。
错误码
错误码 | HTTP状态码 | 描述 |
InvalidArgument | 400 | Cname格式错误，您可以在返回XML中查看具体错误字段和原因。 |
NeedVerifyDomainOwnership | 403 | 未验证域名所有权。 验证域名所有权的步骤说明如下：
|
CnameDenied | 403 | 域名已被占用。 |
CnameIsForbidden | 403 | 该域名为OSS内部保留域名，无法绑定。 |
CnameIsRisk | 403 | 该域名为存在较高风险，无法绑定。 |
NoSuchCnameInRecord | 404 | 域名未备案。关于备案域名的具体步骤，请参见什么是阿里云域名服务。 |
CnameAlreadyExists | 409 | 返回此错误的可能原因如下：
针对以上问题，您需要解除域名绑定。具体步骤，请参见解除域名绑定。 |