智慧车间API接口平台介绍

1.   背景

K/3 Cloud智慧车间系统提供了一套标准的接口调用平台，通过这个平台可以查看、定义、维护和使用智慧车间对外提供的接口。

本文档旨在指导二次开发人员熟悉和了解这个平台，并利用这个平台来实现、扩展与外部系统的集成。

2.   适用对象

二次开发人员。

3.   适用范围

本平台从二次开发的角度来讲，可以在以下范围提供帮助和支持。

3.1     替换或扩展标准产品逻辑

标准产品的每个接口都有一个后台的处理器与之对应，接口的核心逻辑由后台处理器来完成。

二次开发人员根据自身的需求，可以继承标准处理器做逻辑的补充和扩展，也可以替换标准处理器，将逻辑完全覆盖。

3.2     扩展标准接口返回值

标准产品在每个接口处理器上开放了若干时点，如校验数据前/后、逻辑处理前/后，并且将这些时点封装在插件中，以便二次开发人员针对这些时点做不同的处理。

譬如，现有标准接口有些是获取后台单据的数据，将其返回到前端，目前返回的字段是固定的，而现场有时候需要返回额外的一些字段，因此，可以通过平台的自定义插件，在“逻辑处理后”时点附加自己想要的字段及其数据。

3.3     通过前台传入数据更新后台单据

标准产品有些接口的处理逻辑是对已有单据进行更新，或者生成新的单据，逻辑相对固定，而前端界面随着业务的变化可能会增加一些字段，并且需要将这些字段更新到后台单据中。

目前平台支持在前端传入扩展内容，并将其传入到接口处理器以及插件中，二次开发人员可根据需要在不同的层次上处理单据的生成以及更新逻辑。

3.4     增加自定义接口

标准产品提供的接口如果缺少对某些功能的支持，二次开发可以利用智慧车间API接口平台提供的通用接口（可参考5.1.4章通用类接口），也可以在平台中自己定义接口，具体参考5.平台介绍。

4.   平台的价值

利用智慧车间API接口平台，可以灵活定义和配置系统的各个接口。从用户的角度来看，可以带来以下几个好处：

l  增加了接口的透明度。接口的定义和接口调用过程对用户来讲是透明的，用户从平台上可以知道有哪些接口，接口由谁来处理，目前处理的状态，一目了然。

l  增加了接口的扩展能力。用户既可以替换标准产品的处理逻辑，也可以在不同的时点注册插件，对处理逻辑进行扩展。

l  掌握接口的调用情况。平台提供了接口调用日志，可以清楚地看到每次接口调用的时间、执行时长、执行结果等。

5.   平台介绍

智慧车间API接口平台是一套接口的定义和逻辑实现定义的平台，在这个平台中，贯通了从前端调用到后台处理逻辑的全过程，过程中的各个环节都提供了标准的实现逻辑，并开放适当的时点，以便于二次开发根据现场需要进行扩展。

其整体结构及调用过程如下图所示。

图5-1

如上图，前端通过WebService或WebApi发起请求，CLOUD端获取到请求之后根据配置定义，将其分发到不同的处理器中。

处理器接收到消息后，处理必要的校验和逻辑，并在不同时点通知插件进行扩展调用，将结果同步返回到前端。

对复杂的处理逻辑，处理器处理完成之后，需要发送消息到消息队列，CLOUD通过调度计划，处理消息队列中的消息。消息处理器也可以自定义，并支持插件处理。

智慧车间API接口平台包括三个层次，分别为接口层、接口处理层、后端核心处理层，在下面的章节中进行详述。  

5.1     接口层

接口层提供了对外的标准接口，外部系统可以通过这些接口获取CLOUD系统里的业务数据，并可以通过接口驱动对业务数据的逻辑处理。

目前支持两种接口调用方式，分别为WEBSERVICE和WEBAPI。这两种调用方式除了形式不一样，其调用参数、返回结果结构是完全相同的，只不过WEBSERVICE使用的是固定参数和固定返回结果，而WEBAPI使用的是JSON格式的文本，两者的后台处理逻辑是完全一样的。

5.1.1     WEBSERVICE接口方式

WEBSERVICE站点目前集成在K3 Cloud业务站点中，可按如下地址进行访问：HTTP://业务站点IP:端口/Service/SFSWebService.asmx。接口可以分为如下几类：

5.1.1.1              运行环境接口

可以获取到运行环境相关的数据，如SFS_GET_DataCenter可获得当前管理中心注册的所有数据中心。运行环境类接口不支持扩展。

5.1.1.2              系统登录接口

通过WEBSERVICE访问CLOUD站点的各种服务，必须首先登录CLOUD系统成功后才能进行合法访问，因此需要先调用SFS_Login接口，系统登录接口不支持扩展。

该接口示例如下：

图5-2

其中MacAddress为终端唯一标识，对应每台需要调用WEBSERVICE接口的终端设备。

