コンテンツにスキップ

スクリプト開発 / 基本概念

DataFlux Func には、DataFlux Func 固有の概念がいくつか存在します。このドキュメントでは、これらについて説明します。

1. スクリプトセット、スクリプトと関数

スクリプトセット、スクリプト、関数は「開発 / スクリプトライブラリ」で作成でき、DataFlux Func の中心的な概念です。ID は、ユーザーが作成 / コード作成時に直接指定します。

  • 「スクリプトセット」は複数のスクリプトの集合であり、ID は作成時にユーザーが直接指定し、スクリプトのみを含めることができます。
  • 「スクリプト」は Python スクリプトそのものであり、必ずいずれかのスクリプトセットに属します。ID は作成時にユーザーが直接指定します。
  • 「関数」は DataFlux Func において、@DFF.API(...) デコレータで装飾された最上位の関数を指し、関数 API、定期実行タスクなどから呼び出しのエントリポイント関数として使用できます。

スクリプトセットはフォルダではありません

スクリプトセットはフォルダに似ていますが、この「フォルダ」は一般的な Python コーディングにおけるフォルダとは関係ありません

DataFlux Func でコーディングする際には、スクリプトセット、スクリプト、関数の ID が頻繁に登場し、これらの ID は密接に関連しています。

スクリプトセット、スクリプト、関数 ID の関係

スクリプトセット、スクリプト、関数の階層関係に従い、下位概念の ID には必ず上位概念の ID が含まれます。

ID が demo のスクリプトセットが存在するとします。このスクリプトセットに属するすべてのスクリプトは、必ず demo__（二重アンダースコア）で始まります。

さらに、このスクリプトセットに ID が demo__testのスクリプトがあり、関数 def hello(...) を含む場合、その関数の ID は demo__test.hello になります。

ID の例は次の表のとおりです。

概念 ID 例
スクリプトセット demo
スクリプト demo__test
関数 demo__test.hello

コーディングにおける相互参照

DataFlux Func のスクリプトでは、別のスクリプトを参照してコードを再利用できます。

スクリプト demo__script_a が存在し、関数 func_a() を含むとします。その場合、スクリプト demo__script_b 内でこの関数を参照するには、次の方法を使用できます。

demo__script_a
1
2
def func_a():
    pass
demo__script_b
1
2
3
4
import demo__script_b

def test():
    return demo__script_b.func_a()

Python の as 文も同様に使用できます。

demo__script_b
1
2
3
4
import demo__script_b as b

def test():
    return b.func_a()

from ... import 文を使用して、必要な関数だけをインポートすることもできます。

demo__script_b
1
2
3
4
from demo__script_b import func_a

def test():
    return func_a()

同じスクリプトセットに属するスクリプト同士の参照では、スクリプトセット ID を省略し、__（二重アンダースコア）で始まる短縮形で表すことができます。

demo__script_b
1
2
3
4
from __script_b import func_a

def test():
    return func_a()

できるだけ短縮形を使用する

スクリプトセット内部での相互参照は、できるだけ短縮形（つまりスクリプトセット ID を省略し、__ で始まる形式）を使用する必要があります。

こうすることで、スクリプトセット全体をクローンしてスクリプトセット ID が変わった後も、クローンされた新しいスクリプトセット内のコードは、このスクリプトセット内のスクリプトを正しく参照できます。

2. コネクター

コネクターは「開発 / コネクター」で作成でき、DataFlux Func が提供する外部システムに接続するためのツールです。ID は作成時にユーザーが直接指定します。

実際、DataFlux Func で Python コードを記述することは、通常の Python とほとんど変わりません。開発者はコネクターを完全に無視して、コード内で自分で外部システムに接続することもできます。

ただし、コネクションプールの概念を持つ一部の外部システムでは、コネクターにコネクションプールが組み込まれており、関数が繰り返し実行される間も接続を維持し、外部システムとの接続の作成 / クローズを繰り返すことを回避できます。

