PutCname - Memetakan nama domain kustom ke bucket - Object Storage Service

PutCname memetakan nama domain kustom ke bucket. Bucket standar hanya mendukung CNAME eksak, sedangkan Agentic Bucket juga mendukung CNAME wildcard untuk mengakses Bucket Spaces-nya.

Catatan penggunaan

Saat memetakan CNAME eksak atau wildcard ke Agentic Bucket, Anda harus secara eksplisit menyertakan elemen IsWildCard dalam XML permintaan dan mengaturnya ke true atau false. Nilainya tidak boleh kosong.
Untuk Agentic Bucket, elemen-elemen berikut tidak didukung: AccessPointName, AccessPointNameForObjectProcess, PurgeConfiguration/IsPurgeCdnCache, dan ClientCaConfiguration (termasuk casCertId, sertifikat inline, dan operasi delete). Jika salah satu elemen tersebut dikonfigurasi, OSS akan mengembalikan error 400 MalformedXML. Bucket standar tetap mendukung penuh elemen-elemen ini.
Bucket Space tidak dapat dipetakan langsung ke CNAME. Akses jaringan publik ke Bucket Space dilakukan melalui CNAME wildcard yang dipetakan ke Agentic Bucket induknya.

Izin

Secara default, Akun Alibaba Cloud memiliki semua izin. Pengguna RAM dan Peran RAM di bawah Akun Alibaba Cloud tidak memiliki izin secara default. Akun Alibaba Cloud atau administrator akun harus memberikan izin yang diperlukan melalui RAM Policy atau Bucket Policy.

API	Action	Deskripsi
PutCname	oss:PutCname	Memetakan nama domain kustom ke bucket.
	yundun-cert:DescribeSSLCertificatePrivateKey	Jika Anda melakukan bind sertifikat saat memetakan nama domain kustom ke bucket, ketiga izin ini diperlukan.
	yundun-cert:DescribeSSLCertificatePublicKeyDetail
	yundun-cert:CreateSSLCertificate

Sintaksis permintaan

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>

Catatan

PutCname menggunakan elemen IsWildCard dalam XML permintaan untuk menentukan apakah CNAME tersebut eksak atau wildcard. Untuk Agentic Bucket, elemen IsWildCard wajib disertakan.

Header permintaan

Operasi ini hanya menggunakan header permintaan umum. Untuk informasi selengkapnya, lihat Header HTTP umum.

Elemen permintaan

Elemen	Type	Wajib	Contoh	Deskripsi
BucketCnameConfiguration	Container	Ya	N/A	Container yang menyimpan konfigurasi CNAME. Node induk: none Node anak: Cname
Cname	Container	Ya	N/A	Container yang menyimpan informasi CNAME. Node induk: BucketCnameConfiguration Node anak: Domain, IsWildCard, dan CertificateConfiguration
Domain	String	Ya	example.com	Nama domain kustom. Untuk memetakan CNAME eksak, atur elemen ini ke nama domain lengkap, seperti console.example.com. Untuk memetakan CNAME wildcard, atur elemen ini ke nama domain dasar tanpa awalan `*.`, seperti example.com. Node induk: Cname Node anak: none
IsWildCard	Boolean	Bucket standar: Tidak Agentic Bucket: Ya	true	Menentukan apakah akan memetakan CNAME wildcard. Nilai yang valid: true: memetakan CNAME wildcard. Atur Domain ke nama domain dasar. false: memetakan CNAME eksak. Atur Domain ke nama domain lengkap. Untuk Agentic Bucket, elemen ini wajib disertakan. Atur secara eksplisit ke true atau false; nilainya tidak boleh kosong. Untuk bucket standar, elemen ini opsional dan default-nya adalah false. Node induk: Cname Node anak: none
CertificateConfiguration	Container	Tidak	N/A	Container yang menyimpan konfigurasi sertifikat. Saat Anda memetakan CNAME wildcard, CN atau SAN pada sertifikat harus sesuai dengan `*.<Domain>`, sehingga diperlukan Sertifikat wildcard. Node induk: Cname Node anak: CertId, Certificate, PrivateKey, PreviousCertId, Force, dan DeleteCertificate
CertId	String	Tidak	493****-cn-hangzhou	ID sertifikat. Node induk: CertificateConfiguration Node anak: none
Certificate	String	Tidak	-----BEGIN CERTIFICATE----- MIIDhDCCAmwCCQCFs8ixARsyrDANBgkqhkiG9w0BAQsFADCBgzELMAkGA1UEBhMC **** -----END CERTIFICATE-----	Kunci publik sertifikat. Node induk: CertificateConfiguration Node anak: none
PrivateKey	String	Tidak	-----BEGIN PRIVATE KEY----- MIIDhDCCAmwCCQCFs8ixARsyrDANBgkqhkiG9w0BAQsFADCBgzELMAkGA1UEBhMC **** -----END PRIVATE KEY-----	Kunci privat sertifikat. Node induk: CertificateConfiguration Node anak: none
PreviousCertId	String	Tidak	493****-cn-hangzhou	ID sertifikat yang saat ini terikat. Jika Force tidak diatur ke true, OSS akan memeriksa apakah nilai ini sesuai dengan sertifikat yang benar-benar terikat dan mengembalikan error jika tidak sesuai. Penting Jika Anda tidak menentukan PreviousCertId saat melakukan bind sertifikat, atur Force ke true. Node induk: CertificateConfiguration Node anak: none
Force	String	Tidak	true	Menentukan apakah akan menimpa sertifikat. Nilai yang valid: true: menimpa sertifikat. false: tidak menimpa sertifikat. Node induk: CertificateConfiguration Node anak: none
DeleteCertificate	String	Tidak	true	Menentukan apakah akan menghapus sertifikat. Nilai yang valid: true: menghapus sertifikat. false: tidak menghapus sertifikat. Node induk: CertificateConfiguration Node anak: none

