コード管理
SDK
defineAction

defineAction

アクションを定義する関数です。typeフィールドで種別を指定し、種別に応じたフィールドを設定します。

typeによって設定できるフィールドが型で絞り込まれるため、存在しないフィールドを指定するとTypeScriptのコンパイルエラーになります。

以下の設定項目はコード管理の対象外です。これらはベースマキナの管理画面から設定してください。

  • 結果の加工（加工スクリプト、ページネーション）
  • 環境ごとの有効/無効
  • 環境ごとのバージョン

共通フィールド

すべてのアクション種別で使用できるフィールドです。

フィールド型必須説明
idstringはいアクションの識別子。最大128文字で、使用できる文字は英数字・アンダースコア・ハイフン（^[a-zA-Z0-9_-]+$）
previousIdstringいいえ変更前の id。既存アクションの id を bm sync で変更するために宣言する（下記参照）
namestringはいアクション名
descriptionstringいいえ説明
preferJobExecutionbooleanいいえtrueにすると管理画面でこのアクションの実行UIがジョブ実行形式になる
jobDetailVisibility"EXECUTOR_ONLY" | "PUBLIC"いいえジョブ実行結果の閲覧範囲。EXECUTOR_ONLYは実行者のみ、PUBLICは全ユーザーが閲覧可
reviewSettingIdstringいいえレビュー設定の識別子。設定すると、依頼したレビューが承認されてはじめてアクションが実行できるようになる
notificationSettingsNotificationSettingsConfigいいえ成功時・エラー時の通知設定
permissions[PermissionTarget, ...]（非空）いいえ実行を許可する対象。未指定の場合はプロジェクト内の全ユーザーに実行が許可される。指定する場合は1件以上必要

previousId

previousId は、コード管理で既存アクションのidを変更したいときに、変更前のidを宣言します。bm sync は previousId を見て「旧idのアクションを削除 + 新idで新規作成」ではなく 既存アクションの id の変更 として扱います。

// before（typo を含む id）
export default defineAction({
  id: "fetch-user",
  name: "ユーザー取得",
  // ...
});
 
// after（id を変更）
export default defineAction({
  id: "fetch-user-detail",
  previousId: "fetch-user",
  name: "ユーザー詳細取得",
  // ...
});

bm sync --dry を実行すると id 変更 セクションに <previousId> → <id> の形で表示されます。適用後のPRでは、previousId を削除できます（dry-runのNotesに削除候補として表示されます）。

2つのアクションのidを入れ替えるような変更は現在サポートされていません。たとえば A.previousId: "B" と B.previousId: "A" を同時に宣言する変更です。

permissions

permissionsは実行を許可する対象の配列です。未指定の場合はプロジェクト内の全ユーザーに実行が許可されます。

permissions: [
  { type: "user", id: "<ユーザーID>" },
  { type: "userGroup", id: "<ユーザーグループID>" },
  { type: "javascriptAction", id: "<JavaScriptアクションの識別子>" },
];
type説明
"user"特定のユーザーに実行を許可
"userGroup"特定のユーザーグループに属するユーザーに実行を許可
"javascriptAction"JavaScriptアクションの判定結果に従って実行を許可

notificationSettings

アクションの成功時・失敗時に通知するための設定です。

notificationSettings: {
  onSuccess: {
    notificationMethodId: "<通知方法の識別子>",
    mentionTargetUserIds: ["<ユーザーID>"],
    message: { type: "text", value: "ユーザー作成が成功しました" },
  },
  onError: {
    notificationMethodId: "<通知方法の識別子>",
    message: { type: "text", value: "ユーザー作成に失敗しました" },
  },
};
フィールド型必須説明
onSuccess.notificationMethodIdstringはい通知方法の識別子
onSuccess.mentionTargetUserIdsstring[]いいえメンション対象ユーザー
onSuccess.message{ type: "text"; value: string }いいえ通知メッセージ
onError.notificationMethodIdstringはい通知方法の識別子
onError.mentionTargetUserIdsstring[]いいえメンション対象ユーザー
onError.message{ type: "text"; value: string }いいえ通知メッセージ

onSuccessとonErrorはどちらも省略可能で、必要な方だけ指定できます。messageを省略すると、通知方法のデフォルトメッセージが使われます。

Amazon Athenaアクション

import { defineAction } from "@basemachina/sdk/oac";
 
