Create an API data source

Step 1: Create an API connection

In this step, configure the basic authentication, connection mode, and parameter settings for the API connection.

1. Configure the items under Basic Authentication.

   Parameter	Description
   Connection name	A custom name for the API connection. This name is displayed in the Quick BI data source list. The name can contain Chinese characters, digits, letters, underscores (_), and hyphens (-).
   API URL	Enter the request URL of the API.
   Request method	Select the request method for the API. Quick BI supports GET and POST. The default is GET. GET: Retrieves resources from a server. This method does not modify data on the server. POST: Sends data to a server, such as submitting a form. This method can modify data on the server.

2. Select a Connection Mode. You can choose either Extraction or Direct Connection.

   • Extraction: Supports manual or scheduled updates. This mode is suitable for scenarios where data latency is not critical.

   • Direct Connection: Queries the API directly for real-time data. This mode is suitable for low-latency scenarios that involve small datasets.

     For a direct connection, you can enable a short-term cache and set the duration to 5, 10, or 30 minutes. This feature prevents repeated requests within the specified time, which protects the source API's performance and reduces API call costs.

     

   Note

   • In direct connection mode, the response to each request cannot exceed 10 MB, 100 columns, and 1,000 rows.

   • Starting from version 6.0.1, when you create a dataset from an API data source in extraction mode, you can add calculated fields by using system functions.

3. (Optional) In the Parameter Settings section, configure any required parameters.

   Parameter	Description
   Query parameters	Query parameters are parameters appended to the request URL. The format is url?key1=value1&key2=value2. Click Add Parameter to pass query parameters. For example, if an API returns a large amount of data, you can make paginated requests by passing a dynamic parameter, such as ${PageIndex}. For more information about parameters, see Parameters.
   Header parameters	Header parameters are parameters stored in the HTTP request header. Values that do not change are typically passed as header parameters. You can add (①), delete (②), and modify (③) header parameters. For more information about parameters, see Parameters.
   Request body	When the Request Method under Basic Authentication is set to POST, you can configure the request body. The request body typically contains the data you need to send to the server. Its content and format must match the API's requirements. Quick BI supports two request body formats: JSON and x-www-form-urlencoded. JSON: Handles complex data structures. This format is suitable for scenarios where the data contains nested objects or arrays. x-www-form-urlencoded: Handles simple key-value data. This format is suitable for simple form submissions.
   Authorization	You can select no authorization, Basic Authentication, or Digest Authentication. For more information, see HTTP Authentication: Basic and Digest Authentication.
   Pre-request	If you need to perform preparatory tasks or validation steps before calling an API, you can set up a pre-request. For example, you might need to call an authentication API to obtain a token before calling the main API. After configuration, the system executes the added pre-requests in order before calling the main API. You can also store the response from a pre-request as a dynamic parameter and reference it in the header parameters, query parameters, or request body of the main API, or in other pre-requests. For an example of how to use a pre-request, see Example. Note You can add a maximum of three pre-requests.

4. Click Test Connection. If the connection is successful, click Next.

Step 2: Parse response

In the Parse Response step, all fields from the API response are displayed in the Data Structure area. You can select the fields you need and modify their data types.

Step 3: Data sync settings

In the Data Sync Settings step, set the refresh schedule for the API data source.

1. Click the Refresh Schedule dropdown list and select a refresh schedule. You can choose either Manual Update or Scheduled Update.

   Note

   You only need to configure the refresh schedule when the connection mode is extraction.

   

   • Select Manual Update if you want to trigger data synchronization manually.

   • Select Scheduled Update and configure a daily or hourly frequency to synchronize data automatically at scheduled times.

2. Click Finish to create the API data source. After it is created, you can see the new data source on the API data source management page.

   You can click the icon next to the API data source to edit it.

   Note

   You cannot edit the connection mode.

   

Built-in variable parameters

Click the icon to the right of the parameter value input box and select a built-in parameter from the variables panel.

System variables

Quick BI provides date variables and pagination variables. These variables can be used in the API URL, query parameters, header parameters, request body, and pre-request.

• Date variables

  Date-related system variables consist of a base date parameter and a time interval offset:

  • Date dynamic parameters: Provide an offset based on the business date.

    • ${yyyyMMdd} is the business date, which is the day before the current data update date (T-1).

  • Hour parameter offset: Provides an offset based on the hour.

    • HH represents the hour.

    • mm represents the minute.

    • ss represents the second.

    • Hour offset: delta/24

    For example, the expression for one hour before the specified business time is ${HH-1/24}.

  • Minute parameter offset: Provides an offset based on the minute.

    • HH represents the hour.

    • mm represents the minute.

    • ss represents the second.

    • Minute offset: delta/24/60

    For example, one minute before the business date is ${HHmmss-1/24/60}.

  • Second offsets are not supported.

  System variable	Description	Current date	Actual value
  ${yyyyMMdd}	The day before the current data update date (T-1).	2022-01-10	20220109
  ${yyyy-MM-dd}	The day before the current data update date (T-1).	2022-01-10	2022-01-09
  ${yyyy-MM}	Extracts the year and month from the current update date.	2022-01-10	2022-01
  ${yyyy}	Extracts the year from the current update date.	2022-01-10	2022
  ${yyyy/MM/dd HH:mm:ss}	Extracts the current update date and converts it to yyyy/MM/dd HH:mm:ss format.	2022-01-10	2022/01/09 00:00:00
  ${HH}	Extracts the hour from the current update date.	2022-01-10	00
  ${timestamp}	Extracts the UNIX timestamp of the current request in seconds.	1725936000	1725936000

