API 文档 枚举/常量参考 / 变更日志

前言

本文档包含所有的HTTP API接口描述，并提供在线测试工具。

同时，得益于Callme HTTP Adapter，本系统所有HTTP API接口都可以通过RPC方式调用（详情见下文）

注意：请仔细阅读本文档之后，再实际使用下文揭示的HTTP API接口。

注意：在本页面的操作与实际调用HTTP API具有相同效果，请小心演绎。

注意：无论是从本文档发起调用，还是从浏览器、命令行curl或通过RPC调用，都具有完全相同的效果。所以只要能够从本文档正常发起调用，即可认为HTTP API能够正常使用，故请优先检查自身代码。

API设计

本系统接口URL一般规则如下：

/api/{版本}/{操作对象}/{下级操作对象}/{...}/do/{动作}

对于一般的CRUD操作而言，本系统API主要提供以下几种接口：

• 列表接口：GET /api/{版本}/{操作对象}/do/list
• 获取接口：GET /api/{版本}/{操作对象}/{操作对象ID}/do/get
• 添加接口：POST /api/{版本}/{操作对象}/do/add
• 修改接口：POST /api/{版本}/{操作对象}/{操作对象ID}/do/modify
• 删除接口：GET /api/{版本}/{操作对象}/{操作对象ID}/do/delete

注意：根据具体业务不同，有的操作对象可能并不会提供所有的上述接口；有的操作对象可能有额外的接口。

注意：超出上述范畴的API以API文档为准。

数据格式

此外，API接口均使用JSON进行数据交换，且一般情况下，字段名称、字符串常量值使用littleCamel风格。如：

{
  "error"  : 200,
  "message": "",
  "data"   : null,
  "traceId": "TRACE-XXXXXXXXXXXXXXXXXXXXXX",
  "reqCost": 100
}

表示关联字段的表示

除了一般情况下使用到的littleCamel风格的字段名外，有时会使用到下划线表示关联字段。如：

{
  "error"  : 200,
  "message": "",
  "data": {
    "seq"       : 1,
    "id"        : "data-xxxxxxxxxxxxxxxxxxxxxx",
    "name"      : "XXXX",
    "note"      : null,
    "createTime": "2018-08-29T12:47:00.000Z",
    "updateTime": "2018-08-29T12:47:00.000Z",
    "o_id"      : "o-xxxxxxxx",
    "o_uniqueId": "o-xxxxxxxx",
    "o_name"    : "xxxxxxxx Organization"
  },
  "traceId": "TRACE-XXXXXXXXXXXXXXXXXXXXXX",
  "reqCost": 100
}

在上述数据中，data.seq至data.createTime使用littleCamel风格，属于接口操作对象的本身具有的字段。而data.o_id至data.o_name则表示所关联企业的ID、名称等字段，属于关联字段。

为了避免相同字段名冲突，以及明确字段意义。本系统中，操作对象本身具有的字段使用littleCamel风格。而关联对象的字段以<对象简称>_<littleCamel风格的关联对象字段名>方式命名。

本系统内对象的全称与简称举例如下：

注：在URL中，使用中杠连接风格，如user-info。

来自外部系统的字段命名方式

由于本系统使用Node.js开发，所以在JSON数据交换时，均使用littleCamel风格。

但不可避免的是，本系统在与外部系统交互时接收到的JSON数据未必同样使用littleCamel风格来命名字段。如：

• Python项目一般使用下划线分割命名方式：my_variable
• 阿里云API接口返回内容一般为BigCamel风格：InstanceId

为了避免不必要的麻烦，所有来自外部不可控系统的JSON数据，无论命名规则如何，都会保留原有的命名规则。

理念

本系统API设计与教科书版RESTful风格接口非常相似，但是并没有使用教科书中的GET、POST、PUT、DELETE、PATCH等HTTP动词。而仅仅使用了最常用的GET和POST，分别用于需要或不需要提交数据的接口。同时，在接口结尾增加/do/{动作}，来指明具体的动作行为。

这么做的目的在于避免牵强地套用RESTful的风格（如：如何为用户注册、登陆的过程进行RESTful建模？）。同时降低客户端的开发成本（有些语言的HTTP包并不支持自定义HTTP动词）。

认证

根据业务不同，有些接口需要认证（即用户登录）后才可调用，有些则允许直接调用。

可以根据每个API文档的需要登录标签了解接口是否需要认证。

通过内建用户系统认证

此认证方式由本系统的登录接口实现。

登录成功后，登录接口会返回一个xWatAuthToken作为之后调用其他API时的凭证。此凭证存在有效时间限制（默认为2小时）。但每当此凭证发送至本系统，系统会自动刷新此凭证的有限时间。

