如何创建API数据源_智能商业分析 Quick BI(Quick BI)-阿里云帮助中心

Quick BI支持通过应用程序接口（Application Programming Interface，即API），获取不同系统上的业务数据作为数据源，本文将为您介绍如何创建API数据源。

前提条件

已有API接口。

使用限制

仅专业版支持创建API数据源。
当API数据源的连接方式为直连模式时，每次请求返回的数据量应满足以下条件：不超过10MB，同时列数不超过100列，行数不超过1000行。
API数据源暂不支持跨源关联。

功能入口

您可以通过以下任一方式进入API数据源创建页面。

从创建数据源入口进入创建数据源界面，选择API数据源。
您也可以在API数据源管理界面添加API数据源。

操作步骤

新建一个API数据源主要有建立API连接、解析请求结果、数据同步设置三个步骤。

步骤一：建立API连接

您需要在此步骤中配置API连接的基础认证信息、连接方式及参数设置，具体操作说明如下。

配置基础认证下各项内容的信息。

参数名称	描述
连接名称	API接口在Quick BI数据源列表显示的自定义名称。名称由汉字、数字、字母、下划线（_）或短划线（-）组合而成。
接口地址	输入API接口的请求地址。
请求类型	选择API接口的请求类型，支持GET和POST两种类型，默认为GET。 GET：通常用于请求服务器上的资源，为数据检索行为，不能修改服务器上的数据。 POST：通常用于向服务器传输数据，例如提交表单，可以修改服务器上的数据。

选择连接方式，支持选择抽取或直连。
- 抽取：支持手动或周期性定时更新数据，适用于数据实时性要求低的场景。
- 直连：支持直连API查询，实时更新数据，适用于实时性要求高的小数据量场景。
  直连方式支持开启短效缓存，缓存时间可以选择5分钟、10分钟、30分钟。开启后，在一定时间内可避免重复发送请求，保护源端API服务访问性能不受影响，并节省API服务的调用费用。
  说明
  直连模式下，每次请求返回的数据量应满足以下条件：不超过10MB，同时列数不超过100列，行数不超过1000行。

（可选）在参数设置中配置需要传参的数据，您可以按需决定是否配置。

参数名称	描述
普通参数	请求地址后面的参数即为普通参数，格式为`url?key1=value1&key2=value2`。您可以单击添加参数，通过普通参数传参。例如，对于数据量过大的API接口，您可以通过分页的方式请求，提供一个动态参数 `${PageIndex}` 进行传参。关于参数的具体介绍请参见参数介绍。
头参数	存放在Header中的即为头参数。通常不变的量通过Header传参，支持手动增（①）删（②）改（③）Header参数。关于参数的具体介绍请参见参数介绍。
请求体	当基础认证中的请求类型为POST时，参数设置中可维护请求体信息。请求体通常用于携带用户需要向服务器发送的数据，其具体内容和格式，需要您根据当前API的字段内容自行编写。 Quick BI支持JSON、x-www-form-urlencoded两种请求体格式。 JSON：处理复杂的数据结构，适用于数据中包含嵌套对象或数组的场景。 x-www-form-urlencoded：处理简单的键值对数据，适用于表单提交的简单场景。
授权验证	您可以选择无需授权验证，也可以选择基础认证和摘要认证。具体说明请参见http认证鉴权01基本认证和摘要认证。
前置请求	如果在请求API之前，需要执行一些准备工作或验证步骤，例如：需要先通过鉴权接口拿到Token才能顺利调用当前API，此时您可以为当前API设置前置请求。设置完成后，在调用主 API 前，系统将按序执行已添加的“前置请求”。同时，支持将该请求中的响应结果存储为动态参数，引用至主 API 的头参数、普通参数、请求体，或其他前置请求中，以实现参数的动态获取。关于前置请求的使用示例，请参见操作示例。说明最多支持添加3个前置请求。

点击测试连接，成功后进入下一步。

步骤二：解析请求结果

