ユーザ関数

アクションはJavaScriptを使って記述しますが、繰り返し使うJavaScriptの内容やSQLやRESTなど呼び出しに準備が必要なものについてはユーザ関数を利用します。
ユーザ関数はGUIを使って作成し、作成した関数はアクションから呼び出すことが可能です。

ユーザ関数の種類

ユーザ関数は、2種類存在します。

関数	スコープ
ローカル関数	アクション内のみ 他のアクションから直接呼び出すことはできません。
グローバル関数	アプリ アプリ内の他のアクションで利用することが可能です。

ノート

グローバル関数の呼び出しには、$global を利用します。

JavaScript

アクションで繰り返し使うJavaScript処理は関数として登録することができます。

作成方法

1. アクションエディタの左パネルにある[追加]ボタンをクリックします。
2. 関数タイプから[スクリプト] を選択します。
3. 関数名に任意の英字から始まる英数字+アンダースコアの文字列を入力します。
4. [保存]ボタンをクリックします。
5. 関数タイプを選択します。
6. JavaScript 関数のエディタを表示します。
7. JavaScript エディタに関数処理を記述します。

ノート

関数内で非同期処理を呼び出す場合は、関数を非同期に設定する必要があります。

引数

引数は唯一の param オブジェクトになります。

名前	型	引数追加
param	オブジェクト	不可

JavaScript 関数の中で引数 param から値を取得するには、次のように関数エディタで記述します。

const input1 = param.arg1;
const input2 = param.arg2;

return input1 + input2;

一方、関数を呼び出す場合は以下のように呼び出します。

const obj = {} ;// 空オブジェクト作成
obj.arg1 = 10;
obj.arg2 = 20;

myfunc(obj);

ノート

オブジェクトリテラルを使って生成することも可能です。
const obj = {arg1: 10, arg2: 20};

サンプル

２つの数値を加算するJavaScript関数をアクションで利用するサンプルを示します。

ステップ 1

UIに引数となる3つの数値フィールドとボタンを用意します。

コンポーネント	コンポーネント ID	コンポーネントラベル
数値フィールド	number_field_1	数値フィールド 1
数値フィールド	number_field_2	数値フィールド 2
数値フィールド	number_ans	計算結果フィールド
ボタン	button_calc	計算ボタン

ステップ 2

button_calcのアクションエディタを開き、 my_funcという名前でJavaScript関数を作成します。

[my_funcの内容]

const input1 = param.arg1;
const input2 = param.arg2;

return input1 + input2;

ステップ 3

アクションボードにmy_funcの呼び出しを行い、結果を計算結果フィールドに表示する記述を行います。

const obj = {};
obj.arg1 = $ui.number_field_1.value;
obj.arg2 = $ui.number_field_2.value;
$ui.number_ans.value = my_func(obj);

ステップ 4

アクションを保存し、アプリケーションのデプロイを行います。

ステップ 5

アプリケーションから数値フィールド1, 数値フィールド2に数値を入力し、計算ボタンをクリックします。計算結果フィールドに加算結果が表示されることを確認します。

SQL

データベースに SQL を発行してその結果を取得します。SQL エディタにはSQL文のみを記述します。

ノート

• 1ステートメントの実行を推奨します。
  複数ステートメントを実行した場合、結果のオブジェクトは各ステートメントの結果によって不定になります。
• SQLでデータベースオブジェクトに接頭辞としてデータベース名の指定は必須ではありません。
  データベース名を指定した場合は、指定したデータベースに接続します。
  データベース名を指定しない場合は、[アプリケーション設定] -[一般設定] の[既定データベース]に指定したデータベースに接続します。
  データベース名の指定がなく、かつ既定データベースも設定していない場合は、アクション実行時にエラーになりますのでご注意ください。
• VIEWやSQL内でCONCAT句などを利用して生成した文字列との比較を行う場合に、異なる照合順序を持つ文字列の比較によりIllegal mix of collationsのエラーが発生する可能性があります。
  上記エラーを回避するためには、生成した文字列の照合順序をCOLLATE句を利用しutf8mb4_0900_ai_ciに指定をお願いします。

