PutCname - Object Storage Service - Centro de documentación de Alibaba Cloud

PutCname asigna un nombre de dominio personalizado a un bucket. Un bucket estándar solo admite un CNAME exacto. Un Agentic Bucket también admite un CNAME comodín, que se usa para acceder a sus Bucket Spaces.

Notas de uso

Cuando asigne un CNAME exacto o comodín a un Agentic Bucket, incluya explícitamente el elemento IsWildCard en el XML de la solicitud y establézcalo como true o false.
Un Agentic Bucket no es compatible con los siguientes elementos: AccessPointName, AccessPointNameForObjectProcess, PurgeConfiguration/IsPurgeCdnCache y ClientCaConfiguration (incluidos casCertId, los certificados inline y las operaciones de eliminación). Si configura alguno de ellos, OSS devuelve el error 400 MalformedXML. Un bucket estándar conserva la compatibilidad total con estos elementos.
No es posible asignar un Bucket Space directamente a un CNAME. El acceso por red pública a un Bucket Space se efectúa mediante el CNAME comodín asignado a su Agentic Bucket principal.

Permisos

De forma predeterminada, una cuenta de Alibaba Cloud tiene todos los permisos. Los usuarios y roles de RAM bajo una cuenta de Alibaba Cloud carecen de permisos de manera predeterminada. La cuenta de Alibaba Cloud o un administrador de la cuenta debe otorgar los permisos obligatorios mediante RAM Policy o Bucket Policy.

API	Action	Descripción
PutCname	oss:PutCname	Asigna un nombre de dominio personalizado a un bucket.
	yundun-cert:DescribeSSLCertificatePrivateKey	Si vincula un certificado al asignar un nombre de dominio personalizado a un bucket, estos tres permisos son obligatorios.
	yundun-cert:DescribeSSLCertificatePublicKeyDetail
	yundun-cert:CreateSSLCertificate

Sintaxis de la solicitud

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>

Nota

PutCname usa el elemento IsWildCard en el XML de la solicitud para declarar si el CNAME es exacto o comodín. En un Agentic Bucket, el elemento IsWildCard es obligatorio.

Encabezados de solicitud

Esta operación solo usa encabezados de solicitud comunes. Para obtener más información, consulte Common HTTP headers.

Elementos de la solicitud

Elemento	Tipo	Obligatorio	Ejemplo	Descripción
BucketCnameConfiguration	Contenedor	Sí	Ninguna	Contenedor que almacena la configuración del CNAME. Nodos principales: ninguno Nodos secundarios: Cname
Cname	Contenedor	Sí	Ninguna	Contenedor que almacena la información del CNAME. Nodos principales: BucketCnameConfiguration Nodos secundarios: Domain, IsWildCard y CertificateConfiguration
Domain	String	Sí	example.com	Nombre de dominio personalizado. Para asignar un CNAME exacto, establezca este elemento con el nombre de dominio completo, como console.example.com. Para asignar un CNAME comodín, establézcalo con el nombre de dominio base sin el prefijo `*.`, por ejemplo, example.com. Nodos principales: Cname Nodos secundarios: ninguno
IsWildCard	Boolean	Bucket estándar: No Agentic Bucket: Sí	true	Especifica si se asigna un CNAME comodín. Valores válidos: true: asigna un CNAME comodín. Establezca Domain con el nombre de dominio base. false: asigna un CNAME exacto. Establezca Domain con el nombre de dominio completo. En un Agentic Bucket, este elemento es obligatorio. Establézcalo explícitamente como true o false. En un bucket estándar, si omite este elemento, el valor predeterminado es false. Nodos principales: Cname Nodos secundarios: ninguno
CertificateConfiguration	Contenedor	No	Ninguna	Contenedor que almacena la configuración del certificado. Al asignar un CNAME comodín, el CN o SAN del certificado debe coincidir con `*.<Domain>`, por lo que se requiere un certificado comodín. Nodos principales: Cname Nodos secundarios: CertId, Certificate, PrivateKey, PreviousCertId, Force y DeleteCertificate
CertId	String	No	493****-cn-hangzhou	ID del certificado. Nodos principales: CertificateConfiguration Nodos secundarios: ninguno
Certificate	String	No	-----BEGIN CERTIFICATE----- MIIDhDCCAmwCCQCFs8ixARsyrDANBgkqhkiG9w0BAQsFADCBgzELMAkGA1UEBhMC **** -----END CERTIFICATE-----	Clave pública del certificado. Nodos principales: CertificateConfiguration Nodos secundarios: ninguno
PrivateKey	String	No	-----BEGIN PRIVATE KEY----- MIIDhDCCAmwCCQCFs8ixARsyrDANBgkqhkiG9w0BAQsFADCBgzELMAkGA1UEBhMC **** -----END PRIVATE KEY-----	Clave privada del certificado. Nodos principales: CertificateConfiguration Nodos secundarios: ninguno
PreviousCertId	String	No	493****-cn-hangzhou	ID del certificado vinculado actualmente. Si Force no se establece como true, OSS comprueba que este valor coincida con el certificado realmente vinculado y devuelve un error si no coinciden. Importante Si no especifica PreviousCertId al vincular un certificado, establezca Force como true. Nodos principales: CertificateConfiguration Nodos secundarios: ninguno
Force	String	No	true	Especifica si se sobrescribe el certificado. Valores válidos: true: sobrescribe el certificado. false: no sobrescribe el certificado. Nodos principales: CertificateConfiguration Nodos secundarios: ninguno
DeleteCertificate	String	No	true	Especifica si se elimina el certificado. Valores válidos: true: elimina el certificado. false: no elimina el certificado. Nodos principales: CertificateConfiguration Nodos secundarios: ninguno

