全部產品
Search

搜尋本產品

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

    文件中心

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

    更新時間：Apr 22, 2025

    調用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

    是否強制覆蓋認證。取值如下：

    • 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: 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如下：

    命令列工具ossutil

    PutCname介面所對應的ossutil命令，請參見put-cname。

    錯誤碼

    錯誤碼

    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。

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