API 数据源

API 数据源将 HTTP 或 HTTPS 接口返回的数据映射为 AIR 基础视图（PDS），可在 SQL 中查询，并与其他数据源的表进行关联。每张 API 表分别配置主请求、结果解析和数据刷新；主请求需要动态 Token 或业务参数时，可增加前置操作。

创建 API 数据源

1. 进入“数据源”，点击“新建数据源”，选择“API”。
2. 填写数据源名称、描述，按需配置额外参数和投影更新，点击“创建”。通用设置见数据源。
3. 打开数据源下的目标文件夹，例如默认的 default，点击“新建 API 数据”。

数据源用于组织 API 表，具体业务接口地址在“新建 API 数据”时填写。

新建 API 数据

创建流程依次为：基础信息 → API 连接配置 → 解析请求结果 → 数据刷新配置。

在“基础信息”中填写表名称和描述。表名称以字母开头，由字母、数字或下划线组成，并满足页面的唯一性校验。

配置主请求

在“API 连接配置”中选择 GET 或 POST，填写完整的 HTTP 或 HTTPS 地址，再按目标接口要求配置以下内容。

配置区域	使用方式
参数（Params）	填写查询参数。请求地址中的查询参数会同步到参数列表，列表修改也会反映到地址中
请求头（Headers）	选择常用请求头或填写自定义名称，如 Content-Type、Authorization
请求体（Body）	支持 form-data、json、xml，按接口要求填写内容及对应的 Content-Type
权限认证（Authorization）	支持无认证、用户名密码、Token、OAuth 2.0；按接口要求选择并补充相应信息
前置操作	先请求其他接口并提取动态参数，供主请求引用，详见下文

不是每个区域都需要填写。主请求只配置目标接口要求的参数；使用前置操作返回的动态 Token 时，按下文示例填写请求头。

分页参数

分页请求可在参数或请求体中使用 ${PageIndex}，默认从第 1 页开始；使用 ${PageIndex:2} 可指定从第 2 页开始。实际参数名称按目标接口填写，例如 page 或 pageIndex。

GET 示例：在“参数”中填写 page，值为 ${PageIndex}。POST JSON 请求体示例：

{
  "page": "${PageIndex}",
  "pageSize": 100
}

若目标接口要求数字类型，可使用不带引号的占位符，使替换后的内容符合接口格式。分页还需要与响应解析中的总页数等信息配合，不能只配置请求页码而忽略响应结构。

前置操作

前置操作用于在获取业务数据的主请求之前，先调用其他 API，并将响应中的字段提取为动态参数，供主请求使用。例如：先调用认证接口获取 Token，再携带 Token 查询业务数据；或先获取业务标识，再将该标识传入数据查询接口。

执行流程为：发送前置请求 → 从响应 JSON 中提取动态参数 → 替换主请求中的 ${参数名} → 发送主请求 → 解析主请求返回的业务数据。前置请求的响应用于提供参数，API 逻辑表的数据来自主请求的响应。

配置前置请求

1. 在“新建 API 数据”的“API连接配置”中，切换到“前置操作”，点击“新增前置请求”。
2. 填写“请求名称”和“请求地址”，选择 GET 或 POST，并按目标接口要求配置参数、请求头、请求体及权限认证。
3. 点击“测试请求”，在“测试响应”中查看接口返回的 JSON，确认需要提取的字段及其所在层级。
4. 在“动态参数”中填写“参数名”和“结果字段路径”；如需提取多个字段，点击“新增动态参数”。
5. 点击“确认”保存前置请求，再到主请求的参数、请求头或请求体中引用这些动态参数。

配置项	填写说明	示例
请求名称	用于识别前置请求；支持中英文、数字和下划线，不超过 100 个字符，同一 API 数据配置中不能重复	获取访问令牌
请求地址	填写完整的 HTTP 或 HTTPS 地址，并选择接口要求的请求方式	POST https://example.com/auth/token
参数名	保存提取结果的变量名称，此处只填名称，不带 ${}；同一 API 数据配置内所有前置请求的动态参数名不能重复	access_token
结果字段路径	使用 JSONPath 从前置请求的响应中定位字段；$ 表示响应根节点	$.data.token

