This topic describes how to create an API data source.
Prerequisites
You have created an API interface.
Limits
The API data source feature is not supported in the international site environment.
Only the Professional Edition supports creating an API data source.
When the connection method of the API data source is direct connection mode, the data returned by each request must meet the following conditions: no more than 10 MB, with no more than 100 columns and 1000 rows.
Add an API Data Source
Log on to the Quick BI console.
Follow the steps in the figure below to add a user-created data source.
Access the data source creation interface from the data source creation entry.
Select API data source.
Alternatively, you can add an API data source in the API data source management interface.
In the API Data Connection panel, configure the following settings.
Establish an API connection.
Establish an API connection to retrieve web service data, such as CRM and ERP system data. JSON format is currently supported.
Configure the parameters under Basic Authentication.
Parameter Name
Description
Parameter Name
Description
Connection Name
The display name of the custom API interface in the Quick BI data source list.
The name consists of a combination of Chinese characters, numbers, letters, underscores (_), or hyphens (-).
Interface Address
Enter the address of the API interface.
Request Type
Select the request type of the API interface.
Supports
GETandPOSTtypes. The default request type isGET.Choose Connection Method as either Extraction or Direct Connection.
Extraction: Supports manual or periodic scheduled data updates. Ideal for scenarios with low real-time data requirements.
Direct Connection: Enables direct API queries and real-time data updates. Best for scenarios requiring high real-time data availability and small data volumes.
The direct connection method allows you to enable Short-term Cache. You can set the cache duration to 5, 10, or 30 minutes. Once activated, it prevents sending duplicate requests within a set period, thus protecting the source API service's access performance and reducing API service call costs.
In direct connection mode, the data returned by each request must meet the following conditions: no more than 10 MB, with no more than 100 columns and 1000 rows.
(Optional) Configure Parameter Settings.
In the Parameter Settings, you can view and configure the data that needs to be passed.
Parameter Name
Description
Parameter Name
Description
Common Parameter
The parameter after the request address is the common parameter.
The format is
url?key1=value1&key2=value2.You can click Add Parameter to pass parameters through common parameters. For example, for API interfaces with large data volumes, you can request by paging and provide a dynamic parameter
${PageIndex}for parameter passing. For more information, see Paging Request.
For detailed parameter descriptions, see Parameters.Header Parameter
The parameter stored in the Header is the header parameter.
Usually, unchanging quantities are passed through the Header. Supports manual addition (①), deletion (②), and modification (③) of Header parameters.
Query Statement
Optional. Pass parameters through the request body. The request body only supports JSON format input.
For example,
{"key1":"value1"}Authorization Authentication
You can choose no authorization authentication or select Basic Authentication and Digest Authentication.
For more information, see HTTP Authentication 01 Basic Authentication and Digest Authentication.
Click Test Connection. After a successful test, click Next.
In the Parse Request Result interface, the Data Structure area shows all fields from the API request. Select fields and modify field types as needed.
In extraction mode, only selected parameters will be synchronized to the Quick BI system.
When selecting fields, ensure they are at the same level to avoid parsing errors.
In the Data Preview area, view the selected fields to check the field values.
Select Update Cycle and click Finish to configure data synchronization.
The update cycle needs to be configured only when the connection method is extraction.
Select Manual Update. Data synchronization occurs only after manual initiation.
Select Scheduled Update and set the update frequency (daily or hourly). Data synchronization will proceed automatically at the scheduled time.
You can now view the created data source in the API data source management interface.
To edit the API data source, click the
icon on the right side of the API data source.The connection method cannot be edited.
Parameters
The API data source allows configuration of common and header parameters. Parameters can be static or dynamic.
Parameter Format Design
The parameter format is
KeyA = ValueA, whereKeyAis the parameter name andValueAis the parameter value.There are two types of parameters:
Fixed parameter value format, for example:
user=myname.Dynamic parameter value format, for example:
mydate=${bizdate}.For more information on dynamic parameter values, see the description below.
Dynamic Parameters
Dynamic parameters, once correctly parsed, reflect on the interface address based on the current time. You can verify the correctness of parameter configurations by checking the parsing result. Dynamic parameters include the basic date parameter and the time interval offset.
Date dynamic parameters offer two methods based on the business date and running time.
{yyyyMMdd}represents the business date, which is the day before the current data update date, T-1.[yyyyMMdd]is the running date, which is the current data update date, T. T represents the day's granularity.
Hour parameter offset: Provides offsets based on hours.
HHindicates the hour.mmindicates the minute.ssindicates the second.Hour offset:
delta/24.
For example, to indicate one hour before the specified running time, use:
$[HH-1/24].Minute parameter offset: Provides offsets based on minutes.
HHindicates the hour.mmindicates the minute.ssindicates the second.Minute offset:
delta/24/60.
For instance, to represent one minute before the business date, use:
${HHmmss-1/24/60}.Seconds are not supported for offset.
Type | Parameter Format | Parameter Description |
System Dynamic Parameter |
| Business date. The default format is For example, if the current date is 2021-12-29, then |
| Running date. The default format is For example, if the current date is 2021-12-29, then |
For details on specific time dynamic parameters, refer to the table below.
Current Date | Configuration Based on Business Date (T-1) | The Actual Value | Configuration Based on Expected Running Time (T) | The Actual Value |
2022-01-10 | ${yyyyMMdd} | 20220109 | $[yyyyMMdd] | 20220110 |
2022-01-10 | ${yyyyMMdd-1} | 20220108 | $[yyyyMMdd-1] | 20220109 |
2022-01-10 | ${yyyyMMdd-7} | 20220102 | $[yyyyMMdd-7] | 20220103 |
2022-01-10 | ${yyyy-MM-dd} | 2022-01-09 | $[yyyy-MM-dd] | 2022-01-10 |
2022-01-10 | ${yyyy-MM} | 2022-01 | $[yyyy-MM] | 2022-01 |
2022-01-10 | ${yyyy-MM-1} | 2021-12 | $[yyyy-MM -1] | 2021-12 |
2022-01-10 | ${yyyy} | 2022 | $[yyyy] | 2022 |
2022-01-10 | ${yyyy+1} | 2021 | $[yyyy+1] | 2022 |
2022-01-10 | ${yyyy/MM/dd HH:mm:ss} | 2022/01/09 00:00:00 | $[yyyy/MM/dd HH:mm:ss] | 2022/01/10 00:00:00 |
2022-01-10 | ${yyyy/MM/dd HH:mm:ss-1/24} | 2022/01/08 23:00:00 | $[HH:mm:ss-5/24/60] | 23:55:00 |
2022-01-10 | ${HH} | 00 | $[HH] | The hour corresponding to dueTime |
2022-01-10 | ${HH-1} ${HH-1/24} | 23 | $[HH-1] $[HH-1/24] | The hour corresponding to dueTime -1 |
Paging Request
In extraction mode, the API data source supports Paging Request.
Define paging parameters using the dynamic parameter format: ${PageIndex} or ${PageIndex:num}.
${PageIndex} denotes the starting page number for the parameter marked as a paging parameter, defaulting to 1.
${PageIndex:num} indicates the starting page number for the parameter marked as a paging parameter, with the starting page number specified as num. For example, '${PageIndex:2}' starts data retrieval from page 2.
Dynamic parameter parsing is supported for both GET and POST requests. For POST requests, the request body only supports parsing of first-level JSON parameters.
By default, a maximum of 1000 entries per page is allowed, with support for up to 100 pages.
If more than 1000 entries are returned per page, the current sync task will fail and terminate.
