PutCname - Map a custom domain name to a bucket - Object Storage Service: Central de Documentação do Alibaba Cloud

O PutCname mapeia um nome de domínio personalizado para um bucket. Um bucket padrão suporta apenas um CNAME exato. Um Agentic Bucket também suporta um CNAME curinga, usado para acessar seus Bucket Spaces.

Notas 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.
Para um Agentic Bucket, os seguintes elementos não têm suporte: AccessPointName, AccessPointNameForObjectProcess, PurgeConfiguration/IsPurgeCdnCache e ClientCaConfiguration (incluindo casCertId, certificados inline e operações de exclusão). Se configure qualquer um deles, o OSS retorna o erro 400 MalformedXML. Um bucket padrão oferece suporte total a esses elementos.
Não é possível mapear um Bucket Space diretamente para um CNAME. O acesso pela rede pública a um Bucket Space ocorre por meio do CNAME curinga mapeado para o seu Agentic Bucket pai.

Permissões

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

API	Ação	Descrição
PutCname	oss:PutCname	Mapeia um nome de domínio personalizado para um bucket.
	yundun-cert:DescribeSSLCertificatePrivateKey	Se vincular um certificado ao mapear um nome de domínio personalizado para um bucket, essas três permissões sã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

O PutCname usa 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

Elemento	Tipo	Obrigatório	Exemplo	Descrição
BucketCnameConfiguration	Contêiner	Sim	N/D	O contêiner que armazena a configuração do CNAME. Nós pai: nenhum Nós filho: Cname
Cname	Contêiner	Sim	N/D	O contêiner que armazena as informações do CNAME. Nós pai: BucketCnameConfiguration Nós filho: Domain, IsWildCard e CertificateConfiguration
Domain	String	Sim	example.com	O nome de domínio personalizado. Para mapear um CNAME exato, defina este elemento como o nome de domínio completo, como console.example.com. Para mapear um CNAME curinga, defina este elemento como o nome de domínio base sem o prefixo `*.`, como example.com. Nós pai: Cname Nós filho: nenhum
IsWildCard	Booleano	Bucket padrão: Não Agentic Bucket: Sim	true	Indica se o CNAME mapeado é curinga. Valores válidos: true: mapeia um CNAME curinga. Defina Domain como o nome de 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. Para um bucket padrão, se omitir este elemento, o valor padrão será false. Nós pai: Cname Nós filho: nenhum
CertificateConfiguration	Contêiner	Não	N/D	O 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, é obrigatório usar um certificado curinga. Nós pai: Cname Nós filho: CertId, Certificate, PrivateKey, PreviousCertId, Force e DeleteCertificate
CertId	String	Não	493****-cn-hangzhou	O ID do certificado. Nós pai: CertificateConfiguration Nós filho: nenhum
Certificate	String	Não	-----BEGIN CERTIFICATE----- MIIDhDCCAmwCCQCFs8ixARsyrDANBgkqhkiG9w0BAQsFADCBgzELMAkGA1UEBhMC **** -----END CERTIFICATE-----	A chave pública do certificado. Nós pai: CertificateConfiguration Nós filho: nenhum
PrivateKey	String	Não	-----BEGIN PRIVATE KEY----- MIIDhDCCAmwCCQCFs8ixARsyrDANBgkqhkiG9w0BAQsFADCBgzELMAkGA1UEBhMC **** -----END PRIVATE KEY-----	A chave privada do certificado. Nós pai: CertificateConfiguration Nós filho: nenhum
PreviousCertId	String	Não	493****-cn-hangzhou	O ID do certificado vinculado no momento. 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 de divergência. Importante Se não especificar PreviousCertId ao vincular um certificado, defina Force como true. Nós pai: CertificateConfiguration Nós filho: nenhum
Force	String	Não	true	Indica se o certificado será sobrescrito. Valores válidos: true: sobrescreve o certificado. false: não sobrescreve o certificado. Nós pai: CertificateConfiguration Nós filho: nenhum
DeleteCertificate	String	Não	true	Indica se o certificado será excluído. Valores válidos: true: exclua o certificado. false: não exclua o certificado. Nós pai: CertificateConfiguration Nós filho: nenhum

Cabeçalhos da resposta

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

Exemplos

Requisições de exemplo

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 quiser mais que o nome de domínio use 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 um 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>

Resposta de exemplo

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

Os seguintes SDK 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

Código de erro	Código de status HTTP	Descrição
InvalidArgument	400	Possíveis causas do erro: O formato do CNAME é inválido. Verifique o XML retornado para ver o campo e o motivo específicos do erro. Para um Agentic Bucket, o elemento `IsWildCard` está ausente ou seu valor está vazio. A validação do nome de domínio base curinga falhou. Por exemplo, o número de rótulos excede o limite máximo, 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 sem suporte em 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 seguintes etapas: Chame CreateCnameToken para criar o token de CNAME necessário para a verificação de propriedade do nome de domínio. Ao criar um token para um nome de domínio base curinga em um Agentic Bucket, especifique `wildcard=true`. Adicione um registro TXT no provedor de serviços de nome 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 registro de host como `_dnsauth.example` e o valor do registro como o token de CNAME retornado por Step 1. Mantenha as configurações padrão para os outros parâmetros. Para mais informações, consulte Manually add a CNAME record. Nota O registro TXT adicionado leva alguns minutos para fazer efeito. 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 é possível mapeá-lo.
CnameIsRisk	403	O nome de domínio apresenta alto risco e não é possível mapeá-lo.
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 nome de domínio base curinga já está mapeado para outro Agentic Bucket com o mesmo UID. Primeiro, remova o mapeamento do CNAME curinga do Agentic Bucket original 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 é usado para 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 CNAME não está ativado para o tipo de bucket de destino.