# AECORE SP入驻手册（含服务调用全流程）

2020-07-07 联系人 廖波涛(liaobt@glodon.com ) 刘卓(liuz-l@glodon.com)

[toc]

# 名词解释

  • AECORE Architecture, Engineering & Construction Core 是建筑，工程，结构的简称，AECore代表了平台为建筑领域提供基础行业服务应用的理念
  • SP Service Provider 服务提供者
  • ISV Independent Software Vendors 这里指应用开发者

# SP服务注册

# 第一步：服务信息注册

要想将您的服务所具备的通用业务能力共享出来，首先需要以SP的身份完成注册。

1）填写服务基本信息；

2）选择开放的服务类型；

# 具体操作

1）登录AECORE，导航栏选择并进入服务管理，填写服务基本信息。

说明

SP注册当前仅面向广联达公司内部员工开放，若要使用，请使用公司邮箱注册广联达账号登录AECORE

  • 登录

  • 选择服务管理

  • 点击：注册技术产品

基本信息包括：

技术产品名称、英文标识（全局唯一，用于标识服务，请起有意义的名称）、技术产品简介、联系人邮箱与电话，选择服务类型（本节主要讲述API类型服务）

2）填写API服务类型信息

字段说明：

AppKey：

1）如果已经有从用户中心获取的appkey，请输入appkey；

2）如果是第一次注册为服务，并且没有appkey，可以选择系统创建；

Resourceid：

服务资源标识，全局唯一，可=技术产品英文标识，用英文命名一个可读的信息，如GDoc、BIMFACE等。

如原来已经在用户中心拥有resourceid，请直接填写。

服务开通通知地址：

开发者通过AECORE开通服务后，如果需要AECORE通知，请填写回调通知地址。回调url定义：查看文档

服务开通限制类型：

1）应用级：以appkey级别开通，即服务开通只以appkey为维度；

2）用户级：只允许userid对应的一个appkey开通（目前BIMFACE为这类）。

点击提交完成服务基本及类型信息注册。此时服务已具备checktoken的能力，接下来讲述如何将接口注册到AECORE的统一网关上。

# 第二步：API接口注册

API接口注册步骤：

1）环境注册；

2）API接口注册；

3）定义服务scope（选做，不定义scope即服务所有资源向订阅应用开放）；

# 具体操作

1）环境注册——创建服务环境。完成API类型信息提交后，系统默认进入到API管理-环境管理配置页

字段说明：

服务名称： 即技术服务的中文名称，如果是多个微服务，可创建多个服务环境；

如：消息服务-短信推送；消息服务-邮件推送；消息服务-企业微信推送

环境： 即API对应的服务环境，当前支持配置接口对应的：正式、测试、预发布环境；

ResourceId： 服务资源的英文标识。根据自身需求，不同环境可以设置不同的Resourceid；

Appkey： 填写不同环境resourceid对应的appkey信息

AppKey来源： 选择手动填写appkey对应的用户中心的环境，注意：appkey与环境对应错误会导致验权失败。AECORE默认生成的appkey对应用户中心环境唯一，不可修改；

​ 备注：ResourceId、AppKey、AppKey来源，根据服务注册默认填充，如无特殊环境配置，不用修改

服务端点： 服务访问的地址，如：https://xxxx.glodon.com，如果是微服务的形式请写到最后的请求地址，如：https://api.glodon.com/xxx

context_path： 网关统一接口端点，即通过此端点就知道是哪个服务，建议=技术产品英文标识。

说明

关于技术产品的英文标识建议全局统一，即技术产品英文标识=resourceid=context_path（由于历史原因已经存在的服务，如果不符合，就按照实际情况填写，此处系统并未做强制限制）

2）API接口注册

  • 支持swagger导入：针对使用了swagger的java服务，可导出swagger.json，通过系统导入完成接口批量注册

  • 手动创建（根据页面引导填写）

2-1）swagger导入API操作说明

批量导入swagger，选择文件，请填写对应的服务名称（尤其是在多微服务的情况下），以便于后期根据服务名称筛选API。

通过swagger导入API增加预检功能，在导入前系统判断该API是否录入过。

api预检：

  • 若请求路径和http请求相同时，对应api状态为修改，提交后会覆盖原有API；反之为新增；
  • 新增的API系统默认选择，已存在的API若要导入由用户手动选择；
  • 覆盖原有API后，需要二次发布才生效；

2-2）手动新建API操作说明

新建API，根据页面引导操作：

3）定义服务scope

