脚本开发 / 编写并调用函数

本文档为在 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(...)修饰的函数：

执行功能	特点	适用场景
授权链接	生成同步 HTTP API。调用后直接返回处理结果	处理时间较短，客户端需要立刻获得结果的情况
自动触发	基于 Crontab 语法自动执行	定期同步/缓存数据，定时任务等情况
批处理	生成异步 HTTP API。调用后立刻响应，但不返回处理结果	处理时间较长，接口调用仅作为启动信号的场景

详细见 脚本开发 / 基本概念

这里，为本函数创建一个授权链接，即可实现在公网通过 HTTP 的方式调用本函数。

假设为此函数创建的授权链接 ID 为auln-xxxxx，那么调用此函数的最简单方式如下：

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

响应如下（省略部分内容）：

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

{"message":"Hello"}

3. 编写支持文件上传的函数

DataFlux Func 也支持通过授权链接上传文件。

需要处理上传的文件时，可以为函数添加files参数接收上传的文件信息。 文件在上传后，DataFlux Func 会自动将文件存储到一个临时上传目录供脚本进行后续处理。

具体 Python 代码示例如下：

# 接收 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"        : "<文件大小>"
    },
    ...
]

上传文件的示例命令见 脚本开发 / 基本概念 / 授权链接 / 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!'