根据业务需要和配置，凭证可以通过多种方式发送：

• HTTP请求头（默认为X-WAT-Auth-Token字段，可配置为禁用）
• HTTP URL Query参数（默认为xWatAuthToken参数，可配置为禁用）
• Cookies（xAuthToken字段，可配置为禁用）

注意：

一般页面的请求作为例外，始终支持Cookies方式传递凭证。

正式环境部署时，可单独针对API请求禁用通过Cookies传递凭证，但不影响一般页面通过Cookies传递凭证。

内建认证仅作为调试使用，不推荐提供给用户直接使用。

公共JSON响应字段

所有的API接口都有通用的返回值字段，客户端可以根据这些字段来判断API调用成功与否。

成功调用的JSON响应字段

当API调用成功后返回的JSON中，包含以下字段：

data字段具体说明见下文

一个典型的API调用成功返回值JSON如下：

{
  "error"  : 200,
  "message": "",
  "data"   : {...},
  "traceId": "TRACE-XXXXXXXXXXXXXXXXXXXXXX",
  "reqCost": 100
}

失败调用的JSON响应字段

当API调用失败后返回的JSON中，包含以下字段：

一个典型的API调用失败返回值JSON如下：

{
  "error"  : 404.41,
  "message": "No such instance",
  "reason" : "EClientNotFound",
  "detail": {
    "id": "xxx"
  },
  "traceId": "TRACE-XXXXXXXXXXXXXXXXXXXXXX",
  "reqCost": 100
}

列表接口

此类接口主要用于获取操作对象列表。请求方式如下：

GET /api/v1/{操作对象}/do/list

如：

GET /api/v1/data/do/list

分页

绝大部分列表接口都支持分页，客户端可以指定页号（从1开始）和每页记录条数（默认5，最大1000。可由配置文件修改）。

可以根据每个API文档的支持分页标签了解接口是否支持分页。

分页参数如下：

如：

GET /api/v1/data/do/list?pageNumber=1&pageSize=10

搜索/过滤

绝大部分列表接口都支持过滤条件，客户端可以指定通用搜索_search或具体字段进行过滤。

可以根据每个API文档的详情了解所支持的过滤条件

如：

GET /api/v1/data/do/list?_search=XXXXX

再如：

GET /api/v1/data/do/list?name=XXXXX

列表接口JSON响应字段

列表接口的返回值data字段是一个包含若干个JSON的数组。此外，在支持分页的列表接口返回值中，会额外具有一个pageInfo字段表示分页信息。

分页信息如下：

一个典型的列表接口返回值如下（普通分页）：

{
  "error"  : 200,
  "message": "",
  "data": [
    {
      "seq"       : 1,
      "id"        : "data-xxxxxxxxxxxxxxxxxxxxxx",
      "name"      : "XXXX",
      "note"      : null,
      "createTime": "2018-08-29T12:47:00.000Z",
      "updateTime": "2018-08-29T12:47:00.000Z"
    }
  ],
  "pageInfo": {
    "count"          : 1,
    "totalCount"     : 1,
    "pageSize"       : 10,
    "pageNumber"     : 1,
    "pageCount"      : 1,
    "pageMarkerField": null,
    "pageMarker"     : null
  },
  "traceId": "TRACE-XXXXXXXXXXXXXXXXXXXXXX",
  "reqCost": 100
}

一个典型的列表接口返回值如下（标记分页）：

{
  "error"  : 200,
  "message": "",
  "data": [
    {
      "seq"       : 1,
      "id"        : "data-xxxxxxxxxxxxxxxxxxxxxx",
      "name"      : "XXXX",
      "note"      : null,
      "createTime": "2018-08-29T12:47:00.000Z",
      "updateTime": "2018-08-29T12:47:00.000Z"
    }
  ],
  "pageInfo": {
    "count"          : 1,
    "totalCount"     : null,
    "pageSize"       : 10,
    "pageNumber"     : null,
    "pageCount"      : null,
    "pageMarkerField": "seq",
    "pageMarker"     : 1
  },
  "traceId": "TRACE-XXXXXXXXXXXXXXXXXXXXXX",
  "reqCost": 100
}

获取

此类接口主要用于获取操作对象详情。请求方式如下：

GET /api/v1/{操作对象}/{操作对象ID}/do/get

如：

GET /api/v1/data/data-xxxxxxxxxxxxxxxxxxxxxx/do/get

获取JSON响应字段

获取的返回值data字段是一个JSON对象。

一个典型的列表接口返回值如下：

