Data service

Access the service development tab

1. Log in to DMS 5.0.

2. From the top navigation bar, choose data assets > data service.

   Note

   If you use the console in simplified mode, click the icon in the upper-left corner and choose All Features > data assets > data service.

3. Optional: Click the service development tab.

Create a directory

1. Go to the service development tab.

2. Click the icon to the right of directory and select Create Directory.

3. In the Create Directory dialog box, enter a Directory Name.

   Note

   A directory name can contain Chinese characters, letters, digits, and underscores (_) and must meet the following requirements:

   • Be unique.

   • Start with a letter or a Chinese character.

   • Be 4 to 50 characters long.

4. Optional: Enter a business description.

5. Click Confirm.

Create and configure an API

1. Go to the service development tab.

2. Optional: Create a directory.

3. Create an API.

   1. To the right of the target directory, click the icon and select Create API.

   2. In the Create API dialog box, enter an API Name.

      Note

      An API name can contain Chinese characters, letters, digits, and underscores (_) and must meet the following requirements:

      • Be unique.

      • Start with a letter or a Chinese character.

      • Be 4 to 50 characters long.

   3. Optional: Enter a business description.

   4. In the path text box, enter the call path for the API.

      Note

      The path becomes part of the API call URL. It must be unique, start with a forward slash (/), and contain only letters, digits, underscores (_), and hyphens (-). For example: /item/add.

   5. Click Confirm.

4. Configure the API.

   1. Click the name of the target API.

   2. Configure API parameters.

      Parameter		Condition	Description
      Category	Parameter
      API mode	Select Mode	Required	Supports wizard mode and script mode. wizard mode: Visually define the API's data query by selecting tables and fields. script mode: Define the API's data query by writing SQL scripts and variables. Note Due to limitations on special character handling in script mode, the less than sign (<) and greater than sign (>) must be represented as HTML entities, specifically &lt; and &gt;. Otherwise, parsing errors may occur.
      Select Table	data source type	Required	The type of the database to query. Currently, only MySQL and PolarDB for MySQL are supported.
      	data source name		The database to query. Note Enter a keyword to search for databases you have permission to query.
      	Table Name	wizard mode	The data table to query. Note You can enter a keyword to quickly find the target table.
      Select Parameters	Paginate Results	wizard mode	Specifies whether to paginate the response.
      	Set as Request Parameter		Specifies whether to set the field as a request parameter. If you select Set as Request Parameter for a field, the field is added to request parameters on the right. Note After setting a field as a request parameter, you can click request parameters on the right to configure field information.
      	Set as Response Parameter		Specifies whether to set the field as a response parameter. If you select Set as Response Parameter for a field, the field is added to response parameters on the right. Note After setting a field as a response parameter, you can click response parameters on the right to configure field information.
      	Add to Sort Fields		Click Add next to a field to add it to the sort fields area.
      sort fields	sort order	wizard mode	Specifies the sort order. Options are ascending and descending.
      	Actions		Click Move Up or Move Down to reorder fields. Click Remove to remove the field.
      Write Query SQL		script mode	Enter an SQL statement and click auto-parse parameters to generate request and response parameters. Note After the request and response parameters are generated, you can click request parameters or response parameters on the right to configure field information.

   3. Optional: Set the execution properties for the API.

      Click Properties on the right side of the page and configure the parameters.

      Parameter	Description
      protocol	The protocol for API calls. Supported values: HTTPS and SSE.
      maximum number of returned records	The maximum number of records that an API call can return.
      timeout	The timeout for an API call.
      return field metadata	Specifies whether to return metadata in the API response.

   4. Above the API information, click Save to save the API.

Test an API

1. Go to the service development tab.

2. Click the API that you created and configured.

3. Above the API information, click Test.

4. On the API Test page, enter a Value for each request parameter.

   For example, for the ARRAY parameter id_list, enter [1,2].

5. Click Start Test.

