# 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获取如图:

  • 在线客服

  • 意见反馈