{
  "error"  : 200,
  "message": "",
  "data": {
    "seq"       : 1,
    "id"        : "data-xxxxxxxxxxxxxxxxxxxxxx",
    "name"      : "XXXX",
    "note"      : null,
    "createTime": "2018-08-29T12:47:00.000Z",
    "updateTime": "2018-08-29T12:47:00.000Z"
  },
  "traceId": "TRACE-XXXXXXXXXXXXXXXXXXXXXX",
  "reqCost": 100
}

添加接口

此类接口主要用于添加操作对象。请求方式如下：

POST /api/v1/{操作对象}/do/add

{
  "data": {
    ...
  }
}

如：

POST /api/v1/data/do/add

{
  "data": {
    "name": "XXXXX",
    "note": "Just Test!"
  }
}

添加接口JSON响应字段

添加接口的返回值data字段是一个JSON对象。其中，包含一个id字段，表示新建对象的ID。

一个典型的列表接口返回值如下：

{
  "error"  : 200,
  "message": "",
  "data": {
    "id": "data-xxxxxxxxxxxxxxxxxxxxxx"
  },
  "traceId": "TRACE-XXXXXXXXXXXXXXXXXXXXXX",
  "reqCost": 100
}

修改接口

此类接口主要用于修改操作对象，请求方式如下：

POST /api/v1/{操作对象}/{操作对象ID}/do/modify

{
  "data": {
    ...
  }
}

如：

POST /api/v1/data/data-xxxxxxxxxxxxxxxxxxxxxx/do/modify

{
  "data": {
    "name": "YYYYY"
  }
}

修改接口可以根据需要仅对部分字段进行修改，故相对于添加接口必选字段很少。

修改接口JSON响应字段

修改接口的返回值data字段是一个JSON对象。其中，包含一个id字段，表示被修改操作对象的ID。

一个典型的列表接口返回值如下：

{
  "error"  : 200,
  "message": "",
  "data": {
    "id": "data-xxxxxxxxxxxxxxxxxxxxxx"
  },
  "traceId": "TRACE-XXXXXXXXXXXXXXXXXXXXXX",
  "reqCost": 100
}

删除接口

此类接口主要用于删除操作对象，请求方式如下：

GET /api/v1/{操作对象}/{操作对象ID}/do/delete

如：

GET /api/v1/data/data-xxxxxxxxxxxxxxxxxxxxxx/do/delete

注意：一般来说，被删除的内容无法恢复，客户端在调用此接口前应当要求用户确认后方可进行

删除接口JSON响应字段

删除接口的返回值data字段是一个JSON对象。其中，包含一个id字段，表示被删除操作对象的ID。

一个典型的列表接口返回值如下：

{
  "error"  : 200,
  "message": "",
  "data": {
    "id": "data-xxxxxxxxxxxxxxxxxxxxxx"
  },
  "traceId": "TRACE-XXXXXXXXXXXXXXXXXXXXXX",
  "reqCost": 100
}

本系统中所示使用的字段类型

本系统中大多数字段，根据用途都有相同的字段类型。

本系统常用的字段及其类型如下：

根据字段意义特别指定的类型如下：

通过Access Key访问本系统

第三方系统可以通过Access Key ID和Access Secret（下称AK）来访问本系统。

1. 生成AK

可以在Access Key管理页面生成AK。

2. 对请求进行签名

对请求进行签名需要以下字段：

目前支持v1和v2两种签名算法：

1. v1签名为:

Hmac-SHA1("<AK时间戳>&<AK随机数>&<HTTP方法>&<完整请求URL>", <AK Secret>)

1. v2签名为:

Hmac-SHA1("<AK签名算法版本>&<AK时间戳>&<AK随机数>&<HTTP方法>&<完整请求URL>&<原始请求体MD5值>", <AK Secret>)

3. 将签名信息加入请求头

4. 发送请求

至此，发送请求即可

Webhook

每个AK支持添加一个URL作为Webhook触发时的调用地址。

当特定的API被调用成功后，系统会向所有Webhook URL发送请求并包含相关信息。

Webhook 签名

系统在向Webhook URL发送请求时，也会按照上述相同的AK签名方式对请求进行签名。

可用资源

本项目已提供了一些已经实现的HTTP客户端，方便第三方系统使用，详见：

设计文档见链接。

由于CoreStone 本身也作为一个API 网关的角色存在， 并且在处理请求时，按照请求头中的Host 字段来区分请求的具体处理方式。

所以在部署CoreStone 时，对域名配置有一定要求。

概要

CoreStone 系统中的转发系统包含业务系统、接收命名空间、前端域名、后端域名、转发规则、模拟规则概念，简要逻辑如下：

