调用CreateCnameToken接口创建域名所有权验证所需的CnameToken。可通过wildcard参数指定为精确CNAME或泛域名CNAME创建Token。
注意事项
-
CnameToken默认在创建完成后72小时内过期。如果在CnameToken过期时间内重复创建CnameToken,则返回已存在的CnameToken。
-
对于Agentic Bucket,
wildcard参数必选:wildcard=true为泛域名CNAME创建Token,wildcard=false为精确CNAME创建Token,不允许缺省或为空。 -
普通Bucket为精确CNAME创建Token的调用方式与既有OSS CNAME OpenAPI完全一致,无需引入任何新参数。
请求语法
POST /?cname&comp=token&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>
请求头
此接口仅包含公共请求头。更多信息,请参见公共HTTP头定义。
请求参数
|
名称 |
类型 |
是否必选 |
示例值 |
描述 |
|
wildcard |
字符串 |
普通Bucket:否 Agentic Bucket:是 |
true |
是否为泛域名CNAME创建Token。取值如下:
对于Agentic Bucket,该参数必选,必须显式传true或false,不允许缺省或为空。普通Bucket该参数可选,缺省为false。 |
各Bucket类型下wildcard参数的取值规则如下:
|
Bucket类型 |
参数缺省 |
wildcard=false |
wildcard=true |
|
普通Bucket |
允许,为精确CNAME创建Token。 |
允许,为精确CNAME创建Token。 |
不允许 |
|
Agentic Bucket |
不允许 |
允许,为精确CNAME创建Token。 |
允许,为泛域名CNAME创建Token。 |
同一(Bucket,Cname)的Token同时覆盖精确与泛域名两个作用域。
请求元素
|
名称 |
类型 |
是否必选 |
示例值 |
描述 |
|
BucketCnameConfiguration |
容器 |
是 |
不涉及 |
Cname配置的容器。 父节点:无 子节点:Cname |
|
Cname |
容器 |
是 |
不涉及 |
Cname信息的容器。 父节点:BucketCnameConfiguration 子节点:Domain |
|
Domain |
字符串 |
是 |
example.com |
自定义域名。为精确CNAME创建Token时传入完整域名,例如console.example.com;为泛域名CNAME创建Token时传入泛域名基础域(不含 父节点:Cname 子节点:无 |
幂等语义
针对该CNAME是否已绑定到当前Bucket,CreateCnameToken的幂等语义因Bucket类型而异:
-
普通Bucket:该CNAME已被当前Bucket绑定(任一非删除状态)时,返回
NoNeedCreateCnameToken,无需继续创建Token。 -
Agentic Bucket:仅当该基础域名已被当前AgenticBucket绑定同类型的CNAME时,才返回
NoNeedCreateCnameToken。
响应元素
|
名称 |
类型 |
示例值 |
描述 |
|
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创建CnameToken
POST /?cname&comp=token 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> -
为Agentic Bucket的泛域名CNAME创建CnameToken
POST /?cname&comp=token&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> -
为Agentic Bucket的精确CNAME创建CnameToken
POST /?cname&comp=token&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>
-
-
返回示例
-
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 400 Bad Request 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>TooManyCnameToken</Code> <Message>You have attempted to create more cname token than allowed.</Message> <RequestId>6215FD21DA0E27393F004E9E</RequestId> <HostId>127.0.0.1</HostId> <Bucket>examplebucket</Bucket> </Error>
-
SDK
本接口对应的各语言SDK如下:
命令行工具ossutil
CreateCnameToken接口所对应的ossutil命令,请参见create-cname-token。
错误码
|
错误码 |
HTTP状态码 |
描述 |
|
InvalidArgument |
400 |
返回此错误的可能原因如下:
|
|
TooManyCnameToken |
400 |
同一个Bucket创建的Token数量超过最大允许数量限制。 |
|
NoNeedCreateCnameToken |
403 |
该CNAME已完整绑定到当前Bucket,无需继续创建Token。普通Bucket上,该CNAME已被当前Bucket绑定(任一非删除状态)即返回此响应;对于Agentic Bucket,仅当该基础域名已被当前Agentic Bucket绑定同类型的CNAME时,才返回此响应。 |
|
MethodNotAllowed |
405 |
目标Bucket类型未开通CNAME能力。 |