欢迎使用我司产品服务。用户可以使用本文档介绍的API及示例对产品服务进行相关操作。如需使用接口，请确保在使用这些接口前，已开通Accesskey并充分地了解了产品说明及接口使用协议。
对API接口调用是通过向API的服务端地址发送HTTP(s) 创建、查看、修改、删除资源，并按照接口说明在请求中加入相应请求参数来完成的；根据请求的处理情况，系统会返回处理结果。为便于问题跟踪和沟通，我司平台为每一次请求/任务分配一个ID，并在响应的头信息中增加x-cnc-request-id字段，用于返回该请求ID给客户。务必注意：API接口响应中的json字段或xml字段，由于功能规划扩展，会在原有基础上新增json或者xml字段，请使用方的开发人员根据json和xml的规范去解析，而不要通过具体字符串去解析。我司平台对每个客户账号的访问频率做了限制，每5分钟的请求次数默认不超过300次。每个账号对应单个接口建议频率30次/5min。如有特殊需要，可与我司平台接口人员联系。
通信协议
支持通过HTTP或HTTPS通道进行请求通信。为了获得更高的安全性，推荐您使用HTTPS通道发送请求。
请求方法
支持POST、GET、PUT、DELETE等Method动作。
请求参数：
| 请求头 | 类型 | 必要 | 描述 |
|---|---|---|---|
| x-cnc-accessKey | string | 是 | |
| x-cnc-timestamp | int | 是 | 秒级时间戳。如果该时间与服务器时间相差超过5分钟，则该请求失效。 |
| x-cnc-auth-method | string | 是 | 接口认证方法。使用Accesskey方式，该头部必传，值为AKSK。 |
| Authorization | string | 是 | HTTP标准身份认证头部字段，例如：“CNC-HMAC-SHA256 Credential=qiVc3ieau1BlosMghhauAHnBcjd2ceqcCC4Z, SignedHeaders=content-type;host, Signature=5b73ebca11a738be44caa52179af87b4dccac4035fa363ebda4b8328eca3d21f”其中，- CNC-HMAC-SHA256：签名方法，目前固定取该值；- Credential：签名凭证，qiVc3ieau1BlosMghhauAHnBcjd2ceqcCC4Z 是 x-cnc-accessKey；- SignedHeaders：参与签名计算的头部信息，content-type 和 host 为必选头部；- Signature：签名摘要。校验凭证，由所有参数计算而得，详见下文的签名计算过程（加链接）。 同一x-cnc-timestamp，5分钟内Authorization不允许重复 |
| content-Type | string | 是 | 向服务器实际发送的数据类型。 |
| host | string | 是 | 请求域名，api请求的域名 |
响应参数：
| 响应头 | 说明 |
|---|---|
| Accept | 浏览器可接受的MIME类型 |
| Content-Type | 请求资源的属于什么MIME类型，注：当使用POST和PUT方法时需要 |
| Date | 格式需符合RFC 1123规范，如Thu, 17 May 2012 19:37:58 GMT |
我司平台会对每个接口请求进行身份验证，所以无论使用HTTP还是HTTPS协议提交请求，都需要在请求中包含鉴权信息。
用户在调用接口时，需要在请求头中传入{x-cnc-accessKey}、{x-cnc-timestamp}、{Authorization}、{content-Type}、{host}
我司将通过客户请求头参数值计算出Authorization与原请求头的{Authorization}进行比较，校验通过则继续后续处理，不通过返回相应错误信息给调用者。
Authorization = Algorithm + ’ ’ + ‘Credential=’ + AccessKey + ', ’ + ‘SignedHeaders=’ + SignedHeaders + ', ’ + ‘Signature=’ + Signature
字段名称 | 解释 |
|---|---|
| Algorithm | 签名方法，固定为 “CNC-HMAC-SHA256”。 |
| AccessKey | 密钥对中的 AccessKey ID，从控制台“AccessKey管理”页获取，本示例的值为 qiVc3ieau1BlosMghhauAHnBcjd2ceqcCC4Z。 |
| SignedHeaders | 见下文，参与签名的头部信息。此示例取值为 “content-type;host” |
| Signature | 签名值。此示例计算结果是 “5b73ebca11a738be44caa52179af87b4dccac4035fa363ebda4b8328eca3d21f”。 |
签名（Sinature）计算过程
Signature=HexEncode(HMAC_SHA256(SecretKey, StringToSign));
Stringtosign=Algorithm+\n+Timestamp+\n+Hash.SHA256(CanonicalRequest)
CanonicalRequest=
Method+’\n’+
RequestURI+’\n’+
QueryString+’\n’+
CanonicalHeaders+’\n’+
SignedHeaders+’\n’+
HashedRequestPayload
HashedRequestPayload= Lowercase(HexEncode(Hash.SHA256(RequestPayload)))
按如下伪代码格式拼接规范请求串（CanonicalRequest）：
CanonicalRequest =
Method + ‘\n’ +
RequestURI + ‘\n’ +
QueryString + ‘\n’ +
CanonicalHeaders + ‘\n’ +
SignedHeaders + ‘\n’ +
HashedRequestPayload
| 字段名称 | 解释 |
|---|---|
| Method | HTTP 请求方法（GET、POST）。此示例取值为 GET，注意这里的字符为大写。 |
| RequestURI | URI 参数，比如 /api/aksk/test。 |
| QueryString | 发起 HTTP 请求 URL 中的查询字符串。对于 POST 请求，固定为空字符串 ""；对于 GET 请求，则为 URL 中问号（?）后面的字符串内容（需要对这部分进行 decode），例如：decode("test=test&a=a")。 |
| CanonicalHeaders | 参与签名的头部具体信息，至少包含 host 和 content-type 两个头部，也可加入自定义的头部参与签名，以提高自身请求的唯一性和安全性。拼接规则： 1. 头部 key 和 value 统一转成小写，并去掉首尾空格，按照 key:value\n 格式拼接；2. 多个头部按照头部 key（小写）的 ASCII 升序进行拼接。 此示例计算结果是： text<br>content-type:application/json<br>host:openapi.tokencube.net<br>注意： content-type 必须和实际发送的内容相符合。有些编程语言网络库即使未指定，也会自动添加 charset 值。如果签名时和发送时不一致，服务器会返回签名校验失败。 |
| SignedHeaders | 参与签名的头部，说明此次请求有哪些头部参与了签名，和 CanonicalHeaders 包含的头部具体信息一一对应。content-type 和 host 为必选头部。拼接规则： 1. 头部 key 统一转成小写； 2. 多个头部 key（小写）按照 ASCII 升序进行拼接，并且以分号（ ;）分隔。此示例为： content-type;host。 |
| HashedRequestPayload | 请求正文（即有效载荷 payload 或 body）的哈希值。 如果以 content-type: application/json 的格式传参，则示例为 {"test":"body"} 的哈希值；如果以 Content-Type: application/x-www-form-urlencoded 的 POST 请求方式传参，则示例为 "test=body" 的哈希值。计算伪代码为： Lowercase(HexEncode(Hash.SHA256(RequestPayload)))，即对 HTTP 请求正文做 SHA256 哈希，然后进行十六进制编码，最后将编码串转换成小写字母。对于 GET 请求， RequestPayload 固定为空字符串。此示例计算结果是： e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855。 |
根据以上规则，示例中得到的规范请求串CanonicalRequest如下：
GET
/api/aksk/test
test=test&a=a
content-type:application/json
host:openapi.tokencube.net
content-type;host
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
2. 拼接待签名字符串(StringToSign)
按如下格式拼接待签名字符串：
StringToSign = Algorithm + \n + Timestamp + \n + HashedCanonicalRequest
| 字段名称 | 解释 |
|---|---|
| Algorithm | 签名算法，目前固定为 CNC-HMAC-SHA256。 |
| Timestamp | 请求时间戳，即请求头部的公共参数 x-cnc-timestamp 取值。取当前时间 UNIX 时间戳，精确到秒。此示例取值为 1631239486。 |
| HashedCanonicalRequest | 前述步骤拼接所得规范请求串的哈希值，计算伪代码为 Lowercase(HexEncode(Hash.SHA256(CanonicalRequest)))。此示例计算结果是：990b65d70886cbf13eef1a6bffdb695b53ea74e7ab150d77efc64acc464443e0。 |
根据以上规则，示例中得到的待签名字符串StringToSign如下：
CNC-HMAC-SHA256
1631239486
990b65d70886cbf13eef1a6bffdb695b53ea74e7ab150d77efc64acc464443e0
3. 计算签名(Signature)
1）获取签名密钥，例如：
SecretKey = test
| 字段名称 | 解释 |
|---|---|
| SecretKey | 原始的 AccessKey Secret |
2）计算签名，伪代码如下：
Signature = HexEncode(HMAC_SHA256(SecretKey, StringToSign))
根据以上规则，示例中得到的值为：
CNC-HMAC-SHA256 Credential=qiVc3ieau1BlosMghhauAHnBcjd2ceqcCC4Z, SignedHeaders=content-type;host, Signature=1b81bc8fec1058e2df8e5aa7526be348311d3fc97ab428464d833cf23cceb273
最终完整的调用信息如下：
GET https://openapi.tokencube.net/api/aksk/test?test=test&a=a
Authorization: CNC-HMAC-SHA256 Credential=qiVc3ieau1BlosMghhauAHnBcjd2ceqcCC4Z, SignedHeaders=content-type;host, Signature=1b81bc8fec1058e2df8e5aa7526be348311d3fc97ab428464d833cf23cceb273
Content-Type: application/json;
Host: openapi.tokencube.net
x-cnc-accessKey: qiVc3ieau1BlosMghhauAHnBcjd2ceqcCC4Z
x-cnc-timestamp: 1631239486
成功结果
可直接提供成功结果示例。如分别给出json示例和xml示例。
Codeblock 7 json示例
HTTP/1.1 {2xx}
Date: Fri, 26 Oct 2012 06:33:26 GMT
Content-Type: application/xml;charset=utf-8
x-cnc-request-id:{id string auto generated by cloud server} /* 此为全局唯一的requestid */
{
/* 返回结果数据 */
}
Codeblock 8 xml示例
HTTP/1.1 {2xx}
Date: Fri, 26 Oct 2012 06:33:26 GMT
Content-Type: application/xml;charset=utf-8
x-cnc-request-id:{id string auto generated by cloud server} /* 此为全局唯一的requestid */
<?xml version="1.0" encoding="UTF-8"?>
<!—结果的根结点-->
<!—返回结果数据-->
</!—结果的根结点-->
错误结果
调用接口出错后，将不会返回结果数据。调用方可根据“错误码”来定位错误原因。当调用出错时，HTTP请求返回一个4xx或5xx的HTTP状态码。返回的消息体中是具体的错误代码及错误信息。另外，请求头中还包含一个全局唯一的请求ID：RequestId。在调用方找不到错误原因时，可以联系我司对应技术人员，并提供该RequestId，以便我们尽快帮您解决问题。
Codeblock 9 json示例
HTTP/1.1 {4xx or 5xx}{error such as Access Denied or InternalError}
Date: Fri, 26 Oct 2012 06:33:26 GMT
Content-Type: application/xml;charset=utf-8
x-cnc-request-id:{id string auto generated by cloud server} /* 此为全局唯一的requestid */
{
"code": "{the error code, like MissingDateHeader}",
"message": "{description, like Authorized request must have a Date or x-cnc-date header }"
}
Codeblock 10 xml示例
HTTP/1.1 {4xx or 5xx}{error such as Access Denied or InternalError}
Date: Fri, 26 Oct 2012 06:33:26 GMT
Content-Type: application/xml;charset=utf-8
x-cnc-request-id:{id string auto generated by cloud server} /* 此为全局唯一的requestid */
<?xml version="1.0" encoding="UTF-8"?>
<response>
<code>{the error code, like MissingDateHeader}</code>
<message>{description, like Authorized request must have a Date or x-cnc-date header}</message>
</response>
公共鉴权错误码
| HTTP状态码 | code | message | 语义 |
|---|---|---|---|
| 401 | WPLUS_InvalidHTTPAuthHeader | The HTTP authorization header is bad | 请求没有传入账号信息或者账号信息格式不对 |
| 403 | WPLUS_RequestTokenNotExistError | request token not exist or expired | 请求的token超过了设置的有效时间 |
| 431 | WPLUS_MatchApiNone | there is no suitable api you request. | 找不到请求url中匹配的api |
| 432 | WPLUS_ApiPrivilegeError | the account used is not authenticated using this api | 当前使用的账号没有访问api的权限 |
| 434 | WPLUS_RequestExpired | Request has expired. | 请求中的header的date太久（要求请求的date header的时间不能比请求发起的时间早很多，否则视为被窃取的请求） |
| 435 | WPLUS_AccountTooFrequence | The account is too frequence. | 发起请求的账号调用频率达到阈值 |
| 436 | WPLUS_IPTooFrequence | The ip is too frequence. | 发起请求的ip调用频率达到阈值 |
| 437 | WPLUS_AccountCapacityFull | The api capacity is full. | 发起请求的账号使用的带宽量达到阈值 |
| 438 | WPLUS_APiTooFrequence | The api is too frequence. | 请求调用的api调用频率达到阈值 |
| 439 | WPLUS_APiCapacityFull | The api capacity is full. | 请求调用的api使用带宽达到阈值 |
| 440 | WPLUS_AccountWhitelist | remote ip not exists in account white list. | 请求发起的ip不在账号设置的白名单内 |
| 441 | WPLUS_ApiWhitelist | remote ip not exists in api white list. | 请求发起的ip不在api设置的白名单内 |
| 443 | WPLUS_ApiUnactive | the api invoked is unactive. | 请求的api是unactive状态 |
| 446 | WPLUS_AccountApiTooFrequence | The account to the indicated api is too frequence. | 指定账号访问指定api太频繁，超过频率阈值 |
| 447 | WPLUS_APiTooConcurrent | The api call is exceed thd concurrency threshold. | 指定api调用频率过高超过阈值 |
| 448 | WPLUS_AccountTooConcurrent | The account call is exceed thd concurrency threshold. | 指定账号的并发调用达到并发阈值，并发的定义：正在处理的（收到请求但是还没响应返回）这个账号的调用的个数 |
| 449 | WPLUS_AccountApiTooConcurrent | The account to the indicated api call is exceed thd concurrency threshold. | 指定账号调用指定api的频率过高超过限制 |
| 450 | WPLUS_DateError | date is error. | 请求没有传入date header或者header信息非法 |
| 453 | WPLUS_HystrixSocketConnectTimeout | hystrix socket connect timeout! | 请求调用超时 |
| 462 | WPLUS_AuthorizationError | authorization is error! please check signature, accessKey! | 鉴权失败，请检查AKSK |
| 501 | WPLUS_SystemError | system error! | 内部系统错误 |
| 503 | WPLUS_InvokeBackendFail | invoke backend fail! | 系统内部核心服务调用异常，请稍后重试或联系技术支持。 |
| 530 | WPLUS_InvalidArgument | exception occured when read body(InputStream) from HttpServletRequest. | 从HttpServletRequest获取body发生异常 |
| 533 | WPLUS_CollectAgentMakeDirError | collectAgent call error:can not make folder. | CollectAgent调用创建文件夹失败 |
| 534 | WPLUS_CollectAgentMakeFileError | collectAgent call error:can not make file. | CollectAgent调用创建文件失败 |
| 535 | WPLUS_RunShellError | run shell error. | 执行shell出错 |
| 537 | WPLUS_ProcessorHttpJobInvokerCallServiceError | We encountered an internal error in CommonJobInvoker when call netty. Please try again. | processor调用http类型的backend发生异常，此状态码只可能发生在http类型的api的调用中 |
| 555 | WPLUS_HystrixSocketConnectError | hystrix socket connect error! | 内部线程池管理工具hystrix与后端业务组件连接异常 |
我司方秉承为客户提供良好服务的宗旨，响应客户需求封装了一批我司CDN 相关的API接口，非常感谢您信任并使用我司封装的API接口，API接口属于方便客户运营维护的一个快捷操作或查询的工具，带来方便的同时也会给双方带来一些不可控的风险，故结合目前客户使用CNC API规模，需客户同意以下使用协议：
本协议中“API”指：我司平台向您提供的应用程序编程接口（Application Programming Interface,简称API），您编程后通过该应用程序编程接口，可获取我司平台提供的CDN相关操作服务。
1.API使用
1.1.我司方自行独立判断您是否可获得API使用许可；即我司平台许可您APIkey后，您即获得我司平台授予您的一项个人的，免费的，不可转让的、不可转授权的、非排他性的API的使用许可，以使得您通过API获取我司平台提供的云服务。
1.2.您对我司平台API的访问次数以及访问数据量均应在我司平台的规定范围内。如我司平台发现您试图超过或规避限制，您的API会被暂时或永久封禁。
1.3.您理解并同意，我司平台仅提供应用程序接口，您应自行编写程序以按您的需求调用我司平台的服务，我司平台不对您的编程过程或程序应用结果承担任何责任。
1.4 如我方API接口需要调整，收到我方通知后，还请配合调整，需在6个月内要响应调整。
1.5 客户使用API接口如危及到我司内部公共系统，我司方有权对API接口进行频率限制（会先通知），如判断为严重恶意使用API接口者甚至关闭API接口调用的权限；
1.6 客户如果新增无用域名数目过多且存在许多长期没有产生流量的域名（判定为无价值域名），客户必须自行清理，因为域名数目越多查询接口的性能将会下降。
1.7 API接口是为方便客户而开发，API接口调用的故障问题并不影响已经在加速的CDN服务，因此并不属于CDN加速质量范畴，亦不可作为CDN加速不可用的依据，不可以作为索赔的依据；
2.在使用我司平台API时，您不应有如下行为：
2.1.修改、翻译、改编、出租、转许可、在信息网络上传播或转让我司平台提供的应用接口，也不得逆向工程、反编译或试图以其他方式发现我司平台提供的应用接口的源代码（除我司平台明示许可外）；
2.2.进行任何破坏或试图破坏网络安全的行为（包括但不限于钓鱼，黑客，网络诈骗，网站或空间中含有或涉嫌散播：病毒、木马、恶意代码，及通过虚拟服务器对其他网站、服务器进行涉嫌攻击行为如扫描、嗅探、ARP欺骗、DOS等）；
2.3.进行任何改变或试图改变我司平台提供的系统配置或破坏系统安全的行为；
2.4.未按照本使用规范以及我司平台就API在相关页面上展示的规定、公告内容的行为，或侵犯我司平台及第三方的权利的行为；
2.5.其它任何违反相关法律法规的行为。
3.您理解并同意，我司平台保留发布API后续版本以及要求您获得并使用最新版本的权利。
3.1.如因我司平台相关服务器或系统维护或升级的需要而需中断或暂停您使用API的，我司平台将尽可能事先进行通告。
3.2.您通过API调用服务的数据以我司平台后台记录数据为准。
4.担保
您理解并同意，在免费期间，我司平台不对API的任何错误或漏洞提供任何担保。您对我司平台API的使用是根据您自己的判断作出的，并自己承担所带来的风险，对于因使用我司平台API而产生的一切损失将由您承担。
5.终止
您应确保您对我司平台API的使用行为符合本规范的要求、符合国家相关法律法规的要求、并不得损害我司平台的利益。如发生下列任何一种情形的，我司平台有权随时中断或终止您使用API：
5.1.您提供的个人资料或其他资料不真实、虚假或违法；
5.2.您对我司平台API的使用行为违反国家法律法规或本规范、我司平台就API在相关页面上展示的规定、公告内容的任何规定；
5.3.我司平台根据自己的独立判断认为您对API的使用行为不符我司平台要求；
5.4.尽管有上述规定，我司平台保留在不事先通知您的情况下随时变更、中断或终止提供该服务的权利。
6.保密
您及我司平台都应对对方的保密信息承担保密责任，除非经国家行政、司法等有权机关要求披露或该信息已进入公有领域。
7.其他
7.1.您使用我司平台API，即应遵守本使用规范。我司平台保留随时修订本规范的权利，并将提前通知您。本规范一旦发生变动，我司平台将会公布重新修订后的规范，并提示您修改的内容。您理解并同意如果您在规范修订后使用API服务，我司平台将把您的使用行为视为对修订后规范的接受。如果您不能接受修订，您应停止使用应用接口。
7.2.目前我司平台向您免费提供应用接口，但并不排除我司平台将来就此收取费用的可能，届时我司平台将通过发网站内公告或在网站内合适版面发通知等方式公布收费政策及规则。如您需继续使用我司平台API，您应按届时我司平台公布之收费政策及规则支付服务费用，并遵循届时有效的API使用条款、规范及流程。
7.3.本使用条款受中华人民共和国法律管辖。在执行本服务条款过程中如发生纠纷，双方应及时协商解决。协商不成时，任何一方可直接向上海市徐汇区人民法院提起诉讼。