SELECT * FROM table_name WHERE column1 LIKE CONCAT(column2,column3) COLLATE utf8mb4_0900_ai_ci;

作成方法

1. アクションエディタの左パネルにある[追加]ボタンをクリックします。
2. 関数タイプから[SQL]を選択します。
3. 関数名に任意の英字から始まる英数字+アンダースコアの文字列を入力します。
4. [保存]ボタンをクリックします。
5. SQL 関数のエディタを表示します。
6. SQL エディタにSQLを記述します。

引数

引数は唯一の param オブジェクトになります。

名前	型	引数追加
param	オブジェクト	不可

ノート

引数についてはすべてのユーザ関数において共通です。

非同期関数とawait演算子

SQL関数は非同期で処理されます。値が返るまで待機するために、SQL関数実行時には、次のようにawait演算子を使用してください。

戻り値 = await SQL関数

戻り値

SQL関数の戻り値は次のプロパティを含むオブジェクトになります。

プロパティ	型	説明
data	object array	SQL結果のROWデータの配列、またはDMLステートメントを実行した結果
sqlState	string	SQLSTATE 値
errorCode	string	エラーコード
errorMessage	string	エラーメッセージ

ノート

sqlState、errorCode、errorMessageはSQL エラーが発生した場合のみ値が入ります

トランザクション制御について

トランザクションはアクション単位で行われ、コミットおよびロールバックは暗黙的に行われます。 アクション内で複数のSQL関数がコールされた場合、１つでも例外が発生するとロールバックされます。

ノート

例外処理について

• try-catch文で例外をcatchした場合、catch句でthrowを行わなければ呼び出し側のアクションが例外を補足しないためロールバックは行われません。

ロールバックできないステートメント

• データベースの作成または削除、テーブルやストアドルーチンの作成、削除、変更などのデータ定義言語 (DDL) ステートメントについては、ロールバックされません。これらのステートメントを含まないようにトランザクションを設計ください。

サンプル

アクションにおいてテーブルに向けて SELECT の SQL を発行し、結果を JSON 文字列でテキストエリアコンポーネントに表示する例を説明します。

ステップ 1

UI に結果を表示するテキストエリアコンポーネントとアクションを実行するボタンを用意します。

コンポーネント	コンポーネント ID	コンポーネントラベル
テキストエリア	text_area_1	結果 JSON
ボタン	button_sql	SELECT

ステップ 2

mydb という名前のデータベースにt1という名称でテーブルを以下の構成で作成します。

カラム名	データタイプ	M	D	fsp	PK	NN	UQ	AI
id	INT				True	True
name	VARCHAR	20

カラムのデータタブよりテスト用データを格納しておきます。

id	name
1	a
2	b

ステップ 3

button_sqlのアクションエディタを開き、 sql1という名前でSQL関数を作成します。

[sql1の内容]

select * from mydb.t1;

ステップ 4

アクションボードに SQL 関数の呼び出しを行い、データ取得結果をテキストエリアに表示する記述を行います。

ノート

SQL 関数呼び出し時には、必ず await 演算子を使用する必要があります。

[アクションボードの内容]

const obj = await sql1();
$ui.text_area_1.value = JSON.stringify(obj.data);

ステップ 5

アクションを保存し、アプリケーションのデプロイを行います。

ステップ 6

アプリケーションから SELECT ボタンをクリックします。結果 JSON テキストエリアに SQL の SELECT 結果が JSON 形式で表示されることを確認します。

[{"id":1,"name":"a"},{"id":2,"name":"b"}]

REST

REST 関数は REST API や Amazon API Gateway を呼び出すための関数です。

作成方法

