PutCname - Associer un nom de domaine personnalisé à un bucket - Object Storage Service

L'opération PutCname associe un nom de domaine personnalisé à un bucket. Un bucket standard prend uniquement en charge les enregistrements CNAME exacts. Un Agentic Bucket prend également en charge les CNAME génériques (wildcard), utilisés pour accéder à ses Bucket Spaces.

Remarques d'utilisation

Lorsque vous associez un CNAME exact ou générique à un Agentic Bucket, vous devez inclure explicitement l'élément IsWildCard dans le corps XML de la requête et définir sa valeur sur true ou false.
Pour un Agentic Bucket, les éléments suivants ne sont pas pris en charge : AccessPointName, AccessPointNameForObjectProcess, PurgeConfiguration/IsPurgeCdnCache et ClientCaConfiguration (y compris casCertId, les certificats intégrés et les opérations de suppression). Si vous configurez l'un de ces éléments, OSS renvoie l'erreur 400 MalformedXML. Un bucket standard conserve la prise en charge complète de ces éléments.
Il est impossible d'associer directement un CNAME à un Bucket Space. L'accès réseau public à un Bucket Space s'effectue via le CNAME générique associé à son Agentic Bucket parent.

Autorisations

Par défaut, un compte Alibaba Cloud dispose de toutes les autorisations. Les utilisateurs RAM et les rôles RAM rattachés à un compte Alibaba Cloud ne disposent d'aucune autorisation par défaut. Le compte Alibaba Cloud ou un administrateur du compte doit accorder les autorisations requises à l'aide d'une politique RAM ou d'une politique de bucket.

API	Action	Description
PutCname	oss:PutCname	Associe un nom de domaine personnalisé à un bucket.
	yundun-cert:DescribeSSLCertificatePrivateKey	Si vous liez un certificat lors de l'association d'un nom de domaine personnalisé à un bucket, ces trois autorisations sont requises.
	yundun-cert:DescribeSSLCertificatePublicKeyDetail
	yundun-cert:CreateSSLCertificate

Syntaxe de la requête

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>

Remarque

L'opération PutCname utilise l'élément IsWildCard dans le corps XML de la requête pour indiquer si le CNAME est exact ou générique. Pour un Agentic Bucket, l'élément IsWildCard est obligatoire.

En-têtes de requête

Cette opération utilise uniquement des en-têtes de requête communs. Pour plus d'informations, consultez la section En-têtes HTTP communs.

Éléments de requête

Élément	Type	Obligatoire	Exemple	Description
BucketCnameConfiguration	Conteneur	Oui	S.O.	Conteneur qui stocke la configuration CNAME. Nœuds parents : aucun Nœuds enfants : Cname
Cname	Conteneur	Oui	S.O.	Conteneur qui stocke les informations CNAME. Nœuds parents : BucketCnameConfiguration Nœuds enfants : Domain, IsWildCard et CertificateConfiguration
Domain	Chaîne	Oui	example.com	Nom de domaine personnalisé. Pour associer un CNAME exact, définissez cet élément avec le nom de domaine complet, par exemple console.example.com. Pour associer un CNAME générique, définissez cet élément avec le nom de domaine de base sans le préfixe `*.`, par exemple example.com. Nœuds parents : Cname Nœuds enfants : aucun
IsWildCard	Booléen	Bucket standard : Non Agentic Bucket : Oui	true	Indique s'il faut associer un CNAME générique. Valeurs valides : true : associe un CNAME générique. Définissez Domain avec le nom de domaine de base. false : associe un CNAME exact. Définissez Domain avec le nom de domaine complet. Pour un Agentic Bucket, cet élément est obligatoire. Définissez-le explicitement sur true ou false. Pour un bucket standard, si vous omettez cet élément, la valeur par défaut est false. Nœuds parents : Cname Nœuds enfants : aucun
CertificateConfiguration	Conteneur	Non	S.O.	Conteneur qui stocke la configuration du certificat. Lorsque vous associez un CNAME générique, le CN ou le SAN du certificat doit correspondre à `*.<Domain>`, ce qui nécessite un certificat générique. Nœuds parents : Cname Nœuds enfants : CertId, Certificate, PrivateKey, PreviousCertId, Force et DeleteCertificate
CertId	Chaîne	Non	493****-cn-hangzhou	ID du certificat. Nœuds parents : CertificateConfiguration Nœuds enfants : aucun
Certificate	Chaîne	Non	-----BEGIN CERTIFICATE----- MIIDhDCCAmwCCQCFs8ixARsyrDANBgkqhkiG9w0BAQsFADCBgzELMAkGA1UEBhMC **** -----END CERTIFICATE-----	Clé publique du certificat. Nœuds parents : CertificateConfiguration Nœuds enfants : aucun
PrivateKey	Chaîne	Non	-----BEGIN PRIVATE KEY----- MIIDhDCCAmwCCQCFs8ixARsyrDANBgkqhkiG9w0BAQsFADCBgzELMAkGA1UEBhMC **** -----END PRIVATE KEY-----	Clé privée du certificat. Nœuds parents : CertificateConfiguration Nœuds enfants : aucun
PreviousCertId	Chaîne	Non	493****-cn-hangzhou	ID du certificat actuellement lié. Si Force n'est pas défini sur true, OSS vérifie que cette valeur correspond au certificat effectivement lié et renvoie une erreur en cas de non-concordance. Important Si vous ne spécifiez pas PreviousCertId lors de la liaison d'un certificat, définissez Force sur true. Nœuds parents : CertificateConfiguration Nœuds enfants : aucun
Force	Chaîne	Non	true	Indique s'il faut écraser le certificat. Valeurs valides : true : écrase le certificat. false : n'écrase pas le certificat. Nœuds parents : CertificateConfiguration Nœuds enfants : aucun
DeleteCertificate	Chaîne	Non	true	Indique s'il faut supprimer le certificat. Valeurs valides : true : supprime le certificat. false : ne supprime pas le certificat. Nœuds parents : CertificateConfiguration Nœuds enfants : aucun