export const queryAccessLogs = defineAction({
  id: "query-access-logs",
  name: "アクセスログ検索",
  type: "amazonAthena",
  dataSource: "athena-prod",
  statements: [
    {
      sql: "SELECT * FROM access_logs WHERE user_id = {{ userId }}",
    },
  ],
  parameters: [{ type: "TEXT", name: "userId", required: true }],
});
フィールド型必須説明
type"amazonAthena"はいAmazon Athenaアクションを指定
dataSourcestringはいAmazon Athenaデータソースの識別子
statementsSqlReadStatement[]はい実行するSQL文（1件以上）。SELECT系クエリのみサポート
parseColumnTypeJSONEnabledbooleanいいえJSON型の列の値をJavaScriptの配列やオブジェクトに変換するかどうか。未指定時は変換する（true）
parametersParameterConfig[]いいえパラメーター定義（下記参照）

statementsの各要素は以下の通りです。

フィールド型必須説明
sqlstringはい実行するSQL文。{{ paramName }}でパラメーターを埋め込める
titlestringいいえSQL文のタイトル

Amazon S3アクション

operationでバケットへの操作種別を指定し、操作に応じたフィールドを設定します。

import { defineAction } from "@basemachina/sdk/oac";
 
export const uploadInvoice = defineAction({
  id: "upload-invoice",
  name: "請求書をアップロード",
  type: "amazonS3",
  dataSource: "s3-invoices",
  bucket: "invoices-prod",
  operation: "UPLOAD",
  objectKey: "invoices/{{ invoiceId }}.pdf",
  fileParameter: "file",
  parameters: [
    { type: "TEXT", name: "invoiceId", required: true },
    { type: "FILE", name: "file", required: true },
  ],
});
フィールド型必須説明
type"amazonS3"はいAmazon S3アクションを指定
dataSourcestringはいAmazon S3データソースの識別子
bucketstringはい操作対象のバケット名。{{ paramName }}でパラメーターを埋め込める
operationdiscriminated unionはいバケットへの操作種別と関連フィールド（下記参照）
parametersParameterConfig[]いいえパラメーター定義（下記参照）

operationの指定方法

operationの値ごとに必須フィールドが変わります。

// オブジェクトをアップロード
operation: "UPLOAD",
objectKey: "invoices/{{ invoiceId }}.pdf",
fileParameter: "file",
 
// オブジェクトをダウンロード
operation: "DOWNLOAD",
objectKey: "invoices/{{ invoiceId }}.pdf",
 
// バケット内のオブジェクト一覧を取得
operation: "LIST",
 
// 署名付きURLを発行
operation: "ISSUE_SIGNED_URL",
objectKey: "invoices/{{ invoiceId }}.pdf",
signedUrlMethod: "GET",
operation必須フィールド説明
"UPLOAD"objectKey、fileParameter指定したファイルパラメーターの内容をバケットのobjectKeyにアップロードする。fileParameterはparametersに定義したFILEパラメーターのnameと一致する必要がある
"DOWNLOAD"objectKeyバケットのobjectKeyからオブジェクトをダウンロードする
"LIST"なしバケット内のオブジェクト一覧を取得する
"ISSUE_SIGNED_URL"objectKey、signedUrlMethodobjectKeyに対する署名付きURLを発行する。signedUrlMethodは"GET"または"PUT"

objectKeyは{{ paramName }}でパラメーターを埋め込めます。

Amazon S3アクションでは、JSON / SQLの種別と、formatを省略したBOOL / ARRAY / TUPLEは使用できません。BOOL / ARRAY / TUPLEは必ずformatを指定してください。

BigQueryアクション

import { defineAction } from "@basemachina/sdk/oac";
 
export const fetchOrderStats = defineAction({
  id: "fetch-order-stats",
  name: "注文統計取得",
  type: "bigQuery",
  dataSource: "bigquery-analytics",
  statements: [
    {
      sql: "SELECT customer_id, SUM(amount) FROM orders WHERE date >= {{ startDate }} GROUP BY customer_id",
    },
  ],
  parameters: [
    { type: "DATE", name: "startDate", required: true, format: "YYYY-MM-DD" },
  ],
});
フィールド型必須説明
type"bigQuery"はいBigQueryアクションを指定
dataSourcestringはいBigQueryデータソースの識別子
statementsSqlReadStatement[]はい実行するSQL文（1件以上）。SELECT系クエリのみサポート
parseColumnTypeJSONEnabledbooleanいいえJSON型の列の値をJavaScriptの配列やオブジェクトに変換するかどうか。未指定時は変換する（true）
parametersParameterConfig[]いいえパラメーター定義（下記参照）

statementsの各要素はAmazon Athenaアクションと同じです。

Firestoreアクション

import { defineAction, readFile } from "@basemachina/sdk/oac";
 
