# 接口管理
## 1.接口定义
#### 菜单路径
接口管理/接口定义
#### 功能描述
接口的透明转发，在接口定义中定义不同的接口，HAP 将这些接口统一以/r/api的方式暴露出来，请求参数和返回内容的数据统一为json数据格式，开发人员需要将请求的json数据转换为接口实际需要的数据格式。
#### 使用说明

目前框架支持SOAP,REST,PLSQL三种类型的接口透传服务，
下面以查询指定城市天气为例，进行配置说明。

http://www.webxml.com.cn/WebServices/WeatherWebService.asmx?op=getWeatherbyCityName

### `REST`

1.定义系统接口信息，注意系统名称做了唯一性验证，如下图

![add](/assets/addInterface.png)

> 映射类需由开发人员编写，负责将用户请求的JSON数据转换为第三方接口实际需要的数据格式，将第三方接口返回的数据转换为JSON数据格式返回给调用者

> 映射类需要继承HapTransferDataMapper抽象类，可以参考com.hand.hap.intergration.util.ExampleMapper作为样例

>  `注意` 对于SOAP类型的接口，默认进行xml到json的数据转换，不需要配置映射类， 对于PLSQL的调用，目前不支持映射类的配置。
对于GET方式的REST类型的接口调用，框架也做了参数的自动处理。所以一般情况，编写的映射类，是用于处理POST请求的REST接口参数转换问题。比如案例，查询天气的第三方接口，仅支持`application/x-www-form-urlencoded`的报文格式，所以需要手动将调用者以json形式传入的参数，转换为天气接口可以处理的格式(theCityName=string)，当然映射类也需要对返回的数据进行转换，由于接口透传统一将返回内容以json格式返回，所以需要将第三方返回的数据转换为json数据。

2.定义该系统接口下具体的接口服务，如下图

![addLine](/assets/addInterfaceLine.png)

最终调用的地址是系统地址与接口地址拼接而成，用户可以访问 {具体的项目地址}/r/api?sysName={sysName}&apiName={apiName}&access_token={access_token}

> 通过请求参数sysName、apiName和access_token调用第三方接口(sysName是系统代码，apiName是接口代码)

> 注意因为oauth2验证，需要获取access_token,获取方式为: {项目地址}/oauth/token?client_id=client2&client_secret=secret&grant_type=password&username=admin&password=admin
具体的client_id与client_secret见：接口管理/客户端管理

此时请求的参数，必须为json数据格式，具体请求格式与请求地址见下图

![addLine](/assets/exampleAPIRestInvoke.png)

### `SOAP`

1.定义系统接口

![addLine](/assets/exampleAPISoap.png)

关于SOAP报文，天气查询服务提供的报文格式为
```xml
<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
  <soap12:Body>
    <getWeatherbyCityName xmlns="http://WebXml.com.cn/">
      <theCityName>string</theCityName>
    </getWeatherbyCityName>
  </soap12:Body>
</soap12:Envelope>

```
用户请求时动态改变的是theCityName，所以需要配置前缀为```<theCityName>```之前的部分，后缀为```</theCityName>```之后的部分。
theCityName则由接口调用者传入，框架会自动根据前后缀和参数生成完整的报文进行请求。

2.定义具体的接口服务

![addLine](/assets/exampleAPISoapL.png)


SOAP接口的调用地址和REST类型的接口一样，修改sysName和ApiName即可，所以对于用户来说，不需要知道究竟是用什么方式请求的第三方服务，按照参数规范调用即可。

## 2.接口调用记录
#### 菜单路径
接口管理/调用记录
#### 功能描述
提供入站请求和出站请求的调用监控。
#### 使用说明
通过UI界面，可以通过接口名称、接口地址、时间限制等条件查询接口调用的记录。

![addLine](/assets/exampleShowInterfaceIn.png)

![addLine](/assets/exampleShowInterfaceOut.png)

>在每个被记录的请求的具体信息中可以查看到接口返回的内容或是错误信息。

对于restful风格请求的监控，可以在想要监控的URL服务对应的具体方法上加HapInbound注解实现监控。
> 参考com.hand.hap.intergration.controllers.HapApiController
HapInbound的属性apiName。

对于webService请求的监控，是通过CXF的feature来实现的，支持cxf客户端和服务端的调用监控。

>  spring/applicationContext-cxf.xml里的如下配置，开启全局的feature。

```xml

<!--ws的调用记录feature--><bean id = "hapInvokeFeature" class="com.hand.hap.intergration.ws.feature.HapInvokeFeature"></bean><cxf:bus> <cxf:features> <ref bean="hapInvokeFeature"></ref> </cxf:features></cxf:bus>


```



