Script Development / Writing and Calling Functions

This document is the most basic guide to developing scripts on DataFlux Func. After reading it, you can perform basic development and usage on DataFlux Func.

1. Before You Start

When using DataFlux Func,

please do not log in to the same account with multiple people, and do not edit the same code simultaneously.

This is to avoid code overwriting or loss caused by conflicting edits.

2. Write and Call Your First Function

Writing code in DataFlux Func is not much different from writing Python code normally.
For functions that need to be exported as APIs, add the built-in @DFF.API(...) decorator.

The function's return value is the return value of the API. When the return value is a dict or list, the system automatically returns it as JSON.

A typical function is as follows:

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

The DataFlux Func platform provides multiple ways to call functions decorated with DFF.API(...):

Execution Feature	Characteristics	Applicable Scenarios
Synchronous Function API	Generates a synchronous HTTP API. Returns the processing result directly after the call	Scenarios where processing time is short and the client needs to obtain the result immediately
Asynchronous Function API	Generates an asynchronous HTTP API. Responds immediately after the call, but does not return the processing result	Scenarios where processing takes a long time and the API call is only used as a startup signal
Scheduled Task	Executes automatically based on Crontab syntax	Periodic data synchronization / caching, scheduled tasks, and other scenarios

For details, see Script Development / Basic Concepts

Here, create a function API for this function to call it over the public network through HTTP.

Assume that the ID of the "Function API" created for this function is func-api-xxxxx. The simplest way to call this function is as follows:

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

The response is as follows, with some content omitted:

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

{"message":"Hello"}

3. Write a Function That Supports File Uploads

DataFlux Func also supports uploading files through Function APIs.

When uploaded files need to be processed, you can add a files parameter to the function to receive the uploaded file information.
After a file is uploaded, DataFlux Func automatically stores it in a temporary upload directory for subsequent processing by the script.

# Receive an Excel file and return the contents of Sheet1
from openpyxl import load_workbook

@DFF.API('Read 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

The files parameter is automatically populated by the DataFlux Func system as follows:

[
    {
        "filePath"    : "<Temporary file storage path>",
        "originalname": "<Original file name>",
        "encoding"    : "<Encoding>",
        "mimetype"    : "<MIME type>",
        "size"        : "<File size>"
    }
]

For an example command to upload a file, see Script Development / Basic Concepts / Function API / Simplified POST Parameters

4. Receive Non-JSON and Non-Form Data

Added in version 1.6.9

In some cases, a request may be sent by a third-party system or application in its own specific format, and the request body may not be in JSON or Form format. In this case, you can use **data as the input parameter and call the function using the simplified POST format.

When the system receives text or data that cannot be parsed, it automatically packages it as { "text": "<text>" } or { "base64": "<binary data in Base64 format>"} and passes it to the function.

The sample code is as follows:

import json
import binascii

@DFF.API('Function that accepts a Body in any format')
def tiger_balm(**data):
    if 'text' in data:
        # When the request body is text, such as Content-Type: text/plain
        # The `data` parameter always contains a single `text` field for storing the content
        return f"Text: {data['text']}"

    elif 'base64' in data:
        # When the request body has an unparseable format, such as Content-Type: application/xxx
        # The `data` parameter always contains a single `base64` field for storing the Base64 string of the request body
        # The Base64 string can be converted to Python binary data using `binascii.a2b_base64(...)`
        b = binascii.a2b_base64(data['base64'])
        return f"Base64: {data['base64']} -> {b}"

When the Request Body Is Text

The request is as follows:

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

The output is as follows:

Text: hello, world!

When the Request Body Has an Unknown Format

The request is as follows:

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

The output is as follows:

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