ListCname-对象存储(OSS)-阿里云帮助中心

调用ListCname接口用于查询某个存储空间（Bucket）下绑定的所有的自定义域名（Cname）列表。对于Agentic Bucket，响应中可能同时包含精确CNAME和泛域名CNAME条目，泛域名CNAME条目通过IsWildCard节点标识。

注意事项

响应中，精确CNAME条目不额外输出IsWildCard节点，以保持与旧版SDK的兼容；泛域名CNAME条目输出IsWildCard节点（值为true），其Domain为不含*.前缀的泛域名基础域。
Agentic Bucket的响应中可能同时包含精确CNAME和泛域名CNAME条目；普通Bucket的响应格式保持不变。

请求语法

GET /?cname 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

请求头

此接口仅包含公共请求头。更多信息，请参见公共HTTP头定义。

响应头

此接口仅涉及公共响应头。更多信息，请参见公共HTTP头定义。

响应元素

名称	类型	示例值	说明
ListCnameResult	容器	不涉及	查询Cname信息列表的容器。父节点：无子节点：Bucket、Owner和Cname
Bucket	字符串	examplebucket	待获取已绑定Cname列表的Bucket名称。父节点：ListCnameResult 子节点：无
Owner	字符串	testowner	Bucket Owner名称。父节点：ListCnameResult 子节点：无
Cname	容器	不涉及	Cname信息列表的容器。父节点：ListCnameResult 子节点：Domain、LastModified、Status、IsWildCard和Certificate
Domain	字符串	example.com	自定义域名。泛域名CNAME条目中，该值为不含`*.`前缀的泛域名基础域，例如example.com。父节点：Cname 子节点：无
LastModified	字符串	2021-09-15T02:35:07.000Z	绑定自定义域名的时间。父节点：Cname 子节点：无
Status	字符串	Enabled	域名所处状态。取值为： Enabled：启用该域名。 Disabled：禁用该域名。父节点：Cname 子节点：无
IsWildCard	布尔值	true	是否为泛域名CNAME条目。仅泛域名CNAME条目输出该节点，取值为true；精确CNAME条目不输出该节点，以保持与旧版SDK的兼容。父节点：Cname 子节点：无
Certificate	容器	不涉及	证书信息的容器。父节点：Cname 子节点：Type、CertId、Status、CreationDate、Fingerprint、ValidStartDate和ValidEndDate
Type	字符串	CAS	证书来源。取值为： CAS：证书中心。 Upload：旧版证书托管中用户自主上传的证书。父节点：Certificate 子节点：无
CertId	字符串	493****-cn-hangzhou	证书ID。父节点：Certificate 子节点：无
Status	字符串	Enabled	证书状态。取值如下： Enabled：使用证书。 Disabled：未使用证书。父节点：Certificate 子节点：无
CreationDate	字符串	Wed, 15 Sep 2021 02:35:06 GMT	证书绑定时间。父节点：Certificate 子节点：无
Fingerprint	字符串	DE:01:CF:EC:7C:A7:98:CB:D8:6E:FB:1D:97:EB:A9:64:1D:4E::	证书签名。父节点：Certificate 子节点：无
ValidStartDate	字符串	Wed, 12 Apr 2023 10:14:51 GMT	证书有效期起始时间。父节点：Certificate 子节点：无
ValidEndDate	字符串	Mon, 4 May 2048 10:14:51 GMT	证书有效期终止时间。父节点：Certificate 子节点：无

示例

请求示例

GET /?cname HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Content-Type: application/xml
Content-Length: 186
Date: Tues, 11 May 2022 11:39:12 GMT
Authorization: OSS qn6q**************:77Dv****************

返回示例

普通Bucket响应示例

content-length: 1855
x-oss-console-auth: success
server: AliyunOSS
x-oss-server-time: 7
connection: keep-alive
x-oss-request-id: 614169F1AE63BD37355CA12B
date: Tues, 11 May 2022 11:39:12 GMT
content-type: application/xml
<?xml version="1.0" encoding="UTF-8"?>
<ListCnameResult>
  <Bucket>targetbucket</Bucket>
  <Owner>testowner</Owner>
  <Cname>
    <Domain>example.com</Domain>
    <LastModified>2021-09-15T02:35:07.000Z</LastModified>
    <Status>Enabled</Status>
    <Certificate>
      <Type>CAS</Type>
      <CertId>493****-cn-hangzhou</CertId>
      <Status>Enabled</Status>
      <CreationDate>Wed, 15 Sep 2021 02:35:06 GMT</CreationDate>
      <Fingerprint>DE:01:CF:EC:7C:A7:98:CB:D8:6E:FB:1D:97:EB:A9:64:1D:4E:**:**</Fingerprint>
      <ValidStartDate>Wed, 12 Apr 2023 10:14:51 GMT</ValidStartDate>
      <ValidEndDate>Mon, 4 May 2048 10:14:51 GMT</ValidEndDate>
    </Certificate>
  </Cname>
  <Cname>
    <Domain>example.org</Domain>
    <LastModified>2021-09-15T02:34:58.000Z</LastModified>
    <Status>Enabled</Status>
  </Cname>
</ListCnameResult>

Agentic Bucket响应示例（可能同时包含精确和泛域名CNAME条目）

content-length: 1024
x-oss-console-auth: success
server: AliyunOSS
x-oss-server-time: 7
connection: keep-alive
x-oss-request-id: 614169F1AE63BD37355CA12C
date: Tues, 11 May 2022 11:39:12 GMT
content-type: application/xml
<?xml version="1.0" encoding="UTF-8"?>
<ListCnameResult>
  <Bucket>my-uid-region-ab-apsr</Bucket>
  <Owner>1234567890123456</Owner>
  <Cname>
    <Domain>console.example.com</Domain>
    <LastModified>2025-04-17T02:35:07.000Z</LastModified>
    <Status>Enabled</Status>
  </Cname>
  <Cname>
    <Domain>example.com</Domain>
    <LastModified>2025-04-17T02:50:34.000Z</LastModified>
    <Status>Enabled</Status>
    <IsWildCard>true</IsWildCard>
  </Cname>
</ListCnameResult>

SDK

本接口对应的各语言SDK如下：

命令行工具ossutil

ListCname接口所对应的ossutil命令，请参见list-cname。

错误码

错误码	HTTP状态码	描述
AccessDenied	403	没有调用ListCname接口的权限。仅Bucket拥有者以及被授予`oss:ListCname`权限的用户可以查询当前Bucket下绑定的所有Cname列表。
NoSuchCname	404	该Bucket未绑定Cname。
MethodNotAllowed	405	目标Bucket类型未开通CNAME能力。