在解析请求结果环节下的数据结构区域，会呈现当前API请求返回的所有字段，您可以根据需要选中字段并修改字段类型。

说明

抽取模式下，仅选中的参数才会同步至Quick BI系统。
每次选中字段时，必须为相同层级，否则会解析失败。
选中的字段可以在数据预览区域查看字段的值。

步骤三：数据同步设置

在数据同步设置环节中，设定API数据源的更新周期。

点击更新周期选择框，在下拉列表中，选择API数据源的更新周期，支持选择手动更新或定时更新。
说明
仅当连接设置中的连接方式为抽取时，才需配置更新周期。
- 选择手动更新，手动触发后，才会进行数据的同步。
- 选择定时更新并配置更新频率（天级或小时级）后，则每日会定时进行数据的同步。
点击完成即可创建API数据源。成功后，可以在API数据源管理界面，看到您创建的数据源。
支持在此通过单击API数据源右侧的图标编辑API数据源。
说明
不支持编辑连接方式。

参数介绍

Quick BI支持根据实际API调用要求，在普通参数、头参数中以键值对的形式自定义添加参数，以帮助API数据源的顺利接入。关于参数的介绍如下。

固定参数：参数值固定不变即为固定参数，其格式为KeyA = ValueA，例如：user=myname。
变量参数：参数值动态变更即为变量参数，其格式为KeyA = ${ValueA}，例如：mydate=${bizdate}。
Quick BI内置了丰富的变量参数，包括系统变量、系统函数等动态参数，在提供准确规范的参数编写方式的同时，方便您快速应用变量参数。关于内置变量参数的具体说明请参见下文内置变量参数。

内置变量参数

您可以点击参数值输入框右侧的图标，在唤起的变量面板中按需选择内置参数。

系统变量

目前Quick BI提供的系统变量包含日期类变量和分页类变量，其生效范围为：接口地址、普通参数、头参数、请求体、前置请求。

日期类变量

日期类系统变量由基础日期参数和时间间隔偏移两部分组成：

日期动态参数：提供基于业务日期的偏移。
- {yyyyMMdd}为业务日期，即当前更新数据日期的前一天，即T-1。
小时参数的偏移：提供基于小时的偏移。
- HH表示小时
- mm表示分钟
- ss表示秒
- 小时的偏移：delta/24
例如，在指定业务时间前1小时的表达式为：${HH-1/24}。
分钟参数的偏移：提供基于分钟偏移。
- HH表示小时
- mm表示分钟
- ss表示秒
- 分钟的偏移：delta/24/60
例如，在业务日期前1分钟：${HHmmss-1/24/60}。
暂不支持秒。

系统变量	变量说明	当前日期	实际值
${yyyyMMdd}	当前更新数据日期的前一天，即T-1。	2022-01-10	20220109
${yyyy-MM-dd}	当前更新数据日期的前一天，即T-1。	2022-01-10	2022-01-09
${yyyy-MM}	提取当前更新日期的年月部分。	2022-01-10	2022-01
${yyyy}	提取当前更新日期的年部分。	2022-01-10	2022
${yyyy/MM/dd HH:mm:ss}	提取当前更新日期，并转换为yyyy/MM/dd HH:mm:ss格式。	2022-01-10	2022/01/09 00:00:00
${HH}	提取当前更新日期的小时部分。	2022-01-10	00
${timestamp}	提取当前请求的时间戳，单位是秒	1725936000	2024-11-11 00:00:00

分页类变量

抽取模式下，API数据源支持分页请求。

说明

默认每页最多1000条，最大支持100页。
当单页返回数据超过1000条时，本次同步任务会报错并退出。
支持GET/POST请求，请求示例如下。

系统变量	变量说明	示例
${PageIndex}	代表被标记的参数为分页参数的起始页码，默认为1。	${PageIndex}默认从第1页开始获取数据。
${PageIndex:num}	代表被标记的参数为分页参数的起始页码，起始页码被指定为num。	${PageIndex:2}即会从第2页开始获取数据。

