アクションの実行

指定したアクションを同期実行し、結果をレスポンスで受け取ります。データソース系アクション（SQL・REST API・gRPCなど）と、後継のJavaScriptサーバーアクションが対応しています。

エンドポイント

POST /environments/{environment_id}/actions/{action_id}/executions

認証・共通ヘッダー・エラー形式は公開APIとはを参照してください。

パスパラメータ

名前	型	必須	説明
`environment_id`	`string`	必須	対象環境のID（`env_`で始まるULID）
`action_id`	`string`	必須	実行対象アクションのID。`bmrn://`形式は受け付けない

リクエストボディ

Content-Type: application/jsonで、以下の形式のJSONを送信します。

{
  "arguments": {
    "user_id": "usr_01H...",
    "subject": "今月のお知らせ",
    "body": "本文..."
  }
}

フィールド	型	必須	説明
`arguments`	`object`	任意	アクションの引数。キーがパラメータ名、値はそのパラメータのinput_schemaに従う型

argumentsを省略した場合は空オブジェクト（{}）として扱われます。

引数の型

argumentsの各値は、アクション詳細で取得できるinput_schemaの型に従って指定します。代表的な対応関係は以下の通りです。

入力タイプ	リクエストボディでの値
テキスト	文字列（例: `"hello"`）
数値	数値（例: `42`）
真偽値	`true` / `false`
JSON	任意のJSON値（オブジェクト・配列・スカラのいずれも可）
日時	ISO 8601文字列（例: `"2026-04-18T09:00:00Z"`）またはUNIXタイムスタンプ（ミリ秒の整数）
配列	JSON配列
タプル	各要素の型に従ったJSON配列（要素数固定）

リクエスト例

curl -X POST https://platform.basemachina.com/public/v1/environments/env_01H.../actions/send_email/executions \
  -H "Authorization: Bearer $BM_TOKEN" \
  -H "Basemachina-Project: prj_01H..." \
  -H "Content-Type: application/json" \
  -d '{
    "arguments": {
      "user_id": "usr_01H...",
      "subject": "今月のお知らせ",
      "body": "本文..."
    }
  }'

レスポンス

ステータス200 OKで、実行結果がexecutionリソースとして返ります。

{
  "action_id": "send_email",
  "output": {
    "type": "scalar",
    "value": {
      "delivered": true,
      "message_id": "msg_01H..."
    }
  }
}

フィールド	型	説明
`action_id`	`string`	実行されたアクションのID
`output`	`object`	アクションの成功結果。`type`によって他のフィールドが決まる（後述）

`output`の形状

outputはtypeをdiscriminatorとし、アクション種別ごとに以下のいずれかの形になります。

`output.type`	アクション種別	形状
`sql_statements`	SQL系（MySQL / PostgreSQL / BigQuery / Amazon Athena / Snowflake）	`{ "type": "sql_statements", "statements": [...] }`
`google_sheets`	Google スプレッドシート	`{ "type": "google_sheets", "rows": [{...}, ...] }`
`storage_object_list`	Amazon S3 / Google Cloud Storage（一覧取得）	`{ "type": "storage_object_list", "items": [...] }`
`signed_url`	Amazon S3 / Google Cloud Storage（署名付きURL発行）	`{ "type": "signed_url", "signed_url": "https://..." }`
`scalar`	JavaScriptサーバーアクション、HTTP API、gRPC、Firestore、S3 / GCS（アップロード）	`{ "type": "scalar", "value": <任意のJSON値> }`

`sql_statements`

SQLアクションの各ステートメントの結果がstatements配列に入ります。各要素はtypeがqueryかupdateかで形が異なります。

{
  "type": "sql_statements",
  "statements": [
    {
      "type": "query",
      "title": "ユーザー一覧",
      "rows": [{ "id": "usr_01H...", "name": "Taro" }],
      "columns": {
        "id": {
          "database_type_name": "VARCHAR",
          "nullable": false,
          "supported": true
        },
        "name": {
          "database_type_name": "VARCHAR",
          "nullable": true,
          "supported": true
        }
      }
    },
    {
      "type": "update",
      "title": "更新ステートメント"
    }
  ]
}

columnsはクエリ結果から列の型情報を取得できなかった場合はnullになります。supportedがfalseの列はrows内の値がnullになります。

`google_sheets`

各行をヘッダー行のセル値をキーとするオブジェクトに変換した配列がrowsに入ります。

{
  "type": "google_sheets",
  "rows": [{ "id": "1", "name": "Taro" }]
}

`storage_object_list`

Amazon S3 / Google Cloud Storageのオブジェクト一覧がitems配列に入ります。各要素のフィールドはobject_key、last_modified（Unixタイムスタンプ・秒）、size（バイト）です。

{
  "type": "storage_object_list",
  "items": [
    {
      "object_key": "path/to/object",
      "last_modified": 1735689600,
      "size": 1024
    }
  ]
}

`signed_url`

発行された署名付きURLがsigned_urlに入ります。

{
  "type": "signed_url",
  "signed_url": "https://..."
}

`scalar`

アクションが返した任意のJSON値（オブジェクト・配列・プリミティブ・nullのいずれも可）がvalueに入ります。具体形はアクション側の実装に依存するため、事前にアクションの戻り値を確認してから値を扱ってください。

{
  "type": "scalar",
  "value": { "delivered": true, "message_id": "msg_01H..." }
}

公開APIから実行できないアクション

以下のアクションは公開APIから実行できません。いずれも422 argument_invalidまたは404 not_foundで弾かれます。

種別	結果
ファイル入力（fileパラメータ）を持つアクション	`422 argument_invalid`を返す
旧JavaScriptアクション（非推奨）	`422 argument_invalid`を返す
無効化されたアクション	`404 not_found`を返す

エラー

ステータス	`code`	発生条件
`400`	`bad_request`	`action_id`に`bmrn://`形式を指定、`Basemachina-Project`ヘッダー欠落など
`401`	`unauthorized`	`Authorization`ヘッダー欠落・トークン検証失敗
`403`	`forbidden`	アクションの実行権限がない、またはサービスアカウントから実行できない操作の呼び出し
`404`	`not_found`	指定したIDのアクションが存在しない、または無効化されている
`409`	`state_conflict`	アクションの状態不整合
`413`	`payload_too_large`	リクエストボディのサイズ超過
`422`	`argument_invalid`	引数のバリデーション違反、または公開APIから実行できないアクション種別の呼び出し
`422`	`javascript_action_error`	JavaScriptサーバーアクションのコードが投げた業務エラー
`500`	`internal_error`	gatewayまたは内部APIの障害
`502`	`datasource_error`	データソースなど上流の非成功応答（応答情報は`datasource`フィールドに格納）
`503`	`service_unavailable`	ベースマキナ側の一時障害。`Retry-After`ヘッダーに従ってリトライ可能

エラーコードの詳細は公開APIとはを参照してください。

引数バリデーション違反のレスポンス例

{
  "type": "https://docs.basemachina.com/preview/public_api/#argument_invalid",
  "title": "Argument Invalid",
  "status": 422,
  "detail": "user_idの値（）が不正です: この項目は必須です",
  "instance": "/public/v1/environments/env_01H.../actions/send_email/executions",
  "code": "argument_invalid",
  "violations": [
    {
      "field": "arguments.user_id",
      "reason": "user_idの値（）が不正です: この項目は必須です"
    }
  ]
}

アクションの実行

エンドポイント

パスパラメータ

リクエストボディ

引数の型

リクエスト例

レスポンス

outputの形状

sql_statements

google_sheets

storage_object_list

signed_url

scalar