服务scope为服务权限范围，由服务负责人在scope管理页面定义，在API列表页面绑定scope与API关系（scope与API是n:n关系）

是否定义服务scope由各SP决定，不设置scope则开发者订阅该服务后所有资源都可以使用。

scope：服务的功能权限，scope与API多对多的关系

将API于scope关系绑定，可针对单个接口逐一绑定scope，也可以多选接口批量绑定

# 第三步：准备接收isv的订阅

如果您的服务不需要在isv订阅时做初始化的工具，那么可以跳过此步，但如果需要在isv订阅后为isv做一些初始化的工作，怎么办？

AECORE向SP提供了isv订阅事件的通知机制，当isv在AECORE订阅您的服务后，AECORE会向您在注册服务时所留的地址发送通知消息。

# 如何设置接收订阅通知地址

  1. 登录AECORE，进入服务管理，编辑技术服务。
  2. 在API服务信息里配置用于接收ISV订阅通知http url（此地址的接口规则详情参考订阅通知规范）。

# 订阅通知规范

AECORE在向SP发送通知事件时，为安全起见，增加了签名机制，SP通过验签证明通知是由AECORE发出的，下面说明如何找到签名时采用的签名密钥

  1. 在技术服务中详情中查看密钥
  2. 定义回调接口
    • 回调接口URL为： POST https://xxx.glodon.com/isv_subscription，（此地址为用户自定义接口，并配置到技术服务的服务开通通知地址）
    • Reuqest Body为
{
    "appCode":"appCode",
    "appkey":"appkey",
    "appName":"appName",
    "contactEmail":"contactEmail",
    "contactPhone":"contactPhone",
    "resourceId":"resourceId",
    "timestamp":"timestamp",
    "signature":"signature",
    "userId":"userId"
}
1
2
3
4
5
6
7
8
9
10
11
字段 类型 必填 描述
appCode String 是 app编码
appkey String 是 订阅的appkey
appName String 是 应用名称
contactEmail String 是 联系邮箱
contactPhone String 是 联系手机号
resourceId String 是 技术服务的resourceId
timestamp String 是 订阅的时间
userId String 是 订阅人
signature String 是 签名
  • 签名的生成方式为：

signature生成规则为：参数按照字母顺序排序，然后经过HMacSha256加密后，生成Base64编码。示例如下： Base64( HmacSha256((appCode={appCode}&appKey={appKey}&appName={appName}&contactEmail={contactEmail}&contactPhone={contactPhone}&resourceId={resourceId}&signKey={signKey}&timestamp={timestamp}&userId={userId}))) signKey为第一步获取的密钥

  • Response Body
{
    "code": "success",
    "message": null,
    "data": "null"
}
1
2
3
4
5
字段 类型 必填 描述
code String 是 回调成功、失败（success、fail
  1. 样例程序
  • 签名验证样例
//验证签名示例
@PostMapping("/callback")
public ReSPonseBean<String> callback(@RequestBody CallBackBean callBackBean) {
 
String message = SHA256Utils.sha256_HMAC(MessageFormat.format("appCode={0}&appKey={1}&appName={2}&contactEmail={3}&contactPhone={4}&resourceId={5}&signKey={6}×tamp={7}&userId={8}", callBackBean.getAppCode(), callBackBean.getAppkey(), callBackBean.getAppName(),
        callBackBean.getContactEmail(), callBackBean.getContactPhone(), callBackBean.getResourceId(),
        signKey, String.valueOf(callBackBean.getTimestamp()), callBackBean.getUserId()), signKey);
if (StringUtils.equals(callBackBean.getSignature(), message)) {
    return ReSPonseBean.success();
} else {
    return ReSPonseBean.fail("signature not true");
}
}
//CallBackBean定义
public class CallBackBean {
 
	private String appCode;
	 
	private String appkey;
	 
	private String appName;
	 
	private String contactEmail;
	 
	private String contactPhone;
	 
	private String resourceId;
	 
	private Long timestamp;
	 
	private String userId;
	 
	private String signature;
	 
	public CallBackBean() {
	}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
  • 加密工具类
//加密工具类
import javax.crypto.Mac;
import javax.crypto.SPec.SecretKeySpec;
import java.io.UnsupportedEncodingException;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.Base64;
public class SHA256Utils {
 