每个前置请求至少配置一个动态参数，每条动态参数的名称和结果字段路径都必须填写。建议参数名使用字母、数字和下划线，例如 access_token、tenant_id，避免使用系统参数名 PageIndex、PageSize、ACCESS_TOKEN。

示例：提取 Token 并在主请求中使用

以下地址和返回内容仅用于说明配置方式，实际使用时请替换为目标系统的接口和字段。

第一步：配置并测试前置请求。

假设认证接口为 POST https://example.com/auth/token，按接口要求填写认证信息后，点击“测试请求”，得到如下响应：

{
  "code": 200,
  "data": {
    "token": "<token>",
    "tenantId": "tenant_demo"
  }
}

第二步：将返回字段保存为动态参数。

在该前置请求的“动态参数”中添加两行：

参数名	结果字段路径	提取结果
access_token	$.data.token	响应中 data.token 的值
tenant_id	$.data.tenantId	tenant_demo

图中为配置示例，尚未发送测试请求；实际使用时先通过“测试响应”核对返回字段。

“参数名”是自己定义的变量名称，不必与响应字段名一致。例如，将响应字段 token 保存为 access_token 后，主请求应引用 ${access_token}，而不是 ${token} 或 ${data.token}。

第三步：在主请求中引用动态参数。

假设业务数据接口为 GET https://example.com/orders，需要通过请求头携带 Token，并通过查询参数指定租户，配置如下：

主请求配置位置	参数名称	参数值
请求头（Headers）	Authorization	Bearer ${access_token}
参数（Params）	tenantId	${tenant_id}

本例中，主请求的“权限认证”选择“无认证”，由手工配置的 Authorization 请求头携带 Token。Bearer 与 ${access_token} 之间保留一个空格；如果目标接口要求其他格式，以该接口的要求为准。

执行时，AIR 会将 ${access_token} 替换为认证接口返回的 Token，将 ${tenant_id} 替换为 tenant_demo，再发送业务数据请求。引用名称区分大小写，必须与“动态参数”中配置的参数名一致。

如果业务接口使用 POST 并要求在 JSON 请求体中传入租户，可改为在主请求“请求体（Body）”中选择 json，填写：

{
  "tenantId": "${tenant_id}",
  "status": "OPEN"
}

同时按接口要求配置 Content-Type: application/json。主请求的 form-data 参数值和 XML 请求体也支持 ${参数名} 引用。请选择目标接口要求的位置传参，不需要在所有位置重复填写。

第四步：测试完整流程并配置结果解析。

保存前置请求和主请求配置后，点击主请求的“测试连接”，验证前置请求、字段提取和主请求调用是否成功。测试通过后点击“下一步”，按主请求返回的业务 JSON 配置字段或解析脚本，并预览数据。

前置请求窗口中的“测试请求”用于查看该请求的响应，不代表动态参数提取及主请求已经验证通过。修改结果字段路径或主请求中的引用后，应重新执行主请求的“测试连接”。

结果字段路径与使用注意事项

前置响应结构示例	结果字段路径	说明
{"token":"<token>"}	$.token	提取根节点的 token
{"data":{"token":"<token>"}}	$.data.token	提取嵌套对象中的 token
{"data":[{"id":"item_001"}]}	$.data[0].id	提取数组中第一个对象的 id，数组下标从 0 开始

