Script Development / Writing and Calling Functions

This document is the most basic guide for Script Development on DataFlux Func. After reading it, you can perform the most basic development and usage tasks on DataFlux Func.

1. Before You Begin

During the use of DataFlux Func,

Do not let multiple people log in to the same account, and do not let multiple people edit the same code at the same time.

To avoid issues such as code being overwritten or lost.

2. Write and Call the First Function

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

The return value of a function 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 Type	Characteristics	Applicable Scenario
Synchronous Func API	Generates a synchronous HTTP API. Returns the processing result directly after invocation	Scenarios with short processing time where the client needs the result immediately
Asynchronous Func API	Generates an asynchronous HTTP API. Responds immediately after invocation but does not return the processing result	Scenarios with longer processing time where the API call serves only as a start signal
Cron Job	Executes automatically based on Crontab syntax	Scenarios such as periodic synchronization / data caching, Cron Jobs, etc.

For details, see Script Development / Basic Concepts

Here, by creating a Func API for this function, you can call this function over the public network via HTTP.

Assuming the ID of the Func 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 Upload

DataFlux Func also supports uploading files through the Func API.

When you need to process uploaded files, you can add a files parameter to the function to receive the uploaded file information. After the file is uploaded, DataFlux Func automatically stores it in a temporary upload directory for the Script to process later.

# 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, with the following content:

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

For an example command for uploading files, see Script Development / Basic Concepts / Func API / POST Simplified Parameter Passing

4. Receiving Non-JSON and Non-Form Data

Added in version 1.6.9

In some cases, requests may be initiated by third-party systems or applications in their specific format, and the request body is not in JSON or Form format. In such cases, you can use **data as the input parameter and call it using the simplified POST form.

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 example 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 (e.g., Content-Type: text/plain)
        # The `data` parameter always contains a single `text` field holding the content
        return f"Text: {data['text']}"

    elif 'base64' in data:
        # When the request body is in an unparseable format (Content-Type: application/xxx)
        # The `data` parameter always contains a single `base64` field holding 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 Is in 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!'