调用方式

更新时间:2020-10-14 14:20:57

一、简述概览

对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. 发起请求的账号使用的带宽量达到阈值
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与后端业务组件连接异常