全部产品
Search

搜索本产品

    对象存储 OSS：调用CreateCnameToken接口创建域名所有权验证所需的CnameToken

    文档中心

    对象存储 OSS：调用CreateCnameToken接口创建域名所有权验证所需的CnameToken

    更新时间：Sep 15, 2026

    调用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。取值如下：

    • true：为泛域名CNAME创建Token。

    • false：为精确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时传入泛域名基础域（不含*.前缀），例如example.com。

    父节点：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

    返回此错误的可能原因如下：

    • Domain传入了非法字符，例如泛域名字面量*.example.com。

    TooManyCnameToken

    400

    同一个Bucket创建的Token数量超过最大允许数量限制。

    NoNeedCreateCnameToken

    200

    该CNAME已完整绑定到当前Bucket，无需继续创建Token。普通Bucket上，该CNAME已被当前Bucket绑定（任一非删除状态）即返回此响应；对于Agentic Bucket，仅当该基础域名已被当前Agentic Bucket绑定同类型的CNAME时，才返回此响应。

    MethodNotAllowed

    405

    目标Bucket类型未开通CNAME能力。