使用Aviator函數作為過濾器的最佳實務 - DataWorks

資料服務支援編寫函數，並將一個或多個相同類型的函數關聯至API，使得函數可以作為API的過濾器進行使用。本實踐以Aviator函數及對應文法為例，為您介紹幾種函數邏輯的編寫樣本。

應用情境

如果將函數設定為API的前置過濾器，當API被調用時，函數可以對API的請求參數進行預先處理。
如果將函數設定為API的後置過濾器，當API被調用時，函數可以對API的返回結果進行二次加工和改造。

操作指南

函數的建立、測試、提交、發布、刪除、移動、複製等操作指南，詳情請參見管理函數、測試函數、發布函數。
使用函數作為API前置和後置過濾器的操作指南，詳情請參見建立Aviator函數。
Aviator函數文法參考請參見函數文法。

函數的輸入參數樣本

說明 Aviator代碼中的預設變數名稱$0，指的是函數的整體輸入。

情境一：Aviator函數作為API的前置過濾器
此時，API的請求參數及參數值將按照JSON結構（單層JSON）作為函數的整體輸入。請求參數作為函數輸入時的樣本如下：
```
## 請求參數為user_id
## API調用時傳入了多個參數值：user_id = (0,1,2)
{
  "user_id": [0,1,2]
}
```

情境二：Aviator函數作為API的後置過濾器

此時，API的返回結果將按照JSON結構（多層JSON）作為函數的整體輸入。返回結果作為函數輸入時的樣本如下：

## 返回結果共包含3列：user_id，city，tags
## API調用後共返回了3條合格資料記錄（見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
}

函數的使用樣本

情境一：Aviator函數作為API的前置過濾器。使用樣本如下所示：

樣本1：調用函數時，函數對用戶端傳入的請求參數的值進行修改。

Aviator函數：

## 對於請求參數user_id，在用戶端的原始傳值為user_id=1
## 經過濾器處理後，實際查詢的傳值為user_id=2
if $0.user_id == 1
{
    $0.user_id = $0.user_id + 1;
}
return $0;

函數的輸入及輸出：

## 輸入：
{
    "user_id": 1
}

## 輸出：
{
  "user_id": 2
}

樣本2：調用函數時，函數對用戶端未傳值的請求參數進行賦值（即：當請求參數為非必填且未傳值時進行賦值）。

Aviator函數：

## 對於請求參數user_id，在用戶端的原始傳值為user_id=
## 經過濾器處理後，實際查詢的傳值為user_id=1
$0.user_id = 1;
return $0;

函數的輸入及輸出：

## 輸入：
{
    "user_id": ""
}

## 輸出：
{
  "user_id": 1
}

樣本3：調用函數時，當用戶端傳入的請求參數的值為數組時（即：對一個請求參數傳入多個值），函數將根據迴圈條件，遍曆每一個值並修改為新值。

Aviator函數：

## 對於請求參數user_id，在用戶端的原始傳值為user_id=(0,1,2)
## 經過濾器處理後，實際查詢的傳值為user_id=(1,2,3)
user_id = $0.user_id;
for index in user_id
{
    user_id[index] = index + 1;
}
return $0;

函數的輸入及輸出：

## 輸入：
{
  "user_id": [0,1,2]
}

## 輸出：
{
  "user_id": [
    1,
    2,
    3
  ]
}

情境二：Aviator函數作為API的後置過濾器。使用樣本如下所示：

樣本1：調用函數後，函數將對API返回的資料結果（JSON格式）中的某條記錄進行修改。

Aviator函數：

## 首先擷取到JSON中的最內層數組rows，接下來對數組進行遍曆，當遇到某條記錄為"city":"BJ"時,將"tags":""改為"tags":"資料服務"
rows = $0.data.rows;
for row in rows
{
    if(row.city == "BJ")
    {
        row.tags = "資料服務";
    }
}
return $0;

函數的輸入及輸出：