• Pagination variables

  In extraction mode, API data sources support paginated requests.

  Note

  • By default, each page can contain a maximum of 1,000 items, and a maximum of 100 pages are supported.

  • If a single page returns more than 1,000 items, the synchronization task fails and exits.

  • Both GET and POST requests are supported. The following image shows an example request.

  System variable	Description	Example
  ${PageIndex}	Marks the parameter as the starting page number for pagination. The default value is 1.	${PageIndex} starts fetching data from page 1 by default.
  ${PageIndex:num}	Marks the parameter as the starting page number for pagination, where the starting page is specified as num.	${PageIndex:2} starts fetching data from page 2.

System functions

System functions can be used in the API URL, query parameters, header parameters, request body, and pre-request.

Dynamic parameters

The Dynamic Parameters tab displays only the dynamic parameters that have been created in a pre-request. Dynamic parameters can be used in the API URL, query parameters, header parameters, request body, and pre-request.

Step 1: Create an API connection

In the Create API Connection step, configure the following information.

1. Configure the Basic Authentication information.

   • Connection Name: Enter a name that reflects the purpose of the API. In this example, enter Get User Attendance Data.

   • API URL: Obtain the request URL from the API documentation.

   • Request method: Obtain the request method from the API documentation. In this example, it is POST.

2. Configure the Connection Mode.

   In this example, only the current day's attendance data is required, so data latency is not a concern. Therefore, select Extraction for the connection mode.

   

3. Configure a pre-request.

   Before calling the Get User Attendance Data API (the main API), you must first call the Get access_token for an internal application API to obtain an access_token. This token must then be included in the main API's request URL. Therefore, you need to configure a pre-request to obtain the access_token and pass it as a query parameter.

   1. On the Pre-request tab, click Add Pre-request.

   2. In the Add Pre-request dialog box, complete the following configurations.

      • Connection Name: Enter a name that reflects the purpose of the authentication API. In this example, enter Get access_token for an internal application.

      • API URL: Obtain the request URL for the authentication API from its documentation.

      • Request Method: Obtain the request method for the authentication API from its documentation. In this example, it is GET.

      • Query Parameters: According to the API documentation, the request URL must include the appkey and appsecret parameters. Add appkey and appsecret as query parameters and enter their corresponding values. The parameters are automatically appended to the request URL.

      • Header Parameters: Keep the default settings. In this example, Content-Type is set to application/json to inform the server that the data is in JSON format, and Connection is set to keep-alive to request a persistent connection.

   3. Click Test Connection to view the response in the Response section. Quick BI automatically parses the fields in the response. You can then select fields in the Dynamic Parameters section to use as dynamic parameters and reference them in the main API by using the format ${ParameterName}. You can also execute the pre-request without passing any dynamic parameters by not setting them.

      In this example, the access_token obtained from the pre-request needs to be passed as a dynamic parameter to the main API. Therefore, create an access_token dynamic parameter.

      Note

      You can add a maximum of 10 dynamic parameters.

      

4. Configure Query Parameters.

   Based on the main API requirements, the access_token dynamic parameter created in the pre-request must be referenced in the main API's query parameters by using the format ${ParameterName}. On the Query Parameters tab, click Add Parameter.

   Note

   Dynamic parameters can be referenced in the query parameters, header parameters, or request body of the main API, or in other pre-requests. Choose the option that fits your needs.

   

5. Enter a parameter name, click the icon in the parameter value input box, select the required parameter from the variables panel, and then click the icon to save the configuration.

   In this example, switch to the Dynamic Parameters tab in the variables panel. This tab displays all dynamic parameters created in the current process. Select ${access_token}.

6. Configure the Request Body.

   The request method for this example is POST. Therefore, you need to write the request body based on the request parameters of the Get User Attendance Data API.

   • The following code provides an example in JSON format:

     {
         "work_date": "2024-11-14",
         "userid": "user01"
     }

   • The following code provides an example in x-www-form-urlencoded format:

     work_date=2024-11-14&userid=user01

7. Configure other parameters.

   In this example, keep the default settings for the header parameters and authorization.

8. Click Test Connection. If the connection is successful, click Next.

Step 2: Parse response

In the Parse Response step, select the required fields, adjust their data types, and then click Next.

Step 3: Data sync settings

1. In the data sync settings step, set the refresh schedule for this API data source to Manual Update.

   

2. Click Finish to create the Get User Attendance Data API data source.