全部產品
Search
文件中心

Object Storage Service:PutCname

更新時間:Jun 19, 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. 在您的網域名稱服務 (DNS)商處添加TXT記錄。

    例如,您需要為自訂網域名example.com添加TXT記錄。添加記錄時,記錄類型選擇TXT、主機記錄需填寫_dnsauth.example、記錄值填寫步驟1返回的CnameToken,其他參數保留預設配置。具體步驟,請參見手動添加Cname記錄

    說明

    添加的TXT記錄需等待幾分鐘後生效。

  3. 調用PutCname介面綁定自訂網域名。

CnameDenied

403

網域名稱已被佔用。

CnameIsForbidden

403

該網域名稱為OSS內部保留網域名,無法綁定。

CnameIsRisk

403

該網域名稱為存在較高風險,無法綁定。

NoSuchCnameInRecord

404

網域名稱未備案。關於備案網域名稱的具體步驟,請參見什麼是阿里雲網域名稱服務 (DNS)

CnameAlreadyExists

409

返回此錯誤的可能原因如下:

  • 該網域名稱已綁定至當前帳號下的另一個Bucket。

    問題現象:返回錯誤資訊中的CnameType為CNAME_OSS。

  • 該網域名稱是圖片處理網域名稱。

    問題現象:返回錯誤資訊中的CnameType為CNAME_IMG。

針對以上問題,您需要解除網域名稱綁定。具體步驟,請參見解除網域名稱綁定