一、简述概览
对DNS API接口调用是通过向DNS API的服务端地址发送HTTP POST请求，并按照接口说明在请求中加入相应请求参数来完成的；根据请求的处理情况，系统会返回处理结果。

二、调用方式

对云解析 API接口调用是通过向DNS API的服务端地址发送HTTP(s) 创建、查看、修改、删除资源，并按照接口说明在请求中加入相应请求参数来完成的；根据请求的处理情况，系统会返回处理结果。为便于问题跟踪和沟通，我司平台为每一次请求/任务分配一个ID，并在响应的头信息中增加x-cnc-request-id字段，用于返回该请求ID给客户。务必注意：API接口响应中的json字段，由于功能规划扩展，会在原有基础上新增json或者xml字段，请使用方的开发人员根据json和xml的规范去解析，而不要通过具体字符串去解析。我司平台对每个客户账号的访问频率做了限制，每5分钟的请求次数不超过1200次。每个账号对应单个接口建议频率30次/5min。如有特殊需要，可与我司平台接口人员联系。

三、请求结构
通信协议

支持通过HTTP或HTTPS通道进行请求通信。为了获得更高的安全性，推荐您使用HTTPS通道发送请求。

请求参数

全速云API的每个请求都需要指定两类参数：即公共请求参数以及接口请求参数。其中公共请求参数是每个接口都要用到的请求参数，具体可参见公共参数说明，而接口请求参数是各个接口所特有的，具体见各个接口的“请求参数”描述。

四、公共参数
请求参数：

请求头 必要 描述
Authorization 是 授权信息，例如 user:password
Accept 否 浏览器可接受的MIME类型，默认返回json格式，例如
1、“Accept: application/json” ，表示返回json格式。
2、“Accept: application/xml”，表示返回xml格式
Content-Type 条件 请求资源的属于什么MIME类型
注：当使用POST和PUT方法时需要
Date 条件 本地当前时间，用于计算Authorization字段信息，格式需符合RFC 1123规范，如Thu, 17 May 2012 19:37:58 GMT
注：除非使用了x-cnc-date，否则必须要有该字段
x-cnc-date 条件 本地当前时间，用于计算Authorization字段的签名信息，当不能设置Date时，可以通过此字段来设置时间，格式需符合RFC1123规范，如Thu, 17 May 2012 19:37:58 GMT
响应参数：

响应头 说明
Accept 浏览器可接受的MIME类型
Content-Type 请求资源的属于什么MIME类型，注：当使用POST和PUT方法时需要
Date 格式需符合RFC 1123规范，如Thu, 17 May 2012 19:37:58 GMT
五、鉴权方法

我司平台会将接口请求中的{Date}（或者x-cnc-date头）指定的GMT时间和平台本地时间进行比较，如果时间差超过15分钟，会忽略该请求，以避免过期消息的重复发送。然后，按照同样的加密方式加密得到的password与用户传递的password做比较。如果一致则通过，如果不一致则拒绝访问。

六、代码示例
示例下载

Java：本地下载

PHP：本地下载

示例代码仅供参考， 请根据实际情况使用。

七、响应规范
成功结果

可直接提供成功结果示例。

json示例

{
“resCode”:0,
“msg”:“操作成功”,
“content”:[
{
“domainId”:1683943,
“domainName”:“quansucloud.com.cn”,
“ret”:“Success”,
“msg”:“操作成功”,
“msgEn”:null,
“result”:null,
“code”:0,
“success”:true
}
]
}
错误结果

调用接口出错后，将不会返回结果数据。调用方可根据<错误码>来定位错误原因。当调用出错时，HTTP请求返回一个4xx或5xx的HTTP状态码。返回的消息体中是具体的错误代码及错误信息。另外，请求头中还包含一个全局唯一的请求ID：RequestId。在调用方找不到错误原因时，可以联系我司对应技术人员，并提供该RequestId，以便我们尽快帮您解决问题。

json示例

{
“resCode”:105,
“msg”:“批量操作,全部失败”,
“content”:[
{
“domainId”:null,
“domainName”:“quansucloud.com.cn”,
“ret”:“TIP_DOM_REP”,
“msg”:“域名quansucloud.com.cn重复”,
“msgEn”:"Domain name repeated ",
“result”:null,
“code”:201,
“success”:false
}
]
}
八、附录说明
附表1 业务状态码 （适用于云调度及云解析）： 本地下载

附表2 ViewID与线路的对应关系（适用于云调度及云解析）： 本地下载

附表3 监控节点数据（适用于云调度及云解析）： 本地下载

九、错误码表

HTTP状态码 code message 语义
403

（已禁止）服务器拒绝请求，包含无效频道、时间格式错误、开始时间格式错误、介绍时间格式错误、开始时间大于结束时间、时间间隔大于限制、客户为空、客户无效
500

（服务器内部错误）服务器遇到错误，无法完成请求
502

（错误网关）服务器作为网关或代理，从上游服务器收到了无效的响应
901

（参数限制）您请求的域名数大于500或者时间跨度大于31天，系统会长时间无法响应，请修改参数重试

第二、公共鉴权错误码

HTTP状态码

code

message

语义

401

WPLUS_InvalidHTTPAuthHeader

The HTTP authorization header is bad

请求没有传入账号信息或者账号信息格式不对

403

WPLUS_RequestTokenNotExistError

request token not exist ,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!

请求调用超时

501

WPLUS_SystemError

system error!

内部系统错误

503

WPLUS_InvokeBackendFail

invoke backend fail!

调用backend失败（这种失败时backend返回的调用失败，并不是调用产生异常导致失败，一般是被调用者自己的逻辑判断为调用失败），目前只有dna调用会产生

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.本使用条款受中华人民共和国法律管辖。在执行本服务条款过程中如发生纠纷，双方应及时协商解决。协商不成时，任何一方可直接向上海市徐汇区人民法院提起诉讼。