CDN加速

概览

更新时间:2021-06-02 13:56:02

一、简述概览

欢迎使用我司CDN(内容分发网络)服务。用户可以使用本文档介绍的API对CDN服务进行相关操作。如需使用接口,请联系专属技术开通接口权限,请确保在使用这些接口前,已开通apiKey并充分地了解了 CDN 产品说明及接口使用协议。

二、调用方法

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

三、请求结构

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

请求方法
支持POST、GET、PUT、DELETE等Method动作。

四、公共参数

请求参数:

请求头
必要
描述
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

五、鉴权方法

我司平台会对每个接口请求进行身份验证,所以无论使用HTTP还是HTTPS协议提交请求,都需要在请求中包含鉴权信息。用户在调用接口时,需要在请求头中传入{user:password}和{Date头}(或者x-cnc-date头),其中的密码password需用Date头中的GMT时间(例如 Thu, 10 Oct 2013 09:12:20 GMT)与我司平台颁发的apikey(apikey可以在基础资料->用户信息管理->API接口安全管理中{https://account.console.wangsu.com/apiManage}修改设置)计算生成,计算的算法如下:

Codeblock 1 password算法描述

password=Base64(HMAC-SHA1(UTF-8(apikey), UTF-8(Date)))

其中:
1.Date和apikey都需要采用UTF-8编码;
2.使用的加密算法为哈希算法SHA1;
3.加密后得到HMAC值,然后采用Base64对HMAC值进行编码得到password值.(例如
Qp7RBYI792wnpm/OFXK/DqeldAk=

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

六、代码示例

shell:本地下载
Java:本地下载
Python:本地下载
PHP:本地下载
Go:本地下载

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

七、响应规范

成功结果
可直接提供成功结果示例。如分别给出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>
          

八、附录说明

附表1 加速服务类型、加速区域、国家、地区、ISP等列表:本地下载
附表2 header操作:本地下载
附表3 业务状态码 (适用于云调度及云解析):本地下载
附表4 ViewID与线路的对应关系(适用于云调度及云解析):本地下载
附表5 监控节点数据(适用于云调度及云解析):本地下载
附表6 高级源-区域:本地下载

九、错误码表

第一、URL中带有myview标识的接口错误码:

HTTP状态码
code
message
语义
403

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

(服务器内部错误)服务器遇到错误,无法完成请求
502

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

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

第二、公共鉴权错误码

HTTP状态码
code
message
语义
401WPLUS_InvalidHTTPAuthHeaderThe HTTP authorization header is bad请求没有传入账号信息或者账号信息格式不对
403WPLUS_RequestTokenNotExistErrorrequest token not exist or expired请求的token超过了设置的有效时间
431WPLUS_MatchApiNonethere is no suitable api you request.找不到请求url中匹配的api
432WPLUS_ApiPrivilegeErrorthe account used is not authenticated using this api当前使用的账号没有访问api的权限
434WPLUS_RequestExpiredRequest has expired.请求中的header的date太久(要求请求的date header的时间不能比请求发起的时间早很多,否则视为被窃取的请求)
435WPLUS_AccountTooFrequenceThe account is too frequence.发起请求的账号调用频率达到阈值
436WPLUS_IPTooFrequenceThe ip is too frequence.发起请求的ip调用频率达到阈值
437WPLUS_AccountCapacityFullThe api capacity is full.发起请求的账号使用的带宽量达到阈值
438WPLUS_APiTooFrequenceThe api is too frequence.请求调用的api调用频率达到阈值
439WPLUS_APiCapacityFullThe api capacity is full.请求调用的api使用带宽达到阈值
440WPLUS_AccountWhitelistremote ip not exists in account white list.请求发起的ip不在账号设置的白名单内
441WPLUS_ApiWhitelistremote ip not exists in api white list.请求发起的ip不在api设置的白名单内
443WPLUS_ApiUnactivethe api invoked is unactive.请求的api是unactive状态
446WPLUS_AccountApiTooFrequenceThe account to the indicated api is too frequence.指定账号访问指定api太频繁,超过频率阈值
447WPLUS_APiTooConcurrentThe api call is exceed thd concurrency threshold.指定api调用频率过高超过阈值
448WPLUS_AccountTooConcurrentThe account call is exceed thd concurrency threshold.指定账号的并发调用达到并发阈值,并发的定义:正在处理的(收到请求但是还没响应返回)这个账号的调用的个数
449WPLUS_AccountApiTooConcurrentThe account to the indicated api call is exceed thd concurrency threshold.指定账号调用指定api的频率过高超过限制
450WPLUS_DateErrordate is error.请求没有传入date header或者header信息非法
453WPLUS_HystrixSocketConnectTimeouthystrix socket connect timeout!请求调用超时
501WPLUS_SystemErrorsystem error!内部系统错误
503WPLUS_InvokeBackendFailinvoke backend fail!调用backend失败(这种失败时backend返回的调用失败,并不是调用产生异常导致失败,一般是被调用者自己的逻辑判断为调用失败),目前只有dna调用会产生
530WPLUS_InvalidArgumentexception occured when read body(InputStream) from HttpServletRequest.从HttpServletRequest获取body发生异常
533WPLUS_CollectAgentMakeDirErrorcollectAgent call error:can not make folder.CollectAgent调用创建文件夹失败
534WPLUS_CollectAgentMakeFileErrorcollectAgent call error:can not make file.CollectAgent调用创建文件失败
535WPLUS_RunShellErrorrun shell error.执行shell出错
537WPLUS_ProcessorHttpJobInvokerCallServiceErrorWe encountered an internal error in CommonJobInvoker when call netty. Please try again.processor调用http类型的backend发生异常,此状态码只可能发生在http类型的api的调用中
555WPLUS_HystrixSocketConnectErrorhystrix 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.本使用条款受中华人民共和国法律管辖。在执行本服务条款过程中如发生纠纷,双方应及时协商解决。协商不成时,任何一方可直接向上海市徐汇区人民法院提起诉讼。