系统函数

系统函数生效范围：接口地址、普通参数、头参数、请求体、前置请求。

系统函数	函数说明	示例
BI_MD5(String data)	返回MD5加密后结果	b10a8db164e0754105b7a99be72e3fe5

动态参数

动态参数页签下仅展示在前置请求中已创建的动态参数。动态参数生效范围：接口地址、普通参数、头参数、请求体、前置请求。

操作示例

下面以接入获取钉钉用户考勤数据API数据源为例，进行创建API数据源的示例说明，旨在帮助您更好地理解并上手API数据源的新建操作。

本例按本文操作步骤中所述，分为建立API连接、解析请求结果、数据同步设置三个步骤进行。

步骤一：建立API连接

在建立API连接环节中，按以下步骤配置信息。

配置基础认证信息。
- 连接名称：本例以API接口的业务意义作为名称，填入获取用户考勤数据。
- 接口地址：在API文档页面获取其请求地址。
- 请求类型：在API文档页面获取其请求类型，本例为POST。
配置连接方式。
本例只需获取当天的考勤数据，对数据的实时性要求较低，因此连接方式选择抽取。
配置前置请求。
在调用获取用户考勤数据接口（以下称为主API接口）前，需要提前通过获取企业内部应用的access_token接口获取access_token，并将其注入在主API接口的请求地址中，才能顺利调用主API接口获取考勤数据。因此本例需要将获取access_token步骤配置在前置请求中，并将其作为普通参数拼接到主API接口的请求地址。具体前置请求配置操作如下。
1. 点击前置请求页签下的添加前置请求操作。
2. 在添加前置请求弹窗中，完成以下配置。
  - 连接名称：本例填入鉴权接口的业务意义，即获取企业内部应用的access_token。
  - 接口地址：通过接口文档获取鉴权接口的请求地址。
  - 请求类型：通过接口文档获取鉴权接口的请求类型，本例为GET。
  - 普通参数：根据接口文档，请求地址后需要携带appkey及appsecret参数，因此在普通参数中添加appkey及appsecret，并输入对应值。完成后参数将会被自动拼接到请求地址后。
  - 头参数：本例保持默认设置，即选中Content-Type为application/json，以告诉接收请求的服务器，传输数据的格式为JSON；Connection为keep-alive，以告诉接收请求的服务器，当前请求需要持久连接。
3. 点击连接测试，即可在请求结果模块中，查看当前请求的返回信息。同时，Quick BI将为您自动解析请求结果中包含的字段，您可以在动态参数模块中按需选择字段作为动态参数，并在主API中通过${参数名称}的方式进行引用；也可以仅执行前置请求而不传递动态参数（即不设置动态参数）。
  本例需要将前置请求中获取的access_token，作为动态参数传递至主API中，因此本例创建access_token动态参数。
  说明
  最多可添加10个动态参数。
配置普通参数。
本例根据主API调用要求，需要将前置请求中创建的动态参数access_token，通过${参数名称}的方式引用至主API的普通参数中，因此在普通参数页签下点击添加参数操作。
说明
动态参数支持引用至主API的普通参数、头参数、请求体或其他前置请求中，在实际操作中您可以按需选择。
填入参数名称，点击参数值输入框中的图标，在唤起的变量面板中按需选择参数，完成后点击图标保存配置。
本例需将变量面板切换至动态参数页签，在该页签下展示了当前流程中已创建的动态参数，选择${access_token}。
配置请求体。
本例请求类型为POST，因此需要根据获取企业内部应用的access_tokenAPI的请求参数内容，编写请求体。
- JSON格式示例代码如下：
```
{
    "work_date": "2024-11-14",
    "userid": "user01"
}
```
- x-www-form-urlencoded格式示例代码如下：
```
work_date=2024-11-14&userid=user01
```
其余参数配置。
本例头参数及授权验证保持默认设置。
点击连接测试，成功后进入下一步。