6. If the API call succeeds, check the response body to verify the result.

Publish an API

1. Go to the service development tab.

2. Click the API that you have tested.

3. Above the API information, click Publish.

4. In the API publishing request panel, confirm the API's basic information and parameters.

5. Click Confirm and wait for the API to be published.

   Note

   If the API is already published, this action overwrites its online configuration.

Clone an API

1. Go to the service development tab.

2. Hover over the target API and click the icon that appears.

3. Click Clone.

   This action clones the original API's settings. Make sure that the parameters meet the requirements.

   Note

   • In the Clone API dialog box, the cloned API's API Name and path are appended with the _copy suffix.

   • Make sure that the API Name is unique across all directories.

4. Optional: Based on the parameter requirements and your business needs, modify the API Name, business description, path, and target directory.

5. Click Confirm.

Modify an API

1. Go to the service development tab.

2. Click the name of the target API.

3. Modify the API parameters.

   Note

   Changing the request or response parameters might affect API calls. Adjust the logic for handling request and response parameters in your client application accordingly.

4. Above the API information, click Save to save the API.

5. Publish the API.

Delete an API

To delete an API you no longer need, follow these steps.

1. Go to the service development tab.

2. Hover over the target API and click the icon that appears.

3. Click Delete.

4. In the Delete dialog box, click Confirm Deletion.

   The message API deleted successfully appears.

Edit a directory

1. Go to the service development tab.

2. Hover over the target directory and click the icon that appears.

3. Click Edit.

4. In the Edit Directory dialog box, modify the directory information.

5. Click Confirm.

   The message Directory edited successfully appears.

Delete a directory

You can delete a directory only if it contains no online APIs.

1. Go to the service development tab.

2. Hover over the target directory and click the icon that appears.

3. Click Delete.

   Note

   Make sure that the directory does not contain any APIs that are online (with a service status of Running).

4. In the Delete dialog box, click Confirm Deletion.

Go to the service development tab

1. Log in to DMS 5.0.

2. From the top navigation bar, choose data assets > data service.

   Note

   If you use the console in simplified mode, click the icon in the upper-left corner and choose All Features > data assets > data service.

3. Click the service management tab.

Authorize an API

1. Go to the service development tab.

2. In the left-side navigation pane, click API management.

3. On the API management page, find the target API and click authorize in the actions column.

4. In the authorize dialog box, select an Authorized Account and click confirm.

   The Authorization successful message appears.

Take an API offline

1. Go to the service development tab.

2. In the left-side navigation pane, click API management.

3. On the API management page, find the target API and click take offline in the actions column.

   Note

   After you take the API offline, its service status changes to Stopped.

Publish an API

1. Go to the service development tab.

2. In the left-side navigation pane, click API management.

3. On the API management page, find the target API and click publish in the actions column.

   Note

   After you publish the API, its service status changes to Running.

Test an API

1. Go to the service development tab.

2. In the left-side navigation pane, click API test.

3. In the API test section, select the target API.

4. In the request parameters section, enter a Value for each request parameter.

5. Click Start Test.

6. If the API call succeeds, check the response body to verify the result.

Call an API

1. Go to the service development tab.

2. In the left-side navigation pane, click API call.

3. View the API call information and call the API based on your business requirements.

Delete an API

1. Go to the service development tab.

2. In the left-side navigation pane, click API management.

3. On the API management page, find the target API and click delete in the actions column.

4. In the Delete dialog box, click Confirm Deletion.

   The message API deleted successfully appears.

Supported data sources

• MySQL

  Includes RDS MySQL, on-premises self-managed MySQL databases, and MySQL databases from other cloud providers.

• PolarDB for MySQL

Field information

Supported SQL

select c1, c2 from tb where c1 = #{c1};

select * from tb where id = #{id};

select * from tb where id = #{id} limit #{offset}, #{size};

