腳本開發 / 編寫並調用函數

本文檔為在 DataFlux Func 上開發腳本的最基礎文檔，閲讀後可以實現在 DataFlux Func 上進行最基礎的開發、使用工作。

1. 觀前提示

在 DataFlux Func 的使用過程中，

請勿多人登錄同一個賬號，也不要多人同時編輯同一份代碼。

以免造成代碼相互覆蓋、丟失的問題

2. 編寫第一個函數並調用

在 DataFlux Func 中編寫代碼，與正常編寫 Python 代碼並無太大區別。 對於需要導出為 API 的函數，添加內置的 @DFF.API(...) 裝飾器即可實現。

函數的返回值即接口的返回值，當返回值為 dict、list 時，系統會自動當作 JSON 返回。

一個典型的函數如下：

@DFF.API('Hello, world')
def hello_world(message=None):
    ret = {
        'message': message
    }
    return ret

DataFlux Func 平台提供了多種方式調用這種被 DFF.API(...) 修飾的函數：

執行功能	特點	適用場景
同步執行的函數 API	生成同步 HTTP API。調用後直接返回處理結果	處理時間較短，客户端需要立刻獲得結果的情況
異步執行的函數 API	生成異步 HTTP API。調用後立刻響應，但不返回處理結果	處理時間較長，接口調用僅作為啓動信號的場景
定時任務	基於 Crontab 語法自動執行	定期同步 / 緩存數據，定時任務等情況

詳細見 腳本開發 / 基本概念

這裏，為本函數創建一個函數 API，即可實現在公網通過 HTTP 的方式調用本函數。

假設為此函數創建的「函數 API」 ID 為 func-api-xxxxx，那麼調用此函數的最簡單方式如下：

GET /api/v1/al/func-api-xxxxx/simplified?message=Hello

響應如下（省略部分內容）：

HTTP/1.1 200 OK
Content-Type: application/json

{"message":"Hello"}

3. 編寫支持文件上傳的函數

DataFlux Func 也支持通過函數 API 上傳文件。

需要處理上傳的文件時，可以為函數添加 files 參數接收上傳的文件信息。 文件在上傳後，DataFlux Func 會自動將文件存儲到一個臨時上傳目錄供腳本進行後續處理。

# 接收 Excel 文件，並將 Sheet1 內容返回
from openpyxl import load_workbook

@DFF.API('讀取 Excel')
def read_excel(files=None):
    excel_data = []
    if files:
        workbook = load_workbook(filename=files[0]['filePath'])
        for row in workbook['Sheet1'].iter_rows(min_row=1, values_only=True):
            excel_data.append(row)

    return excel_data

files 參數由 DataFlux Func 系統自動填入，內容如下：

[
    {
        "filePath"    : "<文件臨時存放地址>",
        "originalname": "<文件原始文件名>",
        "encoding"    : "<編碼>",
        "mimetype"    : "<MIME 類型>",
        "size"        : "<文件大小>"
    },
    ...
]

上傳文件的示例命令見 腳本開發 / 基本概念 / 函數 API / POST 簡化傳參

4. 接收非 JSON、From 數據

於 1.6.9 版本新增

在某些情況下，請求可能由第三方系統或應用按照其特有的格式發起，且請求體不屬於 JSON 或 Form 格式，那麼可以使用 **data 作為入參，並以 POST 簡化形式來調用。

系統在接收到文本、無法解析的數據時，會自動打包為 { "text": "<文本>" } 或 { "base64": "<Base64 格式的二進制數據>"} 並傳遞給函數。

示例代碼如下：

import json
import binascii

@DFF.API('接受任意格式 Body 的函數')
def tiger_balm(**data):
    if 'text' in data:
        # 當請求體為文本（如：Content-Type: text/plain）時
        # `data`參數中固定包含一個單獨`text`字段存放內容
        return f"文本：{data['text']}"

    elif 'base64' in data:
        # 當請求體為無法解析的格式（Content-Type: application/xxx）時
        # `data`參數中固定包含一個單獨`base64`字段存放請求體的 Base64 字符串
        # Base64 字符串可以使用`binascii.a2b_base64(...)`轉換為 Python 的二進制數據
        b = binascii.a2b_base64(data['base64'])
        return f"Base64：{data['base64']} -> {b}"

請求體為文本時

請求如下：

curl -X POST -H "Content-Type: text/plain" -d 'hello, world!' http://localhost:8089/api/v1/al/auln-unknow-body/simplified

輸出如下：

文本：hello, world!

請求體為未知格式時

請求如下：

curl -X POST -H "Content-Type: unknow/type" -d 'hello, world!' http://localhost:8089/api/v1/al/auln-unknow-body/simplified

輸出如下：

Base64：aGVsbG8sIHdvcmxkIQ== -> b'hello, world!'