PutCname - Mapear um nome de domínio personalizado para um bucket - Object Storage Service: Central de Documentação do Alibaba Cloud

A operação PutCname mapeia um nome de domínio personalizado para um bucket. Buckets padrão aceitam apenas CNAMEs exatos. O Agentic Bucket também aceita CNAMEs curinga para acessar seus Bucket Spaces.

Observações de uso

Ao mapear um CNAME exato ou curinga para um Agentic Bucket, inclua explicitamente o elemento IsWildCard no XML da requisição e defina-o como true ou false. O valor não pode estar vazio.
O Agentic Bucket não oferece suporte aos seguintes elementos: AccessPointName, AccessPointNameForObjectProcess, PurgeConfiguration/IsPurgeCdnCache e ClientCaConfiguration (incluindo casCertId, certificados inline e operações de exclusão). A configuração de qualquer um desses elementos faz o OSS retornar o erro 400 MalformedXML. Buckets padrão mantêm suporte total a esses elementos.
Não é possível mapear um Bucket Space diretamente para um CNAME. O acesso via rede pública a um Bucket Space ocorre por meio do CNAME curinga mapeado para o Agentic Bucket pai.

Permissões

Por padrão, uma conta Alibaba Cloud possui todas as permissões. Usuários RAM e funções RAM vinculados a uma conta Alibaba Cloud não têm permissões por padrão. A conta Alibaba Cloud ou um administrador de contas deve conceder as permissões necessárias usando RAM Policy ou Bucket Policy.

API	Action	Description
PutCname	oss:PutCname	Mapeia um nome de domínio personalizado para um bucket.
	yundun-cert:DescribeSSLCertificatePrivateKey	Se você vincular um certificado ao mapear um nome de domínio personalizado para um bucket, estas três permissões serão necessárias.
	yundun-cert:DescribeSSLCertificatePublicKeyDetail
	yundun-cert:CreateSSLCertificate

Sintaxe da requisição

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

A operação PutCname utiliza o elemento IsWildCard no XML da requisição para declarar se o CNAME é exato ou curinga. Para um Agentic Bucket, o elemento IsWildCard é obrigatório.

Cabeçalhos da requisição

Esta operação usa apenas cabeçalhos de requisição comuns. Para mais informações, consulte Common HTTP headers.

Elementos da requisição

Element	Type	Required	Example	Description
BucketCnameConfiguration	Container	Yes	N/A	Contêiner que armazena a configuração do CNAME. Nós pais: nenhum Nós filhos: Cname
Cname	Container	Yes	N/A	Contêiner que armazena as informações do CNAME. Nós pais: BucketCnameConfiguration Nós filhos: Domain, IsWildCard e CertificateConfiguration
Domain	String	Yes	example.com	Nome de domínio personalizado. Para mapear um CNAME exato, defina este elemento com o nome de domínio completo, como console.example.com. Para mapear um CNAME curinga, defina este elemento com o domínio base sem o prefixo `*.`, como example.com. Nós pais: Cname Nós filhos: nenhum
IsWildCard	Boolean	Bucket padrão: No Agentic Bucket: Yes	true	Especifica se deve ser mapeado um CNAME curinga. Valores válidos: true: mapeia um CNAME curinga. Defina Domain como o domínio base. false: mapeia um CNAME exato. Defina Domain como o nome de domínio completo. Para um Agentic Bucket, este elemento é obrigatório. Defina-o explicitamente como true ou false; ele não pode estar vazio. Para um bucket padrão, este elemento é opcional e tem false como valor padrão. Nós pais: Cname Nós filhos: nenhum
CertificateConfiguration	Container	No	N/A	Contêiner que armazena a configuração do certificado. Ao mapear um CNAME curinga, o CN ou SAN do certificado deve corresponder a `*.<Domain>`; portanto, um certificado curinga é necessário. Nós pais: Cname Nós filhos: CertId, Certificate, PrivateKey, PreviousCertId, Force e DeleteCertificate
CertId	String	No	493****-cn-hangzhou	ID do certificado. Nós pais: CertificateConfiguration Nós filhos: nenhum
Certificate	String	No	-----BEGIN CERTIFICATE----- MIIDhDCCAmwCCQCFs8ixARsyrDANBgkqhkiG9w0BAQsFADCBgzELMAkGA1UEBhMC **** -----END CERTIFICATE-----	Chave pública do certificado. Nós pais: CertificateConfiguration Nós filhos: nenhum
PrivateKey	String	No	-----BEGIN PRIVATE KEY----- MIIDhDCCAmwCCQCFs8ixARsyrDANBgkqhkiG9w0BAQsFADCBgzELMAkGA1UEBhMC **** -----END PRIVATE KEY-----	Chave privada do certificado. Nós pais: CertificateConfiguration Nós filhos: nenhum
PreviousCertId	String	No	493****-cn-hangzhou	ID do certificado atualmente vinculado. Se Force não estiver definido como true, o OSS verifica se este valor corresponde ao certificado realmente vinculado e retorna um erro em caso negativo. Importante Se você não especificar PreviousCertId ao vincular um certificado, defina Force como true. Nós pais: CertificateConfiguration Nós filhos: nenhum
Force	String	No	true	Indica se o certificado deve ser sobrescrito. Valores válidos: true: sobrescreve o certificado. false: não sobrescreve o certificado. Nós pais: CertificateConfiguration Nós filhos: nenhum
DeleteCertificate	String	No	true	Indica se o certificado deve ser excluído. Valores válidos: true: exclui o certificado. false: não exclui o certificado. Nós pais: CertificateConfiguration Nós filhos: nenhum

