defineAction
アクションを定義する関数です。classフィールドで種別を指定し、種別に応じたフィールドを設定します。
classによって設定できるフィールドが型で絞り込まれるため、存在しないフィールドを指定するとTypeScriptのコンパイルエラーになります。
以下の設定項目はコード管理の対象外です。これらはベースマキナの管理画面から設定してください。
- 結果の加工(加工スクリプト、ページネーション)
- 環境ごとの有効/無効
- 環境ごとのバージョン
共通フィールド
すべてのアクション種別で使用できるフィールドです。
| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
id | string | はい | アクションの識別子。1〜128文字で、使用できる文字は英数字・アンダースコア・ハイフン(^[a-zA-Z0-9_-]+$) |
name | string | はい | アクション名。1〜128文字 |
description | string | いいえ | 説明。最大1000文字 |
preferJobExecution | boolean | いいえ | ジョブ実行を優先的に表示するか |
jobDetailVisibility | "EXECUTOR_ONLY" | "PUBLIC" | いいえ | ジョブ詳細の公開範囲 |
reviewSettingId | string | いいえ | レビュー設定の識別子 |
notificationSettings | NotificationSettingsConfig | いいえ | 通知設定 |
permissions | [PermissionTarget, ...](非空) | いいえ | 実行権限の対象。指定する場合は1件以上必要 |
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: "ユーザー作成が成功しました",
},
onError: {
notificationMethodId: "<通知方法の識別子>",
message: "ユーザー作成に失敗しました",
},
};| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
onSuccess.notificationMethodId | string | はい | 通知方法の識別子 |
onSuccess.mentionTargetUserIds | string[] | いいえ | メンション対象ユーザー |
onSuccess.message | string | いいえ | 通知メッセージ |
onError.notificationMethodId | string | はい | 通知方法の識別子 |
onError.mentionTargetUserIds | string[] | いいえ | メンション対象ユーザー |
onError.message | string | いいえ | 通知メッセージ |
onSuccessとonErrorはどちらも省略可能で、必要な方だけ指定できます。
gRPCアクション
import { defineAction } from "@basemachina/sdk/oac";
export const fetchOrders = defineAction({
id: "fetch-orders",
name: "注文一覧取得",
class: "grpc",
dataSource: "orders-service",
fullyQualifiedMethodName: "orders.OrderService/ListOrders",
parameters: [{ type: "TEXT", name: "customerId", required: true }],
});| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
class | "grpc" | はい | gRPCアクションを指定 |
dataSource | string | はい | データソースの識別子 |
fullyQualifiedMethodName | string | はい | gRPCメソッドの完全修飾名 |
headers | { name: string; value: string }[] | いいえ | リクエストヘッダー |
body | { payload: string } | いいえ | リクエストボディ |
parameters | ParameterConfig[] | いいえ | パラメーター定義(下記参照) |
JavaScriptアクション
import { defineAction, readFile } from "@basemachina/sdk/oac";
export const createUser = defineAction({
id: "create-user",
name: "ユーザー作成",
class: "javascript",
code: readFile("./js-action-codes/create-user.ts"),
parameters: [
{ type: "TEXT", name: "email", required: true },
{ type: "NUMBER", name: "age", required: true },
],
});| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
class | "javascript" | はい | JavaScriptアクションを指定 |
code | string | はい | JavaScriptコードまたはreadFile()の戻り値 |
parameters | ParameterConfig[] | いいえ | パラメーター定義(下記参照) |
パラメーター定義
parametersには、アクションの入力パラメーターをtypeフィールドで種別を分けて配列で指定します。gRPCアクションとJavaScriptアクションで、使用できるパラメーター種別とformatTypeが一部異なります。
すべての種別に共通で、nameは1〜128文字、descriptionは最大400文字までです。
| パラメーター種別 | gRPC | JavaScript |
|---|---|---|
TEXT | 使用可 | 使用可 |
NUMBER | 使用可 | 使用可 |
DATE | 使用可 | 使用可 |
BOOL | 使用可 | 使用可 |
SYSTEM_VALUE | 使用可 | 使用可 |
JSON | 使用可 | 使用不可 |
FILE | 使用不可 | 使用可 |
ARRAY | 使用可 | 使用可 |
TUPLE | 使用可 | 使用可 |
TEXTパラメーター
{
type: "TEXT",
name: "email",
required: true,
defaultValue: "example@example.com",
minLength: 1,
maxLength: 255,
multiline: false,
regexValidation: "^[\\w.+-]+@[\\w-]+\\.[\\w.]+$",
regexErrorMessage: "メールアドレスの形式で入力してください",
}| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
type | "TEXT" | はい | テキストパラメーターを指定 |
name | string | はい | パラメーター名 |
description | string | いいえ | 説明 |
required | boolean | いいえ | 必須かどうか |
defaultValue | string | いいえ | デフォルト値 |
minLength | number | いいえ | 最小文字数 |
maxLength | number | いいえ | 最大文字数 |
multiline | boolean | いいえ | 複数行入力を許可するか |
newlineCharacters | string | いいえ | multiline: trueの場合の改行コード |
regexValidation | string | いいえ | 入力値のバリデーション正規表現(multiline: falseのみ) |
regexErrorMessage | string | いいえ | バリデーションエラー時のメッセージ |
selectOptions | { label: string; value: string }[] | いいえ | 選択肢(multiline: falseのみ) |
masterDataFetchSettingId | string | いいえ | マスターデータ取得設定の識別子(multiline: falseのみ) |
selectOptionsとmasterDataFetchSettingIdは排他関係にあり、どちらか一方のみ指定できます。
NUMBERパラメーター
{
type: "NUMBER",
name: "age",
required: true,
min: 0,
max: 150,
}| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
type | "NUMBER" | はい | 数値パラメーターを指定 |
name | string | はい | パラメーター名 |
description | string | いいえ | 説明 |
required | boolean | いいえ | 必須かどうか |
defaultValue | number | いいえ | デフォルト値 |
min | number | いいえ | 最小値 |
max | number | いいえ | 最大値 |
selectOptions | { label: string; value: number }[] | いいえ | 選択肢 |
masterDataFetchSettingId | string | いいえ | マスターデータ取得設定の識別子 |
DATEパラメーター
// ISO文字列で扱う場合
{
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: 1735689600,
}| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
type | "DATE" | はい | 日付パラメーターを指定 |
name | string | はい | パラメーター名 |
description | string | いいえ | 説明 |
required | boolean | いいえ | 必須かどうか |
includeTime | boolean | いいえ | 時刻を含めるか |
useUnixTimestamp | boolean | いいえ | Unixタイムスタンプで扱うか。trueの場合formatは指定不可 |
format | string | いいえ | 日付フォーマット(useUnixTimestamp: falseの場合のみ) |
defaultValue | string | number | いいえ | デフォルト値(useUnixTimestamp: trueの場合はnumber) |
BOOLパラメーター
// JavaScriptアクションの例(真偽値で扱う)
{
type: "BOOL",
name: "isActive",
formatType: "RAW",
defaultValue: true,
}
// JavaScriptアクションの例(文字列で扱う)
{
type: "BOOL",
name: "isActive",
formatType: "STRING",
trueValue: "1",
falseValue: "0",
}
// gRPCアクションの例(BOOLは文字列形式のみ、formatType指定不要)
{
type: "BOOL",
name: "isActive",
trueValue: "true",
falseValue: "false",
}| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
type | "BOOL" | はい | 真偽値パラメーターを指定 |
name | string | はい | パラメーター名 |
description | string | いいえ | 説明 |
defaultValue | boolean | いいえ | デフォルト値 |
formatType | "RAW" | "STRING" | JavaScriptで必須、gRPCでは不要 | 値の扱い方。"RAW"は真偽値、"STRING"はtrueValue/falseValueの文字列 |
trueValue | string | formatType: "STRING"で必須 | trueのときに送信する文字列 |
falseValue | string | formatType: "STRING"で必須 | falseのときに送信する文字列 |
gRPCアクションのBOOLは常に文字列形式で扱われるため、formatTypeの指定は不要でtrueValue/falseValueが必須です。
FILEパラメーター(JavaScriptアクションのみ)
{
type: "FILE",
name: "uploadFile",
required: true,
maxBytes: 10485760,
}| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
type | "FILE" | はい | ファイルパラメーターを指定 |
name | string | はい | パラメーター名 |
description | string | いいえ | 説明 |
required | boolean | いいえ | 必須かどうか |
maxBytes | number | いいえ | 最大バイト数 |
JSONパラメーター(gRPCアクションのみ)
{
type: "JSON",
name: "statusFilter",
valueType: "TEXT",
selectOptions: [
{ label: "有効", value: "ACTIVE" },
{ label: "無効", value: "INACTIVE" },
],
}| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
type | "JSON" | はい | JSONパラメーターを指定 |
name | string | はい | パラメーター名 |
description | string | いいえ | 説明 |
valueType | "TEXT" | "NUMBER" | "DATE" | はい | JSONとして送信する値の型 |
valueTypeに応じて、TEXT/NUMBER/DATEパラメーターと同様のフィールドが追加で指定できます(requiredを除く)。
SYSTEM_VALUEパラメーター
ログイン中のユーザーIDなど、システムが提供する値を自動的に埋め込むパラメーターです。
{
type: "SYSTEM_VALUE",
name: "currentUserId",
required: true,
}| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
type | "SYSTEM_VALUE" | はい | システム値パラメーターを指定 |
name | string | はい | パラメーター名 |
description | string | いいえ | 説明 |
required | boolean | いいえ | 必須かどうか |
ARRAYパラメーター
複数要素を配列として入力するパラメーターです。childElementで要素の型を、formatTypeで送信時の形式を指定します。
{
type: "ARRAY",
name: "targetIds",
formatType: "JSON",
childElement: { type: "NUMBER" },
}| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
type | "ARRAY" | はい | 配列パラメーターを指定 |
name | string | はい | パラメーター名 |
description | string | いいえ | 説明 |
formatType | "RAW" | "JSON" | "SEPARATOR" | はい | 送信時の形式 |
childElement | ElementConfig | はい | 要素の型(TEXT / NUMBER / DATE / ARRAY / TUPLE) |
minItems | number | いいえ | 最小要素数 |
maxItems | number | いいえ | 最大要素数 |
delimiter | string | formatType: "SEPARATOR"のみ | 区切り文字 |
quoteCharacter | string | formatType: "SEPARATOR"のみ | 引用符 |
gRPCアクションではformatType: "RAW"は使用できません。
TUPLEパラメーター
複数のフィールドを1つのパラメーターとしてまとめるタプル型のパラメーターです。
{
type: "TUPLE",
name: "filter",
formatType: "JSON",
tupleElements: [
{ label: "開始日", childElement: { type: "DATE" } },
{ label: "終了日", childElement: { type: "DATE" } },
],
}| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
type | "TUPLE" | はい | タプルパラメーターを指定 |
name | string | はい | パラメーター名 |
description | string | いいえ | 説明 |
formatType | "RAW" | "JSON" | はい | 送信時の形式 |
tupleElements | { label?: string; childElement: TupleChildElementConfig }[] | いいえ | 各要素の定義 |
tupleElementsのchildElementにはTEXT / NUMBER / DATE / BOOLが指定できます。gRPCアクションではformatTypeに"JSON"のみが指定可能です。