概览

更新时间:2023-09-14 19:10:57

一、简述概览

欢迎使用我司产品服务。用户可以使用本文档介绍的API及示例对产品服务进行相关操作。如需使用接口,您可在OpenAPI Explorer上自助申请,或联系专属技术开通接口权限,请确保在使用这些接口前,已开通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-accessKeystring是      
x-cnc-timestampint秒级时间戳。
如果该时间与服务器时间相差超过5分钟,则该请求失效。
x-cnc-auth-methodstring接口认证方法。
1.使用APIKEY方式,默认传值BASIC,可以不传该头部。
2.使用Accesskey方式,该头部必传,值为AKSK。
AuthorizationstringHTTP标准身份认证头部字段,例如:
“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-Typestring向服务器实际发送的数据类型。
hoststring请求域名,api请求的域名,比如“open.chinanetcenter.com

响应参数:

响应头

说明

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算法综述

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)))

  1. 拼接规范请求串(CanonicalRequest)

按如下伪代码格式拼接规范请求串(CanonicalRequest):

CanonicalRequest =
Method + ‘\n’ +
RequestURI + ‘\n’ +
QueryString + ‘\n’ +
CanonicalHeaders + ‘\n’ +
SignedHeaders + ‘\n’ +
HashedRequestPayload

字段名称

解释

MethodHTTP 请求方法(GET、POST )。此示例取值为 GET,注意这里的字符为大写。
RequestURIURI 参数,比如/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 升序进行拼接。此示例计算结果是 “content-type:application/json\nhost:open-its.chinanetcenter.com\n”。
注意: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:open-its.chinanetcenter.com

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”
注意:Timestamp 必须是当前系统时间,且需确保系统时间和标准时间是同步的,如果相差超过五分钟则必定失败。如果长时间不和标准时间同步,可能导致运行一段时间后,请求必定失败,返回签名过期错误。

根据以上规则,示例中得到的待签名字符串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://open-its.chinanetcenter.com/api/aksk/test?test=test&a=a

Authorization: CNC-HMAC-SHA256 Credential=qiVc3ieau1BlosMghhauAHnBcjd2ceqcCC4Z, SignedHeaders=content-type;host, Signature=1b81bc8fec1058e2df8e5aa7526be348311d3fc97ab428464d833cf23cceb273

Content-Type: application/json;

Host: open-its.chinanetcenter.com

x-cnc-accessKey: qiVc3ieau1BlosMghhauAHnBcjd2ceqcCC4Z

x-cnc-timestamp: 1631239486

六、代码示例

推荐使用AccessKey代码示例:
Java:本地下载
Go: 本地下载
Python: 本地下载

若您使用APIkey代码示例如下:
shell:本地下载
Java:本地下载
Python:本地下载
PHP:本地下载
Go:本地下载
.Net:本地下载

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

七、响应规范

成功结果
可直接提供成功结果示例。如分别给出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!请求调用超时
462WPLUS_AuthorizationErrorauthorization is error! please check signature, accessKey!鉴权失败,请检查AKSK
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.本使用条款受中华人民共和国法律管辖。在执行本服务条款过程中如发生纠纷,双方应及时协商解决。协商不成时,任何一方可直接向上海市徐汇区人民法院提起诉讼。

本篇文档内容对您是否有帮助?
有帮助
我要反馈
提交成功!非常感谢您的反馈,我们会继续努力做到更好!