This topic describes how to create an Aviator function and use the Aviator function as the prefilter or post-filter for an API.

Background information

On the DataService Studio page, you can create, test, and publish a function. Then, you can associate the function with an API, and use the function as a filter to process the request parameters or responses of the API to perform complex queries based on your business requirements. For the sample code that shows how to use an Aviator function as a filter for an API in common scenarios, see Best practices of using Aviator functions as filters.

Limits

  • You must use an exclusive resource group for DataService Studio to run an Aviator function.
  • For the same API, the function used as the prefilter and the function used as the post-filter must be of the same type. You are not allowed to use an Aviator function and a Python function as the filters for the same API.

Precautions

To ensure data security and function performance, you must use an exclusive resource group for DataService Studio to run an Aviator function.
  • When you edit or test a function, you must associate the function with an exclusive resource group for DataService Studio. For more information, see Create and manage functions.
  • If you enable the filter feature for an API and associate the API with a function when you develop the API, you must associate the API with an exclusive resource group for DataStudio Service. For more information, see Create an API in the codeless UI.

Syntax of an Aviator function

The system provides the following function template for an Aviator function. For more information about the syntax of an Aviator function, see Aviator function syntax. 

## --- AviatorScript ---
## $0: the default name of the input param.
## Expressions must be separated by the semicolon ";".

## Example 1:
## $0.a: Get the attribute "a" from the input param "$0".
## $0.b[index]: Get the index of the array "b" from the input param "$0". The index cannot be an expression or a variable.

## Example 2:
## Input: {"keyA":[1,2],"keyB":"value"}
## Function: $0.keyA[0]=3; $0.keyB="new_value"; return $0;
## Output: {"keyA":[3,2],"keyB":"new_value"}

return $0;
You can modify the function based on your business requirements.
  • The default name of the input parameter of an Aviator function is $0 and cannot be changed. You can use the $0 parameter to obtain the input of the Aviator function.
  • The input of a function must be in the JSON format. In DataService Studio, a function is used as a filter to process the request parameters or responses of an API. The request parameters of an API are defined in the single-layer JSON format. The responses of the API are defined in the multi-layer JSON format. Therefore, the input of a function must also be in the JSON format. The $0 parameter specifies input data in the JSON format.
  • If a function is used as the prefilter for an API, the system converts request parameters of the API or outputs of the previous function from key-value pairs into data in the JSON format. Then, the system uses the data in the JSON format to replace the $0 parameter. The data type of values in the JSON data can only be STRING.
  • If a function is used as the prefilter for an API, the outputs of the function are key-value pairs. The key-value pairs are used as the input parameter of an SQL statement. Therefore, the key-value pairs cannot contain nested key-value pairs.

Create a function

  1. Go to the DataService Studio page.
    1. Log on to the DataWorks console.
    2. In the left-side navigation pane, click Workspaces.
    3. In the top navigation bar, select the region in which the workspace that you want to manage resides. Find the workspace and click DataService Studio in the Actions column.
  2. On the Service Development page, move the pointer over the Create icon and choose Create Function > Create Aviator Function.
    Alternatively, you can find the desired business process, right-click the name of the business process, and then choose New > Function > Create Aviator Function.
  3. In the Create Aviator Function dialog box, configure the following parameters.
    Python
    Parameter Description
    Function Name The name of the function. The name can be up to 256 characters in length.
    Function Template The template that is used to create the function. Set the value to AviatorScript Standard v1.
    Function Description The description of the function. The description can be up to 512 characters in length.
    Destination Folder The folder in which the function is stored.
    Note The value of this parameter can be a business process name, folder name, or function category. If no business process is available, create a business process first.
  4. Click OK.
  5. Configure the function on the configuration tab.
    1. In the Edit Code section, enter the code for the function.
    2. In the Environment Configuration section, configure the Function Timeout parameter.
  6. Configure an exclusive service resource group for DataService Studio.
    In the right-side navigation pane of the configuration tab of the function, click Resource Group. In the Resource Group pane, select Exclusive Resource Group for DataService Studio for the Scheme parameter and select an exclusive resource group from the Exclusive Resource Group for DataService Studio drop-down list. Function
    Note If the exclusive resource group for DataService Studio that you want to select is not displayed in the drop-down list, you can associate the exclusive resource group with your workspace on the Exclusive Resource Groups tab of the Resource Groups page in the DataWorks console. You can also click Purchase Resource Group for DataService Studio in the Resource Group pane to purchase an exclusive resource group for DataService Studio.
  7. Click the Save icon in the upper-left corner of the configuration tab of the function to save the configurations.

Use a function as a filter for an API

  1. On the Service Development page, click the business process to which the desired API belongs.
  2. Find the desired API and double-click the API name. The configuration tab of the API appears.
  3. In the right-side navigation pane of the configuration tab of the API, click Filter.
    On the Filter tab, select Use Pre-filter or Use Post-filter based on your business requirements. The selected Aviator check box is highlighted upon your selection. Select the function that you want to use as a prefilter or post-filter from the Use Pre-filter or Use Post-filter drop-down list. You can select multiple functions. When you execute these functions, the request parameters or responses of an API with which you associate the multiple functions are processed in the same sequence as the functions are selected.
    Note
    • A filter consists of one or more functions. You can use a filter to preprocess the request parameters of an API or perform secondary processing on query results of the API.
    • If the function that you want to use is not displayed in the Use Pre-filter or Use Post-filter drop-down list, check whether the function is published. If the function is not published, publish the function. You can also create and publish another function. For more information, see Publish a function.
    Filter
  4. Click Preview Responses Returned by API Operation to check whether the result that you obtain by using the filter meets your expectations.