1. アクションエディタの左パネルにある[追加]ボタンをクリックします。
2. 関数タイプから[REST]を選択します。
3. 関数名に任意の英字から始まる英数字+アンダースコアの文字列を入力します。
4. [保存]ボタンをクリックします。
5. REST 関数のエディタを表示します。
6. REST エディタに REST API を呼び出すための設定をします。

基本設定

項目	説明
関数名	関数作成時に設定した名称が表示されています。
引数	引数は他のユーザ関数と同様、唯一の param オブジェクトです。
メソッド	呼び出すAPIによって、次の中から選択します。 GET POST PUT PATCH DELETE
URL	REST API のURLを記入します。 任意の箇所で次の書式を使ってパラメータ値を埋め込めます。 ${param.property_name}
リクエストヘッダ	リクエストヘッダを設定します。 [追加]ボタンをクリックすると、ヘッダ名と値のエントリを追加できます。 ヘッダ名は代表的なものが選択肢にありますが、任意入力も可能です。
リクエストボディ	POST/PUT/PATCH/DELETEメソッドの場合、リクエストボディの指定が可能です。 ヘッダの Conent-Type の指定により、入力形式が変わります。
バイナリレスポンスを取得	レスポンスの戻り値は string ですが、バイナリを返却するサービスの場合はこのチェックボックスにチェックを入れることで、Buffer オブジェクトとして戻り値を取得できます。

ノート

• レスポンス最大データサイズの変更は行えず、最大4MBまで対応しております。
• ただし、バイナリレスポンスを取得にチェックをつけている場合にはサイズに関係なく取得可能となります。

リクエストヘッダ

リクエストヘッダは[ヘッダー]タブから設定します。リクエストヘッダは選択肢として用意されていますが、直接入力することも可能です。