1. 业务系统：表示一个业务系统（如：Shrine后端等）
2. 接收命名空间：表示一个业务系统允许接收的用户所属的命名空间。在登录账号互通的情况下，一个业务系统可以添加多个接收命名空间，允许不同命名空间下的用户发送请求给自身。
3. 前端域名：表示客户端请求的域名。一般每个业务系统都至少有一个前端域名，支持公网解析但IP均指向CoreStone 本身。
4. 后端域名：表示客户端请求转发后的最终目的地址。每个业务系统都至少要有一个，并设置默认转发后端域名。只需CoreStone 能够解析即可。
5. 转发规则：表示某些团队下的所有/部分登录账号的请求会被转发到指定的后端域名。主要用于灰度发布/AB测试等。
6. 模拟规则：表示业务系统的某些接口可以由CoreStone 直接返回固定内容。主要用于在业务系统某些接口未开发完成时的兼容处理。

设计文档见链接。

配置CoreStone 本身域名

部署CoreStone 时，需要有一个域名指向CoreStone 本身， 用于判断是否请求目标为CoreStone 本身的API。如：core-stone.cloudcare.cn。 与此同时，将此域名写入配置文件中的coreStone.hostnames（数组）字段中。

当CoreStone 接收到Host 头为CoreStone 本身的域名时，会自行处理，而不会转发到后端服务器。

添加业务系统

直接在CoreStone 界面上操作，注意使用有意义的名称即可。

为业务系统配置接收命名空间

每个业务系统都需要有配置接收命名空间（支持多个）。

对于已登录的用户，当请求试图转发至某个业务系统时， CoreStone 首先会检查是否接收此用户所属的命名空间。

如接受此用户所属的命名空间，则按照正常登录用户流程转发请求。

如验证未通过，请求依然会转发到后端域名， 但不会包含有关用户的信息（即作为未登录用户的请求）。

前端域名

前端域名指的是客户端（浏览器、手机APP等）发起请求时的请求地址（包含在Host 请求头中）。

这个域名需要在公网能解析，同时都指向CoreStone 服务器， 如： shine-via-core-stone.cloudcare.cn

此地址允许直接填写IP地址。

后端域名

后端域名指的是客户端发起的请求最终的转发目的地址。

这个域名只需要CoreStone 能够解析即可（如内网DNS，内网IP和Port）， 如：192.168.1.100:8088

此地址允许直接填写IP地址。

转发额外配置（高级）

一般针对每一个业务系统，都需要在CoreStone 中配置一个前端域名（允许多个）， 和一个后端域名（允许多个，但必须设置一个为默认）。

对于多个前端域名，客户端无论请求哪个前端域名效果都相同。

对于多个后端域名，客户端的请求在转发时，无特殊规则都会转发到默认后端域名。 在此基础上，可以配置某个团队下所有/部分登录账号的请求转发到指定的后端域名， 以实现类似灰度发布/AB测试等效果。

注意：前端域名不能与后端域名相同，否则可能会导致请求循环转发

为业务系统配置转发规则

每个业务系统都会有一个默认转发的后端地址。

在此基础上，可以针对某个团队下的所有/部分登录账号指定转发目标。

此功能主要用于测试/灰度发布/AB测试等用途。

为业务系统配置模拟规则

每个业务系统可以配置模拟规则。

当请求匹配HTTP 请求方法、URL 地址（支持/data/:param语法）时， CoreStone 会直接返回预先指定的内容，且优先级高于正常转发。

此功能主要用于接口兼容、生成假数据等用于。

注意：所有操作以实际接口说明文档为准

设计文档见链接。

转发过程

CoreStone 支持两种转发方式：

1. 通过前端地址转发
2. 通过请求头中指定业务系统转发

其中，第二种方式可以不配置前端域名。

但无论何种方式，后端域名必须进行配置。

通过前端地址方式转发

当App、Web应用通过前端地址转发时，CoreStone 会首先提取请求头中Host字段， 并根据以下规则依次匹配并执行转发：

1. 如Host指向自身（配置文件中指定），自CoreStone 自行处理请求
2. 如Host指向某个业务系统，则转发至此业务系统
3. 如Host无法找到任何匹配的目标，则拒绝本次请求

通过在Query中指定业务系统前端域名转发

在某些情况下，没有条件为每个业务系统的前端地址实际配置DNS， 那么可以采取在请求头中直接指定业务系统的前端域名进行转发。

操作方式为请求Query中添加xCoreStoneBizSystemHost=<业务系统前端域名>来指定请求发往的业务系统。

业务系统接收转发请求并获取用户信息

对于已登录的用户，客户端在发起请求时， 需要在请求中添加额外字段来传递认证令牌（登录成功后返回的认证令牌）。