select * from tb where id = #{id} limit ${pageNum} * ${pageSize}, ${pageSize};

select * from ds_test_tb where 1 =1
<if test="gmt_create != null">
and gmt_create = #{gmt_create}
</if>
<if test="id !=null">
and id = #{id}
</if>
limit ${pageNum} * ${pageSize}, ${pageSize}

select * from ds_test_tb where 1 =1
<choose>
 <when test="id != null">
 AND id = #{id}
 </when>
 <otherwise>
 AND `gmt_create` = #{gmt_create}
 </otherwise>
 </choose>
limit ${pageNum} * ${pageSize}, ${pageSize}

SELECT * FROM `ds_test_tb`
<where>
 <if test="id != null">
 id = #{id}
 </if>
 <if test="name != null">
 AND `name` = #{name}
 </if>
</where>

SELECT * FROM `ds_test_tb` where id in
<foreach item="item" index="index" collection="id_list" open="(" separator="," close=")">
#{item}
</foreach>

<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>fastjson</artifactId>
    <version>2.0.60</version>
</dependency>

{
  "accessKey" : "xxx", # Required. Your credential AccessKey from DMS.
  "accessSecret" : "xxx", # Required. Your credential AccessSecret from DMS.
  "query" : "call api ${apiPath}", # Required. Replace ${apiPath} with the actual path of your API.
  "params" : { # Optional. Fill in based on the actual data types of the parameters.
     "key1": value1,
     "key2": value2
  }
}

import com.alibaba.fastjson.JSON;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;
public class HttpsCallDataServiceApi {
    private static final HttpClient httpClient = HttpClient.newBuilder()
            .version(HttpClient.Version.HTTP_1_1)
            .connectTimeout(Duration.ofSeconds(10))
            .build();
    public static void main(String[] args) {
        try {
            String response = callDmsApi();
            System.out.println("Response content: " + response);
        } catch (Exception e) {
            System.err.println("Request failed: " + e.getMessage());
            e.printStackTrace();
        }
    }
    public static String callDmsApi() throws Exception {
        // Replace with the service endpoint for your region. You can find it on the data service homepage.
        String url = "https://onequery-cn-hangzhou.proxy.dms.aliyuncs.com/service/http";
        Map<String, Object> requestBody = new HashMap<>();
        // Replace ${accessKey} and ${accessSecret} with your DMS credential information, not your RAM AccessKey pair.
        requestBody.put("accessKey", "${accessKey}");
        requestBody.put("accessSecret", "${accessSecret}");
        // Replace ${apiPath} with the actual path of your API.
        requestBody.put("query", "call api ${apiPath}");
        // Build the params object. This object can be omitted if no parameters are needed.
        Map<String, Object> params = new HashMap<>();
        // In an actual call, replace the sample parameters with your actual parameters.
        // Numeric parameter
        params.put("userId", 111);
        // String parameter
        params.put("name", "abc");
        // Boolean parameter
        params.put("isActive", true);
        // List parameter
        params.put("tags", Arrays.asList(1, 2, 3));
        // If the params object is empty, you do not need to add it to the request body.
        requestBody.put("params", params);
        String jsonBody = JSON.toJSONString(requestBody);
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(url))
                .header("Content-Type", "application/json;charset=utf-8")
                .method("POST", HttpRequest.BodyPublishers.ofString(jsonBody))
                .timeout(Duration.ofSeconds(30))
                .build();
        HttpResponse<String> response = httpClient.send(request,
                HttpResponse.BodyHandlers.ofString());
        // Check the response status code.
        if (response.statusCode() != 200) {
            throw new RuntimeException("HTTP error code: " + response.statusCode());
        }
        return response.body();
    }
}

