我家云开放平台 2 单点登陆方案
单点登陆
第1章 概述
1.1 目的
本文档旨在编写一个面向开发者的完整的API调用规范，供需要调用我家云接口的开发者使用。本文档不包括API具体的实现细节。
1.2 适用范围
本文档适用阅读人员包括：我家云的开发人员，公司外部开发伙伴。本文档的接口不仅限于公司内部使用。
1.3 适用版本
全部。
第2章详细描述
2.1 API通用约定
2.1.1 调用方式
我家云API采用RESTfull的设计方式，客户端通过HTTP协议的GET、POST(目前主要是这两种)方法请求进行调用。
Restful：参考资料http://www.infoq.com/cn/articles/designing-restful-http-apps-roth。
API的调用地址基本上遵循如下约定的方式：API地址前缀+ 服务 + 资源+ 参数API地址前缀：基本不变的API访问URL地址，如下：
正式：https://api.wojiacloud.com
正式申请应用地址是：https://wy.wojiacloud.com
正式开放平台地址是：https://open.wojiacloud.com
测试：https://api.wojiacloud.cn
测试申请应用地址是：https://wy.wojiacloud.cn
测试开放平台地址是：https://open.wojiacloud.cn
服务：操作资源所处的情境，如Auth，Passport，Kdrive等
资源：操作的对象，如users, orgs和groups等
操作：HTTP标准的操作，如PUT，POST，GET，DELETE，一般操作语义如下：
GET：获取资源
POST：新增/更新资源
PUT：更新资源
DELETE：删除资源
接口统一使用小写、单词之间使用下划线"_"分隔，如user/access_token。
每个API都会指定支持调用的操作方法，因此可参考具体的API详细。
RESTful的架构方式是无状态的，客户端调用API时需要标识自己，同时服务端需要对客户端的调用进行认证。
2.1.2 认证授权
我家云API分为功能类API和资源类API。
功能类API：我家云提供的一类与用户数据无关的，使用应用ID和应用secret作为凭证认证的API。
资源类API：需要获取或操作用户、团队、组织数据API，采用token认证方式(结合oauth2)，客户端先通过应用凭证(应用ID和应用secret)和资
2.1.3 返回结果
我家云API正常服务并能访问的情况下，HTTP协议头部 Status Code固定返回200状态值，除非具体的API说明中规定用到其它状态值。
API调用返回json格式字符串，可通过方法将它转换成对象。
一般来说，返回数据中都包含errcode、description、description_cn标记此次调用的结果。errcode值分为通用的约定值和与具体接口业务相关的约定值，description描述信息仅作为参考信息。
2.1.4 交互流程 
2.2 API接入
2.2.1 Web后台集成嵌入链接
Web集成地址
蓝色部分为身份认证信息，需要根据不同的用户替换。
红色部分为具体业务， 替换红色中具体业务的链接，即可进行相应的业务操作页面。
https://wy.wojiacloud.com/thirdUser/login?access_token=6q7rpmhoddptrhw2ajvuf5na1dhilqgq&moduleType=/menus/toMain/rentIndex&appId=aaniqt58me5kgg1m
2.2.2 管家APPH5嵌入到对方app链接
我家云提供H5接入地址，但地址中的access_token，必须更换为open.wojiacloud.com在线文档1.2身份认证中获取的access_token。
管家H5地址如下：https://gj.wojiacloud.com/vue/index.html?access_token=d16nsbhyc704y5oieac5h8spl4cfdcio#/query
测试服务器地址
http://mhgj.kingdee.com/vue/index.html?access_token=d16nsbhyc704y5oieac5h8spl4cfdcio#/ucenter
蓝色部分为身份认证信息，需要根据不同的用户替换。
红色部分为具体业务， 替换红色中具体业务的链接，即可进行相应的业务操作页面。
业务链接如下表：产品
模块
链接
物业App H5
抄水表
/meter/1
--
抄电表
/meter/2
--
抄燃气表
/meter/3
--
工单查询
/work/0
--
抢单
/work/task
--
报事
/report
--
车辆违停
/vehicleParking
--
访客查验
/visitor
--
装修巡检
/decorate
--
设备巡检
/inspection/type
--
物品放行
/release
--
突发事件
/emergency
--
设备维保
/service/type
--
设备维修
/repair/0
--
受理派工
/dispatch/0
--
移动验房
/house/1
--
欠费催缴
/query
--
住户管理
/household
--
设备巡查
/patrol
--
会议预订
/meeting
--
品质考评
/qualityEval
--
品质检查
/qualityCheck
--
品质整改
/qualityOrder
--
快递代收
/receiveExpress
--
巡更任务
/patrolTask
--
巡更排班
/patrolPlan
--
离线巡更
/patrolOffline
--
预约管理
/rentOrder
--
预定管理
/rentReserve
--
合同管理
/rentContract
--
合同审批
/rentApproval
--
运营数据
/rentReport
--
用户中心
/ucenter
2.2.3 我家APPH5嵌入到对方app链接
我家H5地址如下：
https://wj.wojiacloud.com/users/login?access_token=d16nsbhyc704y5oieac5h8spl4cfdcio&menu=/user/bill/0&openId=123456
测试服务器
https://mhwx.kingdee.com/users/login?access_token=d16nsbhyc704y5oieac5h8spl4cfdcio&menu=/service/form/REP&openId=123456
蓝色部分为身份认证信息，需要根据不同的用户替换。
红色部分为具体业务信息， 替换红色中具体业务的链接，即可进行相应的业务操作页面。
业务链接如下表：产品
模块
链接
业主APP H5
报事报修
/service/form/REP
--
投诉建议
/service/form/COM
--
快递查询
/service/express2/0
--
查费缴费
/user/bill/0
--
个人中心
/user
--
我的管家
/service/callButler
--
便民电话
/service/phone
--
社区活动
/home/activity/hot
--
社区消息
/home/msg/community
--
物品放行
/service/release
--
邻里图书
/service/book/0
--
场地预订
/service/venue
--
房屋租赁
/service/rentRoom
2.2.4 App本地接口
我家云H5页面，需要调用App相关功能，才能完成某些业务操作， 如拍照等。
需要接口如下：
我家端：
1、H5调用Android大图展示页面： window.Android.showPic(String pathList, int index);
PS：pathList的值形如http://img1.jgp,http://img2.jgp,http://img3.jgp
假设一共5张大图，那么index的传值范围是0到4。
2、H5触发Android带有“拍照”、“相册取图”和“取消”选项的取图页面： window.Android.selectFiles(String numberOfSelected);
PS：numberOfSelected的传值范围是1到9。
3、Android将相册图片上传好，回传 形如 xxx,yyy;http://img1.jgp,http://img2.jgp 的 data
给H5的方法： "javascript:receiveFiles('"+ data + "')"
管家端：
1、H5调用Android大图展示页面： window.WebController.showPic(String pathList, int index);
PS：pathList的值形如http://img1.jgp,http://img2.jgp,http://img3.jgp
假设一共5张大图，那么index的传值范围是0到4。
2、H5触发Android带有“拍照”、“相册取图”和“取消”选项的取图页面： window.WebController.getPic(String numberOfSelected);
PS：numberOfSelected的传值范围是1到9。
3、Android将相册图片上传好，回传 形如 xxx,yyy;http://img1.jgp,http://img2.jgp 的 data
给H5的方法： "javascript:getPic('"+ data + "')"
2.3 基础API接口
2.3.1 签名算法
待加密串为该次请求中的appKey、clientTime、version，以&连接的字符串，按参数的字母先后顺序排序，再连接appSecret
如appKey=ap119jaz6b6te84v&clientTime=1465180217306&version=V1.0&yhegf6ehllfegayh3bem6l3gvswp2r50得到和字符串
经MD5加密，最后再进行SHA1加密，得到signature。
其中， appKey和appSecret的获取，见开放平台说明接入方式和说明。2.3.2 获取ticket
- 接口描述：获取用户的ticket
- 功能说明：
对用户资源进行操作前，需要通过签名算法得到签名串。 - HTTP请求方式：GET
- 返回格式：JSON
- 认证方式：
功能类API，使用appkey和signature认证 - 调用限制：无
- 请求参数：
参数名称
必选
类型
说明
appKey
true
string
开发者账号创建授权接入
createTime
true
int
访问时间毫秒数, 在30分钟内有效
version
true
string
客户端版本, 固定值V1.0
signature
true
string
签名串
- 请求示例：
{
"result" : "success",
"success": true|false,
"code" : 0 ,
"msg" : ""
"data" : {
"ticket" : "nrb8ffrg23230wfywv6bpagkomkgfb"，
"expires" : 7200
}
}9.返回参数：
返回参数
字段类型
字段说明
result
string
状态错误或成功 error/success
success
string
结果或错误描述 true/false
code
integer
错误码，0正常
msg
string
消息，正常时为空
data
string
数据结果集
ticket
string
Ticket令牌
expires
integer
ticket的生命周期，单位是毫秒数。
- 注意事项
ticket有效时间2小时,超时需要重新获取。 重新获取后，原ticket失效。
ticket获取需要在开发者服务端获取，我家云会校验白名单。
2.3.3 获取access_token
- 接口描述：获取用户的access_token
- 功能说明：
对用户资源进行操作前，需要获取用户的ticket。 - HTTP请求方式：POST
- 返回格式：JSON
- 认证方式：
功能类API，使用ticket认证 - 调用限制：无
- 请求参数：
参数名称
必选
类型
说明
ticket
true
string
Ticket令牌
username
true
string
用户名（手机号码）
pid
true
string
项目ID
type
true
string
接入类型(0物业WEB,1我家APP,2管家APP)
source
false
string
来源
- 请求示例：
{
"result" : "success",
"success": true|false,
"code" : 0 ,
"msg" : ""
"data" : {
"access_token" : "nrb8ffrg23230wfywv6bpagkomkgfb"，
"expires_time" : 7200,
"type" : 0
}
}9.返回参数：
返回参数
字段类型
字段说明
result
string
状态错误或成功 error/success
success
string
结果或错误描述 true/false
code
integer
错误码，0正常
msg
stringr
消息，正常时为空
data
stringr
数据结果集
access_token
stringr
用户的token
expires_time
integer
access_token的生命周期，单位是毫秒数。
type
integer
类型
- 注意事项
无
Original url: Access
Created at: 2019-12-10 21:19:01
Category: default
Tags: none
未标明原创文章均为采集，版权归作者所有，转载无需和我联系，请注明原出处，南摩阿彌陀佛，知识，不只知道，要得到
最新评论