export const fetchUsers = defineAction({
  id: "fetch-users",
  name: "ユーザー取得",
  type: "firestore",
  dataSource: "firestore-prod",
  code: readFile("./js-action-codes/fetch-users.ts"),
  parameters: [
    { type: "TEXT", name: "userId", required: true },
    {
      type: "BOOL",
      name: "active",
      format: { trueValue: "yes", falseValue: "no" },
    },
  ],
});
フィールド型必須説明
type"firestore"はいFirestoreアクションを指定
dataSourcestringはいFirestoreデータソースの識別子
codestringはい実行するスクリプト。firebase-admin SDKのfirestoreインスタンスを利用できる。readFile()の戻り値も指定可能（JavaScriptアクションと同様）
parametersParameterConfig[]いいえパラメーター定義（下記参照）

Firestoreアクションのパラメーターでは、FILE / JSON / SQLの種別と、formatを省略したBOOL / ARRAY / TUPLEは使用できません。BOOL / ARRAY / TUPLEは必ずformatを指定してください。

Google Cloud Storageアクション

設定方法はAmazon S3アクションと同じです。typeに"googleCloudStorage"を指定します。

import { defineAction } from "@basemachina/sdk/oac";
 
export const issueReportUrl = defineAction({
  id: "issue-report-url",
  name: "レポートのダウンロードURLを発行",
  type: "googleCloudStorage",
  dataSource: "gcs-reports",
  bucket: "reports-prod",
  operation: "ISSUE_SIGNED_URL",
  objectKey: "monthly/{{ yearMonth }}.csv",
  signedUrlMethod: "GET",
  parameters: [{ type: "TEXT", name: "yearMonth", required: true }],
});
フィールド型必須説明
type"googleCloudStorage"はいGoogle Cloud Storageアクションを指定
dataSourcestringはいGoogle Cloud Storageデータソースの識別子
bucketstringはい操作対象のバケット名。{{ paramName }}でパラメーターを埋め込める
operationdiscriminated unionはいバケットへの操作種別と関連フィールド
parametersParameterConfig[]いいえパラメーター定義（下記参照）

operationの指定方法と取りうる値、パラメーターで利用できない種別はAmazon S3アクションと同じです。詳しくはAmazon S3アクションのoperationをご参照ください。

Google Sheetsアクション

operationでシートへの操作種別を指定し、操作に応じたフィールドを設定します。

import { defineAction } from "@basemachina/sdk/oac";
 
// シートから読み取る
export const readMonthlyReport = defineAction({
  id: "read-monthly-report",
  name: "月次レポートを読み取る",
  type: "googleSheets",
  dataSource: "sheets-reports",
  spreadsheetId: "1AbCdEfGhIjK...",
  sheetId: 0,
  operation: "READ",
  a1Notation: "Sheet1!A1:D{{ rowCount }}",
  valueRenderOption: "UNFORMATTED_VALUE",
  parameters: [{ type: "NUMBER", name: "rowCount", required: true }],
});
 
// シートに行を追記する
export const appendOrder = defineAction({
  id: "append-order",
  name: "注文を追記",
  type: "googleSheets",
  dataSource: "sheets-orders",
  spreadsheetId: "1AbCdEfGhIjK...",
  operation: "APPEND_ROWS",
  rows: [
    [
      { value: "{{ orderId }}" },
      { value: "{{ customer }}" },
      { value: "{{ amount }}" },
    ],
  ],
  valueInputOption: "USER_ENTERED",
  parameters: [
    { type: "TEXT", name: "orderId", required: true },
    { type: "TEXT", name: "customer", required: true },
    { type: "NUMBER", name: "amount", required: true },
  ],
});
フィールド型必須説明
type"googleSheets"はいGoogle Sheetsアクションを指定
dataSourcestringはいGoogle Sheetsデータソースの識別子
spreadsheetIdstringはい対象スプレッドシートのID
sheetIdnumberいいえ対象シートのID。省略時は先頭シート
operationdiscriminated unionはいシートへの操作種別と関連フィールド（下記参照）
parametersParameterConfig[]いいえパラメーター定義（下記参照）

operationの指定方法

operationの値ごとに必須フィールドが変わります。

operation必須フィールド説明
"READ"valueRenderOptionシートからデータを読み取る。a1Notationでフィルター範囲を指定可（例: "Sheet1!A1:B10"）。{{ paramName }}でパラメーターを埋め込める
"APPEND_ROWS"rows、valueInputOptionシートに行を追記する。rowsは2次元配列で、各セルのvalueに{{ paramName }}でパラメーターを埋め込める