{
  "attributes": {
    "QueryTime": 13
  },
  "columnMetas": [
    {
      "autoIncrement": true,
      "catalogName": "test_schema",
      "columnLabel": "id",
      "columnName": "id",
      "columnTypeName": "BIGINT UNSIGNED",
      "nullable": false,
      "precision": 20,
      "scale": 0,
      "schemaName": "",
      "tableName": "test_table"
    },
    {
      "autoIncrement": false,
      "catalogName": "test_schema",
      "columnLabel": "gmt_create",
      "columnName": "gmt_create",
      "columnTypeName": "DATETIME",
      "nullable": true,
      "precision": 19,
      "scale": 0,
      "schemaName": "",
      "tableName": "test_table"
    }
  ],
  "count": 1,
  "message": null,
  "rows": [
    {
      "id": 1,
      "gmt_create": "2025-12-17 16:23:53"
    }
  ],
  "sessionId": 1560935281,
  "traceId": "HZ1560935281OCQJOTKW",
  "type": "RESULTSET"
}

import com.alibaba.fastjson.JSON;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import java.util.HashMap;
import java.util.Map;
import java.util.stream.Stream;
public class SseCallDataServiceApi {
    private static final HttpClient httpClient = HttpClient.newBuilder()
            .version(HttpClient.Version.HTTP_1_1)
            .connectTimeout(Duration.ofSeconds(10))
            .build();
    public static void main(String[] args) {
        try {
            callDmsApiSse();
        } catch (Exception e) {
            System.err.println("SSE request failed: " + e.getMessage());
            e.printStackTrace();
        }
    }
    public static void callDmsApiSse() throws Exception {
        // Replace with the service endpoint for your region. You can find it on the data service homepage.
        String url = "https://onequery-cn-hangzhou.proxy.dms.aliyuncs.com/service/sse";
        Map<String, Object> requestBody = new HashMap<>();
        // Replace ${accessKey} and ${accessSecret} with your DMS credential information, not your RAM AccessKey pair.
        requestBody.put("accessKey", "${accessKey}");
        requestBody.put("accessSecret", "${accessSecret}");
        // Replace ${apiPath} with the actual path of your API.
        requestBody.put("query", "call api ${apiPath}");
        // Build the params object. This object can be omitted if no parameters are needed.
        Map<String, Object> params = new HashMap<>();
        // In an actual call, replace the sample parameters with your actual parameters.
        // Numeric parameter
        params.put("userId", 111);
        // String parameter
        params.put("name", "abc");
        // Boolean parameter
        params.put("isActive", true);
        // List parameter
        params.put("tags", Arrays.asList(1, 2, 3));
        // If the params object is empty, you do not need to add it to the request body.
        requestBody.put("params", params);
        String jsonBody = JSON.toJSONString(requestBody);
        // Build the HttpRequest and add the necessary headers for SSE.
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(url))
                .header("Content-Type", "application/json;charset=utf-8")
                .header("Accept", "text/event-stream") // Specify that you accept an SSE stream.
                .header("Cache-Control", "no-cache")
                .method("POST", HttpRequest.BodyPublishers.ofString(jsonBody))
                .timeout(Duration.ofMinutes(5)) // SSE connections are typically long-lived, so set a longer timeout.
                .build();
        // Send the request and use ofLines to process the streaming response.
        System.out.println("Starting to receive SSE stream...");
        httpClient.sendAsync(request, HttpResponse.BodyHandlers.ofLines())
                .thenAccept(response -> {
                    if (response.statusCode() != 200) {
                        System.err.println("HTTP error: " + response.statusCode());
                        return;
                    }
                    // Parse the response content line by line.
                    try (Stream<String> lines = response.body()) {
                        lines.forEach(line -> {
                            if (line.startsWith("data:")) {
                                // Extract the content after "data:".
                                String data = line.substring(5).trim();
                                System.out.println("Data received: " + data);
                            } else if (line.startsWith("error:")) {
                                System.err.println("Error received: " + line);
                            }
                        });
                    }
                })
                .join(); // For demonstration purposes, the main thread waits for the async operation to complete.
    }
}