作为开发,需要关注的是具体的实现,这其中会遇到各种各样的问题,其中最开始我们遇到的问题是,如何调通艺龙的开放API接口。
一、 接口结构
艺龙开放API提供了两类接口,分别用于获取静态数据和动态数据(关于静态数据和动态数据的概念参考:http://open.elong.com/faq/detail?id=157&plt=2 ,第二节),我们可以命名为静态接口和动态接口,下面我们具体看下静态接口和动态接口的区别和一些开发时要注意的地方。
1. 静态接口
静态接口的构造比较简单一些,使用http协议,请求方式为GET,正式环境域名为api.elongstatic.com,测试环境域名和正式环境相同,但是请求时需要在域名后加一级路径/test用以区分,后续的公共路径为/xml/v2.0/hotel,表示/{xml格式的文件}/{2.0版本的数据格式}/{国内酒店业务线},之后的路径不同接口各不相同,以获取一个酒店的详情文件为例:
正式环境:
http://api.elongstatic.com/xml/v2.0/hotel/cn/06/40101006.xml
测试环境:
http://api.elongstatic.com/test/xml/v2.0/hotel/cn/06/40101006.xml
有时候我们会遇到需要填写{lang}来获取对应语言的文件,目前艺龙仅支持中文和英文,{lang}可以填入cn和en。值得注意的是,由于艺龙并未大力推广英文业务,所以很多文件英文信息要比对应的中文信息少很多,甚至有些文件只有中文没有英文。
2. 动态接口
动态接口由于占用大量的服务器计算资源,所以限制上相较于静态接口要多一些,开发难度有所上升。依旧先看下接口的结构,使用http和https协议,订单相关接口强制使用https,其他接口可以自己决定,请求方式为GET,正式环境域名api.elong.com,测试环境域名为api-test.elong.com,访问路径为/rest,后续各个参数的说明请参考文档:http://open.elong.com/doc/info/cn-main-api_list-common_params 。
本文之后的难点中会讲解signature的加密和data参数的使用方式,其他参数使用没有什么难点,不再说明。
二、接口限制
接口的限制主要有两方面,一个是访问频率限制,另一个是IP白名单限制。
1. 静态接口
静态接口没有访问频率限制,只有IP白名单限制,测试环境IP白名单维护地址:http://api-test.elong.com/user/ ,正式环境IP白名单需要在open.elong.com登录个人中心后,在合作业务-国内酒店中维护,静态接口IP白名单更改后会在下一个整点的1分钟生效。
由于静态接口没有访问频率限制,所以如果同一时间有太多分销商请求,会导致其中一些请求返回40x、50x的错误,详细的说明和解决办法可以查看http://open.elong.com/faq/detail?id=155&plt=2 。
2. 动态接口
动态接口既有频率限制又有IP白名单限制,每个动态接口的默认访问限制不同,默认限制可以查看http://open.elong.com/faq/detail?id=91&plt=2 。IP白名单限制和静态接口添加方式相同,但是动态接口的IP白名单生效更快,无论正式环境还是测试环境,更改后5分钟内生效。
三、接口开发难点
1. 动态接口data参数
data参数不同接口的格式不同,但是他们都有同样的最外层结构,文档中没有明显的说明,只在调用示例里面出现,这个外层结构是这样的
{“Version”:”1.36”,”Local”:”zh_CN”,”Request”:{}}
其中Request中才是不同接口的具体请求参数,Version表示api版本,目前建议使用1.36,Local表示请求的参数和返回值使用的语言,zh_CN表示中文,en_US表示英文。
当整个请求的json字符串拼接完成后,需要对字符串进行URLEncode操作,否则会导致特殊字符无法发送的问题,encode之后再拼接到请求中的data参数之后。
2. 动态接口signature签名
当我们第一次把拼接好的请求发出之后,可能会得到一个signature签名错误的返回,这时我们要一步一步的来梳理可能出现问题的地方。
a. md5算法
md5算法本身没有什么问题,网上或者开发语言的sdk中能够轻易的找到,但是需要注意的地方在于md5计算后的结果需要转为32位的小写字母和数字的字符串。
b. 时间戳
大多数语言从系统中获取的时间戳单位都是毫秒,而我们用来计算signature时要求的时间戳单位是秒,如果获取到的是毫秒,那么请除以1000。
c. data参数加密
data参数在参与signature计算时,不要进行URLEncode,但是在url拼接发送时一定要进行URLEncode。拼接发送时不进行URLEncode,有可能因为data参数中的特殊字符导致有部分没有发送出去,这样艺龙服务器收到后进行data参数验证时会发现其md5计算后与signature不同而报错。
d. appKey与secretKey
signature计算时使用的这两个key值,一般不会出现问题,容易出现问题的地方在于从测试环境切换到正式环境时,有些开发同事只更改了user的配置,没有更改这两个,导致signature签名不正确。