valueRenderOption / valueInputOptionの値は以下の通りです。

フィールド値説明
valueRenderOption"FORMATTED_VALUE" / "UNFORMATTED_VALUE"読み取り時の値の解釈方法。表示形式を適用した値か生の値かを指定
valueInputOption"RAW" / "USER_ENTERED"追記時の値の解釈方法。生のまま格納するか、ユーザー入力として解釈し数式を評価するかを指定

Google Sheetsアクションのパラメーターでは、FILE / JSON / SQLの種別と、formatを省略したBOOL / ARRAY / TUPLEは使用できません。BOOL / ARRAY / TUPLEは必ずformatを指定してください。

gRPCアクション

import { defineAction } from "@basemachina/sdk/oac";
 
export const fetchOrders = defineAction({
  id: "fetch-orders",
  name: "注文一覧取得",
  type: "grpc",
  dataSource: "orders-service",
  fullMethodName: "orders.OrderService/ListOrders",
  body: {
    payload: '{ "customerId": "{{ customerId }}" }',
  },
  parameters: [{ type: "TEXT", name: "customerId", required: true }],
});
フィールド型必須説明
type"grpc"はいgRPCアクションを指定
dataSourcestringはいgRPCデータソースの識別子
fullMethodNamestringはいgRPCメソッドの完全修飾名。形式は{package}.{Service}/{Method}
headers{ name: string; value: string }[]いいえリクエストヘッダー
body{ payload: string }いいえリクエストボディ。payloadはJSON文字列で指定し、内部で{{ paramName }}の形式でパラメーターを埋め込める
parametersParameterConfig[]いいえパラメーター定義（下記参照）

HTTP APIアクション

import { defineAction } from "@basemachina/sdk/oac";
 
export const fetchUser = defineAction({
  id: "fetch-user",
  name: "ユーザー取得",
  type: "httpApi",
  dataSource: "users-api",
  url: "/v1/users/{{ userId }}",
  method: "GET",
  headers: [{ name: "Authorization", value: "Bearer {{ authToken }}" }],
  parameters: [
    { type: "TEXT", name: "userId", required: true },
    { type: "TEXT", name: "authToken", required: true },
  ],
});
フィールド型必須説明
type"httpApi"はいHTTP APIアクションを指定
dataSourcestringはいHTTP APIデータソースの識別子
urlstringはいリクエストURL。{{ paramName }}でパラメーターを埋め込める
method"GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "PURGE"はいHTTPメソッド
headers{ name: string; value: string }[]いいえリクエストヘッダー。valueは{{ paramName }}でパラメーターを埋め込める
queryParams{ name: string; value: string }[]いいえURLクエリパラメーター。valueは{{ paramName }}でパラメーターを埋め込める
bodyオブジェクトいいえリクエストボディ（下記参照）。GET/HEADでは指定不可
validateStatusbooleanいいえ200系以外のレスポンスステータスコードをエラーとして扱うか。未指定時はtrue
parametersParameterConfig[]いいえパラメーター定義（下記参照）

bodyフィールド

bodyはcontentTypeによって構造が異なるdiscriminated unionです。送信するボディがない場合はbodyプロパティ自体を省略します。

// JSON
body: {
  contentType: "application/json",
  content: '{"id":"{{ userId }}"}',
}
 
// multipart/form-data
body: {
  contentType: "multipart/form-data",
  entries: [
    { name: "title", value: "{{ title }}" },
    { name: "image", fileParameter: "image" },
  ],
}
 
// application/x-www-form-urlencoded
body: {
  contentType: "application/x-www-form-urlencoded",
  entries: [{ name: "q", value: "{{ keyword }}" }],
}
 
// GraphQL
body: {
  contentType: "graphql",
  query: "query GetUser { user(id: {{ userId }}) { name } }",
  variables: '{"id":"{{ userId }}"}',
}
 
// Content-Type未指定（任意のテキスト）
body: {
  content: "raw payload here",
}
contentType必須フィールド説明
"application/json"contentJSON文字列
"multipart/form-data"entries（1件以上）nameとvalueまたはfileParameterで指定。fileParameterはFILEパラメーターのnameと一致する必要がある
"application/x-www-form-urlencoded"entriesnameとvalueのペア
"graphql"queryGraphQLクエリ。variablesはJSON文字列で指定
未指定contentContent-TypeをSDK側でつけない。MIMEを指定したい場合はheadersでContent-Typeを別途指定

JavaScriptアクション

import { defineAction, readFile } from "@basemachina/sdk/oac";
 
