調用PutCname介面為某個儲存空間Bucket綁定自訂網域名 - Object Storage Service

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