Cabeçalhos da resposta

Esta operação retorna apenas cabeçalhos de resposta comuns. Para mais informações, consulte Common HTTP headers.

Exemplos

Exemplos de requisições

Mapear um nome de domínio personalizado para um bucket padrão

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>

Vincular um certificado a um nome de domínio personalizado de um bucket padrão

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>

Desvincular um certificado de um nome de domínio personalizado de um bucket padrão

Se não desejar mais que o nome de domínio utilize este certificado, desvincule-o.

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>

Mapear um CNAME curinga para um Agentic Bucket (com certificado curinga)

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>

Mapear um CNAME exato para um 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>

Exemplo de resposta

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

SDKs do OSS

Os seguintes SDKs do OSS oferecem suporte à operação PutCname:

ossutil

Para obter informações sobre o comando do ossutil correspondente à operação PutCname, consulte put-cname.

Códigos de erro

Error code	HTTP status code	Description
InvalidArgument	400	Possíveis causas do erro: O formato do CNAME é inválido. Verifique o XML retornado para identificar o campo específico e o motivo do erro. Em um Agentic Bucket, o elemento `IsWildCard` está ausente ou seu valor está vazio. Falha na verificação do domínio base curinga. Por exemplo, o número de rótulos excede o limite superior, o número de níveis é insuficiente ou o nome de domínio usa uma combinação de TLD de alto risco.
MalformedXML	400	A requisição inclui um elemento incompatível com Agentic Buckets (AccessPointName, AccessPointNameForObjectProcess, PurgeConfiguration/IsPurgeCdnCache ou ClientCaConfiguration) ou o formato do corpo da requisição é inválido.
CnameCertificateMismatch	400	O certificado não corresponde ao nome de domínio do CNAME. Ao mapear um CNAME curinga, use um certificado curinga cujo CN ou SAN corresponda a `*.<Domain>`.
NeedVerifyDomainOwnership	403	A propriedade do nome de domínio não foi verificada. Para verificar a propriedade do nome de domínio, execute as etapas a seguir: Chame CreateCnameToken para criar o token de CNAME necessário para a verificação de propriedade do domínio. Ao criar um token para um domínio base curinga em um Agentic Bucket, especifique `wildcard=true`. Adicione um registro TXT no provedor de service de domínio. Por exemplo, para adicionar um registro TXT para o nome de domínio personalizado `example.com`, defina o tipo de registro como TXT, o host record como `_dnsauth.example` e o valor do registro como o token de CNAME retornado pela Etapa 1. Mantenha as configurações padrão para os demais parâmetros. Para mais informações, consulte Manually add a CNAME record. Nota O registro TXT adicionado leva alguns minutos para entrar em vigor. Chame PutCname para mapear o nome de domínio personalizado.
CnameDenied	403	O nome de domínio já está em uso.
CnameIsForbidden	403	O nome de domínio é reservado pelo OSS e não pode ser mapeado.
CnameIsRisk	403	O nome de domínio apresenta alto risco e não pode ser mapeado.
NoSuchCnameInRecord	404	O nome de domínio não possui registro ICP. Para mais informações sobre como solicitar um registro ICP, consulte Alibaba Cloud Domain Names.
ConflictCname	409	O domínio base curinga já está mapeado para outro Agentic Bucket sob o mesmo UID. Remova o mapeamento do CNAME curinga do Agentic Bucket original primeiro e, em seguida, mapeie-o novamente.
CnameAlreadyExists	409	Possíveis causas do erro: O nome de domínio já está mapeado para outro bucket na conta atual. Sintoma: O CnameType na mensagem de erro retornada é CNAME_OSS. O nome de domínio é um domínio de processamento de imagens. Sintoma: O CnameType na mensagem de erro retornada é CNAME_IMG. Para resolver esses problemas, remova o mapeamento do nome de domínio. Para mais informações, consulte Unmap a domain name.
MethodNotAllowed	405	O recurso de CNAME não está ativado para o tipo de bucket de destino.