Calling an API

Prerequisites

• An API has been developed and approved.
• The API has been authorized through app authentication.
• You have set up a Java development environment by installing Java Development Kit (JDK) 1.8.111 or a later version. If you have not, download it from the official Oracle website.
• You have installed IntelliJ IDEA. If you have not, download it from the official IntelliJ IDEA website.

Notes and Constraints

• To call an API in DataArts DataService locally, you need to bind an EIP to the DataArts DataService Exclusive cluster when creating the cluster.
• When an API in DataArts DataService is called, if the total duration of query and response exceeds 60 seconds (default value), a timeout error is reported. In this case, you can optimize the API configuration based on the API calling duration recorded in the access log.

Obtaining App and API Information

1. Log in to the DataArts Studio console.

   For details, see Accessing the DataArts Studio Instance Console.

2. On the DataArts Studio console, locate a workspace and click DataArts DataService.
3. In the left navigation pane, choose an edition, for example, Exclusive Edition. The Overview page is displayed.
4. Obtain the AppKey and AppSecret of the app authorized by the API. (If multiple apps have been authorized, you only need to obtain information about one of them.)

   In the navigation pane on the left, choose Apps. Locate the app to which the API has been authorized, click the app name to access its details page, and record the AppKey and AppSecret.

   Figure 1 Recording the AppKey and AppSecret
   

5. Obtain the URL, request method, and input parameters of the API to be called.

   In the navigation pane on the left, choose APIs. Locate the API to be called, click the API name to access its details page, and record the URL, request method, and input parameters.

   The exclusive edition supports both private and public IP addresses. To use the public IP address, you need to bind an EIP to the cluster during cluster creation. If you want to call an API in DataArts DataService Exclusive locally, you need to use a public IP address to ensure network connectivity.

   Figure 2 Recording the URL, request method, and input parameters
   

Obtaining the SDK Package

1. On the DataArts DataService console, choose SDKs in the navigation pane. On the displayed page, download the Java SDK.
   Figure 3 Downloading the SDK
   

2. Verify integrity of the SDK package. In Windows, open the CLI and run the following command to generate the SHA-256 value of the downloaded SDK package. In the command, D:\java-sdk.zip is an example local path and name of the SDK package. Replace it with the actual value.

   certutil -hashfile D:\java-sdk.zip SHA256

   The following is an example command output:

   SHA-256 hash value of D:\java-sdk.zip
   96fced412700cf9b863cb2d867e6f4edf76480bc679416efab88a9e1912503b9
   CertUtil: -hashfile command executed.

   Compare the SHA-256 value of the downloaded SDK package with that provided in the following table. If they are the same, no tampering or packet loss occurred during the package download.

   Table 1 SDK packages and the corresponding SHA-256 values

   Language	SHA-256 Value of the SDK Package
   Java	96fced412700cf9b863cb2d867e6f4edf76480bc679416efab88a9e1912503b9
   Go	f448645da65b4f765d9569fc97ca45dc3e8f1ce4f79d70c5c43934318521d767
   Python	54b4984d91db641d2b1b0e77064c162850cb2511a587f95e2f8b8340e7afa128
   C#	b66caf856ffccb61fe758872aac08876aa33fb0cf5f4790e3bec163593b2cbae
   JavaScript	43da0b54d6b04d1f5ed7f278c2918c2a63a1ddb8048e2d1c5db60baafb17663c
   PHP	394c068420a3817f32d5d88b6c1632978f573f2a685e4a1d10c2f698e0f6786e
   C++	abae5473d47594f88dcd5eaa0902dc12cd6f1e3bd63c0b82d9d1fab8b4351f54
   C	a376573fe8aa3a636a6d123926ddc3dca11748b289b8c2c16a5056830a095acb
   Android	c19175d736f05b1945dab4675df19311834ede0d9b1978b11b50c86687baf85c

Calling an API Using an SDK

1. Decompress the Java SDK package and import the SDK to IntelliJ IDEA.
2. After the import is successful, open the main.java file and modify the content in the red box shown in the figure below.
   Figure 4 Modifying the main.java file
   
   • Set the method and URL for calling the API.
     If the input parameter contains the Path parameter, change the {path} variable in the calling address to a specific value. In this example, the settings are as follows:

     1 2	request.setMethod("GET"); request.setUrl("https://xx.xx.xx.xx/TestScore");

   • Set the values of the Query, Header, and Body parameters.

     Use double quotation marks and braces ("{}") to enclose the string in "Body parameter name":Body parameter value format and escape the double quotation marks ("") using a backslash (\). In this example, the body parameter is not involved. You can comment out the setBody invoking method. The method of invoking addQueryStringParam is as follows:

     • Query the scores of all examinees in the English exam.

       You do not need to transfer the query parameter. You can comment out or delete the addQueryStringParam method.

     • Query the score of an examinee.

       request.addQueryStringParam("Number", "xxxxxx");

     • Check whether an examinee passed the English exam. For example, the pass score is 425.

       request.addQueryStringParam("Number", "xxxxxx");
       request.addQueryStringParam("Score", "425");

     • Query the examinees who passed the English exam. For example, the pass score is 425.

       request.addQueryStringParam("Score", "425");

     • Sort the examinees who passed the English exam in descending order of score. For example, the pass score is 425.

       request.addQueryStringParam("Score", "425");

   • (Optional) Set values of ranking parameters.

     The system ranks the results in ascending order by default based on the ranking parameters. To change the rank, change the value of pre_order_by to Ranking parameter name:ASC (ascending order) or Ranking parameter name:DESC (descending order). Separate multiple ranking parameter descriptions by semicolons (;).

     To rank the examinees who passed the English exam in descending order of score, set the parameters as follows:

     1	request.addQueryStringParam("pre_order_by", "Score:DESC");

   • (Optional) Set pagination parameters.

     By default, the system assigns pagination data to the APIs created using configuration or a script/MyBatis. If you want to obtain specified pagination data, modify the following parameters. pageSize indicates the page size, and pageNum indicates the page number.

     You can leave them blank.

     1 2	request.addQueryStringParam("page_size", "100"); request.addQueryStringParam("page_num", "1");

     

     For APIs created using a script/MyBatis with custom pagination configuration, the pagination logic is written to the data acquisition SQL statement during API creation. Therefore, the pagination settings cannot be modified during an API call.

   • (Optional) Set the total number of returned records.

     If Return Total Records is enabled during API creation, it takes a long time to obtain the total number of data records if the data table corresponding to the API contains a large amount of data. You can control whether to calculate and return the total number of data records by modifying the use_total_num parameter. If you set it to 1, the total number of data records will be returned. If you set it to any other value, the total number of data records will not be returned.

     In this example, Return Total Records is not enabled. You can choose not to set it.

     1	request.addQueryStringParam("use_total_num", "0");

3. Set AppKey and AppSecret. Coded or plaintext AppKey and AppSecret in code pose significant security risks. You are advised to store them in configuration files or environment variables. This example takes environment variables as an example.
   Figure 5 Configuring the AppKey and AppSecret
   

4. After running the program, view the API calling result. "errCode":"DLM.0" in the 200 message indicates that the API call is successful. If the API call fails, rectify the fault based on the error message.
   Figure 6 Running the program