目前认证令牌支持以下几种方式传递：

• HTTP 请求头中添加X-Core-Stone-Auth-Token字段。
• HTTP Query中添加xCoreStoneAuthToken字段。

请求发送到CoreStone 后，CoreStone 会对认证令牌进行验证。

如验证通过，则正常转发请求到后端域名， 并在HTTP 请求头中额外添加X-Core-Stone-Auth-Info-Token传递认证信息。

认证信息（CoreStoneAuthInfo）是一个通过JWT签名后的令牌，解析后结构如下：

如验证未通过，请求依然会转发到后端域名， 但不会包含有关用户的信息（即作为未登录用户的请求）。

跟踪ID（Trace ID）

由于当前整体系统架构进行了分层， 一个请求会连续经过多个系统处理后才会最终响应回到客户端， 这对一些错误的排查带来了挑战。

跟踪ID的目的在于在全局范围内跟踪每一个客户端发出的请求， 并在方便在日志系统中查找与此请求相关的所有日志（即使这些日志由不同的系统产生）。

跟踪ID的产生和使用规范

客户端请求在发送到CoreStone 之后，CoreStone 会生成一个格式为TRACE-<UUID> 的跟踪ID。 并在转发时，在HTTP 请求头中额外添加X-Trace-Id字段传递本跟踪ID。

业务系统/基础系统在接收到请求后，应当从HTTP 请求头X-Trace-Id中获取跟踪ID， 并以此跟踪ID初始化日志对象，并在打印日志时，每一行日志都应包含此跟踪ID。

注意：如业务系统需要继续调用基础系统，也应在HTTP 请求头中添加此跟踪ID

注意：如觉得跟踪ID过长，可以只打印TRACE-<UUID前8个字符>

跟踪ID返回至客户端

由于目前所有请求都经由CoreStone 转发， 所以在最终响应客户端时，CoreStone 自动会将生成的跟踪ID 写入HTTP 响应头X-Trace-Id中， 业务系统在响应请求时，无论在HTTP 响应中是否添加跟踪ID 都没有关系。

即：CoreStone作为跟踪ID的创建者，同时会将跟踪ID传递给客户端； 业务系统作为跟踪ID使用者，只需在必要之处输出跟踪ID即可。

注意：所有操作以实际接口说明文档为准

设计文档见链接。

概要

CoreStone 系统中的账户系统包含团队、登录账号概念，简要逻辑如下：

1. 团队：使用我公司服务或产品的团队，名称可为昵称（如：上海驻云）
2. 登录账号：所属于客户并实际进行登录及操作的账号 （如：zhang3@jiagouyun.com）
3. 团队与登录账号之间关系为 N:N 。即一个团队可以包含多个登录账号；一个登录账号也可属于多个团队。
4. 团队类型分为单用户团队和多用户团队，单用户团队为仅包含本登录账号的团队，无法进行添加/修改/删除成员的操作。单用户团队主要在登录账号创建/团队删除登录账号后，登录账号无所属团队时自动创建。
5. 登录账号存在命名空间属性，不同命名空间下的登录账号完全隔离，即使同名，也认为是不同登录账号。
6. 登录账号的命名空间会影响请求是否允许转发、请求的转发目的。
7. 各系统的注册、登录、登出页面和接口由各个系统通过调用本系统相关API自行实现。
8. 内建团队角色：CoreStone定义的基本团队角色
9. 内建权限：CoreStone定义的基本权限（不附带访问规则）
10. 权限：由业务系统自定义的权限（可附带访问规则）
11. 访问规则：由业务系统自定义的访问规则，可指定HTTP方法、路由（带模式匹配），允许或禁用，优先级
12. 团队角色：每个团队可自定义添加的角色，可以附加内建权限和权限
13. 额外权限：允许在团队角色的基础上，额外为登录账号直接增加的权限

单词表见链接。

用户注册

涉及接口：

• 添加登录账号

通常而言，对于独立用户系统，一般流程即向本地数据库写入公司/用户数据。

而在对接CoreStone 之后，原有的业务逻辑需要进行修改为调用本系统的添加登录账号API。

passwordEncryptType与passwordSalt字段

本字段主要用于向旧有独立用户系统兼容所用。

由于本系统、旧有系统的密码加密方式、密钥、盐值策略各不相同，需要对密码进行区分处理。

对于已经对接后，新注册的团队/登录账号，除非有特殊需求，本字段留空即可。

添加登录账号的同时，加入团队

添加登录账号的同时，可以额外指定加入的多用户团队。

正确指定加入的团队后，登录账号会在创建的同时加入团队，并存在以下额外处理：