ヘッダ名	値
Accept	*/* application/* audio/* image/* text/*
Accept-Charset	utf-8
Accept-Encoding	compress deflate gzip
Accept-Language	en-US ja
Authorization
Cache-Control	max-age=3600 no-cache no-store
Connection	close keep-alive
Content-Length
Content-Type	application/json application/octet-stream application/x-www-form-urlencoded application/xml multipart/form-data text/css text/html text/plain
Cookie	name=value name=value; name2=value2; name3=value3
Date	Wed, 21 Oct 2015 07:28:00 GMT
Expect	100-continue
From	webmaster@example.org
Host
Proxy-Authorization
Referer	https://example.com/
User-Agent
X-Amz-Content-Sha256
X-Amz-Date
X-Amz-Security-Token
X-API-Key

ノート

X-API-Key は AWS API Gateway のAPIキーです。

リクエストボディ

リクエストボディは[ボディ]タブから設定します。リクエストヘッダの Content-Type 指定により入力形式が変化します。

リクエストヘッダの Content-Type	入力形式	入力内容
application/json	テキストエリア	テキスト
application/octet-stream	テキストフィールド	ファイルパス
application/x-www-form-urlencoded	[追加]ボタン テキストフィールド (名前) テキストフィールド (値)	パラメータ名 パラメータ
application/xml	テキストエリア	テキスト
multipart/form-data	[テキストパート追加]ボタン [ファイルパート追加]ボタン テキストフィールド(名前) テキストフィールド (値)	パラメータ名 パラメータ値
text/css	テキストエリア	テキスト
text/html	テキストエリア	テキスト
text/plain	テキストエリア	テキスト

非同期関数と await 演算子

REST 関数は非同期で処理されます。値が返るまで待機するために、REST 関数実行時には、次のように await 演算子を使用してください。

戻り値 = await REST 関数

戻り値

REST関数の戻り値は次のプロパティを含むオブジェクトになります。

プロパティ	型	説明
status	object	HTTPステータスオブジェクト プロパティ 型 code number text string
headers	object	レスポンスヘッダ
body	string | Buffer	レスポンス
errorMessage	string	エラーメッセージ

サンプル

アクションにおいて GET タイプの REST API（パラメータ１つ）を呼び出し、結果を JSON 文字列でテキストエリアコンポーネントに表示する例を説明します。

ノート

サンプルで用いるREST API はクエリーパラメータに入力した文字列を「Hello 」の後に連結した文字列を返します。

パラメーター	JSON 文字列
URL	https://bl2dqouo8g.execute-api.ap-northeast-1.amazonaws.com/dev/res1?name=文字列
API キー	bcVrf52Wvs3jAKMFYOK596hlLsTtmczH5tTCjQxI

ステップ 1

UIにテキストフィールド、テキストエリア、ボタンを用意します。

コンポーネント	コンポーネント ID	コンポーネントラベル
テキストフィールド	text_field_name	名前
テキストエリア	text_area_response	レスポンス
ボタン	button_rest	REST API

ステップ 2

button_restのアクションエディタを開き、 my_restという名前でREST関数を作成します。

[my_restの基本設定]

関数名	my_rest
引数	param
メソッド	GET
URL	https://bl2dqouo8g.execute-api.ap-northeast-1.amazonaws.com/dev/res1?name=${param.name}
リクエストヘッダ	名前 - X-API-Key 値- bcVrf52Wvs3jAKMFYOK596hlLsTtmczH5tTCjQxI
バイナリ取得	チェックなし

ステップ 3

アクションボードに REST 関数の呼び出しを行い、レスポンスをテキストエリアに表示する記述を行います。

ノート

REST 関数呼び出し時には、必ず await 演算子を使用する必要があります。

[アクションボードの内容]

const encoded_name = encodeURIComponent($ui.text_field_name.value);
const obj = {name: encoded_name};
const ret = await my_rest(obj);
$ui.text_area_response.value = ret.body;

** ステップ 4**

アクションを保存し、アプリケーションのデプロイを行います。

ステップ 5

アプリケーションから[名前]テキストフィールドに任意の文字列を入力し、[REST API]ボタンをクリックします。[レスポンス]テキストエリアに「Hello 入力文字列」が表示されることを確認します。

(例) Hello World!

同期のJavaScript関数で非同期関数を呼び出す時のサンプル

JavaScript関数で非同期関数(SQL関数、REST関数、ビルトイン関数の$fn.getFile等)を呼び出す際は、サンプルの様にPromiseオブジェクトとして返却する必要があります。
下記executeScript関数内では、REST関数、SQL関数、JavaScript関数、ビルトイン関数を実行し、結果を返却する例を記載しています。
アクションボードでは、executeScript関数から返却された結果を、各テーブルコンポーネントの値に設定する例を記載しています。

アクションボード

{const { books, tasks, plans, files } = await executeScript();}

// Books
$ui.books.value = books.map((book) => ({
    bookTitle: book?.volumeInfo?.title,
    bookPublisher: book?.volumeInfo?.publisher,
    bookPublishedDate: book?.volumeInfo?.publishedDate,
}));

// Tasks
$ui.tasks.value = tasks;

// Plans
$ui.plans.value = plans.map((plan) => ({
    planId: plan.id,
    planName: plan.name,
}));

// Files
$ui.files.value = files.map((fileName) => ({ fileName }));

JavaScript関数：executeScript（関数タイプ：同期）

const execute = async () => {
    // REST関数呼び出し
    const sendResult = await sendGetBooksRequest();
    const body = JSON.parse(sendResult.body);
    const books = body.items;

    // SQL関数呼び出し
    const selectResult = await selectTaskRecords();
    const tasks = selectResult.data;

    // JavaScript関数呼び出し
    const plans = getPlans();

    // ビルトイン関数呼び出し
    const files = await $fn.getFileNames("/");

    return {
        books,
        tasks,
        plans,
        files,
    };
};

// Promiseオブジェクトを返却する
return execute();

JavaScript関数：getPlans（関数タイプ：同期）

return [
    {
        name: "プラン1",
        id: "p001",
    },
    {
        name: "プラン2",
        id: "p002",
    },
    {
        name: "プラン3",
        id: "p003",
    },
];