Document Center

All Products

Document Center

DataWorks:Best practices of using Aviator functions as filters

Last Updated:Mar 28, 2022

In DataService Studio, you can write functions, associate a single function or multiple functions of the same type with an API, and use the functions as filters for the API. This topic provides examples on how to write an Aviator function that has a specific logic based on Aviator function syntax.

Scenarios

If you use a function as the prefilter for an API, the function preprocesses the request parameters of the API when the API is called.
If you use a function as the post-filter for an API, the function processes and reconstructs the responses of the API when the API is called.

References

For more information about how to create, test, submit, publish, delete, move, and clone a function, see Create and manage functions, Test a function, and Publish a function.
For more information about how to use a function as the prefilter or post-filter for an API, see Create an Aviator function and use the Aviator function as a filter.
For more information about Aviator function syntax, see Function syntax.

Input parameters of a function

Note The name of the default variable in the code for an Aviator function is $0, which indicates the entire input of the Aviator function.

Scenario 1: Use an Aviator function as the prefilter for an API.
The request parameters and the values of the request parameters of the API are used as the entire input for the Aviator function. The input is in a single-layer JSON format. Example:
```
## user_id is the request parameter.
## user_id = (0,1,2) indicates that multiple values are passed in for the request parameter when the API is called.
{
  "user_id": [0,1,2]
}
```

Scenario 2: Use an Aviator function as the post-filter for an API.

The responses of the API are used as the entire input of the Aviator function. The input is in a multi-layer JSON format. Example:

## The returned data contains three columns: user_id, city, and tags.
## Three data entries that meet the conditions are returned after the API is called. Check the code for rows.
{
  "data": {
    "totalNum": 3,
    "pageSize": 10,
    "rows": [
      {
        "user_id": 2,
        "city": "BJ",
        "tags": "B,D,dongcs,ccccc"
      },
      {
        "user_id": 3,
        "city": "SH",
        "tags": "A,C,D,F"
      },
      {
        "user_id": 1,
        "city": "HZ",
        "tags": "A,B,C"
      }
    ],
    "pageNum": 1
  },
  "errCode": 0,
  "requestId": "0bb211c516357674333185698eb07b",
  "errMsg": "success",
  "apiLog": null
}

Use an Aviator function

Scenario 1: Use an Aviator function as the prefilter for an API. Examples:

Example 1: The Aviator function is called to change the value of the request parameter that is passed in from the client.

Aviator function:

## The original value that is passed in from the client for the request parameter user_id is 1.
## After you use the Aviator function as the prefilter to preprocess the request parameter user_id, the value of the request parameter that you query is 2.
if $0.user_id == 1
{
    $0.user_id = $0.user_id + 1;
}
return $0;

Input and output of the Aviator function:

## Input:
{
    "user_id": 1
}

## Output:
{
  "user_id": 2
}

Example 2: The Aviator function is called to assign a value to the request parameter whose value is not passed in from the client. If the request parameter is optional and no value is available for the request parameter, the request parameter can be assigned a value.
- Aviator function:
```
## user_id= indicates that the request parameter user_id is not specified on the client.
## After you use the Aviator function as the prefilter to preprocess the request parameter user_id, the value of the request parameter that you query is 1.
$0.user_id = 1;
return $0;
```
- Input and output of the Aviator function:
```
## Input:
{
    "user_id": ""
}

## Output:
{
  "user_id": 1
}
```

Example 3: The Aviator function is called to traverse all values in the array that is passed in from the client for the request parameter user_id and change the values.

Aviator function:

## The original values that are passed in from the client for the request parameter user_id is 0, 1, and 2.
## After you use the Aviator function as the prefilter to preprocess the request parameter user_id, the values of the request parameter that you query are 1, 2, and 3.
user_id = $0.user_id;
for index in user_id
{
    user_id[index] = index + 1;
}
return $0;

Input and output of the Aviator function:

## Input:
{
  "user_id": [0,1,2]
}

## Output:
{
  "user_id": [
    1,
    2,
    3
  ]
}

Scenario 2: Use an Aviator function as the post-filter for an API. Examples:

Example 1: The Aviator function is called to modify a specific data entry in the JSON data that is returned by the API.

Aviator function:

## Obtain and traverse the innermost array that is named rows in the JSON data to find the data entry in which city is BJ. Then, change "tags":"" to "tags":"DataService Studio" for the data entry.
rows = $0.data.rows;
for row in rows
{
    if(row.city == "BJ")
    {
        row.tags = "DataService Studio";
    }
}
return $0;

Input and output of the Aviator function:

## Input:
{
  "data": {
    "totalNum": 3,
    "pageSize": 10,
    "rows": [
      {
        "user_id": 2,
        "city": "BJ",
        "tags": "DataService Studio"
      },
      {
        "user_id": 1,
        "city": "HZ",
        "tags": "A,B,C"
      },
      {
        "user_id": 3,
        "city": "SH",
        "tags": "A,C,D,F"
      }
    ],
    "pageNum": 1
  },
  "errCode": 0,
  "requestId": "0bb211e016357705412263266e571e",
  "errMsg": "success",
  "apiLog": null
}

## Output:
{
  "data": {
    "totalNum": 3,
    "pageSize": 10,
    "rows": [
      {
        "user_id": 2,
        "city": "BJ",
        "tags": "DataService Studio"
      },
      {
        "user_id": 1,
        "city": "HZ",
        "tags": "A,B,C"
      },
      {
        "user_id": 3,
        "city": "SH",
        "tags": "A,C,D,F"
      }
    ],
    "pageNum": 1
  },
  "errCode": 0,
  "requestId": "0bb211e016357705412263266e571e",
  "errMsg": "success"
}

Example 2: The Aviator function is called to add a constant column to each data entry in the JSON data that is returned by the API.

Aviator function:

## Obtain and traverse the innermost array that is named rows in the JSON data and add the constant column is_target= "Y" to each data entry.
rows = $0.data.rows;
for row in rows
{
    row.is_target= "Y";
}

return $0;

Input and output of the Aviator function:

## Input:
{
  "data": {
    "totalNum": 3,
    "pageSize": 10,
    "rows": [
      {
        "user_id": 2,
        "city": "BJ",
        "tags": "DataService Studio"
      },
      {
        "user_id": 1,
        "city": "HZ",
        "tags": "A,B,C"
      },
      {
        "user_id": 3,
        "city": "SH",
        "tags": "A,C,D,F"
      }
    ],
    "pageNum": 1
  },
  "errCode": 0,
  "requestId": "0bb211e016357705412263266e571e",
  "errMsg": "success",
  "apiLog": null
}

## Output:
{
  "data": {
    "totalNum": 3,
    "pageSize": 10,
    "rows": [
      {
        "is_target": "Y",
        "user_id": 2,
        "city": "BJ",
        "tags": "DataService Studio"
      },
      {
        "is_target": "Y",
        "user_id": 1,
        "city": "HZ",
        "tags": "A,B,C"
      },
      {
        "is_target": "Y",
        "user_id": 3,
        "city": "SH",
        "tags": "A,C,D,F"
      }
    ],
    "pageNum": 1
  },
  "errCode": 0,
  "requestId": "0bb211e016357705412263266e571e",
  "errMsg": "success"
}

Example 3: The JSON data that is returned by the API contains numerous fields, and you do not want to determine the return values of the fields one by one. The Aviator function is called to traverse all fields and change the values of the fields that have special values.

Aviator function:

## Obtain the innermost array that is named rows in the JSON data. Traverse the nested data in the rows array to obtain the map of each data entry. Then, change the value of the map whose value is null to test.
## In Aviator syntax, nil specifies a null constant, which is equivalent to null in other syntax.
rows = $0.data.rows;
for row in rows
{
    for index in row
    {
        if(index.value == nil)
        {
            index.value = "test"
        }
    }
}
return $0;

Input and output of the Aviator function:

## Input:
{
  "data": {
    "totalNum": 3,
    "pageSize": 10,
    "rows": [
      {
        "user_id": null,
        "city": "SH",
        "tags": "A,C,D,F"
      },
      {
        "user_id": 2,
        "city": "BJ",
        "tags": "DataService Studio"
      },
      {
        "user_id": null,
        "city": null,
        "tags": "A,B,C"
      }
    ],
    "pageNum": 1
  },
  "errCode": 0,
  "requestId": "0bb211f016372870359913841e52d8",
  "errMsg": "success",
  "apiLog": null
}

## Output:
{
  "data": {
    "totalNum": 3,
    "pageSize": 10,
    "rows": [
      {
        "user_id": "test",
        "city": "SH",
        "tags": "A,C,D,F"
      },
      {
        "user_id": 2,
        "city": "BJ",
        "tags": "DataService Studio"
      },
      {
        "user_id": "test",
        "city": "test",
        "tags": "A,B,C"
      }
    ],
    "pageNum": 1
  },
  "errCode": 0,
  "requestId": "0bb211f016372870359913841e52d8",
  "errMsg": "success"
}

Filter use effect

Note You can use only a published function as a filter for an API.

Input and output of the API:

## API input:
{
  "user_id": ""
}

## API output:
{
  "data": {
    "totalNum": 1,
    "pageSize": 10,
    "rows": [
      {
        "is_target": "Y",
        "user_id": 2,
        "city": "BJ",
        "tags": "DataService Studio"
      }
    ],
    "pageNum": 1
  },
  "errCode": 0,
  "requestId": "0be30a8716357721257118118e2b0f",
  "errMsg": "success"
}