DatacenterId为运行环境类接口SFS_GET_DataCenter返回的数据中心Id。

UserName、Password为登录Cloud站点的用户名、密码。

LocaleId为语言标识，可为空，默认为2052，即简体中文。

此接口返回登录结果信息，如果成功，则UserToken值为本次登录的标识，除运行环境类接口外，其他接口在调用时，必须要把UserToken值作为参数传入，后端会验证此参数值的合法性。

5.1.1.3              业务处理类接口

一般为数据获取和数据更新类型的接口，其参数为标准产品预置，其中比较重要的属性为3.1.2节中描述的UserToken。

另外，考虑到扩展性，大部分接口都增加了3个简单扩展参数：ExtendParam1~ ExtendParam3，以及一个复杂扩展参数：ExtendJsonParam，前者用来传入简单参数值，如单个字符串、单个数字，后者用于传入复杂结构的参数，如数组、列表，以及父子结构的数据，以JSON格式表示。

图5-3

5.1.1.4              通用类接口

通用接口主要是为了扩展业务使用，譬如从新单据中获取数据，或者要对已有单据进行新的操作处理，而这些操作从原有的接口中无法返回或处理，则需要使用通用接口。

通用接口的参数除了3.1.2中描述的UserToken外，还需要传入ApiName，此ApiName与后续3.2章节中【车间WEB接口定义】中的接口编码对应，用来定位具体的后端逻辑处理类。其他的参数则是系统预置的Param1~Param10，以及复杂参数ExtendJsonParam。

图5-4

5.1.2     WEBAPI接口方式

平台提供了WEBAPI服务类SFCWebApiService，预置Execute方法，客户端可以通过Cloud标准WEBAPI的方式进行调用，其参数以JSON格式文本进行传递，参数结构以KEY-VALUE键值对的方式，内容与WEBSERVICE完全一致。如WEBSERVICE提供了参数ScanCode，值为“001”，则WEBAPI中传递格式为{ScanCode: “001”}。

5.2     接口处理层

接口处理层主要负责对前端请求进行响应，并对传入参数进行校验和业务处理。包括车间WEB接口定义、逻辑处理器及处理器插件三个部分。

5.2.1     车间WEB接口定义

车间WEB接口定义用来定义响应前端请求的处理器及其扩展。其中比较重要的属性有以下几个：

l  接口编码：接口的唯一标识，在前端请求时，通过与传入的接口编码值进行比较，匹配后端的处理器。

l  参数类：由于处理过程的复杂性，一般会在处理器中使用内部的参数类，这样代码编写更加方便和简洁，因此建议在接口定义中维护【参数类】，这样平台在获取到前端参数后，会自动将参数值映射到对应的参数类中，而在处理器和插件中可以通过简单的标签，就可以直接使用类的实例了（后续有具体基于场景的指南文档）。而对于一些简单的接口，参数层次和个数都不多的情况下，可以不定义，平台会将参数的JSON文本传递到处理器和插件中。

l  返回结果类：其作用与【参数类】类似，只是其值是由处理器生成和返回的。对于复杂的返回结果，建议维护这个字段。

图5-5

5.2.2     逻辑处理器

处理器用来处理标准逻辑，如获取传入参数、解析参数、数据处理、返回结果等。其中主要的几个时点如下：

l  初始化：对传入参数进行简单的校验，并根据参数对处理器中的本地变量进行初始化，以方便后续时点使用。

l  校验：对输入参数进行详细的业务校验，校验失败的将返回错误信息。

l  处理：核心逻辑处理，如查询、关联取数、更新内部数据结构，并构造返回值。

5.2.3     处理器插件

插件是逻辑处理器各个时点的“楔子”，加在每个时点的前后，通过插件可以对标准逻辑进行扩充，以丰富处理逻辑并添加个性化的返回。插件有以下几个方法：

l  初始化前：处理器初始化本地变量之前，可扩充初始化逻辑。

l  初始化后：处理器初始化本地变量之后，可扩充初始化逻辑。

l  校验前：输入参数校验之前，可增加自定义的校验逻辑。

l  校验后：输入参数校验之后，可增加自定义的校验逻辑。

l  处理前：处理器核心逻辑处理前，可增加自定义的处理逻辑。

l  处理后：处理器核心逻辑处理后，可增加自定义的处理逻辑，或增加返回值的扩展。

5.3     后端核心处理层

包括消息队列和执行计划。这一层的主要目的是为了将请求的校验、响应与CLOUD底层的单据生成、处理逻辑解耦。其中消息队列用于存储接口处理层发送过来的各种指令，而执行计划则定时执行这些指令。

图5-6

而针对不同的执行指令，平台定义了相应的消息处理器以及插件，以便于二次开发进行扩展。

图5-7

其处理器与插件的作用与使用方式基本上和接口处理器类似，这里不再赘述，后续有基于场景的指南文档。