実行時に受け取るパラメーター
アクションの実行時、任意の値を実行時の引数（以下パラメーター）として渡すことができます。
設定したパラメーターは、アクションの実行内容に相当するSQLやAPI呼び出しの中で、{{ パラメーター名 }}の形式で利用できます。
パラメーターの追加方法
パラメーターはアクション設定画面の基本情報の設定から追加できます。
パラメーター名とその種類（後述）を設定することで、アクション実行画面で設定したパラメーターを入力するフォームの入力欄が生成されます。
パラメーターの種類
パラメーターは入力形式に応じて異なるフォームを生成できるように、いくつかの種類が用意されています。
入力値の種類という表記がされた項目をクリックすると、種類の詳細設定を行なうモーダルが表示されます。
以下のドキュメントでは種類ごとの設定内容について説明します。
テキスト
テキストは通常の文字列を扱う場合に設定するパラメーターの種類です。
- 入力必須かどうか
- 初期値
- 選択形式にする場合の選択候補
- 正規表現による入力値チェック
を設定できます。
数値
数値で値を扱う場合に設定するパラメーターの種類です。
- 入力必須かどうか
- 初期値
- 選択形式にする場合の選択候補
日付
日付や時刻の情報を値として扱う場合に設定するパラメーターの種類です。
- 入力必須かどうか
- 初期値
- 日付だけでなく時刻も詳細に含めるか
- UNIX TIMESTAMP形式で送信するか
- 日付・時刻のフォーマット
ファイル
ファイルアップロードする形式で値として扱う場合に設定するパラメーターの種類です。
- 入力必須かどうか
ファイル形式の場合、{{ パラメーター名 }}のような値の利用はできません。
主にHTTP APIでの利用を想定しており、アップロードするform-dataのキーに、値がファイル形式であることと紐付けるファイル形式のパラメーターを設定する必要があります。
実行画面ではファイルアップロード用のフォームが表示されます。
システム値
システム値はベースマキナ上の処理の結果（例：ページネーション設定時の情報）を値に紐づける際に設定するパラメーターの種類です。
ユーザー自身がシステム値を任意入力で変更することは想定されていません。
特に紐付けがされていない場合は空文字列として送信されます。
システム値を実際に利用する例としてページネーションの設定があります。
ぜひそちらのドキュメントもご確認ください。
SQL
SQL系のアクションを実行するときに設定するパラメーターの種類です。
通常のパラメーターは、SQLアクションに埋め込まれる時に、自動的にプレースホルダーへの置換が行われ安全に実行されます。
SQL形式のパラメーターは、アクション実行時にSQLの実行内容そのものを変更できます。下記の項目を設定できます。
- 入力必須かどうか
- 初期値
- 選択形式にする場合の選択候補
例えば、下記のようなMySQLアクションが存在するとします。
この時、下記のようにパラメーターを設定すると、実行されるSQLは次の内容になります。
SELECT文のテーブル名に相当する箇所が、SQL形式のパラメーターによって置き換えられています。
真偽値
値を真・偽の2値で表現したいときに設定するパラメータの種類です。
真の場合、偽の場合のそれぞれに対応する値を設定し、アクションの設定内で使用できます。
下記の例では、ユーザーのプラン情報を使った検索で、プレミアム会員かどうかの値を真偽値として扱う例を示しています。
アクション実行時は、真偽値のパラメータはチェックボックス形式で表示され、チェックされているときは真の場合の値、チェックされていないときは偽の場合の値が入力されます。
JSON値
JSONの中で使う値を設定するパラメーターの種類です。
通常のパラメーターもJSONとして送信できますが、JSON値として設定されたパラメーターは、置き換えるときに値の種類に応じてクオーテーションが自動で付与されます。
また、値を入力したくない場合に、空文字や0ではなく null を値として設定できます。
JSON値のパラメーターでは、置き換え方法が異なる点と null 値の扱い以外、他の種類のパラメーターとほぼ同様に扱うことができます。
「JSON値の種類」という選択肢の中で、「テキスト・数値・日付」の3種類から値の種類を選択できます。
ただし、「入力必須かどうか」は項目として選べません。
これは他の種類のパラメーターと異なり、nullを入力可能にするのがJSON値の役割の1つであるためです。
JSON値は種類に応じて以下のように置き換えられます。
| 型 | 値 |
|---|---|
| 文字列 | 入力値にダブルクオーテーションを付与した文字列 |
| 数値 | 入力値そのままの文字列 |
| 日付 | ダブルクオーテーションを付与した文字列 |
| 日付(UnixTime) | 入力値そのままの文字列 |
文字列や日付（Unixtime以外）の値には、自動でクオーテーションがつきます。
実際にJSON値を使用したリクエストの設定例は、以下の通りです。
実行画面、ならびに実行結果は以下のようになります。
「値にnullを設定する」というトグルが表示され、ONにされた値は送信時にnullが設定されます。
URLパラメーターによる初期値の設定
別のアクションからの画面遷移などで、URLパラメーターを指定すると、JSON値の初期値は次のように設定されます。
| URLパラメーター | 初期値 |
|---|---|
| キーなし | 初期値が設定されていたら初期値。設定されてないならnull。 |
| ?key=（空文字指定） | null |
| ?key=aaa | テキスト：aaa, 数値：0, 日付：aaa |
| ?key=123 | テキスト：123（文字列）, 数値：123, 日付：123 |
| ?key=2022-01-01 | テキスト：2022-01-01, 数値：0か設定された初期値, 日付：2022-01-01 |
上記の表の通り、遷移時に初期値に関わらずnullを設定したい場合は、パラメーターに空文字を設定していただくと画面遷移後にnullとして扱われます。
複数の選択肢を用意する
テキストと数値は複数の値から選択するような入力形式を取ることができます。
選択肢は値だけでなく、ラベル（フォーム上で表示される表記）も設定できます。
また複数選択肢の形式に切り替えた際には、初期値も選択候補の中から選択できるようになっています。
実際に実行画面のフォーム上の選択肢にはラベル、またはラベルが未設定の場合は値の表記がそのまま表示されます。
アクション実行時には選択された候補の値がアクションに渡されます。
ラベルはあくまでフォームの見た目を調整する用途でお使いください。