即在最终效果看来，任何一个登录账号必然存在一个默认登录的团队

升级为团队版

涉及接口：

• 修改团队

登录账号的团队如果为单用户团队，那么对应到CloudCare 业务体系中被称为「个人版」。

当「个人版」升级为「团队版」时，仅需在CoreStone 中修改团队为多用户团队，而不必额外创建团队。

注意：只能由单用户团队修改为多用户团队，不支持从多用户团队退回单用户团队

后台直接开设登录账号

涉及接口：

• 添加登录账号

此操作与上述「用户注册」并无区别。

后台直接开设团队

涉及接口：

• 添加团队

此操作在一般CloudCare 业务体系中并不存在， 但有可能存在为公司内部工作人员创建团队的情况。

注意：添加团队接口只能创建多用户团队

团队成员操作、团队角色/额外权限的添加/修改

涉及接口：

• 向团队添加登录账号（附带团队角色/额外权限）
• 修改团队中登录账号（附带团队角色/额外权限）
• 从团队中删除登录账号

当需要修改团队成员时，调用相应的API 接口即可， 此类API 接口都支持批量操作。

注意：团队成员操作不适用于单用户团队。

将登录账号从默认登录团队中删除

将登录账号从默认团队中删除后，系统会自动查找此登录账号加入的其他团队，并作以下额外处理：

即在最终效果看来，任何一个登录账号必然存在一个默认登录的团队

用户登录

涉及接口：

• 直接创建认证令牌

对于CoreStone 本身，任何登录账号的认证令牌均可以直接创建。 各业务系统自行规定创建和发行时机。

对于需要使用密码登录创建认证令牌时， 应在API 接口中额外传递password供CoreStone 进行计算比对。

登录成功后，CoreStone 会返回coreStoneAuthToken（CoreStone认证令牌）。 客户端直接在请求头（X-Core-Stone-Auth-Token） 或Query（xCoreStoneAuthToken）中附带此内容即可被CoreStone 授权。

用户登出

涉及接口：

• 作废认证令牌（对应客户端登出操作）

对于CoreStone 本身，认证令牌可以直接销毁。

作废认证令牌支持按认证令牌、登录账号ID等批量作废，用于支持踢出用户/强制下线等处理。

CoreStone 本身提供了用户认证（通过发行认证令牌）和转发， 与此同时，所有基于WAT 的系统都支持AK 方式认证。

而一个查询请求是经过业务系统，还是直接发到CoreStone， 是有明确的业务场景区分的，并不是一个模棱两可的事情。

认证令牌认证的是登录账号；AK认证的是业务系统

首先，App/Web等终端用户登录后得到的认证令牌， 是「颁发给这一个登录账号的认证令牌」， 用这个认证令牌经过的认证原则上是只能访问「这个登录账号所属团队的数据」。

经过业务系统「转发」，实际上并不是真正的转发， 而是「业务系统接收到前端请求后，重新以业务系统的名义向CoreStone 发起请求」。 这个时候认证用的是系统间AK方式来认证的，权限比登录账号的认证令牌要大许多， 并且允许访问任何团队/登录账号的数据。

这两者具有本质区别的， 简而言之，认证令牌认证的是登录账号；AK认证的是业务系统。

举个例子：

Home中查询团队下属所有登录账号， 必须要提供「当前用户所属团队ID」作为过滤条件。

而Shrine中查询团队下属所有登录账号，十有八九是「销售或服务人员查询客户团队下属登录账号」。 这种情况下，存在跨团队的数据访问，必须用系统间AK认证方式调用， 传递的团队ID也不是「当前销售/服务人员登录账号的ID」而是「目标客户的ID」。

认证令牌直接直接发往CoreStone 的情形

CoreStone 允许接收允许登录账号认证令牌， 本身是因为CoreStone 底层代码（以下简称WAT）的一个数据隔离机制， 这个机制只有在WAT 项目作为「业务系统」的时候才能体现出好处。

好处主要在于，依靠WAT 底层数据隔离机制，会根据每个数据模型的配置， 自动在SQL语句中插入类似WHERE TeamID = '<Team ID>' AND AccountID = 'Account ID'的条件语句。 保证开发人员在编写业务代码的时候，不用关注团队问题（也就是多租户问题）， 直接写SQL查出来的就是本团队的数据。

目前WAT 没有使用在任何业务系统中， 所以这个机制暂时没有实际体现。

CoreStone 本身提供了Socket.io 的支持。 Web/App等客户端只需接入CoreStone 的Socket.io，即可与所有业务系统通过Socket.io 进行通讯。 业务系统也同时可以通过CoreStone 与客户端进行通讯。