	public static String sha256_HMAC(String message, String secret) throws NoSuchAlgorithmException, UnsupportedEncodingException, InvalidKeyException {
	    Mac hmacSha256 = Mac.getInstance("HmacSHA256");
	    byte[] keyBytes = secret.getBytes("UTF-8");
	    hmacSha256.init(new SecretKeySpec(keyBytes, 0, keyBytes.length, "HmacSHA256"));
	    String sign = Base64.getEncoder().encodeToString(hmacSha256.doFinal(message.getBytes("UTF-8")));
	    return sign;
	}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# 第四步：为isv准备控制台

如果开发者只通过API调用就能使用您的服务，可跳过此步。

当ISV在准备使用您的服务时，需要进行一定的设置工作，或使用服务时需要页面的交互工作，这时，您可以将这部分页面集成到AECORE的ISV控制台里。AECORE将会以iframe的方式将您提供的页面嵌入进来，您的页面需要集成AECORE SSO功能，以让ISV在AECORE登录后，无缝进入到您的页面。

# 在SP的管理后台配置开发者控制台

# 为开发者控制台提供权限控制

我们为SP的开发者控制台提供了比较完备的权限管理体系。如您需要为控制台添加权限模块，可以联系我们，将您需要添加的权限信息发给我们，我们将为您的控制台添加相对应的权限

权限的示例如下：

配置完成所需的权限。当开发者开通了你们的技术服务后，添加成员时就可以为成员授予该控制台下的权限。

# 在开发控制台，基于jsonp的形式实现单点登录实现单点登录的方式

通过jsonp接口获取ticket

1、使用说明

通过jsonp获取的ticket有效期为30s，30s后自动失效。验证一次之后也会自动失效。 使用的appkey需要开通用户中心的CAS单点登录功能

2、接口定义

GET https://account.glodon.com/v3/user_ticket?service_key=${serviceKey}&callback=${callback}

3、参数说明

参数名称 参数类型 取值范围 是否必传 描述
callback string 是 回调执行的js函数
service_key string 是 应用的appkey

4、返回值

jsonp_1584069875899_41619('ST-252-tfowudYfG54PsaEnzeeh-account-test-web-service-7d554f46b9-xxspq');
1

5、调用示例

点击下载jsonp的DEMO实例

<!DOCTYPE html><html>
<head>
    <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.8.3/jquery.min.js">
    </script>
    <script>
        $(document).ready(function(){
            $.ajax({
                type: "get",
                async: false,
                url: "https://account.glodon.com/user_ticket?service_key=pkiz5Q73uTaJYKo3kzDd6CIrYECOhVxm",
                dataType: "jsonp",
                jsonp: "callback",
                jsonpCallback:"my_callback",
                success: function(data){
                    console.log("ticket:"+data);
                    /**
                     * 在发送ajax请求到自己业务系统，并传递ticket。
                     * 业务系统后台调用用户中心验证ticket，成功返回用户信息
                     * */
                }
            });
        });
    </script>
</head>
<body>
</body>
</html>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

ticket有效性检查

1、使用说明

验证cas登录成功后，ticket（ST）验证，返回用户信息和 accesstoken，返回json数据。 如需返回access_token，请联系负责人开通权限 返回用户accessToken有效期为7天，建议缓存，该accessToken是获取用户信息和业务操作的凭证。需要业务线妥善保管，防止泄露。例如：不要将accessToken放在url

2、接口定义

GET/POST account.glodon.com/v3/api/serviceValidate

3、参数说明

header

参数名称 参数值 取值范围 是否必填 描述
Authorization Basic **** 是 Basic后面为Base64(appkey:secret)
Content-type application/x-www-form-urlencoded

form

参数名称 参数类型 取值范围 是否必填 描述
service_key string 是 appkey
ticket string 是 cas生产的ticket，有效期30s，且仅一次有效

4、返回值

{
        "user": { //用户信息
            "id": 6298824699712676770, //用户id
            "fullname": "18791489712@163.com", //用户昵称
            "username": null, //用户登录名
            "email": "18791489712@163.com", //用户登录邮箱
            "mobile": null, //用户登录手机号
            "globalId": "6298824699712676770", //用户GlobalId
            "gender": "m", //性别 ：m 男  f 女  以及null值
            "birthday": "2018-01-01",//生日 
            "qq": null, //QQ号码
            "company": null, //公司名称
            "avatarPath": [ //用户头像，4种不同的分辨率
                "https://account.glodon.com/avatar/show/6298824699712676770/32",
                "https://account.glodon.com/avatar/show/6298824699712676770/48",
                "https://account.glodon.com/avatar/show/6298824699712676770/120",
                "https://account.glodon.com/avatar/show/6298824699712676770/200"
            ],
            "avatarETag": "1605d4a79db3a5c39a5e05549f06560f", //裁剪之后图片的md5值,用于判断头像是否有更新
            "displayName": "18791489712@163.com",//用户显示名称，显示优先级：昵称>用户名>邮箱>手机号
            "strId": "6298824699712676770", //用户id字符串，防止浏览器自动截取
            "nickname": null,//昵称 同 fullname
            "accountName": "18791489712@163.com", //用户账号 显示优先级：昵称>用户名>邮箱>手机号
            "createTime": 1501756834000,//用户创建时间戳
            "passwordStrength": 1, //密码强度，0：未设置 1：弱 2：中 3：强
            "passwordMobile": null, // 密保手机号
            "verified": true, // 用户是否可用
            "mobileVerified": false,//是否绑定手机号
            "emailVerified": true, //是否绑定邮箱
            "enterpriseUser": false,//是否为企业账号
            "defaultAvatar": true //是否是默认头像
        },
        "accessToken": "9a3aaaa4-47a0-4e1a-9597-c5d3ca753485"// accessToken
    }
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

# 开发者控制台sso接入后页面超时前端跳转问题解决方案

当用户长时间未操作界面导致登录超时后，请通过postMessage，将{type:'setTimeout'}传出，aecore监听后会跳转回登录页。

window.parent.postMessage({type:'setTimeout'}, '*')
1

# 第五步：编写并发布文档

为帮助开发更好的使用服务，所有服务上线需要提供：

SP文档包含：

