DeleteCname

DeleteCname unmaps a custom domain name (CNAME) from a bucket. This operation is idempotent: if the specified CNAME is not mapped to the bucket, it still returns HTTP 200 with no error. For an Agentic Bucket, you must use the wildcard parameter to explicitly specify whether to unmap an exact CNAME or a wildcard CNAME.

Usage notes

When you call DeleteCname on an Agentic Bucket, the wildcard parameter is required: wildcard=true unmaps a wildcard CNAME, and wildcard=false unmaps an exact CNAME.
To unmap an exact CNAME from a standard bucket, you call this operation in exactly the same way as the existing OSS CNAME operations. No new parameters are required.

Request syntax

POST /?cname&comp=delete&wildcard=true 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>

Note

The wildcard parameter distinguishes the type of CNAME to unmap. For an Agentic Bucket, this parameter is required. Set it explicitly to true or false. For a standard bucket, if you omit this parameter, the value defaults to false.

Request headers

This operation uses only common request headers. For more information, see Common HTTP headers.

Request parameters

Parameter

Type

Required

Example

Description

wildcard

String

Standard bucket: No

Agentic Bucket: Yes

true

Specifies whether to unmap a wildcard CNAME. Valid values:

true: unmaps a wildcard CNAME.
false: unmaps an exact CNAME.

For an Agentic Bucket, this parameter is required. Set it explicitly to true or false. For a standard bucket, if you omit this parameter, the value defaults to false.

The wildcard parameter takes different values for each bucket type:

Bucket type	Parameter omitted	wildcard=false	wildcard=true
Standard bucket	Unmaps an exact CNAME	Unmaps an exact CNAME	Not allowed
Agentic Bucket	Not allowed	Unmaps an exact CNAME from the Agentic Bucket	Unmaps a wildcard CNAME

Note

For an Agentic Bucket, the same base domain name can have an exact CNAME and a wildcard CNAME mapped at the same time. Specify the wildcard parameter explicitly to identify which CNAME to unmap.

Request elements

Element	Type	Required	Example	Description
BucketCnameConfiguration	Container	Yes	N/A	The container that stores the CNAME configuration. Parent nodes: none Child nodes: Cname
Cname	Container	Yes	N/A	The container that stores the CNAME information. Parent nodes: BucketCnameConfiguration Child nodes: Domain
Domain	String	Yes	example.com	The custom domain name. To unmap an exact CNAME, set this element to the complete domain name, such as console.example.com. To unmap a wildcard CNAME, set this element to the base domain name without the `*.` prefix, such as example.com. Parent nodes: Cname Child nodes: none

Response headers

This operation returns only common response headers. For more information, see Common HTTP headers.

Examples

Sample requests

Unmap an exact CNAME from a standard bucket

POST /?cname&comp=delete HTTP/1.1
Host: oss-example.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=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

<BucketCnameConfiguration>
  <Cname>
    <Domain>example.com</Domain>
  </Cname>
</BucketCnameConfiguration>

Unmap a wildcard CNAME from an Agentic Bucket

POST /?cname&comp=delete&wildcard=true 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=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

<BucketCnameConfiguration>
  <Cname>
    <Domain>example.com</Domain>
  </Cname>
</BucketCnameConfiguration>

Unmap an exact CNAME from an Agentic Bucket

POST /?cname&comp=delete&wildcard=false 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=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

<BucketCnameConfiguration>
  <Cname>
    <Domain>console.example.com</Domain>
  </Cname>
</BucketCnameConfiguration>

Sample response

HTTP/1.1 200 OK
x-oss-request-id: 5C1B138A109F4E405B2D
Date: Mon, 26 Jul 2021 13:08:38 GMT
Content-Length: 0
Connection: keep-alive
Server: AliyunOSS

OSS SDKs

The following OSS SDKs support the DeleteCname operation:

ossutil

For information about the ossutil command that corresponds to the DeleteCname operation, see delete-cname.

Error codes

Error code	HTTP status code	Description
InvalidArgument	400	Possible cause: The Domain element contains invalid characters, such as the wildcard literal `*.example.com`.
MalformedXML	400	The format of the request body is invalid.
AccessDenied	403	You do not have the permissions to call the DeleteCname operation. Only the bucket owner and users who are granted the `oss:DeleteCname` permission can unmap the CNAMEs that are mapped to the current bucket.
MethodNotAllowed	405	The CNAME feature is not enabled for the target bucket type.