PutCname - Object Storage Service

調用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	未驗證網域名稱所有權。驗證網域名稱所有權的步驟說明如下：調用CreateCnameToken介面建立網域名稱所有權驗證所需的CnameToken。說明 CnameToken預設在建立完成後72小時內到期。如果在CnameToken到期時間內重複建立CnameToken，則返回已存在的CnameToken。在您的網域名稱服務 (DNS)商處添加TXT記錄。例如，您需要為自訂網域名`example.com`添加TXT記錄。添加記錄時，記錄類型選擇TXT、主機記錄需填寫`_dnsauth.example`、記錄值填寫步驟1返回的CnameToken，其他參數保留預設配置。具體步驟，請參見手動添加Cname記錄。說明添加的TXT記錄需等待幾分鐘後生效。調用PutCname介面綁定自訂網域名。
CnameDenied	403	網域名稱已被佔用。
CnameIsForbidden	403	該網域名稱為OSS內部保留網域名，無法綁定。
CnameIsRisk	403	該網域名稱為存在較高風險，無法綁定。
NoSuchCnameInRecord	404	網域名稱未備案。關於備案網域名稱的具體步驟，請參見什麼是阿里雲網域名稱服務 (DNS)。
CnameAlreadyExists	409	返回此錯誤的可能原因如下：該網域名稱已綁定至當前帳號下的另一個Bucket。問題現象：返回錯誤資訊中的CnameType為CNAME_OSS。該網域名稱是圖片處理網域名稱。問題現象：返回錯誤資訊中的CnameType為CNAME_IMG。針對以上問題，您需要解除網域名稱綁定。具體步驟，請參見解除網域名稱綁定。