• 提取单个值。 建议路径定位到字符串、数字等单个值。主请求中的占位符按文本替换，不能将对象或数组的提取结果视为自动展开的 JSON 请求体；使用 JSON 或 XML 时，应保证替换后的内容符合接口格式要求。
• 字段必须存在且非空值。 前置响应不是有效 JSON、路径无法匹配或提取结果为 null 时，流程会报错，主请求不会继续发送。先检查“测试响应”，再修正结果字段路径。
• 认证字段的填写位置。 前置操作生成的动态参数可用于主请求的参数、请求头和请求体；“权限认证”中的 Token、用户名、密码等配置项不支持这种动态参数替换。需要动态 Token 时，按上例配置 Authorization 请求头，并选择“无认证”，避免认证配置覆盖该请求头。
• 多个前置请求。 多个前置请求按配置列表顺序执行，提取结果汇总后供主请求使用。目前不支持在后一个前置请求中引用前一个前置请求生成的动态参数。
• 执行次数。 前置操作在发送主请求前执行，并非仅在创建 API 数据时执行一次；分页读取时，也会在各次主请求前执行。请结合接口调用频率限制配置前置请求。
• SQL 查询。 由前置操作生成的参数不需要再通过 SQL 的 where 条件传入。例如，本例的 access_token 和 tenant_id 由前置请求提供；其他需要由查询传入的动态参数，仍按“API逻辑表查询”中的说明配置。

测试连接与解析请求结果

点击主请求的“测试连接”会实际调用接口。配置了前置操作时，会先执行前置请求、提取动态参数，再发送主请求。测试通过后点击“下一步”，在“解析请求结果”中配置业务数据字段。

表单模式

从响应结构中勾选要使用的字段，设置 AIR 中的字段名称与数据类型，并预览数据。检查是否选中了业务记录所在层级，避免把响应状态码、消息等包装字段误当作业务数据。

脚本模式

对于需要自定义解析的响应，可切换到脚本模式，使用 Groovy 脚本读取 jsonText，输出字段和数据行。以下为分页接口的响应示例：

{
  "data": [
    {"id": 1, "name": "item_1"},
    {"id": 2, "name": "item_2"}
  ],
  "rowCount": 10,
  "totalPages": 5
}

对应解析脚本：

import groovy.json.JsonSlurper

def result = new JsonSlurper().parseText(jsonText)
fieldList = ["id", "name"]
dataRows = result.data.collect { item ->
    fieldList.collect { key -> item[key] }
}
rowCount = (long) result.rowCount
totalPages = (long) result.totalPages

变量	作用
jsonText	主请求返回的原始响应文本，是脚本的输入
fieldList	输出字段名列表
dataRows	输出数据行；每行的值顺序必须与 fieldList 一致
rowCount	分页结果的总记录数，按实际响应提取
totalPages	分页结果的总页数，按实际响应提取

示例仅适用于上述响应结构。应根据实际接口修改路径、分页信息及字段，并在界面中检查字段类型与预览结果。

数据刷新配置与创建

结果解析完成后点击“下一步”，进入“数据刷新配置”，按业务需要配置更新策略，再点击“创建”。创建后检查基础视图的字段和数据，并通过工作簿执行小范围查询。

接口认证、参数或返回结构发生变化时，应同步修改 API 表配置，重新测试连接和解析结果。使用投影时，还需检查投影的刷新结果。

API 逻辑表查询

如果 API 请求参数中配置了动态参数，例如参数值为 ${name}、${c1}、${c2}，可以在 SQL 的 where 条件中使用等值条件传入参数值。查询执行时，AIR 会识别这些条件，并在请求 API 时将参数值替换到对应的 HTTP 参数中。

单组参数查询示例：

select *
from api_catalog.default.api_table
where name = 'alice'
  and c1 = 'a'
  and c2 = 'x';

如果需要查询多组动态参数组合，建议使用 union all 拆成多条等值查询，每个分支表示一组 API 请求参数：

select *
from api_catalog.default.api_table
where name = 'alice'
  and c1 = 'a'
  and c2 = 'x'

union all

select *
from api_catalog.default.api_table
where name = 'alice'
  and c1 = 'a'
  and c2 = 'y'

union all

select *
from api_catalog.default.api_table
where name = 'alice'
  and c1 = 'b'
  and c2 = 'x'

union all

select *
from api_catalog.default.api_table
where name = 'alice'
  and c1 = 'b'
  and c2 = 'y';

说明：

• 动态参数条件建议使用 = 等值表达式。
• 不支持使用 or 拼接 API 动态参数条件；如需表达多组参数组合，请按上例使用 union all。
• 如果 API 配置了前置请求，并由前置请求结果生成动态参数，这类参数不需要在 SQL 中传入。