数据源-API源

概述

API源主要用于对接外部系统提供的API服务，将每个API映射成AIR里面的一张逻辑表，以便在AIR产品中可以对该表进行任意的SQL查询和使用，一旦一个API成功注册成一个PDS表之后，在AIR里面就跟其它任意PDS使用上无任何差异，例如可以对该表跟其它任意源中的表进行Join或者union等各类关联查询等等。

添加API数据源

首先进入“数据源”界面
选择创建API数据源 填入源的名称（只能填入英文和数字），并点击“确定”按钮

内容	说明
数据源名称	长度大于3个字符，仅允许字母、数字、下划线开头
描述（可选）	数据源的描述信息
数据源额外配置信息	连接数据源所需的额外配置信息
投影更新类型	手动更新：投影数据不进行自动更新，需要手动去更新投影数据周期更新：周期更新可以执行更新周期的类型，更新周期类型包含“月”、“周”、“日”、“小时”
数据周期	决定投影的更新是否按照强依赖策略更新
投影过期时间	永不过期：投影数据不会自动过期失效，删除投影需要手动过期删除指定过期时间：指定投影过期时间后，如果到达指定时间投影未更新，投影状态将判断为过期不可用
保存	保存后，系统会自动生成默认的二级目录“default”。

创建成功后会看到如下Catalog信息，其中系统会为每个API源创建一个默认的default的目录：

新建API数据

选择API数据源目录，点击“新建API数据”

API 基础信息

选择上面创建源下面的default目录，点击右上角的“创建API数据” 系统会进入API数据的配置界面：

内容	说明
表名称	仅允许字母、数字、下划线。字母开头。API数据源范围内唯一
描述	API数据的描述信息

API连接配置

目前AIR只能支持HTTP或者HTTPS方式的API源配置。请求地址：用户可以选择HTTP请求的类型“POST”还是“GET”，在后面输入完整的HTTP连接地址，当HTTP请求为GET类型时，请求参数会附加在URL地址中（备注：每个HTTP请求参数并非要求所有的参数项都需要配置，用户可以根据实际API的要求按需配置即可）。

内容	说明
请求地址	支持`GET` 、`POST`两种请求方式支持输入请求地址，以 http 或 https 开头请求地址中如果输入了参数，则会自动解析并在参数列表展示；同时，参数列表中的信息也会自动拼接到请求的url中
请求参数	请求参数包含参数（Params）、请求头（Headers）、请求体（Body）以及权限认证（Authorization），具体介绍见下文。

参数（Params）

内容	说明
参数值	参数值支持动态参数，格式示例${PageIndex} ，支持分页参数分页参数：分页时使用${PageIndex} 或${PageIndex:num} 表示，代表一个占位符，发送请求时会自动替换${PageIndex}代表被标记的参数为分页参数的起始页码，默认为1。${PageIndex:num}代表被标记的参数为分页参数的起始页码，起始页码被指定为num。比如：'${PageIndex:2}'即会从第2页开始获取数据。分页参数可以定义在参数中或者请求体中

请求头（Headers）

可以配置HTTP请求Header中的标准参数，也可以输入自定义的参数头：

内容	说明
参数名称	请求头参数可以从常用的参数中选择，也可以自定义常用的请求头参数：Accept、Content-Type、User-Agent、Authorization、Referer、Cookie

请求体（Body）

配置HTTP请求体（Body）的内容，目前支持三种类型“form-data”：key=value形式；“json”：{"json":""}；“xml”：

分页参数配置：分页参数配置可，如果是GET请求以在Params填写。如果是POST请求，可以把分页参数配置在Body中。

Get请求携带分页参数写法如下：

Post请求携带分页参数写法如下：

权限认证（Authorization）

权限认证支持无认证、用户名密码、Token以及OAuth 2.0 4种认证类型，配置信息如下：

上述配置信息用户根据需要配置完成后，即可点击“测试连接”来测试API配置是否正常，如果显示测试正常，则可以点击“下一步”进入API结果解析配置

测试连接

测试连接仅判断API的连通性，返回的状态码为“200”时，则测试通过

解析请求结果

解析请求结果支持表单模式和脚本模式

表单模式

支持选择字段，配置字段的名称和数据类型，进行数据预览

脚本模式

当某些API结果无法正常解析的情况下，可以选择“脚本模式”，脚本模式支持用户编写Groovy脚本来解析查询结果，通过脚本模式，理论上可以支持绝大部分类型的API结果的解析。

自定义脚本解析器：

API源的结果解析器支持用户手工编写Groovy脚本来解析复杂的API返回结果，假设API返回的结果内容如下：

{
  "data": [
    {
      "id": 0,
      "name": "name0"
    },
    {
      "id": 1,
      "name": "name1"
    },
    {
      "id": 2,
      "name": "name2"
    },
    {
      "id": 3,
      "name": "name3"
    },
    {
      "id": 4,
      "name": "name4"
    },
    {
      "id": 5,
      "name": "name5"
    },
    {
      "id": 6,
      "name": "name6"
    },
    {
      "id": 7,
      "name": "name7"
    },
    {
      "id": 8,
      "name": "name8"
    },
    {
      "id": 9,
      "name": "name9"
    }
  ],
  "code": 200,
  "message": null,
  "rowCount": 50,
  "totalPages": 5
}

可编辑如下Groovy脚本：

/*********** groovy script start ***/
import groovy.json.JsonSlurper;
import groovy.json.JsonOutput;

def jsonSlurper = new JsonSlurper();
def jsonObject = jsonSlurper.parseText(jsonText);
fieldList = ["id", "name"];
dataRows = [];
rowCount = (long)jsonObject.rowCount;
totalPages = (long)jsonObject.totalPages;
jsonObject.data.each {
    app ->
        List<Object> rowData = [];
        fieldList.each { key ->
            value = app[key]
            rowData.add(value);
        }
        dataRows.add(rowData);
}

其中Groovy脚本中的关键变量如下：

变量	变量作用	示例
jsonText	API的返回结果会存储在jsonText中，Groovy脚本可以通过该变量获取API的返回内容。	def jsonObject = jsonSlurper.parseText(jsonText);将jsonTest转换成一个对象。可通过rowCount = (long)jsonObject.rowCount;来获取API返回的rowCount值。
dataRows	用于存储解析后的结果数据，是一个对象数组，每个元素保存一行记录，数据的顺序要和fieldList的顺序保持一致。	返回对象数据的类型会通过界面用户配置的字段类型进行转换，默认为String类型。
fieldList	用于存储解析后的结果字段信息，查询引擎会读取该对象值，作为API返回结果的字段列名。

点击“创建”，出现PDS表示API映射的逻辑表创建成功。

API逻辑表查询

通过API映射的PDS查询API结果：

```// filepath: /Users/rouzhang/Desktop/AIR用户手册/my-docs/docs/数据源-API源.md

概述