  • 产品介绍；
  • 快速启动（如何对接本服务、最小demo示例、demo示例用到API或控制台操作说明）；
  • API文档；
  • SDK文档；

AECORE提供文档编写模板，统一以md编写文档，文档模板是基础要求的内容，各个SP可不断扩充。

API类服务文档规范可参考：API类服务doc_demo

如果本服务即提供API接口又提供控制台页面操作，可根据SP文档模板混合使用。

# 第六步：服务发布

服务注册步骤完成后，等待AECORE管理员在后台审核并发布服务。服务发布后即会出现在ISV控制台，所有的开发者可以通过AECORE调用该服务。

# 接收isv调用

当ISV来调用时，我如何知道是哪个ISV调用了我的服务？

因为ISV是带着OAuth2 token通过AECORE网关apigate.glodon.com来调用SP服务的，所以，AECORE能够从token中识别出来ISV的身份，将识别出来的身份信息放入到http header "x-token-info"中发向SP服务。

x-token-info以json格式存储ISV身份信息，字段说明如下

{
	"scope": [],
	"exp": 1594637537,
	"resource_ids": [],
	"client_authorities": [
		{
			"authority": "ROLE_RESOURCE"
		},
		{
			"authority": "ROLE_CLIENT"
		}
	],
	"client_name": "test-app", //isv应用名称
	"client_id": "YBOiBzRKS2jqkXbYEAhrWYV9qDw0kWw1", //isv的appKey
	"oauth_client_id": "isv-Bhavhi78KT"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# 模拟isv调用服务

# 第一步：创建应用

登录AECORE创建应用，若已经登录，导航栏切换至应用开发即进入ISV控制台

创建应用

# 第二步：订阅服务

应用创建成功后，即进入应用详情页，在应用详情页内选择该应用需要订阅的服务。选择我们刚发布的服务，立即开通。

若服务设置了scope权限，那么开通服务时需要选择所需的服务权限，授权后调用才生效（scope授权在SP工作台-授权管理页面操作）；

若服务未设置scope权限，那么开通后应用可使用服务的全部资源

服务scope设置可查看

1）在全部产品与服务里选择需要开通服务

2）点击立即开通，实现服务订阅

3）针对有scope的权限的服务，订阅后需要选择并开通scope授权

备注：ISV订阅服务并申请scope权限后，SP在哪里审核通过呢？

SP服务审核，在SP工作台-服务授权管理-待审批授权。

具体操作：

3-1）通过导航栏切换至服务管理

3-2）进入服务工作台，选择服务授权-待处理授权（以图像服务测试为例）

4）服务开通后进入服务控制台（以图像服务测试为例）

AECORE为所有服务提供了控制台标准页，对于没有自定义控制台的服务，开通后默认进入该页面；

若有自定义控制台的服务，开通后默认进入该服务的控制台，如图2：短信邮件为例；

# 第三步：调用服务

根据SP提供的文档，拿订阅该服务的appkey和appsecret获取token调用该服务。

AECORE提供了临时token功能，方便测试使用，真实调用请查看获取AccessToken

临时应用token获取如图：

← 运营服务操作手册 →

  • 在线客服

  • 意见反馈