Header respons

Operasi ini hanya mengembalikan header respons umum. Untuk informasi selengkapnya, lihat Header HTTP umum.

Contoh

Contoh permintaan

Memetakan nama domain kustom ke bucket standar

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>

Mengikat sertifikat ke nama domain kustom bucket standar

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>

Melepas ikatan sertifikat dari nama domain kustom bucket standar

Jika Anda tidak lagi ingin nama domain menggunakan sertifikat ini, lepaskan ikatannya.

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>

Memetakan CNAME wildcard ke Agentic Bucket (dengan sertifikat wildcard)

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>

Memetakan CNAME eksak ke Agentic Bucket

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>

Contoh respons

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

OSS SDKs

OSS SDK berikut mendukung operasi PutCname:

ossutil

Untuk informasi tentang perintah ossutil yang sesuai dengan operasi PutCname, lihat put-cname.

Kode error

Kode error	Kode status HTTP	Deskripsi
InvalidArgument	400	Penyebab error berikut mungkin terjadi: Format CNAME tidak valid. Anda dapat memeriksa XML yang dikembalikan untuk mengetahui bidang error dan alasannya secara spesifik. Untuk Agentic Bucket, elemen `IsWildCard` tidak ada atau nilainya kosong. Verifikasi nama domain dasar wildcard gagal. Misalnya, jumlah label melebihi batas maksimum, jumlah level tidak mencukupi, atau nama domain menggunakan kombinasi TLD berisiko tinggi.
MalformedXML	400	Permintaan menyertakan elemen yang tidak didukung oleh Agentic Bucket (AccessPointName, AccessPointNameForObjectProcess, PurgeConfiguration/IsPurgeCdnCache, atau ClientCaConfiguration), atau format badan permintaan tidak valid.
CnameCertificateMismatch	400	Sertifikat tidak sesuai dengan nama domain CNAME. Saat Anda memetakan CNAME wildcard, gunakan Sertifikat wildcard yang CN atau SAN-nya sesuai dengan `*.<Domain>`.
NeedVerifyDomainOwnership	403	Kepemilikan nama domain belum diverifikasi. Untuk memverifikasi kepemilikan nama domain, lakukan langkah-langkah berikut: Panggil CreateCnameToken untuk membuat token CNAME yang diperlukan untuk verifikasi kepemilikan nama domain. Saat membuat token untuk nama domain dasar wildcard pada Agentic Bucket, tentukan `wildcard=true`. Tambahkan rekaman TXT di penyedia layanan nama domain Anda. Misalnya, untuk menambahkan rekaman TXT untuk nama domain kustom `example.com`, atur tipe catatan ke TXT, rekaman host ke `_dnsauth.example`, dan nilai catatan ke token CNAME yang dikembalikan oleh Langkah 1. Gunakan pengaturan default untuk parameter lainnya. Untuk informasi selengkapnya, lihat Menambahkan rekaman CNAME secara manual. Catatan Rekaman TXT yang Anda tambahkan memerlukan beberapa menit hingga berlaku. Panggil PutCname untuk memetakan nama domain kustom.
CnameDenied	403	Nama domain sedang digunakan.
CnameIsForbidden	403	Nama domain dicadangkan oleh OSS dan tidak dapat dipetakan.
CnameIsRisk	403	Nama domain berisiko tinggi dan tidak dapat dipetakan.
NoSuchCnameInRecord	404	Nama domain tidak memiliki Pendaftaran ICP. Untuk informasi lebih lanjut tentang cara mengajukan Pendaftaran ICP, lihat Nama Domain Alibaba Cloud.
ConflictCname	409	Nama domain dasar wildcard sudah dipetakan ke Agentic Bucket lain di bawah UID yang sama. Pertama-tama, hapus pemetaan CNAME wildcard dari Agentic Bucket asal, lalu petakan kembali.
CnameAlreadyExists	409	Penyebab error berikut mungkin terjadi: Nama domain sudah dipetakan ke bucket lain di akun saat ini. Gejala: CnameType dalam pesan error yang dikembalikan adalah CNAME_OSS. Nama domain adalah nama domain Pemrosesan gambar. Gejala: CnameType dalam pesan error yang dikembalikan adalah CNAME_IMG. Untuk mengatasi masalah ini, hapus pemetaan nama domain tersebut. Untuk informasi selengkapnya, lihat Menghapus pemetaan nama domain.
MethodNotAllowed	405	Fitur CNAME tidak diaktifkan untuk tipe bucket target.