应用开发指南

一、应用创建及上线流程

应用的创建及上线按下图流程进行,开发者可以根据应用当前的状态,依照平台页面提示进行相应的操作。关于开发者账号注册及平台签约事项请参见《新手指南》

二、应用管理要点

1、应用信息修改

如应用未提交上线申请,应用的各项信息(基本信息、能力绑定、图标信息、安全信息)均可即时修改,无需二次审核。

如应用处于审核过程中,或是已通过审核上线的应用,如需修改应用信息,需按照流程再次提交应用上线申请,由平台运营人员对应用信息的更改进行审核确认。

2、应用测试

开发者成功创建应用并绑定能力接口后,应用处于测试状态。开发者可以在应用的测试阶段对绑定的能力接口进行调用测试,以便确认应用对能力接口的调用无误。在测试阶段,开发者可自行增添、或删除应用希望测试的能力接口并可随时查看所有能力接口的使用帮助和文档。

3、应用上线

开发者完善了应用的各项信息,并完成了能力接口的调用测试后,可在应用信息页面点击“应用上线”,将应用提交天翼开放平台审核。审核过程中,应用无法进行修改,审核完毕后,平台管理员会将结果以邮件、短信或站内信的形式通知开发者。

应用进入上线状态后,对应用的信息修改、下线、删除操作都将影响应用已有的用户授权关系,请开发者谨慎使用。

4、应用升级

天翼开放平台的应用升级以建立新应用的方式的进行,平台同时保留升级的新版本应用和原版本应用,新旧版本应用相对独立运行。开发者创建升级应用后,旧版本应用的对外服务状态不受影响,原用户已对该版本应用的授权关系将全部保留。应用用户在首次登录新版本应用时,需对新版本应用进行显式授权。

开发者可根据应用的实际运营情况和需求对旧版本应用进行主动下线或删除操作。对应用的下线和删除操作不可逆,开发者需谨慎操作。

三、技术开发要点

1、获取App Key、App Secret

开发者创建应用后,平台会为开发者自动生成App Key和App Secret。App Key是应用的唯一数字ID,一旦生成将无法更改。App Secret是平台给应用分配的密钥,此密钥用来保证调用请求来源的可靠性,开发者可在平台内重置更换。

        

2、如何获取Access Token

开发者可以通过天翼帐号下的认证授权接口来获取AccessToken,根据不同的应用获取AccessToken的方式也不同。

应用分为两种:

  有服务端的应用(如web应用),需先调用authorize接口response_type为“code”来获取AC(Access Code)。再使用AC(Access Code)通过调用access_token接口grant_type为“authorization_code”来获取Access Token。

  无服务端的应用(如桌面、手机客户端),调用authorize接口response_type为“token”来直接获取Access Token。

具体内容详见《 授权机制说明》。

3、如何访问匿名接口

  为了方便一些应用在没有用户认证情况下需要获取一些数据,EMP平台提供了一些匿名访问接口。应用直接调用access_token接口grant_type为“client_credentials”来获取Access Token进行访问。

4、如何调用API接口

  调用API接口请求参数可采用如下三种具体传递方式。其中,方式A与方式B是目前最为常见的两种HTTP/REST参数传递方式。

A.通过URI参数形式传递给能力平台

方式A利用URI传递请求参数,其有助于提高开放能力接口对开发者调用、调试的友好性,但并不适合传递较多、较长的参数,因此建议仅在开放API接口相对简单的情况下使用。

B.通过POST form形式传递给能力平台

方式B使用POST form表单形式传递参数,其最大优点在于对于请求参数的数量和长度没有限制,可用于传递复杂参数,但与方式A相比,其接口调用的过程略显繁琐。

C.通过HTTP header形式传递给能力平台

方式C借助于HTTP首部扩展机制来传递参数,在一般的接口调用场合下,其较方式A、B相对少见,同时在协议兼容性和参数定义方面也存在一定的限制,不及方式A、B易于扩展,因此在开放系统环境下宜避免过度使用。

  在参数传递过程中,对于某些安全性要求较高的特定API调用场合而言(例如认证授权接口、支付接口等),应当考虑采用HTTPS机制,以保障其端对端传输的安全性。HTTPS协议对于上述三种方式的HTTP传输负载均能给予充分保护。但值得指出的是,由于方式A采用URI明文进行参数编码,即便是在使用HTTPS协议的前提下,其在客户端侧依然存在着一定的安全隐患(如客户端存在URL缓冲或历史记录、从而导致参数泄露等),因此建议在安全性要求较高的场合下,优先选择方式B进行参数传递。

  原则上,接口参数的具体传递方式可由能力提供方自行指定。一般而言,建议遵循业界接口惯例,在HTTP GET等幂等操作的接口场合下,使用方式A传递参数;在HTTP POST等非幂等操作的API调用场合下,优选方式B进行参数传递。对于同一开放接口,不建议混合使用不同的参数传递方式。

以URI形式传递参数的开放API接口调用范例如下:

	 http://api.189.cn/iMusic/ActorAlbum/getInfo? access_token= XXXX&sign=YYYY 

以POST form表单形式传递参数的开放API接口调用范例如下。对于多表单场合或者是既需传递参数又需同时上传数据的参数传递场合,统一采用multipart/form-data编码方式。

	POST/iMusic/ActorAlbum/setInfo HTTP/1.1

 

Host:www.testapp.com

 

Content-Type:application/x-www-form-urlencoded; charset=UTF-8

 

access_token= XXXX&sign=YYYY&info=”INFORMATION” 

以HTTP header首部形式传递参数的开放API接口调用范例如下:

	GET/iMusic/ActorAlbum/getInfo HTTP/1.1

 

Host:www.testapp.com

 

Content-Type:application/json;charset=UTF-8

 

access_token:XXXX

 

sign: YYYY 

具体调用参数与返回参数,请参见”API文档”

5、公共参数

合作应用在调用任一EMP开放API接口时,均须携带以下公共系统参数:

参数名

必选

类型

  

access_token

true

string

完成应用-用户-能力授权的令牌

app_id

false

string

应用注册时分配的应用ID

format

false

string

指定响应格式,可选JSON或XML,默认为JSON

timestamp

false

string

请求时间戳。以提升安全性,用于防止replay等攻击。

cacheable

false

string

cacheable参数仅用于重定向访问模式。默认取值为true。

cacheable为true时,EMP重定向响应将包括HTTP缓冲首部,在缓存有效期内,应用可使用本地缓存的重定向响应,直接访问EP侧接口,而无需EMP介入调用请求过程。cacheable为false时,将强制EMP重定向响应不包括HTTP缓冲首部,应用的每次请求均将由经EMP重定向至实际的EP侧调用接口。

state

false

string

用于区分应用请求-响应的对应关系。

若应用发起的调用请求中包含该参数,则EP将在应答响应中加上原封不动地加上该参数,以表示请求与响应之间的对应关系。

sign

false

string

APP_ID+ACCESSS_TOKEN+TIMESTAMP(如果存在)+STATE(如果存在)+APP_SECRET组成的字符串进行MD5散列所得到的取值。建议应用在调用HTTP接口调用时携带该参数,以增强安全性,防止调用参数被篡改。

6、认证授权SDK

为了降低开发难度,我们提供了 认证授权SDK供您参考使用。