export const createUser = defineAction({
  id: "create-user",
  name: "ユーザー作成",
  type: "javascript",
  code: readFile("./js-action-codes/create-user.ts"),
  parameters: [
    { type: "TEXT", name: "email", required: true },
    { type: "NUMBER", name: "age", required: true },
  ],
});
フィールド型必須説明
type"javascript"はいJavaScriptアクションを指定
codestringはいJavaScriptコードまたはreadFile()の戻り値
parametersParameterConfig[]いいえパラメーター定義（下記参照）

コード本体の書き方

code: readFile("./js-action-codes/<id>.ts")で参照するファイルは、デフォルトエクスポートの関数として記述します。第1引数にdefineActionで宣言したアクションパラメーター、第2引数に事前定義パラメーターを受け取ります。

ダウンロードしたtsconfig.jsonがそのまま@basemachina/sdk/tsconfig.code.jsonを継承しているため、@basemachina/actionのimportパスは追加設定なしで型定義に解決されます。

TypeScriptで書く場合（推奨）

@basemachina/actionからJSActionHandler型をインポートし、アクションIDを型引数で指定します。defineActionで宣言したパラメーターの型が自動で推論されます。

// src/actions/js-action-codes/create-user.ts
import { executeAction, type JSActionHandler } from "@basemachina/action";
 
const handler: JSActionHandler<"create-user"> = async (
  { email, age },
  { currentUser, vars },
) => {
  // email: string, age: number として推論される
  return { ok: true };
};
 
export default handler;

readFile()は.tsファイルを自動でJavaScriptにトランスパイルするため、TypeScriptで書いたコードもそのまま実行できます。詳しくはreadFileをご参照ください。

JavaScriptで書く場合

JSDocの@typeコメントでJSActionHandler<"id">を指定すると、エディタ上で型推論を有効にできます。

// src/actions/js-action-codes/create-user.js
/** @type { import("@basemachina/action").JSActionHandler<"create-user"> } */
export default async ({ email, age }, { currentUser, vars }) => {
  return { ok: true };
};

ブラウザのエディタで使うHandler型は、コード管理では使用できません。アクションIDを型引数に渡すJSActionHandler<"id">を使用してください。

ブラウザからコードを持ち込む場合は、以下のように書き換えます。

- /** @type { import("@basemachina/action").Handler } */
+ /** @type { import("@basemachina/action").JSActionHandler<"create-user"> } */

MySQLアクション

import { defineAction } from "@basemachina/sdk/oac";
 
export const listUsers = defineAction({
  id: "list-users",
  name: "ユーザー一覧取得",
  type: "mysql",
  dataSource: "mysql-main",
  statements: [
    {
      sql: "SELECT * FROM users WHERE id IN ({{ userIds }})",
      type: "READ",
    },
  ],
  parameters: [
    {
      type: "ARRAY",
      name: "userIds",
      format: { type: "SQL", expansionTarget: "IN" },
      childElement: { type: "NUMBER" },
    },
  ],
});
フィールド型必須説明
type"mysql"はいMySQLアクションを指定
dataSourcestringはいMySQLデータソースの識別子
statementsSqlStatement[]はい実行するSQL文（1件以上）
convertNullToStringbooleanいいえ結果のNULLを空文字列に変換するか。未指定時は変換しない
parametersParameterConfig[]いいえパラメーター定義（下記参照）

statementsの各要素は以下の通りです。

フィールド型必須説明
sqlstringはい実行するSQL文。{{ paramName }}でパラメーターを埋め込める
type"READ" | "WRITE"はい実行種別。READはSELECT、WRITEはINSERT / UPDATE / DELETE
titlestringいいえSQL文のタイトル

PostgreSQLアクション

import { defineAction } from "@basemachina/sdk/oac";
 
export const listOrders = defineAction({
  id: "list-orders",
  name: "注文一覧取得",
  type: "postgresql",
  dataSource: "postgres-main",
  statements: [
    {
      sql: "SELECT * FROM orders WHERE id IN ({{ orderIds }})",
      type: "READ",
    },
  ],
  parameters: [
    {
      type: "ARRAY",
      name: "orderIds",
      format: { type: "SQL", expansionTarget: "IN" },
      childElement: { type: "NUMBER" },
    },
  ],
});
フィールド型必須説明
type"postgresql"はいPostgreSQLアクションを指定
dataSourcestringはいPostgreSQLデータソースの識別子
statementsSqlStatement[]はい実行するSQL文（1件以上）
convertNullToStringbooleanいいえ結果のNULLを空文字列に変換するか。未指定時は変換しない
parametersParameterConfig[]いいえパラメーター定義（下記参照）