ID が mysql のコネクターがすでに設定されているとします。このコネクターの操作オブジェクトを取得するコードは次のとおりです。

Python
1
mysql = DFF.CONN('mysql')

具体的なコネクターによって操作方法やパラメータは異なります。詳細は スクリプト開発 / コネクターオブジェクト DFF.CONN を参照してください。

3. 環境変数

環境変数は「開発 / 環境変数」で作成でき、DataFlux Func が提供するシンプルな Key-Value 設定読み取りツールです。ID は作成時にユーザーが直接指定します。

環境変数は、同じコードを異なる環境で実行するシナリオに特に適しています。

たとえば、スクリプトがアクセスするシステムがテスト / 本番環境を区別している場合、環境変数を設定することで、コードを変更せずにテスト / 本番環境を切り替えることができます。

ID が api_endpoint の環境変数がすでに設定されているとします。この環境変数の値を取得するコードは次のとおりです。

Python
1
api_endpoint = DFF.ENV('api_endpoint')

4. 関数 API

関数 API は「管理 / 関数 API」で作成でき、外部から DataFlux Func の関数を呼び出す一般的な方法です。呼び出しは同期または非同期を選択でき、同期実行の場合、関数の実行完了後に結果を呼び出し元に直接返すことができます。

関数に関数 API を作成すると、さまざまな呼び出し方法がサポートされます。

関数 API は GET、POST の 2 つの方式をサポートしています。2 つの異なる方式のパラメータ渡しは、どちらも「簡易形式」、「標準形式」をサポートしています。

また、POST 方式の「簡易」形式ではファイルのアップロードにも対応しています。以下は、各呼び出し方式の機能サポート一覧です。

呼び出し方式 kwargs パラメータの受け渡し kwargs パラメータの型 options の受け渡し ファイルアップロード 任意形式の Body の送信
GET 簡易形式 対応 文字列のみ 非対応 非対応 非対応
GET 標準形式 対応 JSON のデータ型 対応 非対応 非対応
POST 簡易形式 対応 文字列のみ 非対応 対応 対応
POST 標準形式 対応 JSON のデータ型 対応 非対応 非対応

受け渡し方式が異なると、パラメータの型に制限が生じる

kwargs のパラメータに文字列しか渡せない呼び出し方式では、関数内でパラメータの型変換を行う必要があります。関数 API 一覧で、「API 呼び出しサンプル」をクリックすると、具体的な呼び出し方式を確認できます。

次のような関数が存在するとします。

Python
1
2
3
@DFF.API('私の関数')
def my_func(x, y):
    pass

この関数用に作成された「関数 API」の ID が func-api-xxxxx であり、渡すパラメータが x=100（整数）、y="hello"（文字列）だとします。

では、さまざまな呼び出し方式は次のとおりです。

GET 簡易形式でのパラメータ渡し

関数のパラメータが比較的単純な場合は、GET 簡易形式でパラメータを渡すことができ、API がより直感的になります。

URL でパラメータを渡す場合、文字列の "100" と整数の 100 を区別できないため、 関数が呼び出されたときに受け取るパラメータはすべて文字列になります。 関数は自分でパラメータの型変換を行う必要があります。

Text Only
1
GET /api/v1/al/func-api-xxxxx/s?x=100&y=hello

読みやすくするため、例は URLEncode 前の内容です。実際の URL パラメータは URLEncode が必要です

GET 標準形式でのパラメータ渡し

場合によっては、POST リクエストを送信できない場合、GET 方式で API を呼び出すこともできます。

GET 標準形式でパラメータを渡す場合、kwargs 全体を JSON シリアライズし、URL パラメータとして渡すだけです。 パラメータは実際には JSON 形式で送信されるため、パラメータの元の型はすべて保持されます。 関数はパラメータの型変換を行う必要はありません。

