DocsICP FilingConsole
官方文档
首页

Create an API using service orchestration

更新时间：
复制 MD 格式
产品详情
我的收藏

You can create an API by orchestrating multiple existing APIs. This topic describes how to create an API using service orchestration.

Step 1: Select a method to create an API

  1. In the top menu bar of the Dataphin home page, choose Service > API Development.

  2. In the upper-left corner, select a service project. In the navigation pane on the left, click API Service. On the API page, click the +Create API button.

  3. In the Create API dialog box, select Composite API.

Step 2: Configure API parameters

  1. Configure parameters on the Create API page.

    Parameter

    Description

    Basic information

    API Name

    The naming conventions for an API name are as follows:

    • The name can contain only Chinese characters, letters, digits, or underscores (_).

    • The name must be 4 to 100 characters in length.

    • The name must start with a letter.

    • The name must be globally unique.

    Request Method

    The API request method supports only GET:

    GET: requests the server to retrieve a specified resource.

    Data Update Frequency

    Defines the update frequency of the data returned by the API, which helps the caller understand the timeliness of the data. The supported update frequencies are Daily, Hourly, Every Minute, and Custom. If you select Custom, you can enter up to 128 characters.

    API Group

    Select an API group configured in the current project. To create an API group, see Create a service group.

    Mode

    Supports two modes: Basic or Dev-Prod.

    • In Basic mode, development, submission, and online publishing all read from the production database.

    • In Dev-Prod mode, development and submission read from the development database, while online publishing reads from the production database.

    Description

    Enter a brief description of the API. The description can contain up to 128 characters.

    Protocol

    The interface protocol for data generation APIs. HTTP and HTTPS are supported.

    • HTTP: Hypertext Transfer Protocol (HTTP) is the most widely used network protocol.

    • HTTPS: If the gateway is configured as an Alibaba Cloud API Gateway (dedicated or shared instance), you can select the HTTPS protocol. Ensure that the SSL Certificate for the independent domain is valid to prevent call failures. To configure the SSL Certificate, choose Platform Management Network Configuration and go to the Network Configuration page.

    Timeout

    The maximum duration for monitoring API calls. If an API call exceeds the specified Timeout, an error is reported. This helps you promptly detect and handle API call exceptions. For more information about how to view exceptions, see Manage Service Monitoring APIs.

    Cache Settings

    Supports Enable or Disable. If enabled, you need to configure Cache Timeout. The default is 300 seconds. You can set a positive integer between 60 and 1000000.

    Version Number

    Enter the version number of the API. Each configuration has its own version number for comparison with previous versions. The version number can contain up to 64 characters and must be unique within the API.

    Return Type

    Default is JSON.

    Service orchestration

    API Reference

    In the API Reference panel, you can view the name, API_ID, request parameters, and return parameters of the child APIs. Click the Copy icon to quickly copy the API_ID and field names. Click API Test to test whether the parameters of the referenced child API are working properly to prevent reference failures.

    Follow the operation guide in the image below to quickly add return parameters to the script.

    image.png

    Note

    The conditions for supporting composite APIs are:

    • You must have personal usage permissions for the API to use it. For details, see Manage API permissions.

    • The API is a non-composite API type, such as a direct-connection API, a logical table API, a registered API, or a model API.

    • The API request method must be GET and the API must be published in synchronous call mode.

    Orchestration Script

    Edit the script in the script editor according to the system prompts. Replace the parameters in ${} with the field names of the return parameters from the child APIs, and fill in the defined fields (such as f1, f2) in the return parameter list.

    image

    • Script syntax description:

      Supports AviatorScript version 5.0. Refer to the version 5.0 programming guide when writing scripts.

      AviatorScript only supports single-line comments starting with ##. For multi-line comments, use ## at the beginning of each line you want to comment.

      When defining variables in AviatorScript, you need to assign values to the parameters.

      a = 1;

      let p = 2;

      When writing business processing logic that references child APIs, use API_APIID.return_parameter_name to specify the return parameters of child APIs. The request parameters of the composite API need to be defined as ${parameter_name}, and the request parameter names of the composite API cannot start with API_.

      c1 = ${API_APIID.c1};

      c2 = ${API_APIID.c2};

      c3 = c1 + c2 + ${p3};

      Define the fields to be returned by the composite API and return them with return, where f1 and f2 are the return field names, and c1 and c2 are the value variables for the return fields.

      let result = seq.map("f1", c1, "f2", c2);

      return result;

    • Script scenario descriptions:

      • Scenario 1: Call multiple APIs and return the results of multiple APIs in a unified way:

        ## Write calculation scripts based on business requirements, and specify the return parameters of child APIs through "API_APIID.return_parameter_name" c1 =${API_00001.c1}