En-têtes de réponse

Cette opération renvoie uniquement des en-têtes de réponse communs. Pour plus d'informations, consultez la section En-têtes HTTP communs.

Exemples

Exemples de requêtes

Associer un nom de domaine personnalisé à un bucket standard

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>

Lier un certificat à un nom de domaine personnalisé d'un bucket standard

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>

Dissocier un certificat d'un nom de domaine personnalisé d'un bucket standard

Si vous ne souhaitez plus que le nom de domaine utilise ce certificat, dissociez-le.

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>

Associer un CNAME générique à un Agentic Bucket (avec un certificat générique)

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>

Associer un CNAME exact à un 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>

Exemple de réponse

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 OSS

Les SDK OSS suivants prennent en charge l'opération PutCname :

ossutil

Pour obtenir des informations sur la commande ossutil correspondant à l'opération PutCname, consultez la section put-cname.

Codes d'erreur

Code d'erreur	Code d'état HTTP	Description
InvalidArgument	400	Les causes possibles de cette erreur sont les suivantes : Le format CNAME n'est pas valide. Vous pouvez vérifier le champ d'erreur spécifique et la raison dans le XML renvoyé. Pour un Agentic Bucket, l'élément `IsWildCard` est manquant ou sa valeur est vide. La vérification du nom de domaine de base générique a échoué. Par exemple, le nombre d'étiquettes dépasse la limite supérieure, le nombre de niveaux est insuffisant ou le nom de domaine utilise une combinaison TLD à haut risque.
MalformedXML	400	La requête inclut un élément non pris en charge par les Agentic Buckets (AccessPointName, AccessPointNameForObjectProcess, PurgeConfiguration/IsPurgeCdnCache ou ClientCaConfiguration), ou le format du corps de la requête n'est pas valide.
CnameCertificateMismatch	400	Le certificat ne correspond pas au nom de domaine CNAME. Lorsque vous associez un CNAME générique, utilisez un certificat générique dont le CN ou le SAN correspond à `*.<Domain>`.
NeedVerifyDomainOwnership	403	La propriété du nom de domaine n'est pas vérifiée. Pour vérifier la propriété du nom de domaine, procédez comme suit : Appelez CreateCnameToken pour créer le jeton CNAME requis pour la vérification de la propriété du nom de domaine. Lorsque vous créez un jeton pour un nom de domaine de base générique sur un Agentic Bucket, spécifiez `wildcard=true`. Ajoutez un enregistrement TXT auprès de votre fournisseur de services de noms de domaine. Par exemple, pour ajouter un enregistrement TXT pour le nom de domaine personnalisé `example.com`, définissez le type d'enregistrement sur TXT, l'enregistrement hôte sur `_dnsauth.example` et la valeur d'enregistrement sur le jeton CNAME renvoyé par l'étape 1. Conservez les paramètres par défaut pour les autres paramètres. Pour plus d'informations, consultez la section Ajouter manuellement un enregistrement CNAME. Remarque L'enregistrement TXT que vous ajoutez prend plusieurs minutes pour devenir effectif. Appelez PutCname pour associer le nom de domaine personnalisé.
CnameDenied	403	Le nom de domaine est déjà utilisé.
CnameIsForbidden	403	Le nom de domaine est réservé par OSS et ne peut pas être associé.
CnameIsRisk	403	Le nom de domaine présente un risque élevé et ne peut pas être associé.
NoSuchCnameInRecord	404	Le nom de domaine ne possède pas de dépôt ICP. Pour plus d'informations sur la demande de dépôt ICP, consultez la section Noms de domaine Alibaba Cloud.
ConflictCname	409	Le nom de domaine de base générique est déjà associé à un autre Agentic Bucket sous le même UID. Dissociez d'abord le CNAME générique de l'Agentic Bucket d'origine, puis associez-le à nouveau.
CnameAlreadyExists	409	Les causes possibles de cette erreur sont les suivantes : Le nom de domaine est déjà associé à un autre bucket dans le compte actuel. Symptôme : La valeur CnameType dans le message d'erreur renvoyé est CNAME_OSS. Le nom de domaine est un nom de domaine de traitement d'image. Symptôme : La valeur CnameType dans le message d'erreur renvoyé est CNAME_IMG. Pour résoudre ces problèmes, dissociez le nom de domaine. Pour plus d'informations, consultez la section Dissocier un nom de domaine.
MethodNotAllowed	405	La fonctionnalité CNAME n'est pas activée pour le type de bucket cible.