智慧车间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，前者用来传入简单参数值，如单个字符串、单个数字，后者用于传入复杂结构的参数，如数组、列表，以及父子结构