c2 = ${API_00002.c1}
let result = seq.map("f1", c1, "f2", c2);
return result;

      • Scenario 2: Call different APIs based on conditions:

        ## Write processing logic: Call different APIs based on conditions to get different return results;
c1='';
if (${p3} == "linlin"){
## Use the number value returned by API_00001 as the return parameter of the composite API;
c1=${ API_00001.number}; }
else {
## Use the number value returned by API_00002 as the return parameter of the composite API;
c1= ${API_00002.number}; }
let result = seq.map("f1", c1);
return result;

      • Scenario 3: Call multiple APIs and perform calculations on the values returned by the APIs:

        ##Write processing logic: Sum and average the return values of multiple APIs;
## Sum the numbers returned by API_00001 and API_00002, and use the result as the return parameter of the composite API;
total = ${API_00001.number} + ${API_00002.number};
## Calculate the average of the numbers returned by API_00001 and API_00002, and use the result as the return parameter of the composite API;
average = (${API_00001.number} + ${API_00002.number}) / 2;
let result = seq.map("f1", total,"f2",average);
return result;

    Parameter Parsing

    After completing the script editing, click the Parameter Parsing button to perform syntax validation and parse the request parameter mapping relationships of the referenced child APIs. If you modify the script, you need to parse it again.

    Script Trial Run

    First, you need to add the fields defined in the script editor (such as f1 and f2) to the return parameter list, then click SQL Trial Run. In the Request Parameter Input dialog box, enter the values for the trial run, and then click OK. You can view the actual SQL statements executed during the SQL trial run in Runtime Log.

    Request parameters

    Parameter Name

    The publicly exposed parameters that users directly use when accessing the API. Cannot start with API_ and must be within 128 characters.

    Parameter Type

    Supports parameter types including Array(int), Array(string), DOUBLE, FlOAT, STRING, DATE(yyyy-MM-dd HH:mm:ss), BOOLEAN, INT, LONG, SHORT, and BIGDECIMAL. You need to select the parameter type that corresponds to the bound field of the parameter name.

    Example

    Enter an example of the request parameter value to help developers understand.

    Description

    Enter a brief description of the request parameter. The description can contain up to 1,000 characters.

    Required

    Specifies whether the parameter is required. If a required parameter is not passed when the API is called, the call fails.

    Request parameter mapping relationships

    The system parses the child APIs referenced in the script based on the configured parameter mapping between the child APIs and the composite API. This returns the referenced child APIs and their request parameters. When a child API is called, the request parameter values of the composite API are passed to the child API based on this mapping. If a request parameter of a child API is required, you must configure a mapping for it.

    Return parameters

    Parameter Name

    The return parameter name must be the same as the return field name defined in the script. Otherwise, the corresponding field return value cannot be obtained.

    Parameter Type

    Return parameter types include DOUBLE, FlOAT, STRING, DATE(yyyy-MM-dd HH:mm:ss), BOOLEAN, INT, LONG, SHORT, BIGDECIMAL, Array(int), and Array(string). You need to select the parameter type that corresponds to the bound field of the parameter name.

    Example

    Enter an example of a return parameter value to help developers understand the parameter. You can enter up to 1000 characters.

    Description

    Enter a brief description of the return parameter. You can enter up to 1000 characters.

    Associated row-level permissions

    The row-level permissions of the current API are automatically enabled following the referenced child APIs. This displays the row-level permission information associated with and enabled for the referenced child APIs.

  2. Click Submit to complete the API creation.

What to do next

  • After creating the API, you need to test it and publish it to the DataService Studio marketplace for subsequent applications to call the API. For more information, see Test and publish APIs.

  • To delete the API, manage versions, transfer ownership, or perform other operations, see Manage APIs.

Previous：Create an API through service orchestrationNext：Create an API task