指令碼開發 / 編寫並呼叫函式

本文件為在 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!'