应用开发

本章主要介绍应用托管边缘集群中需要的应用改造和相关的操作流程。

1. 对接说明

应用开发对接分为：操作系统适配、OAuth对接、数据模型对接、服务模型对接、LinkEdge对接、LinkVisual对接、其他平台相关的组件对接。其中，“操作系统适配”是必须项，其他均为可选项，根据使用场景和项目总体设计方案而定

• 操作系统适配：目前平台基于CentOS 7.6构建，因此应用在对接前，请先确保能够在此操作系统上正常运行，否则应用需要做适当适配；

• OAuth对接：通过边缘集群控制台，直接访问应用内部，无需重复登录；

• 数据模型、服务模型对接：通过集成工作台，对接领域服务；

• Link IoT Edge对接：云端指令下发边缘集群，LE平台会将指令转发至某一组设备；

• LinkVisual对接：边缘集群内部调用功能算法与图像处理；

  2. OAuth对接

  2.1 业务代码改造

1. 系统应用环境变量中获取访问域名。System.getenv(“iot.hosting.api.domain”)

2. 应用跳转IoT oauth验证地址，同时携带认证后跳转的callback地址

3. IoT认证后，携带授权码oauthcode跳转第2步callback的地址

4. 应用获取到oauthcode后可以换取accesscode，并通过accesscode获取到用户的完整信息

调用流程

接入流程

1. 获取部署应用的免登地址应用通过API发送请求，获取部署在边缘集群内部应用的免登地址url。请求格式及示例具体参考文档：边缘集群免登开发文档

http://30.42.82.42:32187/api/console/app/get?appKey=28135051

1. 获取部署应用的host请求地址应用通过API发起请求，获取部署在边缘集群内部应用的请求host。请求格式及示例具体参考文档：边缘集群免登开发文档

http://30.42.82.42:32187/api/console/host/account

3.应用请求发起用户通过在应用免登地址配置时的默认地址来发起浏览器访问，应用需要判断当前请求需要进行IoT OAuth2免登IoT在验证当前用户合法后，将生成当前用户授权码oauthcode，在回跳redirect_uri地址时通过GET方式传递oauthcode，并同时返回state

2.2 请求格式及示例

具体参考文档：边缘集群免登开发文档

http://30.42.82.42:32187/oauth2/auth? 
 redirect_uri=http://30.42.82.42:32187/index&
 client_id=28135051&state=28135051&
 response_type=code

2.3 入参说明

2.4 出参列表

返回结果示例

http://30.42.82.42:32187/index?code=64a67ee15534defea7ad0d0535189b24&state=28135051

1.通过oauthcode换取accessToken接口获取OAuth授权code后可通过该接口获取accessToken身份信息。具体参考文档：边缘集群免登开发文档2.通过accessToken换取用户信息获取accessToken信息后，可通过accessToken来换取登录用户的用户信息。具体参考文档：边缘集群免登开发文档

3. 数据模型-代码改造

数据集成标准化的目标是规范应用之间数据的传递方式和表达方式。

• 传递方式：即应用之间的数据如何流通。平台提供了对数据进行增删改查的4个API，以及HTTP2方式的消息订阅机制。

• 表达方式：即应用之间如何对数据内容有一致的理解。为了实现这个目标，需要做到如下两点，一是数据结构需要由小二后台统一管控（目前全部由小二后台录入，未来会引入审核机制）；二是应用集成对接之前（比如应用上架的时候）需要声明本应用对哪些数据模型产生什么样的数据操作（如查询、新增，或者订阅）。

  API 描述

  具体参考文档：边缘集群数据模型开发文档

1. 日期类型的参数传入格式：当前时间到格林威治时间1970年01月01日00时00分00秒的毫秒数。

2. 数量查询的一些约定：

   1. 单次查询最多返回200条数据，未指定分页参数情况下，查询返回满足条件的前200条，可根据返回参数中的hasNext判断是否有更多数据。

   2. 若需要按照指定条件返回数据总数，则指定返回参数为COUNT，API返回参数中会带有COUNT以及对应的值。

   3. 若需要按照指定条件，及按照字段分组进行数量查询，则指定返回参数为COUNT（分组字段1，分组字段2），API返回参数中会带有COUNT以及对应的值。

3. 更新删除的约定：单次操作，最多支持200条数据。

4. 运算符定义：

5.数据包括系统属性，API中不允许赋值和更新系统属性，系统属性如下：

4.服务模型-代码改造

4.1设计目标

用于规范应用之间行为表达方式和对结果的预期。

• 对于服务提供方来讲，通过服务标准化，能够清晰而简洁的表达本服务提供了哪些接口、定义、以及他们所应实现的具体功能，并且任何对该服务所提供的能力有依赖的应用，都必须按照这套接口来实现服务供应；

• 对于服务依赖方来讲，（即使用该服务的应用）能够清晰而简洁的表达他所依赖的接口有哪些，分别期望这些接口完成什么样的具体功能，并且任何为其提供服务的应用，只要遵循相同的服务模型，即可实现服务提供方的替换。

  4.2 概念定义

  对服务模型的定义，如下几点说明：

• 服务即接口。我们这里定义的服务，从概念上理解，这是一个对应用能力的抽象表达；但是从实际操作层面，服务的实际体现方式，就是RESTful风格的HTTP接口。

• 接口是分组的。分组的原则是能力原子化，即我们按照接口的能力范围，将一组完成功能闭环的接口标定为一组。并且，我们将这一组接口，定义为“一个服务模型”。

• 服务模型是受管控的。目前，每一个服务模型都是由行业小二在后台制定并发布。ISV在实践过程中可以根据实际情况，向相关小儿提出调整意见。

• 服务模型是有版本的。一个基础服务模型，随着不用ISV、不同场景的需求，会有版本迭代。因此，唯一确定一个服务模型提供的接口信息的，是模型ID+版本。

具体参考文档：边缘集群服务模型开发文档

4.3 具体对接步骤

• 系统应用环境变量中获取访问域名。System.getenv(“iot.hosting.mesh.domain”)

• 用appkey和appsecret进行鉴权和建立连接。

• 填写对应服务模型接口的参数值和API版本。

• 发送请求到iot网关路由，获取到服务模型接口返回结果。

请求示例

    /**
     * 系统环境变量中获取的
     */
    public static final String appKey = System.getenv("iot.hosting.appKey");
    public static final String AppSecret = System.getenv("iot.hosting.appSecret");
    //服务模型请求的路由
    private static final String SERVICE_EDGE__PATH = System.getenv("iot.hosting.mesh.domain");
public static void main(String[] args) throws UnsupportedEncodingException {
    IoTApiClientBuilderParams ioTApiClientBuilderParams =
      new IoTApiClientBuilderParams();
    ioTApiClientBuilderParams.setAppKey("你的<AppKey>");
    ioTApiClientBuilderParams.setAppSecret("你的<AppSecret>");
    SyncApiClient syncClient = new SyncApiClient(ioTApiClientBuilderParams);

    IoTApiRequest request = new IoTApiRequest();
    //设置api的版本
        request.setApiVer("1.0");
        request.putParam("requestId", "213123");
        request.putParam("meterNo", "213123");
        request.putParam("amount", "213123");
        request.putParam("sourceAppId", "213123");
        request.putParam("targetAppId", "213123");

        //请求参数版本,域名、path、request
        request.setVersion("1.0");

    //请求参数域名、path、request
    ApiResponse response = syncClient.postBody(SERVICE_EDGE__PATH,
      "/服务名称/接口名称", request, true);
    System.out.println( "response code = " + response.getCode()
      + " response = " + new String(response.getBody(), "UTF-8"));
}