## 輸入：
{
  "data": {
    "totalNum": 3,
    "pageSize": 10,
    "rows": [
      {
        "user_id": 2,
        "city": "BJ",
        "tags": "資料服務"
      },
      {
        "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
}

## 輸出：
{
  "data": {
    "totalNum": 3,
    "pageSize": 10,
    "rows": [
      {
        "user_id": 2,
        "city": "BJ",
        "tags": "資料服務"
      },
      {
        "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"
}

樣本2：調用函數後，函數將對API返回的資料結果（JSON格式）的每條記錄增加一個常量列。

Aviator函數：

## 首先擷取到JSON中的最內層數組rows，接下來對數組進行遍曆，對每條記錄均增加一個常量列is_target= "Y"
rows = $0.data.rows;
for row in rows
{
    row.is_target= "Y";
}

return $0;

函數的輸入及輸出：

## 輸入：
{
  "data": {
    "totalNum": 3,
    "pageSize": 10,
    "rows": [
      {
        "user_id": 2,
        "city": "BJ",
        "tags": "資料服務"
      },
      {
        "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
}

## 輸出：
{
  "data": {
    "totalNum": 3,
    "pageSize": 10,
    "rows": [
      {
        "is_target": "Y",
        "user_id": 2,
        "city": "BJ",
        "tags": "資料服務"
      },
      {
        "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"
}

樣本3：調用函數後，如果API返回的資料結果（JSON格式）中欄位很多，不想逐個判斷欄位傳回值，可以用函數來遍曆所有欄位，並對有特殊值的欄位進行改值。

Aviator函數：

## 首先擷取到JSON中的最內層數組rows，然後對數組rows進行嵌套遍曆，即：對數組rows中的每個元素，進一步擷取其中的map；當map中的value值為null時，改值為"測試"
## 在Aviator文法中，nil是空值常量，相當於其他文法中的null
rows = $0.data.rows;
for row in rows
{
    for index in row
    {
        if(index.value == nil)
        {
            index.value = "測試"
        }
    }
}
return $0;

函數的輸入及輸出：

## 輸入：
{
  "data": {
    "totalNum": 3,
    "pageSize": 10,
    "rows": [
      {
        "user_id": null,
        "city": "SH",
        "tags": "A,C,D,F"
      },
      {
        "user_id": 2,
        "city": "BJ",
        "tags": "資料服務"
      },
      {
        "user_id": null,
        "city": null,
        "tags": "A,B,C"
      }
    ],
    "pageNum": 1
  },
  "errCode": 0,
  "requestId": "0bb211f016372870359913841e52d8",
  "errMsg": "success",
  "apiLog": null
}

## 輸出：
{
  "data": {
    "totalNum": 3,
    "pageSize": 10,
    "rows": [
      {
        "user_id": "測試",
        "city": "SH",
        "tags": "A,C,D,F"
      },
      {
        "user_id": 2,
        "city": "BJ",
        "tags": "資料服務"
      },
      {
        "user_id": "測試",
        "city": "測試",
        "tags": "A,B,C"
      }
    ],
    "pageNum": 1
  },
  "errCode": 0,
  "requestId": "0bb211f016372870359913841e52d8",
  "errMsg": "success"
}

效果展示

API前置過濾函數使用函數的使用樣本中情境一的樣本2和樣本1，順序執行：
API後置過濾函數使用函數的使用樣本中情境二的樣本1和樣本2，順序執行：

說明 API的過濾器中僅支援選擇發行的函數。

API執行結果如下：

## API的輸入：
{
  "user_id": ""
}

## API的輸出：
{
  "data": {
    "totalNum": 1,
    "pageSize": 10,
    "rows": [
      {
        "is_target": "Y",
        "user_id": 2,
        "city": "BJ",
        "tags": "資料服務"
      }
    ],
    "pageNum": 1
  },
  "errCode": 0,
  "requestId": "0be30a8716357721257118118e2b0f",
  "errMsg": "success"
}