为了方便客户端以及业务系统开发，集中处理Websocket 连接、消息。 所有的客户端实际都只和CoreStone 保持Websocket 连接， 而CoreStone 与业务系统之间并无Websocket 连接。

当客户端向业务系统发送Websocket 数据包时， 消息通过Websocket 协议到达CoreStone 之后， 会被转换为HTTP 请求，以WebHook 的方式转发给业务系统。

相反，业务系统希望向客户端发送Websocket 数据包时， 直接调用CoreStone 的相关接口即可。 CoreStone 在接收到业务系统有关Socket.io 的调用后， 向相关的客户端推送Websocket 数据包。

从整体上来说，仅需要客户端增加Socket.io 的开发， 在业务系统中依然是标准、普通的HTTP请求。

版本

CoreStone 集成的Socket.io 版本为 2.X，且Socket.io 2.X 与 1.X 并不兼容。 客户端在接入时应当选择使用支持Socket.io 2.X 版本的第三方库。

客户端的对接

对于Web端，只需在HTML代码中引用CoreStone 本身提供的Socket.io 客户端即可：

<script type="text/javascript" src="/socket.io/socket.io.js"></script>

对于移动端，请参考官方提供的资源选择合适的客户端： socket.io - Other-client-implementations

连接服务器

Web端为例，前端对接CoreStone 的Socket.io 服务器（与HTTP复用端口）， 使用以下代码即可与CoreStone 建立Websocket 连接：

var socketIO = io();

需要注意的是， 由于Socket.io 对错误处理上的封装， 服务器再向客户端发送错误时，必须使用Error对象， 且客户端实际接收到的是此Error对象的message内容（字符串）。

为了方便统一处理，CoreStone 规定，在与客户端之间数据交互时， 所有的数据包都是JSON字符串（即JSON.stringify(data)）。

认证

当Socket.io 服务器连接成功后，服务器会立刻发送一段欢迎信息， 客户端可以使用以下方式接收到此欢迎信息：

socketIO.on('hello', function(data) {
  console.log(data); // "Welcome, please sent X-Core-Stone-Auth-Token string as `auth` event for authentication."
});

根据提示，客户端将X-Core-Stone-Auth-Token字符串作为auth事件发送给服务器：

socketIO.emit('auth', '<X-Core-Stone-Auth-Token>');

服务器会响应一个数据包给客户端，作为是否成功的判断依据，详情见下文「发送消息回应（ACK）」

当服务器响应200表示认证成功，客户端可以进行下一步操作。 否则，请根据提示排查问题。

接收消息

任何以socketio.开头的事件都能够被客户端接受， 事件名称需要客户端与具体业务系统之间协商决定， 且避免以.ack结尾（.ack结尾的事件一般用作响应使用，详见下文「发送消息回应（ACK）」）。

socketIO.on('socketio.newMessage', function(data) {
  console.log(data);
});

发送消息

客户端认证之后可以向CoreStone 发送消息（实际向业务系统广播）。

Socket.io 的消息最终都会通过WebHook 转发给业务系统。 在转发时， 客户端发送的事件event即WebHook调用时的事件event； 客户端发送的数据data即WebHook调用时的数据data。 为了避免混淆，客户端发送的所有Socket.io 事件都必须以socketio.开头，如socketio.message。 同样，客户端接收到的来自业务系统的Socket.io 事件也都会以socketio.开头。

可以使用以下方式发送一条消息：

var data = {"hello": "world"};
socketIO.emit('socketio.message', JSON.stringify(data));

消息响应（ACK）

客户端向服务器发送的任何一条消息，服务器都会有响应（ACK）。

注意：消息响应（ACK）来自CoreStone， 仅表示CoreStone 正确处理了客户端发来的消息。 并不代表后续业务系统正确处理了消息。 业务系统处理结果以业务系统发出的消息为准

响应（ACK）有以下几种：

1. Socket.io 内建的响应，通过相同事件event名称发回客户端
2. CoreStone 实现的响应，通过<事件>.ack发回客户端
3. 错误响应，通过error事件发回客户端

服务器的响应数据包为一个JSON字符串，包含以下字段：

如表示成功的数据包如下：

{
  "error"  : 200,
  "message": "",
  "data"   : null
}

再如表示登录失败的数据包如下：

{
  "error"  : 401.92,
  "message": "Invalid Auth Token.",
  "reason" : "EAuthToken"
}

这两种响应服务器都会发送，客户端选择其中一种接收即可。

接收Socket.io 内建的响应

对于Socket.io 内建的响应，直接指定emit()函数的回调方法即可：