statementsの各要素はMySQLアクションと同じです。

Snowflakeアクション

import { defineAction } from "@basemachina/sdk/oac";
 
export const fetchOrders = defineAction({
  id: "fetch-orders",
  name: "注文取得",
  type: "snowflake",
  dataSource: "snowflake-warehouse",
  statements: [
    {
      sql: "SELECT * FROM orders WHERE id = {{ orderId }}",
    },
  ],
  parameters: [{ type: "NUMBER", name: "orderId", required: true }],
});
フィールド型必須説明
type"snowflake"はいSnowflakeアクションを指定
dataSourcestringはいSnowflakeデータソースの識別子
statementsSqlReadStatement[]はい実行するSQL文（1件以上）。SELECT系クエリのみサポート
parametersParameterConfig[]いいえパラメーター定義（下記参照）

statementsの各要素はAmazon Athenaアクションと同じです。

パラメーター定義

parametersには、アクションの入力パラメーターをtypeフィールドで種別を分けて配列で指定します。アクション種別ごとに、使用できるパラメーター種別と各フィールドの仕様が一部異なります。

パラメーター種別使用可能なアクション種別
TEXTすべて
NUMBERすべて
DATEすべて
BOOLすべて
ARRAYすべて
TUPLEすべて
SYSTEM_VALUEAmazon S3 / Firestore / Google Cloud Storage / Google Sheets / gRPC / HTTP API / JavaScript / MySQL / PostgreSQL
JSONgRPC / HTTP API / MySQL / PostgreSQL
FILEAmazon S3 / Google Cloud Storage / HTTP API / JavaScript
SQLAmazon Athena / BigQuery / MySQL / PostgreSQL / Snowflake

以下のアクションでは、BOOL / ARRAY / TUPLEのformat指定が必須です。

  • Amazon Athena
  • Amazon S3
  • BigQuery
  • Firestore
  • Google Cloud Storage
  • Google Sheets
  • gRPC
  • HTTP API
  • Snowflake

各アクション種別のセクションも併せて参照してください。

すべての種別に共通で、nameはパラメーター名、descriptionはパラメーターの説明として指定できます。

defaultValueを指定できるパラメーターでは、未指定を表す場合はdefaultValueフィールド自体を省略してください。nullは指定できません。ARRAY/TUPLEのdefaultValueでも、配列やタプル内の要素にnullやundefinedを含めることはできません。

TEXTパラメーター

{
  type: "TEXT",
  name: "email",
  required: true,
  defaultValue: "example@example.com",
  minLength: 1,
  maxLength: 255,
  multiline: false,
  regexValidation: {
    pattern: "^[\\w.+-]+@[\\w-]+\\.[\\w.]+$",
    errorMessage: "メールアドレスの形式で入力してください",
  },
}
フィールド型必須説明
type"TEXT"はいテキストパラメーターを指定
namestringはいパラメーター名
descriptionstringいいえ説明
requiredbooleanいいえ必須かどうか
defaultValuestringいいえ初期値
minLengthnumberいいえ最小文字数
maxLengthnumberいいえ最大文字数
multilinebooleanいいえ複数行入力を許可するか
newlineCharactersstringいいえmultiline: trueの場合の改行コード
regexValidation{ type?: "custom"; pattern: string; errorMessage?: string }いいえ入力値のバリデーション正規表現（multiline: falseのみ）
selectOptions{ label?: string; value: string }[]いいえ選択肢（multiline: falseのみ。1件以上必須）。label省略時はvalueを表示
masterDataFetchSettingIdstringいいえマスターデータ取得設定の識別子（multiline: falseのみ）

selectOptionsとmasterDataFetchSettingIdは排他関係にあり、どちらか一方のみ指定できます。

NUMBERパラメーター

{
  type: "NUMBER",
  name: "age",
  required: true,
  min: 0,
  max: 150,
}
フィールド型必須説明
type"NUMBER"はい数値パラメーターを指定
namestringはいパラメーター名
descriptionstringいいえ説明
requiredbooleanいいえ必須かどうか
defaultValuenumberいいえ初期値
minnumberいいえ最小値
maxnumberいいえ最大値
selectOptions{ label?: string; value: number }[]いいえ選択肢（1件以上必須）。label省略時はvalueを表示
masterDataFetchSettingIdstringいいえマスターデータ取得設定の識別子

selectOptionsとmasterDataFetchSettingIdは排他関係にあり、どちらか一方のみ指定できます。

DATEパラメーター