この例では、関数が受け取る x パラメータは整数のままであり、型変換は不要です。

Text Only
1
GET /api/v1/al/func-api-xxxxx?kwargs={"x":100,"y":"hello"}

読みやすくするため、例は URLEncode 前の内容です。実際の URL パラメータは URLEncode が必要です

POST 簡易形式でのパラメータ渡し

場合によっては、リクエストボディが JSON の HTTP リクエストを送信できない場合、 Form フォームのようにパラメータを渡すこともできます。各フィールド名がパラメータ名になります。

Form フォームでデータを送信する場合、文字列の "100" と整数の 100 を区別できないため、関数が呼び出されたときに受け取るパラメータはすべて文字列になり、関数は自分でパラメータの型変換を行う必要があります。

Text Only
1
2
3
4
POST /api/v1/al/func-api-xxxxx/s
Content-Type: x-www-form-urlencoded

x=100&y=hello

また、POST 簡易形式でのパラメータ渡しは、ファイルアップロード（パラメータ/フィールド名は files である必要があります）にも追加で対応しています。 form-data/multipart 方式で処理する必要があります。

ページの HTML コード例は次のとおりです。

HTML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
<html>
    <body>
        <h1>ファイルアップロード</h1>
        <input id="file" type="file" name="files" required />
        <input id="submit" type="submit" value="アップロード"/>
    </body>
    <script>
        // 関数 API アドレス（このページと DataFlux Func が同じドメインにない場合は、http://domain:port/api/v1/al/func-api-xxxxx/s と完全に記述する必要があります）
        // 注意：ファイルのアップロードには簡易形式の関数 API を使用する必要があります
        var API_URL = '/api/v1/al/func-api-xxxxx/s';

        document.querySelector('#submit').addEventListener('click', function(event) {
            // アップロードボタンをクリックすると、FormData オブジェクトを生成してリクエストボディとして送信します
            var data = new FormData();
            data.append('x', '100');
            data.append('y', 'hello');
            data.append('files', document.querySelector('#file').files[0]);

            var xhr = new XMLHttpRequest();
            xhr.open('POST', API_URL);
            xhr.send(data);
        });
    </script>
</html>

POST 標準形式でのパラメータ渡し

POST 標準形式でのパラメータ渡しは、最も一般的な呼び出し方法です。 パラメータは JSON 形式でリクエストボディとして送信されるため、パラメータの元の型はすべて保持されます。 関数はパラメータの型変換を行う必要はありません。

この例では、関数が受け取る x パラメータは整数のままであり、型変換は不要です。

Text Only
1
2
3
4
5
6
7
8
9
POST /api/v1/al/func-api-xxxxx
Content-Type: application/json

{
  "kwargs": {
    "x": 100,
    "y": "hello"
  }
}

5. 定期実行タスク

定期実行タスクは「管理 / 定期実行タスク」で作成でき、DataFlux Func が関数を定期的に自動で呼び出すために使用します。

関数に定期実行タスクを作成すると、関数は指定された Crontab 式に従って定期的に実行され、外部からの呼び出しは不要です。

このため、実行される関数のすべてのパラメータが満たされている必要があります。すなわち、

  1. 関数がパラメータを必要としない
  2. 関数がパラメータを必要とするが、すべてオプションパラメータである
  3. 関数が必須パラメータを必要とし、定期実行タスクでその具体的な値を設定する

関数の実行時に属する実行機能を判別する

関数に「定期実行タスク」と他の実行機能が同時に設定されており、異なる実行機能ごとに処理を区別したい場合は、組み込み変数 _DFF_CRONTAB を判定することで区別できます。

Python
1
2
3
4
5
6
7
8
9
@DFF.API('私の関数')
def my_func(x, y):
    result = x + y

    if _DFF_CRON_EXPR:
        # 定期実行タスクのときだけログを出力する
        print(f'x + y = {result}')

    return