var data = {"hello": "world"};
socketIO.emit('socketio.message', JSON.stringify(data), function(ack) {
  console.log(ack); // ack即响应数据包
});

接收CoreStone 实现的响应

对于CoreStone 实现的响应，直接监听<事件>.ack即可：

socketIO.on('socketio.message.ack', function(ack) {
  console.log(ack); // ack即响应数据包
});

var data = {"hello": "world"};
socketIO.emit('socketio.message', JSON.stringify(data));

此外，为了方便客户端判断每个响应所对应的数据包， 客户端在发送消息时，可以附带一个ackId字段，值由客户端自行生成。 服务器在响应（ACK）时，会将字段原样返回：

socketIO.on('socketio.message.ack', function(ack) {
  console.log(ack.ackId); // "12345"
});

var data = {"hello": "world", "ackId": "12345"};
socketIO.emit('socketio.message', JSON.stringify(data));

接收错误响应

对于错误响应，直接监听error即可：

注意：所有的错误都会通过error事件发出， 正常响应（ACK）中并不会接受到任何有关错误的响应

socketIO.on('error', function(error) {
  console.log(error);
});

业务系统的对接

业务系统除了在原先接收WebHook 的基础上做更多event的区分处理外，无其他额外工作。

接受消息

由客户端发出的Socket.io 事件经由CoreStone 通过WebHook 方式转发后，会有如下字段：

消息来源from中各字段说明如下：

各字段说明如下：

发送消息

调用CoreStone API 接口即可，详情见「发送Socket.io 消息」。

全域广播

调用CoreStone API 接口即可，详情见「发送Socket.io 全域广播消息」。

在特定操作执行成功后，会触发WebHook，并向在AccessKey 列表中注册的WebHook URL 发送HTTP POST 请求。

一个典型的WebHook 的请求体如下：

{
  "isEcho": false,
  "event" : "team.added",
  "from": {
    "socketIOClientId": "XXXXXXX-XXXXXXXXXXXX",
    "accountId"       : "acnt-XXXXXXXXXXXXXXXXXXXXXX",
    "namespace"       : "default",
    "teamId"          : "team-XXXXXXXXXXXXXXXXXXXXXX",
    "authTokenId"     : "csat-XXXXXXXXXXXXXXXXXXXXXX",
    "authTokenMarker" : "web"
  },
  "data": {
    "id"       : "team-XXXXXXXXXXXXXXXXXXXXXX",
    "name"     : "上海驻云",
    "email"    : "postmaster@jiagouyun.com",
    "telephone": "02100000000",
    "mobile"   : "18000000000",
    "industry" : "云计算",
    "country"  : "中国",
    "province" : "上海",
    "city"     : "上海市",
    "district" : "云计算浦东新区",
    "address"  : "张江创新园",
    "zip"      : "200000"
  }
}

各字段说明如下：

注：当某个业务系统调用本系统某些接口触发Webhook 之后，Webhook 请求有可能又会发送到同一个业务系统，这被称为「回声」

注：from字段主要在客户端通过Socket.io触发事件时，填入客户端的详细信息。如本事件为系统内触发，则本字段保持为null

注：具体数据包格式见下文

触发来源

各字段说明如下：

注：Socket.io 客户端触发的事件，事件命名一定为`socketio.`格式*

登录账号

登录账号已新建

触发事件：account.added

数据包结构：

登录账号已修改

触发事件：account.modified

数据包结构：

登录账号已切换默认登录团队

触发事件：account.defaultTeamSwitched

数据包结构：

团队

团队已新建

触发事件：team.added

数据包结构：

团队已修改

触发事件：team.modified

数据包结构：

团队已新增登录账号

触发事件：team.accountsAdded

数据包结构：

团队已修改登录账号

触发事件：team.accountsModified

数据包结构：

团队已删除登录账号

触发事件：team.accountsDeleted

数据包结构：

本系统除了通过传统HTTP请求发送Webhook数据外， 同时支持通过Kafka发送Webhook数据。

由基础系统发出的Webhook数据，都会发往basis主题， 同时，为了保证接收方能够按照顺序接受到消息，所有的消息都会发往0号分区。

通过Kafka发送的Webhook数据与传统HTTP请求发送的Webhook相同，但不会有isEcho字段。

详细对接文档请参考 301.06-Kafka 对接说明

注意：基础系统只负责通过Kafka发送Webhook数据，本身并不接收任何Kafka消息。

注意：基础系统并不强制要求业务系统接入Kafka，如何使用请根据实际情况决定。

注意：基础系统同时会以传统HTTP方式和向Kafka发送Webhook数据， 为了避免重复接受消息，业务系统在切换为Kafka之后，必须删除本系统中有关Webhook URL的配置。