// 文字列で扱う場合
{
  type: "DATE",
  name: "targetDate",
  required: true,
  includeTime: false,
  format: "YYYY-MM-DD",
  defaultValue: "2025-01-01",
}
 
// Unixタイムスタンプで扱う場合
{
  type: "DATE",
  name: "targetDate",
  required: true,
  includeTime: true,
  useUnixTimestamp: true,
  defaultValue: "2025-01-01T00:00:00Z",
}
フィールド型必須説明
type"DATE"はい日付パラメーターを指定
namestringはいパラメーター名
descriptionstringいいえ説明
requiredbooleanいいえ必須かどうか
includeTimebooleanいいえ時刻を含めるか
useUnixTimestampbooleanいいえUnixタイムスタンプで扱うか。trueの場合formatは指定不可
formatstringいいえ日付フォーマット（useUnixTimestamp: falseの場合のみ）
defaultValuestringいいえ初期値。日付として有効な文字列であればformatに従わない値も受け付ける（例: "2024-01-31", "2024-01-31T14:30:00Z"）

BOOLパラメーター

Amazon S3 / Firestore / Google Cloud Storage / Google Sheets / gRPC / HTTP APIアクションでは文字列化が必須のため、formatを必ず指定する必要があります。

それ以外のアクション（Amazon Athena / BigQuery / JavaScript / MySQL / PostgreSQL / Snowflake）では、formatを省略すると真偽値のまま扱われます。

formatを指定した場合は、指定した文字列値として扱われます。

// JavaScriptアクション（真偽値のまま扱う）
{
  type: "BOOL",
  name: "isActive",
  defaultValue: true,
}
 
// JavaScriptアクション（文字列値として扱う）
{
  type: "BOOL",
  name: "isActive",
  format: { trueValue: "1", falseValue: "0" },
}
 
// gRPCアクション（formatは必須）
{
  type: "BOOL",
  name: "isActive",
  format: { trueValue: "true", falseValue: "false" },
}
フィールド型必須説明
type"BOOL"はい真偽値パラメーターを指定
namestringはいパラメーター名
descriptionstringいいえ説明
defaultValuebooleanいいえ初期値
formatオブジェクトAmazon S3 / Firestore / Google Cloud Storage / Google Sheets / gRPC / HTTP APIで必須、Amazon Athena / BigQuery / JavaScript / MySQL / PostgreSQL / Snowflakeで任意文字列値として扱う場合の設定。{ trueValue: string; falseValue: string; type?: "STRING" }

formatの各フィールドは以下の通りです。

フィールド型必須説明
type"STRING"いいえフォーマット種別。現状"STRING"のみサポート。省略時は"STRING"扱い
trueValuestringはいtrueのときに送信する文字列
falseValuestringはいfalseのときに送信する文字列

FILEパラメーター（Amazon S3 / Google Cloud Storage / HTTP API / JavaScriptアクションのみ）

{
  type: "FILE",
  name: "uploadFile",
  required: true,
  maxBytes: 10485760,
}
フィールド型必須説明
type"FILE"はいファイルパラメーターを指定
namestringはいパラメーター名
descriptionstringいいえ説明
requiredbooleanいいえ必須かどうか
maxBytesnumberいいえ最大バイト数

JSONパラメーター（gRPC / HTTP API / MySQL / PostgreSQLアクションのみ）

valueTypeで内部の値の型を指定し、その型に応じたフィールドを追加で指定できます。

// テキスト型
{
  type: "JSON",
  name: "statusFilter",
  valueType: "TEXT",
  selectOptions: [
    { label: "有効", value: "ACTIVE" },
    { label: "無効", value: "INACTIVE" },
  ],
}
 
// 数値型
{
  type: "JSON",
  name: "priority",
  valueType: "NUMBER",
  min: 0,
  max: 10,
  defaultValue: 5,
}
 
// 日付型（文字列形式）
{
  type: "JSON",
  name: "targetDate",
  valueType: "DATE",
  includeTime: false,
  format: "YYYY-MM-DD",
  defaultValue: "2025-01-01",
}
 
// 日付型（Unixタイムスタンプ）
{
  type: "JSON",
  name: "targetTimestamp",
  valueType: "DATE",
  useUnixTimestamp: true,
  includeTime: true,
  defaultValue: "2023-11-15T00:00:00Z",
}
フィールド型必須説明
type"JSON"はいJSONパラメーターを指定
namestringはいパラメーター名
descriptionstringいいえ説明
valueType"TEXT" | "NUMBER" | "DATE"はいJSONとして送信する値の型

valueTypeに応じて、TEXT/NUMBER/DATEパラメーターと同様のフィールドを追加で指定できます（requiredを除く）。

