佳信客服即时通信服务器对外暴露RESTful的HTTP接口以及XMPP接口，第三方APP通过佳信客服SDK接入佳信客服即时通信服务器，可以快速地将即时通信功能集成到APP中。
XMPP接口通过XMPP协议提供即时即时通信功能。
RESTful是一种HTTP协议实现的轻量级Web Service，通过简单的HTTP请求，佳信客服 SDK、第三方APP服务器以及佳信客服开发者平台可以方便地获取相关数据。
第三方APP服务器与其对应的APP使用第三方自定义协议通讯。
1、REST介绍
什么是REST
REST（Representational State Transfer）是一种轻量级的Web Service架构风格,可以翻译成“表述性状态转移”，实现和操作明显比SOAP和XML-RPC更为简洁，可以完全通过HTTP协议实现，还可以利用缓存Cache来提高响应速度，性能、效率和易用性上都优于SOAP协议。
REST从资源的角度来观察整个网络，分布在各处的资源由URI确定，而客户端的应用通过URI来获取资源的表征。获得这些表征致使这些应用程序转变了其状态。随着不断获取资源的表征，客户端应用不断地在转变着其状态，所谓表征状态转移（Representational State Transfer） REST架构遵循了CRUD原则，CRUD原则对于资源只需要四种行为：Create（创建）、Read（读取）、Update（更新）和Delete（删除）就可以完成对其操作和处理.这四个操作是一种原子操作，对资源的操作包括获取、创建、修改和删除资源的操作正好对应HTTP协议提供的GET、POST、PUT和DELETE方法，因此REST把HTTP对一个URL资源的操作限制在GET、POST、PUT和DELETE这四个之内。这种针对网络应用的设计和开发方式，可以降低开发的复杂性，提高系统的可伸缩性。
什么是JSON
JSON(JavaScript Object Notation) 是一种轻量级的数据交换格式，易于人阅读和编写，同时也易于机器解析和生成。佳信客服即时通信服务器RESTful接口以JSON作为服务端与客户端的数据交换格式。
IP次数访问限制
同一个IP每秒最多可调用30次, 超过的部分将会返回503错误, 在调用程序中, 如果碰到了这样的错误, 需要稍微暂停一下并且重试。
URL占位符说明
在佳信客服即时通信服务器REST接口定义中，会出现如{orgName}、{appName}、{username}等占位符，开发者调用接口时需要根据自己注册时填写的企业id、App id等信息替换相应的占位符。
2、场景分析
获取Token
场景说明：
客户端发起获取Token请求
RESTful服务检测该IP的访问在1s内的访问次数，超过访问次数将禁止该IP访问
RESTful服务检查请求参数是否合法
RESTful服务与IM Server通信请求获取Token
IM Server返回操作结果
RESTful服务放回操作结果
REST业务请求
场景说明：
客户端发起其他REST请求
RESTful服务检测该IP的访问在1s内的访问次数，超过访问次数将禁止该IP访问
RESTful服务检查用户是否已经授权，未授权将返回401未认证错误码
RESTful服务检查请求参数是否合法
RESTful服务与IM Server通信获取请求结果
IM Server返回操作结果
RESTful服务放回操作结果
3、鉴权机制
佳信客服即时通信服务器提供的RESTful接口需要通过鉴权之后才能使用，通过Token管理接口开发者将获取到一个Token，在Token有效期内，HTTP请求会被服务端接受；如果Token超有有效期，服务端将拒绝该HTTP访问，并返回401未认证的错误码，此时开发者需要重新获取Token值。
在访问需要鉴权的RESTful接口时，开发者需要在HTTP请求中添加X-Token额外头域，其值为获取到的Token值，服务端通过该Token判断用户是否已经鉴权。
DIGEST认证概述
Http Digest是一个简单的认证机制，最初是为HTTP协议开发的，因而也常叫做HTTP摘要，在RFC2617中描述。其身份验证机制很简单，采用杂凑式（hash）加密方法，以避免用明文传输用户的口令。聚合代理模块IM-AP主要基于Digest的认证机制。
Digest认证需要在HTTP消息头多传递额外的头域：Authorization、WWW-Authenticate、Authorization-Info等。各字段说明如下表所示：
| 头域字段 |
参数 |
参数说明 |
| Authorization |
realm（域名） |
领域参数是强制的，在所有的盘问中都必须有。 |
| nonce（现时） |
这是由服务器规定的数据字符串，在服务器每次产生一个摘要盘问时，这个参数都是不一样的（与前面所产生的不会雷同）。 |
|
| username |
用户名或者用户唯一标识 |
|
| qop（保护的质量） |
这个参数规定服务器支持哪种保护方案。客户端可以从列表中选择一个。 |
|
| uri（统一资源指示符） |
这个参数包含了客户端想要访问的URI |
|
| response（响应） |
这是由客户端计算出的一个字符串，以证明客户端知道口令。 |
|
| cnonce |
这也是一个不透明的字符串值，由客户端提供，并且客户端和服务器都会使用，以避免用明文文本。这使得双方都可以查验对方的身份，并对消息的完整性提供一些保护。 |
|
| nc（“现时”计数器） |
这是一个16进制的数值，即客户端发送出请求的数量（包括当前这个请求），这些请求都使用了当前请求中这个“现时”值。例如，对一个给定的“现时”值，在响应的第一个请求中，客户端将发送“nc=00000001”。这个指示值的目的，是让服务器保持这个计数器的一个副本，以便检测重复的请求。如果这个相同的值看到了两次，则这个请求是重复的。 |
|
| WWW-Authenticate |
realm（域名） |
详见上述描述 |
| nonce（现时） |
详见上述描述 |
|
| qopqop（保护的质量） |
详见上述描述 |
|
| Authorization-Info |
nextnonce |
在鉴权成功的情况下返回应答传递的信息 |
DIGEST认证步骤
步骤说明：
客户端发起HTTP请求
服务端返回401未认证的HTTP响应，在响应中带上Authorization、WWW-Authenticate、Authorization-Info等头部信息
客户端根据Authorization、WWW-Authenticate、Authorization-Info以及用户名密码生成response值
客户端发起HTTP Digest认证的请求
服务端校验response值，返回认证成功的HTTP响应
response的计算过程：
HA1 = MD5(A1) = MD5(username:realm:password)
HA2 = MD5(A2) = MD5(method:digestURI)
response = MD5(HA1:nonce:nc:cnonce:qop:HA2)
DIGEST认证示例
1. Client request (no authentication)
GET /dir/index.html HTTP/1.0
Host: localhost
2. Server response（401）
HTTP/1.0 401 Unauthorized
Server: HTTPd/0.9
Date: Sun, 10 Apr 2005 20:26:47 GMT
WWW-Authenticate: Digest realm="testrealm@host.com",
qop="auth,auth-int",
nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093",
opaque="5ccc069c403ebaf9f0171e9517f40e41"
Content-Type: text/html
Content-Length: 311
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
<HTML>
<HEAD>
<TITLE>Error</TITLE>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
</HEAD>
<BODY><H1>401 Unauthorized.</H1></BODY>
</HTML>
3. Client request (username “Mufasa”, password “Circle Of Life”)
GET /dir/index.html HTTP/1.0
Host: localhost
Authorization: Digest username="Mufasa",
realm="testrealm@host.com",
nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093",
uri="/dir/index.html",
qop=auth,
nc=00000001,
cnonce="0a4f113b",
response="6629fae49393a05397450978507c4ef1",
opaque="5ccc069c403ebaf9f0171e9517f40e41"
4. Server response（200）
HTTP/1.0 200 OK
Server: HTTPd/0.9
Date: Sun, 10 Apr 2005 20:27:03 GMT
Content-Type: text/html
Content-Length: 7984
………
4、TOKEN管理
开发者Token存在有效期，只有在Token有效期内开发者才能正常访问佳信客服即时通信服务器RESTful接口。
当Token超过有效期，访问RESTFul接口将返回401未认证的错误码，开发者需要重新访问获取Token。
获取Token采用Digest认证方式，需要在HTTP请求头传递额外的头域，参考鉴权机制。
获取用户Token
接口定义：
| 请求URI |
|
| 请求方法 |
GET |
| 请求数据 |
|
| 请求响应 |
5、用户管理
5.1、添加IM用户
接口定义：
| 请求URI |
https://api.jiaxincloud.com/rest/{orgName}/{appName}/users |
| 访问角色 |
dev、devAdmin |
| 请求方法 |
POST |
| 请求数据 |
添加单个用户： |
| 请求响应 |
{ |
请求参数说明：
| 参数名 |
类型 |
必选 |
说明 |
| username |
String |
Y |
用户账号 |
| password |
String |
Y |
用户密码 |
| name |
String |
N |
用户昵称 |
响应参数说明：
| 参数名 |
类型 |
必选 |
说明 |
最低0.47元/天 解锁文章
689
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
