アクションの実行

指定したアクションを同期実行し、結果をレスポンスで受け取ります。SQL・HTTP API・gRPC・Firestore・Googleスプレッドシート・ストレージ系などのアクションと、JavaScriptアクションが対応しています。

エンドポイント

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

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

パスパラメータ

名前	型	必須	説明
`project_id`	`string`	必須	対象プロジェクトのID
`environment_id`	`string`	必須	対象環境のID
`action_id`	`string`	必須	実行対象アクションの識別子

リクエストボディ

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値（オブジェクト・配列・スカラーのいずれも可）
日時	`input_schema`の`format`に従う文字列。`date`は`YYYY-MM-DD`、`date-time`はISO 8601形式
配列	JSON配列
タプル	各要素の型に従ったJSON配列（要素数固定）

リクエスト例

curl -X POST https://platform.basemachina.com/public/v1/projects/csi2hcc0iaejrqgivkfg/environments/9m4e2mr0ui3e8a215n4g/actions/send_email/executions \
  -H "Authorization: Bearer $BM_TOKEN" \
  -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`	実行されたアクションの識別子
`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	`{ "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`	リクエストパラメーターが不正
`401`	`unauthorized`	`Authorization`ヘッダー欠落・トークン検証失敗
`403`	`forbidden`	アクションの実行権限がない、またはサービスアカウントから実行できない操作の呼び出し
`404`	`not_found`	指定したIDのアクションが存在しない、または無効化されている
`409`	`state_conflict`	アクションの状態不整合
`413`	`payload_too_large`	リクエストボディのサイズ超過
`415`	`unsupported_media_type`	`Content-Type`が`application/json`以外
`422`	`argument_invalid`	引数のバリデーション違反、または公開APIから実行できないアクション種別の呼び出し
`422`	`javascript_action_error`	JavaScriptサーバーアクションのコードが投げた業務エラー
`422`	`datasource_error`	データソースなど接続先のエラー
`500`	`internal_error`	gatewayまたは内部APIの障害
`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/projects/csi2hcc0iaejrqgivkfg/environments/9m4e2mr0ui3e8a215n4g/actions/send_email/executions",
  "code": "argument_invalid",
  "violations": [
    {
      "field": "arguments.user_id",
      "reason": "user_idの値（）が不正です: この項目は必須です"
    }
  ]
}

データソースエラーのレスポンス例

HTTP系の上流ステータスを取得できた場合は、datasourceにステータスとレスポンス本文の冒頭が入ります。

{
  "type": "https://docs.basemachina.com/preview/public_api/#datasource_error",
  "title": "Datasource Error",
  "status": 422,
  "detail": "データソースからエラーが返されました",
  "instance": "/public/v1/projects/csi2hcc0iaejrqgivkfg/environments/9m4e2mr0ui3e8a215n4g/actions/fetch_user/executions",
  "code": "datasource_error",
  "action_id": "fetch_user",
  "datasource": {
    "status": 503,
    "body_snippet": "{\"message\":\"temporarily unavailable\"}"
  }
}

SQL系アクションでは、実行されたステートメントごとの結果がstatementsに入ることがあります。

アクションの実行

エンドポイント

パスパラメータ

リクエストボディ

引数の型

リクエスト例

レスポンス

outputの形状

sql_statements

google_sheets

storage_object_list

signed_url

scalar