valueType: "TEXT"の場合、regexValidationはTEXTパラメーターと同じく{ pattern: string; errorMessage?: string }形式で指定します。

SYSTEM_VALUEパラメーター

ログイン中のユーザーIDなど、システムが提供する値を自動的に埋め込むパラメーターです。

{
  type: "SYSTEM_VALUE",
  name: "currentUserId",
  required: true,
}
フィールド型必須説明
type"SYSTEM_VALUE"はいシステム値パラメーターを指定
namestringはいパラメーター名
descriptionstringいいえ説明
requiredbooleanいいえ必須かどうか

SQLパラメーター（MySQL / PostgreSQL / Amazon Athena / BigQuery / Snowflakeアクションのみ）

SQL文の一部として展開する文字列値を指定するパラメーターです。プレースホルダー（{{ paramName }}）を介してSQL文に埋め込むことを想定しています。

{
  type: "SQL",
  name: "orderBy",
  required: true,
  defaultValue: "created_at DESC",
  selectOptions: [
    { label: "新しい順", value: "created_at DESC" },
    { label: "古い順", value: "created_at ASC" },
  ],
}
フィールド型必須説明
type"SQL"はいSQLパラメーターを指定
namestringはいパラメーター名
descriptionstringいいえ説明
requiredbooleanいいえ必須かどうか
defaultValuestringいいえ初期値
selectOptions{ label?: string; value: string }[]いいえ選択肢（1件以上必須）。label省略時はvalueを表示

ARRAYパラメーター

複数要素を配列として入力するパラメーターです。childElementで要素の型を、formatで送信時の形式を指定します。formatを省略した場合は配列のまま渡されます。

// JSON形式
{
  type: "ARRAY",
  name: "targetIds",
  format: { type: "JSON" },
  childElement: { type: "NUMBER" },
}
 
// 区切り文字形式
{
  type: "ARRAY",
  name: "tags",
  format: {
    type: "SEPARATOR",
    delimiter: ",",
    quoteCharacter: '"',
  },
  childElement: { type: "TEXT" },
}
 
// 配列のまま渡す（format省略）
{
  type: "ARRAY",
  name: "rawValues",
  childElement: { type: "TEXT" },
}
フィールド型必須説明
type"ARRAY"はい配列パラメーターを指定
namestringはいパラメーター名
descriptionstringいいえ説明
formatオブジェクトいいえ送信時の形式。省略時は配列のまま渡す
childElementElementConfigはい要素の型（TEXT / NUMBER / DATE / ARRAY / TUPLE）
defaultValue配列いいえ初期値。要素にはnullやundefinedを指定不可
minItemsnumberいいえ最小要素数
maxItemsnumberいいえ最大要素数

formatの指定方法は以下の通りです。

format送信形式
省略配列のまま渡す（gRPC / JavaScript / MySQL / PostgreSQLアクションのみ）
{ type: "JSON" }JSON文字列に変換して送信
{ type: "SEPARATOR", delimiter?: string, quoteCharacter?: string }delimiterで区切った文字列として送信。quoteCharacterで各要素を囲む
{ type: "SQL", expansionTarget: "IN" }SQLのIN句に展開（MySQL / PostgreSQLアクションのみ）
{ type: "SQL" }SQLのIN句相当として展開（Amazon Athena / BigQuery / Snowflakeアクションのみ）

TUPLEパラメーター

複数のフィールドを1つのパラメーターとしてまとめるタプル型のパラメーターです。formatを省略した場合は配列のまま渡されます。

{
  type: "TUPLE",
  name: "filter",
  format: { type: "JSON" },
  tupleElements: [
    { label: "開始日", childElement: { type: "DATE" } },
    { label: "終了日", childElement: { type: "DATE" } },
  ],
}
フィールド型必須説明
type"TUPLE"はいタプルパラメーターを指定
namestringはいパラメーター名
descriptionstringいいえ説明
formatオブジェクトいいえ送信時の形式（ARRAYと同じ指定方法）
tupleElements{ label?: string; childElement: TupleChildElementConfig }[]はい各要素の定義（1件以上必須）
defaultValueタプルいいえ初期値。要素にはnullやundefinedを指定不可

tupleElementsのchildElementにはTEXT / NUMBER / DATE / BOOLが指定できます。

BOOLを指定する場合、Amazon S3 / Firestore / Google Cloud Storage / Google Sheets / gRPC / HTTP APIアクションではformatの指定が必須です。それ以外のアクションではformatを省略すると真偽値のまま扱われます。

defineConfigreadFile