Encabezados de respuesta

Esta operación solo devuelve encabezados de respuesta comunes. Para obtener más información, consulte Common HTTP headers.

Ejemplos

Solicitudes de ejemplo

Asignación de un nombre de dominio personalizado a un bucket estándar

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>

Vinculación de un certificado a un nombre de dominio personalizado de un bucket estándar

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>

Desvinculación de un certificado de un nombre de dominio personalizado de un bucket estándar

Si ya no desea que el nombre de dominio use este certificado, desvincúlelo.

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>

Asignación de un CNAME comodín a un Agentic Bucket (con un certificado comodín)

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>

Asignación de un CNAME exacto a 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>

Respuesta de ejemplo

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 de OSS

Los siguientes SDK de OSS admiten la operación PutCname:

ossutil

Para obtener información sobre el comando de ossutil correspondiente a la operación PutCname, consulte put-cname.

Códigos de error

Código de error	Código de estado HTTP	Descripción
InvalidArgument	400	Las posibles causas del error son a continuación: El formato del CNAME no es válido. Revise el XML devuelto para identificar el campo específico del error y su motivo. En un Agentic Bucket, falta el elemento `IsWildCard` o su valor está vacío. La verificación del nombre de dominio base comodín terminó con errores. Por ejemplo, la cantidad de etiquetas supera el límite superior, el número de niveles es insuficiente o el nombre de dominio usa una combinación de TLD de alto riesgo.
MalformedXML	400	La solicitud incluye un elemento que los Agentic Buckets no admiten (AccessPointName, AccessPointNameForObjectProcess, PurgeConfiguration/IsPurgeCdnCache o ClientCaConfiguration), o bien el formato del cuerpo de la solicitud no es válido.
CnameCertificateMismatch	400	El certificado no coincide con el nombre de dominio del CNAME. Cuando asigne un CNAME comodín, use un certificado comodín cuyo CN o SAN coincida con `*.<Domain>`.
NeedVerifyDomainOwnership	403	No se verificó la propiedad del nombre de dominio. Para comprobar la propiedad del nombre de dominio, siga estos pasos: Llame a CreateCnameToken para crear el token de CNAME necesario para la verificación de propiedad del nombre de dominio. Cuando cree un token para un nombre de dominio base comodín en un Agentic Bucket, especifique `wildcard=true`. Agregue un registro TXT en su proveedor de servicios de nombres de dominio. Por ejemplo, para agregar un registro TXT al nombre de dominio personalizado `example.com`, establezca el tipo de registro como TXT, el registro de host como `_dnsauth.example` y el valor del registro con el token de CNAME devuelto por Step 1. Mantenga la configuración predeterminada para los demás parámetros. Para obtener más información, consulte Manually add a CNAME record. Nota El registro TXT que agregue tarda varios minutos en surtir efecto. Llame a PutCname para asignar el nombre de dominio personalizado.
CnameDenied	403	El nombre de dominio ya está in use.
CnameIsForbidden	403	OSS reservó el nombre de dominio y no se puede asignar.
CnameIsRisk	403	El nombre de dominio representa un riesgo alto y no se puede asignar.
NoSuchCnameInRecord	404	El nombre de dominio no cuenta con un registro ICP. Para obtener más información sobre cómo solicitar un registro ICP, consulte Alibaba Cloud Domain Names.
ConflictCname	409	El nombre de dominio base comodín ya está asignado a otro Agentic Bucket bajo el mismo UID. Desasigne primero el CNAME comodín del Agentic Bucket original y vuelva a asignarlo después.
CnameAlreadyExists	409	Las posibles causas del error son a continuación: El nombre de dominio ya está asignado a otro bucket de la cuenta actual. Síntoma: el valor de CnameType en el mensaje de error devuelto es CNAME_OSS. El nombre de dominio corresponde a procesamiento de imágenes. Síntoma: el valor de CnameType en el mensaje de error devuelto es CNAME_IMG. Para resolver estos problemas, desasigne el nombre de dominio. Para obtener más información, consulte Unmap a domain name.
MethodNotAllowed	405	La función de CNAME no está habilitada para el tipo de bucket de destino.