中国联通APaaS能力开放平台API规范积分商城分册v19.docx
《中国联通APaaS能力开放平台API规范积分商城分册v19.docx》由会员分享，可在线阅读，更多相关《中国联通APaaS能力开放平台API规范积分商城分册v19.docx（64页珍藏版）》请在冰豆网上搜索。
中国联通APaaS能力开放平台API规范积分商城分册v19
中国联通A-ＰａaＳ能力开放平台ＡPＩ规范－积分商城分册v1.9
————————————————————————————————作者：
———————————————————————————————— 日期：
中国联通公司发布
中国联通A-PaaS能力开放平台
API规范
积分商城分册
1概述
1.1背景
随着行业和公司发展，IT和各业务领域更深度融合,IT已不仅是信息化部门的专有任务，越来越多业务单元需要直接参与到ＩT建设中。
传统IＴ模式正在转变，“平台+应用”新格局快速形成,IT部门将逐步更加聚焦于IT整体规划、共享能力提供、数据聚合、基础设施和服务提供等领域。
为构建平台和应用间桥梁，A-PaaS能力体系应运而生，在2015年IT整体规划中,参照IＴ三层架构总体规划，进一步将各类公共业务能力进行沉淀，形成应用能力层（A-PaaS）,通过A-PaaS实现IT、数据、运营、应用能力的复用和整合，促进集中统一运营红利释放。
各类业务单元（BU）作为A－ＰaaS能力使用方，获得更加透明、标准化的平台能力支撑，通过平台+业务应用新的IT模式，最大程度发挥自身运营灵活性，并也可实现自身能力复用、沉淀。
各类能力单元（AＵ）做为A－PaaS能力提供方，视角也在逐步发生变化,由系统建设组织者逐步变为公共能力的生产者或运营者，可以专注能力潜力挖掘,打造更有价值的能力。
1.2范围
此文档是A-PaaＳ能力开放平台对外提供的服务接口规范,适用于所有通过API和SＤK方式调用开放能力的场景。
所有业务应用需要按照此规范要求进行服务调用,并根据返回结果做适当的业务处理。
1.3平台介绍
A-PａaS运营支撑平台是面向业务单元的一个能力视图，是具体的服务、管理、交易平台，包括能力商店、能力开放平台、应用部署环境管理。
通过能力商店实现能力提供统一管理,所有开放能力均在能力商店上架，统一管理，统一订购；通过能力开放平台，实现能力开放，对第三方、子公司、省分ＢU、总部BU提供统一能力调用；通过应用部署环境管理,为创新应用提供自助式分布式部署环境。
对于ＢU来说，A-PａaS运营支撑平台呈现业务标准化能力,屏蔽各能力提供平台差异化服务;另一方面对于内部各类AU提供规范服务接入,A-PａaS运营支撑平台是公司平台化运营的基础业务能力体系。
本规范主要是针对A-ＰaaS能力开放平台对外提供的服务接口规范;
1.4参考文献
1.5缩略语与术语
1.5.1缩略语
英文缩写
英文全称
中文解释
A－PａａＳ
Aｂiliｔy-PlatforｍａsaＳｅrviｃe
业务能力层
Ｉ-PａaS
IntegrａtiｏｎＰｌatfｏrmasａSeｒvice
技术组件层
AU
AbiｌityUnit
能力单元
BU
ＢusｉnｅsｓUｎｉｔ
业务单元
APＰ－ＫEY
ＡPP-KEY
应用ＩD
ＡPＰ_SECRET
APP＿SECRＥT
应用密钥
1.5.2术语
本文档所涉及的术语定义请参见下表。
名词
解释
能力
用于支撑各类业务活动的公共要素或环节，各类业务应用的“公约数”、承载一定业务功能，可复用,相对稳定。
一个能力可以包括多个服务
服务
服务是指提供某项业务功能的具体API接口
应用接入
业务单元使用能力开放平台的能力，完成业务应用建设的过程
业务经理
业务应用的建设与维护人员,
能力经理
能力的建设和运营人员，ＡU的能力提供方
平台运营方
A-PaaS整体运营基本责任单元,负责A-PaaS体系的运营
ＡPＩ调用方式
通过接口地址调用服务的技术实现方式
SDK调用方式
通过SDK方式调用服务的技术实现方式
2接入技术
2.1传输协议
Ø采用ＨTTP传输协议,并采用RESTＦUL风格的服务访问方式。
ØPOＳT把提交的数据则放置在HTTP包的包体中。
Ø所有参数值需要转换为UTF－８编码。
Ø支持POST请求方式的ＡPI接口，所需要拼接的ＵＲＬ格式示例如下：
ａｐi/xxx（服务名称）／xx（版本号）?
2.2ＡPI调用方式
本章节主要介绍通过接口地址调用服务的技术实现方式,简称ＡPI调用方式;
2.2.1传输协议
Ø采用HTTP传输协议，并采用REＳTFUL风格的服务访问方式。
ØＰOSＴ把提交的数据则放置在HＴTＰ包的包体中。
Ø所有参数值需要转换为UTF-8编码。
Ø支持PＯST请求方式的API接口,所需要拼接的UＲL格式示例如下:
（服务名称）／ｘx（版本号）？
2.2.2 调用方式
通过HTTPPOＳT请求方式进行API调用，并根据ＡPI规范拼接正确的URＬ,就能够办理相应业务或取得相应数据。
2.2.3调用参数
发起ＡＰI调用的请求有二类参数：
系统参数、应用参数,系统参数与应用参数以POST的方式把提交的数据则放置在ＨＴTP包的包体中传输;
1）系统参数
名称
类型
必填？
说明
备注
aｐp_key
cｈar（3０）
Y
接入标识码
timeｓｔaｍp
timestamp
Y
时间戳
当前的系统时间戳,单位为毫秒，举例：
2０1６-03-２51２:
12:
１２187
ｓerial＿nuｍber
char（23）
Y
序列号
YYYYMMDDHＨＭMSS+毫秒（３） +6位随机数
ｓigｎ
ｖarchar（256）
Y
签名信息
2）应用参数
ﻩ应参参数参照实时接口规范
2.2.4签名方式
调用ａpｉ值需要进行签名ｓiｇn值的校验，服务器也会对该请求参数进行验证是否合法的。
签名值sｉgn是将请求源串以及ａｐp_secrｅt根据一定签名方法生成的签名值；
方法如下：
1.根据系统参数名称（除sign签名）将所有请求系统参数按照字母先后顺序排序:
key+ vaｌue..．.kｅｙ+ vａlue
例如:
请求ＵRＬ为：
;
将系统参数值
aｐp_kｅy=abｃ,timestamｐ=２０16-0３-2512:
12:
1218７,serｉaｌ_nuｍｂｅr=912321eqwrwqｑ
参数名和参数值链接后，得到拼装字符串:
ａpp_keｙabcserial_ｎｕmber912321eqｗｒwqqtimestamｐ2016-0３-2５12:
12:
１2187
2.拼接apｐ_sｅcret
app＿ｓecreｔ为应用申请时分配的Apｐ密钥,不在ＵRＬ中传递，双方配置在自己系统中,用于计算sign值，增强安全性。
ａpp＿ｓecrｅｔ值拼接到上面的字串中后面，加入app＿secrｅt值为B273242７，最终得到：
ａpp_kｅｙabｃsｅrｉal_numｂer912３21eqwrwqqｔｉmestａmp２01６-０3-25１2：
1２：
121８7Ｂ2732427
3.系统支持ＭＤ5（６4位）加密方式ﻫmd5：
将app＿ｓeｃrｅt拼接到参数字符串尾后进行md5（64位）加密,格式是:
md5（key１vａｌue1key2ｖａlue2...aｐp_sｅcret）
4.Sign计算：
把上面得到的源串进行MD5计算,得到sign值为eｗqewq123214ｔuｉiｗe３9
2.3SDK调用方式
A-PaaS能力开放平台SＤK提供了调用接口（ＡPI）的请求封装、签名、返回解析、消息监听等功能,使用SDK可以轻松完成ＡＰＩ的调用，API结果的获取,消息的实时监听。
ﻬ
3实时接口
3.1积分消费记录查询
3.1.1应用场景
用于查询客户的积分消费历史;
3.1.2请求说明
AＰI名称
cn．intｅgrａｌmall．coreｂasicqｕery.scoreｅxpendrecorｄ
外网调用入口
内网调用入口
HTＴP请求方式
HTTP－POＳＴ
格式
JＳＯN
API授权类型
需要授权
是否收费API
否
类型
基础服务
版本
ｖ1
3.1.3输入参数
3.1.3.1 应用级输入参数
名称
类型
必填？
说明
备注
reqts
chａr（14）
Ｙ
请求发起时间戳
yyｙｙMMddＨHmmss
chａnnelcode
varchａr（５0）
Y
发起方渠道编码
bｉzparamｓ
varcｈar（6５53６）
Y
jsｏn字符串
{“paｒam1”：
”ｖａｌue１”,”parａm2”:
”vａlue2”,..．..．}
参数列表参数以其参数名的字典序升序进行排序，结果进行aeｓ加密,并且转成base64字符串。
加密所用kｅy由积分商城提供（同appSeｃrect）
所传参数见下表
authsiｇn
vａｒchar（256）
Y
数字签名
chaｎnｅlcode＋rｅqｔs+{“pａｒam1”：
”ｖalue1”,”parａm2”:
”ｖaluｅ2”,......｝+ａppSeｃrect
加号不传
参数列表参数以其参数名的字典序升序进行排序,按照上面顺序进行排序后MD5加密（UTＦ－８编码），
接入渠道编码ｃhannelcｏde，密钥appSeｃrecｔ由积分商城提供
所传参数见下表
加密解密方法：
测试时，系统参数里面加密使用的是申请应用的时候提供的apｐkey／ａppsｅcret；应用参数里面加密时使用的渠道编码为“AP+两位省份编码”，密钥为“RｙiＱｗkaIB2AMvmｐJk5RG1ｇ==”
bｉz＿pａrams入参
名称
类型
必填?
说明
备注
ｔraｎsｉｄ
vａrｃhar（50）
Y
发起方流水
渠道编码+yyyｙｍmddhh24mｉss+6位不重复序列
reqseｒｖiｃecode
vaｒchａｒ（9）
Y
服务编码
积分消费记录查询:
1101100２
provｉｎcecode
cｈaｒ（3）
Ｙ
省份编码
ｃitycode
ｃhａｒ（3）
Ｙ
地市编码
neｔｔype
char（２）
Y
网别
0１2G
０2３G
９94G
pａytyｐe
ｃhａｒ
（2）
Ｙ
付费类型
1预付费
２后付费
usｅrtype
chaｒ
（1）
Y
用户类型
0手机
1 宽带
２固话
3上网卡
uｓｅrnumber
ｖarchar（30）
Y
服务号码
telaｒeacode
ｖａrchａr（４）
N
区号
固网必填
begindate
ｃｈar（8）
Y
开始时间
ＹYYＹMMDD
enddate
char（８）
Y
结束时间
ＹYYYMＭＤD
3.1.4返回结果
名称
类型
必填?
说明
备注
ｒeｓpcodｅ
ｃhar（４）
Y
应答编码
应答编码
０00０成功
99９9系统异常
respdeｓc
vａrchar（５０0）
N
应答描述
应答描述
rsｐｔs
char（14）
Ｙ
响应时间戳ｙyｙyMMｄdHHmmss
rｓｐmsｇ
varchaｒ（65536）
Y
业务应答（业务参数列表）消息
应答参数为jsｏn格式,同请求参数一样，整体结果进行aes加密，并且转成ｂaｓe6４字符串
rsｐmsg内参数说明
名
升级会员 