全部产品
Search
文档中心

对象存储 OSS:PutCname

更新时间:Apr 28, 2024

调用PutCname接口为某个存储空间(Bucket)绑定自定义域名。

请求语法

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

是否强制覆盖证书。取值如下:

  • true:强制覆盖证书。

  • false:不覆盖证书。

父节点:CertificateConfiguration

子节点:无

DeleteCertificate

字符串

true

是否删除证书。取值如下:

  • true:删除证书。

  • false:不删除证书。

父节点: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: OSS qn6q**************:77Dv****************
      <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: OSS qn6q**************:77Dv****************
      <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: OSS qn6q**************:77Dv****************
      <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

错误码

错误码

HTTP状态码

描述

InvalidArgument

400

Cname格式错误,您可以在返回XML中查看具体错误字段和原因。

NeedVerifyDomainOwnership

403

未验证域名所有权。

验证域名所有权的步骤说明如下:

  1. 调用CreateCnameToken接口创建域名所有权验证所需的CnameToken。

    说明

    CnameToken默认在创建完成后72小时内过期。如果在CnameToken过期时间内重复创建CnameToken,则返回已存在的CnameToken。

  2. 在您的域名服务商处添加TXT记录。

    例如,您需要为自定义域名example.com添加TXT记录。添加记录时,记录类型选择TXT、主机记录需填写_dnsauth.example、记录值填写步骤1返回的CnameToken,其他参数保留默认配置。具体步骤,请参见手动添加Cname记录

    说明

    添加的TXT记录需等待几分钟后生效。

  3. 调用PutCname接口绑定自定义域名。

CnameDenied

403

域名已被占用。

CnameIsForbidden

403

该域名为OSS内部保留域名,无法绑定。

CnameIsRisk

403

该域名为存在较高风险,无法绑定。

NoSuchCnameInRecord

404

域名未备案。关于备案域名的具体步骤,请参见什么是阿里云域名服务

CnameAlreadyExists

409

返回此错误的可能原因如下:

  • 该域名已绑定至当前账号下的另一个Bucket。

    问题现象:返回错误信息中的CnameType为CNAME_OSS。

  • 该域名是图片处理域名。

    问题现象:返回错误信息中的CnameType为CNAME_IMG。

针对以上问题,您需要解除域名绑定。具体步骤,请参见解除域名绑定