调用GetCnameToken接口获取已创建的CnameToken - 对象存储 OSS

调用GetCnameToken接口获取已创建的CnameToken。可通过wildcard参数指定获取精确CNAME或泛域名CNAME对应的Token。

注意事项

对于Agentic Bucket，wildcard参数必选：wildcard=true为泛域名CNAME获取Token，wildcard=false为精确CNAME获取Token，不允许缺省或为空。普通Bucket该参数可选，缺省为精确CNAME（false）。
查询泛域名CNAME的Token时，cname需传入泛域名基础域（不含*.前缀），例如example.com。

请求语法

GET /?cname&comp=token&cname=example.com&wildcard=true HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Content-Type: application/xml
Content-Length: 186
Date: GMT Date
Authorization: SignatureValue

请求头

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

请求参数

名称

类型

是否必选

示例值

描述

cname

字符串

是

example.com

目标域名。精确CNAME传入完整域名，例如console.example.com；泛域名CNAME传入泛域名基础域（不含*.前缀），例如example.com。

wildcard

字符串

普通Bucket：否

Agentic Bucket：是

true

是否获取泛域名CNAME的Token。取值如下：

true：获取泛域名CNAME的Token。
false：获取精确CNAME的Token。

在Agentic Bucket上，该参数必选，必须显式传true或false，不允许缺省或为空。普通Bucket该参数可选，缺省为false。

响应头

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

响应元素

名称	类型	示例值	描述
CnameToken	容器	不涉及	CnameToken的容器。父节点：无子节点：Bucket、Cname、Token和ExpireTime
Bucket	字符串	examplebucket	绑定Cname的Bucket名称。父节点：CnameToken 子节点：无
Cname	字符串	example.com	绑定的Cname名称。父节点：CnameToken 子节点：无
Token	字符串	be1d49d863dea9ffeff3df7d6455****	OSS返回的CnameToken。父节点：CnameToken 子节点：无
ExpireTime	字符串	Wed, 23 Feb 2022 21:16:37 GMT	CnameToken的有效时间。父节点：CnameToken 子节点：无

示例

请求示例

查询普通Bucket精确CNAME的CnameToken

GET /?cname&comp=token&cname=example.com 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

查询Agentic Bucket泛域名CNAME的CnameToken

GET /?cname&comp=token&cname=example.com&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

返回示例

CnameToken查询成功

HTTP/1.1 200 OK
x-oss-request-id: 5C1B138A109F4E405B2D
Date: Mon, 26 Jul 2021 13:08:38 GMT
Content-Length: 118
Content-Type: application/xml
Connection: keep-alive
Server: AliyunOSS
<?xml version="1.0" encoding="UTF-8"?>
<CnameToken>
  <Bucket>myab-$uid-$region-ab-apsr</Bucket>
  <Cname>example.com</Cname>
  <Token>be1d49d863dea9ffeff3df7d6455****</Token>
  <ExpireTime>Fri, 01 Aug 2026 03:00:00 GMT</ExpireTime>
</CnameToken>

CnameToken未创建或已过期

HTTP/1.1 404 Not Found
x-oss-request-id: 5C1B138A109F4E405B2D
Date: Mon, 26 Jul 2021 13:08:38 GMT
Content-Length: 118
Content-Type: application/xml
Connection: keep-alive
Server: AliyunOSS
<?xml version="1.0" encoding="UTF-8"?>
<Error>
  <Code>NoSuchCnameToken</Code>
  <Message>The specified cname token does not exist.</Message>
  <RequestId>6215FE05DA0E27393F005F0E</RequestId>
  <HostId>myab-$uid-$region-ab-apsr.oss-cn-hangzhou.aliyuncs.com</HostId>
  <Bucket>myab-$uid-$region-ab-apsr</Bucket>
  <Cname>example.com</Cname>
</Error>

SDK

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

命令行工具ossutil

GetCnameToken接口所对应的ossutil命令，请参见get-cname-token。

错误码

错误码	HTTP状态码	描述
InvalidArgument	400	返回此错误的可能原因如下：参数列表中未提供要查询的Cname或Cname格式错误。 Domain传入了非法字符，例如泛域名字面量`*.example.com`。 Agentic Bucket上未传`wildcard`参数，或`wildcard`参数存在但取值非法。
NoSuchCnameToken	404	该CNAME未创建过Token或Token已过期。
MethodNotAllowed	405	目标Bucket类型未开通CNAME能力。