ベースマキナとは

# ベースマキナとは

![ベースマキナとは](/images/what_is_basemachina/turntoui.png)

「BaseMachina（ベースマキナ）」は自社のデータを使った社内向けシステムを簡単に作成できるサービスです。

- エンジニアの方が開発業務以外で時間を使っていたオペレーション業務
- カスタマーサポート、マーケティング、営業企画の方が担当する顧客対応

などを定型化するため、エンジニアがサービス開発の合間に時間を使って管理画面を実装していました。

ベースマキナを使えば、そうした社内のオペレーション業務を定型化するために1から実装コストを払うことなく、データソースや処理をローコードで登録することにより、必要な画面を揃えることができます。

## ベースマキナの仕組み [](#ベースマキナの仕組み)

ベースマキナを使って社内向けシステムを作るために必要な作業はたった数ステップです。

1. MySQL、PostgreSQL、HTTP API、gRPCなどのデータソースを接続先として登録します。
1. SQLやAPI呼び出しのロジックを登録します（ベースマキナ内ではこれらを「アクション」と呼んでいます）。
1. 権限や加工処理など、呼び出しやアウトプットの方法を設定します。

これだけで社内向けシステムとして機能するUIが自動で作成され、ライブラリのアップデートの追従や画面作成、認証認可などの機能を実装する工数を削減できます。

さらに、セキュリティ面でもシングルサインオンや監査ログ、アクション単位でのきめ細かい権限管理などをサポートしており、顧客情報などの機密性の高いデータを扱う業務にもスムーズに応用できます。

## ドキュメントの利用方法 [](#ドキュメントの利用方法)

本ドキュメントは、いくつかの部分に分かれています。

まず、はじめてベースマキナをご利用の方向けの [スタートガイド](/start_guide/what_is_start_guide/) があります。
こちらで、ベースマキナの基本的な設定方法と、簡単なアクションの作成手順を体系的に学べます。

初回セットアップに必要な情報や、ベースマキナの重要な用語については、 [よくある疑問点](/faq/howto_setup/) に記載しています。

それ以降のドキュメントは、アクションなどの個別の機能に関する詳細な解説となっております。

また、ベースマキナ ドキュメントでは、 [llms-full.txt (opens in a new tab)](https://docs.basemachina.com/llms-full.txt) の配布もしています。
AIとのチャット形式でドキュメントを活用したい方は、 [Gemini連携](/tips/gemini_gem_integration/) 、 [NotebookLM連携](/tips/notebooklm_integration/) および、 [Claude連携](/tips/claude_project_integration/) のドキュメントを参考に `llms-full.txt` 利用の設定をしてください。

[スタートガイド](/start_guide/)
---
アクション

# アクションとは

アクションは、ベースマキナの中核となる機能で、データベースやAPIに対する操作を定型化し、誰でも安全に実行できるようにする仕組みです。

## アクションの概念 [](#アクションの概念)

アクションを使うことで、SQLクエリの実行やAPI呼び出しなど、これまで開発者が担っていた操作を、誰でも簡単に実行できるようになります。

たとえば、以下のような業務をアクションとして定型化できます。

- 顧客情報の検索・更新
- 注文ステータスの変更
- レポートの生成・ダウンロード
- 外部サービスとの連携処理

## アクションの仕組み [](#アクションの仕組み)

アクションは以下の3つの要素で構成されます。

### 1. データソース [](#1-データソース)

MySQL、PostgreSQL、HTTP API、gRPCなど、接続先のデータソースを登録します。

詳しくは各データソースの設定のページを参照してください。

### 2. 処理ロジック [](#2-処理ロジック)

SQLクエリやAPI呼び出しのロジックを定義します。パラメーターを受け取って動的に処理を変えることも可能です。

### 3. 権限・レビュー・バージョンの設定 [](#3-権限レビューバージョンの設定)

実行権限、レビュー、バージョン管理など、アクションの動作を制御する項目を設定します。

## アクションの利点 [](#アクションの利点)

### 実行画面の自動生成 [](#実行画面の自動生成)

アクションを登録すると、実行画面が自動で生成されます。画面を1から実装する必要はありません。

### 細かい権限管理 [](#細かい権限管理)

ユーザーやグループ単位で、アクションごとに実行権限を細かく設定できます。

詳しくは [実行権限](/action/action_permission/) を参照してください。

### レビュー依頼により、承認作業を仕組み化できる [](#レビュー依頼により承認作業を仕組み化できる)

重要な操作には、実行前に他のユーザーによる承認を必須にできます。

詳しくは [レビュー設定](/action/review/) を参照してください。

### バージョン管理 [](#バージョン管理)

アクションの変更履歴を管理し、環境ごとに別のバージョンを使用する、必要に応じて過去のバージョンに戻すといったことが可能です。

詳しくは [バージョン管理](/action/versions/) を参照してください。

### 柔軟な実行方法 [](#柔軟な実行方法)

アクションは、以下のような多様な方法で実行できます。

- アクション実行画面から手動実行
- [予約実行](/action/scheduled_jobs/) でスケジュール実行
- [定期実行](/action/cron_jobs/) でスケジュールによる自動実行
- [一括実行](/action/batch/) で複数データを一度に処理
- [ビュー](/view/) から呼び出して実行
- [JavaScriptアクション](/action/datasources/javascript_action/) から他のアクションを呼び出して実行

## アクションの最大実行時間 [](#アクションの最大実行時間)

アクションは実行方法によって最大実行時間が異なります。

| 実行方法 | 最大実行時間 |
| --- | --- |
| 通常実行 | 1分 |
| ジョブとして実行 | 30分 |

時間のかかるアクション、たとえば大量のレコードを対象にした長時間実行のSQLなどは、ジョブとして非同期実行することで1分の制限を避けつつ処理を継続できます。詳しくは [ジョブとして実行](/action/jobs/) を参照してください。

bridgeやデータソース側で短いタイムアウトを設定している場合、アクションの実行処理は最大実行時間の制限より前に中断されることがあります。bridgeの設定や [MySQLデータソース](/action/datasources/mysql_integration/) 、 [PostgreSQLデータソース](/action/datasources/postgresql_integration/) などのタイムアウトはアクション実行時にも適用されるため、長時間の処理を想定する際は余裕のある値に調整してください。設定値については [bridgeとは](/faq/what_is_bridge/) や [トラブルシューティング](/faq/troubleshooting/) も合わせて参照してください。

[画面作成機能の使い分け](/faq/screen_creation_features_comparison/) [MySQL](/action/datasources/mysql_integration/)
---
[アクション](/action/)

アクショングループ

# アクショングループ

## アクショングループとは [](#アクショングループとは)

![グループの詳細](/images/action_group/group_detail.png)

複数のアクションを1つの画面上で扱えるようにする機能です。

操作する対象のデータが共通していたり、よく併用するアクションをまとめることで、画面移動の手間を省いてオペレーションの作業時間を短縮できます。

## アクショングループの作成・更新方法 [](#アクショングループの作成更新方法)

アクショングループの画面には、画面上部のメニューからグループのアイコンをクリックすることで移動できます。

![グループのアイコン](/images/action_group/nav_icon.png)

新しくグループを作る場合、または設定を更新する場合にも、操作方法は同じです。

グループ名とグループに含めるアクションを選択します。

選択済みのアクションはドラッグアンドドロップで表示順序を変えられます。

![グループの作成](/images/action_group/group_form.png)

## 利用方法 [](#利用方法)

作成されたグループの画面に移動すると、追加されたアクションの実行導線が順序ごとにソートされて表示されます。

実行結果を加工したり、画面移動の設定を追加したい場合はアクション個別の画面から設定を変更してください。

[定期実行](/action/cron_jobs/) [一括実行](/action/batch/)
---
[アクション](/action/)

画像や動画の表示

# 画像や動画の表示

アクションの結果表示画面では画像や動画を表示できます。

画像や動画だと判定できるURLの文字列が返ってきたとき、文字列ではなく画像や動画の表示用のUIが代わりに表示されます。

URLの末尾が `png` や `jpg` などの画像の拡張子だった場合は画像表示用のUIが表示されます。

URLの末尾が `mp4` や `m3u8` などの動画の拡張子だった場合や、ドメインが `youtube.com` などの動画配信サイトであった場合、動画表示用のUIが表示されます。

また、HTTP APIの実行結果が画像、動画、PDFファイルだった場合、それに応じたUIが表示されます。

画像をクリックすると別タブで画像が開きます。また、動画も再生や拡大が可能で、手軽にプレビューをする手段としてお使いいただけます。

![レスポンス内容](/images/action_media_result/response.png)

![コンポーネント](/images/action_media_result/media_component.png)

## 画像の表示サイズを調整する/拡張子が画像以外のURLで画像を表示する [](#画像の表示サイズを調整する拡張子が画像以外のurlで画像を表示する)

結果表示のカスタマイズで `image` 関数を利用すると、画像の表示サイズの調整や、拡張子が画像以外のURLでの画像の表示ができます。

詳細は [`image`](/action/transformer_script/builtin_functions/image/) をご参照ください。

[アクションのコピー](/action/copy_action/) [結果のダウンロード](/action/download_result/)
---
[アクション](/action/)

実行権限

# 実行権限

![権限設定](/images/action_permission/basic.png)

アクションの実行者を制限したい場合には、アクションの設定画面のなかで実行権限を変更できます。

初期設定では **誰でも実行可能** となっており、制限は特にかかっていません。

**実行権限を制限する** を選択すると、プロジェクトの中に追加されているユーザー、またはロールをベースにして実行権限を付与する対象を決められます。

![実行権限を制限](/images/action_permission/limited.png)

権限が制限されていない場合は、誰でもアクションを実行できますが、権限を制限すると、実行権限を持っていないユーザーがアクションを実行できなくなります。

![レビュー必須](/images/action_permission/limited_form.png)

### JavaScriptアクションからしか実行できないように実行権限を制限する [](#javascriptアクションからしか実行できないように実行権限を制限する)

実行権限では、権限の持ち主にJavaScriptアクションも設定できます。
権限の持ち主にJavaScriptアクションを設定すると、そのアクションはJavaScriptアクションからしか実行できなくなります。

詳細は [JavaScriptアクションからしか実行できないアクションを作成する](/action/datasources/javascript_action/#JavaScript%E3%82%A2%E3%82%AF%E3%82%B7%E3%83%A7%E3%83%B3%E3%81%8B%E3%82%89%E3%81%97%E3%81%8B%E5%AE%9F%E8%A1%8C%E3%81%A7%E3%81%8D%E3%81%AA%E3%81%84%E3%82%A2%E3%82%AF%E3%82%B7%E3%83%A7%E3%83%B3%E3%82%92%E4%BD%9C%E6%88%90%E3%81%99%E3%82%8B) をご参照ください。

[image](/action/transformer_script/builtin_functions/image/) [JWT認証](/action/jwt_authentication/)
---
[アクション](/action/)

一括実行

# 一括実行

一括実行は、異なる引数でアクションをまとめて実行できる機能です。

引数の値はフォームからだけでなくCSVファイルによる入力も可能です。

![一括実行画面](/images/action_batch/form.png)

## 一括実行の方法 [](#一括実行の方法)

1. アクション実行画面の右上にある「一括実行へ進む」ボタンから一括実行画面に移動します。

![「一括実行へ進む」ボタン](/images/action_batch/button_to_batch_page.png)

1. アクションの引数の入力画面が表示され、「実行内容を追加する」ボタンを押すと引数の入力フォームが追加されます。
1. 各実行内容の引数の値を入力し、ページ最下部の「一括実行する」ボタンを押すと一括実行が開始されます。

### 一括実行結果を確認する [](#一括実行結果を確認する)

一括実行を開始するとサイドバーに各実行結果のステータスが表示されます。

| アイコン | ステータス |
| --- | --- |
| ⏳ | 実行待ち |
| 🟡 | 実行中 |
| ✅ | 実行成功 |
| ❌ | 実行失敗 |

サイドバーの各項目を選択すると、各実行結果を確認できます。

各実行結果は通常のアクションの実行結果と同様に、CSVやJSON形式でのダウンロードも可能です。

別の引数で一括実行をする場合は、サイドバーの一番上にある「実行内容の入力」ボタンから引数の入力画面に移動し、引数の値を変更して実行してください。

## CSVファイルをアップロードして引数の値を入力する [](#csvファイルをアップロードして引数の値を入力する)

一括実行画面の「CSVで入力する」ボタンからCSVファイルをアップロードして引数の値を入力できます。

### CSVファイルの入力形式 [](#csvファイルの入力形式)

1行目にパラメータ名、2行目以降の各行に実行する引数の値を入力します。

```
text_param,number_param,date_param // パラメータ名
a,1,2023-01-01 // 1件目の実行での引数の値
b,2,2023-01-02 // 2件目の実行での引数の値
```

一括実行画面の右上にある「CSV入力用テンプレート」から、1行目のパラメータ名が入力されたテンプレートのダウンロードも可能です。

パラメータの各種類ごとの入力形式は以下の通りです。

| 種類 | 説明 | 例（ `CSVの入力値` → `フォームの値` ） |
| --- | --- | --- |
| テキスト | 任意の値を入力してください。 文字列中で `"`, `,`, `\n` を使う場合は文字列全体を `"` で囲ってください。 `"` を使う場合は `""` と入力してください。 | `…,a,…` → `'a'` `…,"a,b",…` → `'a,b'` `…,"a\nb",…` → `'a\nb'` `…,"""ab""",…` → `'"ab"'` |
| 数値 | 数値に変換できる値を入力してください。 | `…,123,…` → `123` |
| 日付 | JavaScriptのDate型に変換できる値、または UnixTimestamp (秒)を入力してください。 文字列中で `,` を使う場合は文字列全体を `"` で囲ってください。 | `…,2023-01-01,…` → `'2023-01-01'` `…,2023-01-01T01:01:01,…` → `'2023-01-01T01:01:01'` `…,1609459200,…` → `1609459200` |
| 真偽値 | `true` または `false` を入力してください。（大文字小文字の区別なし） 未入力の場合は `false` として扱われます。 | `…,true,…` → `true` |
| JSON値 | JSON値の種類ごとに、各種類と同じです。 未入力の場合は `null` として扱われます。 | テキスト、数値、日付の例をご参考ください。 |
| SQL | テキストと同じです。 | `…,select * from users;,…` → `'select * from users;'` |
| 配列 | JSON形式の配列の `"` を `""` に置き換えた上で、配列全体を `"` で囲んで入力してください。 | `…,"[""a"",""b""]",…` → `['a','b']` `…,"[1,2]",…` → `[1,2]` `…,"[""a,b"",""\""ab\""""]",…` → `['a,b','"ab"']` `…,"[[""a"",""b""]]",…` → `[['a','b']]` |
| タプル | 配列と同じです。 | `…,"[""a"",1]",…` → `['a',1]` `…,"[""\""ab\"""",12]",…` → `['"ab"',12]` |
| システム値 | テキストと同じです。 | `…,10,…` → `'10'` |
| ファイル | CSV入力には対応していません。 |  |

ExcelやGoogleスプレッドシートではCSVエクスポート時に必要に応じて `"` が付与されるため、各セルの値の入力では不要です。

例えばGoogleスプレッドシートで以下のように入力します。

![一括実行用のCSVファイルをスプレッドシートで作成する例](/images/action_batch/spread_sheet.png)

入力したシートをCSV形式でエクスポートした結果が以下で、そのまま一括実行で利用できます。

```
text1,text2,text3,array1,array2,array3
a,"a,b","""ab""","[""a"",""b""]","[""a,b"", ""c,d""]","[""\""ab\"""", ""\""cd\""""]"
```

### 選択肢が設定されたパラメーターの入力 [](#選択肢が設定されたパラメーターの入力)

[複数の選択肢](/action/parameter/select_parameter/) や [マスターデータ取得設定](/action/parameter/master_data_fetch_setting/) が設定されたパラメーターでは、CSVに **選択肢の値** と **選択肢のラベル** のどちらでも入力できます。

CSVに入力した値が選択肢のラベルと一致する場合は、対応する選択肢の値に変換されます。いずれのラベルとも一致しない場合は、入力した値がそのまま使われます。

例えば値が `13` 、ラベルが `東京都` の選択肢が設定されたパラメーターでは、以下のいずれの入力でも `13` として扱われます。

| CSVの入力値 | フォームの値 | 変換の内容 |
| --- | --- | --- |
| `…,東京都,…` | `13` | ラベルと一致するため値に変換する |
| `…,13,…` | `13` | 値をそのまま使う |

[アクショングループ](/action/action_group/) [設定内容のダウンロード](/action/download_action_settings/)
---
[アクション](/action/)

アクションのコピー

# アクションのコピー

アクションの設定を複製して別のアクションを作成できます。アクションの複製は、アクションの設定画面からできます。

画面右上に複製用のボタンが置かれているので、そちらをクリックしてください。

複製に成功すると複製されたアクションの画面に移動します。設定内容は、複製後の新しいアクションの編集画面で変更してください。

![複製の導線](/images/copy_action/copy_button.png)

[バージョン管理](/action/versions/) [画像や動画の表示](/action/action_media_result/)
---
[アクション](/action/)

定期実行

# 定期実行

定期実行は、アクションを指定したスケジュールで自動的に繰り返し実行する機能です。

毎日の定時レポート生成や、定期的なデータ同期など、繰り返し発生する業務を自動化できます。

![定期実行のデモ動画](/images/action_cron_job/demo.gif)

## 前提条件 [](#前提条件)

定期実行を作成するには、実行対象のアクションを事前に作成しておく必要があります。

## 必要なロール [](#必要なロール)

定期実行の作成・管理には、以下のいずれかの [ロール](/admin/user_management/project_group/#%E3%83%AD%E3%83%BC%E3%83%AB) が必要です。

- プロジェクト管理者
- 開発責任者
- 開発者
- アクション運用責任者

定期実行の一覧表示や実行履歴の閲覧は、すべてのプロジェクトメンバーが利用できます。

## 定期実行を作成する [](#定期実行を作成する)

1. メニューバーで「定期実行の一覧」を選択して、定期実行の一覧画面に移動します。
1. 「定期実行の追加」を選択します。

![定期実行の追加フォーム。名前入力欄（例：日次レポート送信）、cron式切り替えトグル付きのスケジュール設定、曜日指定（日〜土の全曜日が選択済み）、実行時刻の指定（時刻指定モードで9時0分、追加ボタンあり）、アクション選択ドロップダウン、「この定期実行は現在選択中の環境『開発環境』に設定されます」という案内メッセージ、保存ボタンで構成されたUI。](/images/action_cron_job/new_form.png)

1. 以下の項目を入力します。
  - **名前**: 定期実行の名前を入力します。1文字以上128文字以内で設定できます。
  - **スケジュール**: 実行スケジュールを設定します。詳しくは [スケジュールの設定形式](/action/cron_jobs/#%E3%82%B9%E3%82%B1%E3%82%B8%E3%83%A5%E3%83%BC%E3%83%AB%E3%81%AE%E8%A8%AD%E5%AE%9A%E5%BD%A2%E5%BC%8F) をご覧ください。
  - **アクション**: 実行するアクションを選択します。
  - **パラメーター**: 選択したアクションにパラメーターがある場合、実行時の値を設定します。
  - **実行者**: アクションを実行するユーザーまたはサービスアカウントを設定します。詳しくは [実行者](/action/cron_jobs/#%E5%AE%9F%E8%A1%8C%E8%80%85) をご覧ください。
1. 「保存」を選択して定期実行の作成は完了です。

定期実行は、現在選択中の環境に対して設定されます。

## 実行者 [](#実行者)

⚠️

この機能は現在開発中であり、まだ公開されていません。記載内容は今後変更される可能性があります。

定期実行のアクションを実行するユーザーまたはサービスアカウントです。既定では設定者（定期実行を作成したユーザー）が実行者になります。プロジェクトに所属する [サービスアカウント](/service_account/) を実行者にする場合は、「サービスアカウントを実行者にする」を有効にしてサービスアカウントを選択します。

サービスアカウントを実行者に指定すると、実行履歴や監査ログの実行者がそのサービスアカウントになります。担当者ではなくシステムが実行したことを記録として残したい場合に利用します。

実行者にサービスアカウントを指定するには、以下をすべて満たす必要があります。

- サービスアカウントが、定期実行の環境が属するプロジェクトに所属していること
- サービスアカウントが、対象アクションの実行権限を持っていること
- 定期実行を設定するユーザー自身も、対象アクションの実行権限を持っていること
- 実行環境で [環境別の利用制限](/admin/environment/access_control/) が有効になっていないこと

サービスアカウントを実行者に指定した場合、定義済み引数の `currentUser.id` /
`currentUser.name` / `currentUser.email`
はいずれも空文字になります。実行するユーザーが存在しないためです。

## スケジュールの設定形式 [](#スケジュールの設定形式)

画面上の入力フォームからスケジュールを設定します。実行日と実行時刻の組み合わせで指定します。

### 実行日 [](#実行日)

| 指定方法 | 説明 | 例 |
| --- | --- | --- |
| 曜日で指定 | 特定の曜日に実行する | 毎週月曜日と金曜日 |
| 日にちで指定 | 毎月特定の日に実行する | 毎月1日と15日 |

### 実行時刻 [](#実行時刻)

| 指定方法 | 説明 | 例 |
| --- | --- | --- |
| 時刻指定 | 指定した時刻に実行する | 毎日9:00と18:00 |
| 毎時 | 毎時、指定した分に実行する | 毎時0分と30分 |
| 一定間隔 | 一定間隔で実行する | 5分ごと、2時間ごと |

「一定間隔」を選択した場合、指定した値の倍数の時刻に実行されます。たとえば5分ごとの場合、毎時0分、5分、10分、…に実行されます。

スケジュールの時刻は日本標準時（JST）で設定されます。

### cron式で入力 [](#cron式で入力)

「cron式で入力」トグルを有効にすると、cron式を直接入力してスケジュールを設定できます。UI形式では表現できない複雑なスケジュールを設定したい場合に使用します。

## 定期実行を管理する [](#定期実行を管理する)

### 定期実行の一覧 [](#定期実行の一覧)

定期実行の一覧画面では、以下の情報を確認できます。

| 項目 | 説明 |
| --- | --- |
| 名前 | 定期実行の名前 |
| アクション | 実行するアクション名 |
| スケジュール | 設定されたスケジュール |
| 稼働状態 | 現在の稼働状態 |
| 設定者 | 定期実行を作成したユーザー名 |
| 実行者 | アクションを実行するユーザーまたはサービスアカウント |

一覧から定期実行を選択すると、詳細ページに移動します。

### 詳細ページ [](#詳細ページ)

定期実行の詳細ページでは、以下の情報を確認できます。

| 項目 | 説明 |
| --- | --- |
| 名前 | 定期実行の名前 |
| アクション | 実行するアクション名 |
| スケジュール | 設定されたスケジュール |
| 次回の実行予定日時 | スケジュールに基づく次回の実行予定日時 |
| 次次回の実行予定日時 | スケジュールに基づく次次回の実行予定日時 |
| パラメーター | アクションに設定されたパラメーターの値 |
| 実行者 | アクションを実行するユーザーまたはサービスアカウント |

名前、スケジュール、アクション、実行者はそれぞれ詳細ページから編集できます。

### 稼働状態 [](#稼働状態)

定期実行の稼働状態は以下の通りです。

| 稼働状態 | 説明 |
| --- | --- |
| 稼働中 | スケジュールに従って定期的に実行されている状態 |
| 停止中 | スケジュールの実行が一時的に停止されている状態 |

### 停止と再開 [](#停止と再開)

定期実行を一時的に停止できます。停止中はスケジュールに従った自動実行はされません。

1. 定期実行の詳細ページを開きます。
1. 「停止」を選択すると、定期実行が停止されます。

停止した定期実行は、「再開」を選択することでスケジュールに従った自動実行を再開できます。

### スケジュールの変更 [](#スケジュールの変更)

1. 定期実行の詳細ページを開きます。
1. スケジュールの横にある編集ボタンを選択します。
1. 新しいスケジュールを入力し、「保存」を選択します。

### 名前の変更 [](#名前の変更)

1. 定期実行の詳細ページを開きます。
1. 名前の横にある編集ボタンを選択します。
1. 新しい名前を入力し、「保存」を選択します。

### アクションの変更 [](#アクションの変更)

1. 定期実行の詳細ページを開きます。
1. アクションの横にある編集ボタンを選択します。
1. 新しいアクションを選択し、必要に応じてパラメーターを設定して「保存」を選択します。

### 実行者の変更 [](#実行者の変更)

⚠️

この機能は現在開発中であり、まだ公開されていません。記載内容は今後変更される可能性があります。

1. 定期実行の詳細ページを開きます。
1. 実行者の横にある編集ボタンを選択します。
1. 設定者を実行者にする場合は「サービスアカウントを実行者にする」を無効にします。サービスアカウントを実行者にする場合は「サービスアカウントを実行者にする」を有効にしてサービスアカウントを選択します。
1. 「保存」を選択します。

アクションを変更しても実行者は引き継がれます。ただし、変更後のアクションの実行権限を実行者のサービスアカウントが持っていない場合は変更できません。

### 削除 [](#削除)

不要になった定期実行は削除できます。

1. 定期実行の詳細ページを開きます。
1. 「削除」を選択します。
1. 確認画面で削除を確定します。

⚠️

削除した定期実行は元に戻せません。再度同じスケジュールで実行したい場合は、新しく定期実行を作成してください。

## 実行履歴を確認する [](#実行履歴を確認する)

定期実行の詳細ページでは、過去の実行履歴を確認できます。ステータスやスケジュール日時の範囲で絞り込み検索もできます。

実行履歴では、以下の情報を確認できます。

| 項目 | 説明 |
| --- | --- |
| スケジュール | スケジュールされた実行日時 |
| 試行回数 | 実行の試行回数 |
| 実行ステータス | 実行の結果 |
| 実行日時 | 実際に実行された日時 |

実行ステータスは以下の通りです。

| ステータス | 説明 |
| --- | --- |
| 待機中 | まだ実行されていない状態 |
| 実行中 | 実行中の状態 |
| 実行完了 | 実行が正常に完了した状態 |
| キャンセル | キャンセルされた状態 |
| エラー | 実行時にエラーが発生した状態 |

### 再試行する [](#再試行する)

過去の実行履歴から、特定のスケジュール日時の実行を手動で再試行できます。

1. 実行履歴から再試行したい実行を選択します。
1. 「再試行」を選択します。

実行が失敗した場合や、結果を再度取得したい場合に活用できます。

[予約実行](/action/scheduled_jobs/) [アクショングループ](/action/action_group/)
---
[アクション](/action/)

データソース別の設定

Amazon Athena

# Amazon Athenaアクション

[Amazon Athena (opens in a new tab)](https://docs.aws.amazon.com/ja_jp/athena/latest/ug/what-is.html) は、Amazon S3に保存されているJSONやCSV形式のデータをSQLで分析できるサービスです。

Amazon Athenaアクションは、ベースマキナからAmazon AthenaのデータベースにSQLを実行できるアクションです。

設定方法は以下をご参照ください。

- [Amazon Athenaデータソースの設定](/action/datasources/amazon_athena/datasource_setting/)
- [Amazon Athenaアクションの設定](/action/datasources/amazon_athena/action_setting/)

また、Amazon Athenaアクションを使用して、監査ログストリーミングでAmazon S3に保存した監査ログの検索も可能です。

詳細は [Amazon S3に保存した監査ログをAmazon Athenaアクションで検索する](/admin/security/audit_log/search/s3/) をご参照ください。

[型定義ファイルのダウンロード](/action/datasources/javascript_action/download_dts_file/) [データソースの設定](/action/datasources/amazon_athena/datasource_setting/)
---
[アクション](/action/)

データソース別の設定

[Amazon Athena](/action/datasources/amazon_athena/)

アクションの設定

# Amazon Athenaアクションの設定

※ Amazon Athena アクションを使用するには事前に Amazon Athena のデータソースの作成が必要です。
データソースの作成方法は [Amazon Athena データソースの設定](/action/datasources/amazon_athena/datasource_setting/) をご参照ください。

Amazon Athena アクションは以下の手順で設定します。

1. 右上のメニューから「アクション」を選択してアクション一覧画面に移動します。
1. 「アクションの追加」を選択してアクションの作成画面に移動します。
1. 「基本情報の設定」を入力後「次へ」を選択して、「処理の設定」画面に移動します。
1. 「データソース」から事前に作成した Amazon Athena のデータソースを選択します。

![Amazon Athenaアクションの設定画面](/images/amazon_athena/action_setting.png)

Amazon Athena アクションではパラメーターなどの他のアクションと共通の項目に加えて、以下の項目を設定します。

- SQL文のタイトル
- SQL文
- JSON型の値をパースする

## SQL文のタイトル [](#sql文のタイトル)

SQL文のタイトルを設定します。

## SQL文 [](#sql文)

実行するSQL文を設定します。

SQL文は1つの Amazon Athena アクションに複数設定できます。

※ Amazon Athena アクションでは、それぞれのSQL文は別のトランザクションで実行されます。

### SQL文内でパラメーターを使用する [](#sql文内でパラメーターを使用する)

SQL文内では `{{ パラメーター名 }}` の形式でパラメーターを使用できます。

例えば、パラメーター名が「メールアドレス」のテキストパラメーターを使って `users` テーブルから特定のユーザーを検索するSQL文は以下です。

```
SELECT * FROM users WHERE email = {{ メールアドレス }};
```

`{{ パラメーター名 }}` の部分はアクションの実行時にプレースホルダーへ置換され、パラメーターの値が入力されてSQL文が実行されます。

パラメーターの種類ごとに、入力される値の形式は以下です。

| 種類 | 入力される値の形式 | 例 |
| --- | --- | --- |
| [テキスト](/action/parameter/text_parameter/) | 文字列（値が未入力の場合は空文字列） | `'test@example.com'` |
| [数値](/action/parameter/number_parameter/) | 数値（値が未入力の場合は `null` ） | `123`, `4.56`, `0`, `null` |
| [真偽値](/action/parameter/bool_parameter/) （フォーマットなし） | 真偽値 | `true`, `false` |
| [真偽値](/action/parameter/bool_parameter/) （フォーマット形式が文字列） | 文字列 | `'有効'`, `'無効'` |
| [日付](/action/parameter/date_parameter/) （unixtimeとして利用するが有効） | 数値（値が未入力の場合は `null` ） | `1672531200000`, `null` |
| [日付](/action/parameter/date_parameter/) （unixtimeとして利用するが無効） | 文字列（値が未入力の場合は空文字列） | `'2023-01-01'`, `'2023-01-01T00:00:00Z'` |
| [配列](/action/parameter/array_parameter/) （フォーマット形式がSQL） | 配列 | `(10,11,12)` |
| [配列](/action/parameter/array_parameter/) （フォーマット形式がJSON） | 文字列 | `'["taro","jiro","saburo"]'` |
| [配列](/action/parameter/array_parameter/) （フォーマット形式が区切り文字） | 文字列 | `'"taro","jiro","saburo"'` （区切り文字が `,` 、引用符が `"` の場合） |
| [タプル](/action/parameter/tuple_parameter/) （フォーマット形式がJSON） | 文字列 | `'["taro",25,"2023-01-01"]'` |
| [タプル](/action/parameter/tuple_parameter/) （フォーマット形式が区切り文字） | 文字列 | `'"taro","jiro","saburo"'` （区切り文字が `,` 、引用符が `"` の場合） |
| [SQL](/action/parameter/sql_parameter/) | プレースホルダーを使用せずに `{{ パラメータ名 }}` が値にそのまま置換されます。 | SQL型のパラメーターのドキュメントをご参照ください |
| JSON値 | Amazon Athena アクションでは使用できません | - |
| ファイル | Amazon Athena アクションでは使用できません | - |
| システム値 | Amazon Athena アクションでは使用できません | - |

## JSON型の値をパースする [](#json型の値をパースする)

アクションの実行結果に含まれるJSON型の列の値を、JavaScriptのオブジェクトや配列などに変換します。

詳細は [JSON型の列の値をJavaScriptの配列やオブジェクトに変換する](/action/datasources/amazon_athena/data_type/#json%E5%9E%8B%E3%81%AE%E5%88%97%E3%81%AE%E5%80%A4%E3%82%92javascript%E3%81%AE%E9%85%8D%E5%88%97%E3%82%84%E3%82%AA%E3%83%96%E3%82%B8%E3%82%A7%E3%82%AF%E3%83%88%E3%81%AB%E5%A4%89%E6%8F%9B%E3%81%99%E3%82%8B) をご参照ください。

[データソースの設定](/action/datasources/amazon_athena/datasource_setting/) [各データ型の値の扱い](/action/datasources/amazon_athena/data_type/)
---
[アクション](/action/)

データソース別の設定

[Amazon Athena](/action/datasources/amazon_athena/)

各データ型の値の扱い

# Amazon AthenaアクションでのAthenaの各データ型の値の扱い

ベースマキナにはアクションの実行結果に対してJavaScriptで処理を書く機能があります。

- [アクションの実行結果の加工スクリプト](/action/transformer_script/action_transform/)
- [ビュー](/view/what_is_view/)
- [JavaScriptアクション](/action/datasources/javascript_action/)

各アクションの実行結果の値は、それに対応するJavaScriptの型へと自動的に変換されます。

以下の表は、上記の機能でAmazon Athenaアクションの結果として使用される、Amazon Athenaのデータ型と、対応するJavaScriptの型の一覧です。

| Amazon Athenaのデータ型 | アクションの実行結果でのJavaScriptの型 | 対応状況 |
| --- | --- | --- |
| `VARCHAR` | `string | null` | 対応 |
| `CHAR` | `string | null` | 対応 |
| `UUID` | `string | null` | 対応 |
| `IPADDRESS` | `string | null` | 対応 |
| `DATE` | `string | null` | 対応 |
| `TIME` | `string | null` | 対応 |
| `TIME WITH TIME ZONE` | `string | null` | 対応 |
| `TIMESTAMP` | `string | null` | 対応 |
| `TIMESTAMP WITH TIME ZONE` | `string | null` | 対応 |
| `ARRAY` | `string | null` | 対応 |
| `ROW` | `string | null` | 対応 |
| `MAP` | `string | null` | 対応 |
| `DOUBLE` | `number | null` | 対応 |
| `INTEGER` | `number | null` | 対応 |
| `FLOAT` | `number | null` | 対応 |
| `TINYINT` | `number | null` | 対応 |
| `SMALLINT` | `number | null` | 対応 |
| `BOOLEAN` | `boolean | null` | 対応 |
| `BIGINT` | `bigint | null` | 対応 |
| `JSON` （JSON型の値をパースするが有効） | `Record<string, unknown> | unknown[] | string | number | boolean | null` | 対応 |
| `JSON` （JSON型の値をパースするが無効） | `string | null` | 対応 |
| `DECIMAL` | `string | null` | 未対応 |
| `VARBINARY` | `string | null` | 未対応 |
| `INTERVAL YEAR TO MONTH` | `string | null` | 未対応 |
| `INTERVAL DAY TO SECOND` | `string | null` | 未対応 |

各データ型の詳細はAWSのドキュメントの [Amazon Athenaのデータ型 (opens in a new tab)](https://docs.aws.amazon.com/ja_jp/athena/latest/ug/data-types.html) をご参照ください。

## 未対応のデータ型 [](#未対応のデータ型)

対応状況が未対応のデータ型はJavaScriptの型への変換が未対応で、現在は `string | null` に変換されますが、今後別のJavaScriptの型に変更される可能性があります。

なおAmazon Athenaアクションの実行結果に未対応のデータ型の列の値が含まれる場合、アクションの実行結果に以下のメッセージが表示されます。

![未対応のデータ型のメッセージ](/images/amazon_athena/unsupported_column.png)

## 各データ型の列の値を別のJavaScriptの型に変換する [](#各データ型の列の値を別のjavascriptの型に変換する)

以下は各データ型の列の値を、別のJavaScriptの型として扱いたい場合の変換方法です。

### SQL文でデータ型を変換する [](#sql文でデータ型を変換する)

アクションの実行で共通の変換をする場合は、SQL文内で `CAST` 関数を使ってデータ型を変換する方法が便利です。

例えば、以下のように `VARCHAR` 型の列の値を `INTEGER` 型に変換すると、
アクションの実行結果のJavaScriptの型は `number | null` になります。

```
SELECT
    -- ここでVARCHAR型の列「id」の値をINTEGER型に変換
    CAST(id AS INTEGER)
FROM
    users;
```

`CAST` 関数の詳細はTrino（Amazon Athenaのエンジン）のドキュメントの [Conversion functions (opens in a new tab)](https://trino.io/docs/current/functions/conversion.html#cast) をご参照ください。

### JavaScriptで値の型を変換する [](#javascriptで値の型を変換する)

各アクション実行ごとに別の変換をしたい場合は、JavaScriptのコード内で値の型を変換できます。

以下は、アクションの実行結果の加工スクリプトで `string | null` 型の値を `number` 型に変換する例です。

```
return [
  {
    success: results[0].success.map((user) => ({
      // `Number()`コンストラクターで`string | null`型の値を`number | null`型に変換
      id: user.id !== null ? Number(user.id) : null,
      name: user.name,
    })),
  },
];
```

### JSON型の列の値をJavaScriptの配列やオブジェクトに変換する [](#json型の列の値をjavascriptの配列やオブジェクトに変換する)

アクションの設定で「JSON型の値をパースする」を有効にすると、JSON型の列の値がJavaScriptのオブジェクトや配列などに変換されます。

例えば `'{"name": "John", "age": 30}'` という値は `{name: "John", age: 30}` というオブジェクトに変換されます。

### `ARRAY`, `ROW`, `MAP` 型の列の値をJavaScriptの配列やオブジェクトに変換する [](#arrayrowmap型の列の値をjavascriptの配列やオブジェクトに変換する)

通常、 `ARRAY`, `ROW`, `MAP` 型の列の値は `string | null` に変換されますが、以下の手順でJavaScriptの配列やオブジェクトに変換できます。

1. 「JSON型の値をパースする」を有効にする
1. `CAST` 関数で `ARRAY`, `ROW`, `MAP` 型の列の値を `JSON` 型に変換する

```
SELECT
    -- MAP型の列「login_user」の値をJSON型に変換
    CAST(login_user AS JSON)
FROM
    audit_logs;
```

[アクションの設定](/action/datasources/amazon_athena/action_setting/) [BigQuery](/action/datasources/bigquery/)
---
[アクション](/action/)

データソース別の設定

[Amazon Athena](/action/datasources/amazon_athena/)

データソースの設定

# Amazon Athenaデータソースの設定

Amazon Athenaのデータソースは以下の手順で設定します。

## Amazon AthenaのデータベースとIAMユーザーの作成

ベースマキナでAmazon Athenaを利用するには、事前にAWSで以下の操作が必要です。

- Amazon Athenaのデータベースの作成
- IAMユーザーの作成とアクセスキーの発行

### Amazon Athenaのデータベースの作成

AWSのコンソール上で、ベースマキナから接続するAmazon Athenaのデータベースを作成します。

Amazon Athenaのデータベースの作成方法は、AWSのドキュメントの [ステップ 1: データベースを作成する (opens in a new tab)](https://docs.aws.amazon.com/ja_jp/athena/latest/ug/step-1-create-a-database.html) をご参照ください。

### IAMユーザーの作成とアクセスキーの発行 [](#iamユーザーの作成とアクセスキーの発行)

次に、ベースマキナからAmazon Athenaへ接続するために、IAMユーザーを作成しアクセスキーを発行します。

IAMユーザーの作成とアクセスキーの発行は、AWSのドキュメントの [IAM ユーザーのアクセスキーの管理 (opens in a new tab)](https://docs.aws.amazon.com/ja_jp/IAM/latest/UserGuide/id_credentials_access-keys.html) をご参照ください。

IAMユーザーには、少なくとも下記の権限を持ったIAMポリシーを割り当てる必要があります。

- `athena:StartQueryExecution`
- `athena:GetQueryExecution`
- `athena:GetQueryResults`
- `athena:GetPreparedStatement`
- `athena:CreatePreparedStatement`
- `athena:DeletePreparedStatement`
- `glue:GetDatabase`
- `glue:GetTable`
- `s3:GetObject`
- `s3:ListBucket`
- `s3:PutObject`

その他、ベースマキナからAmazon Athenaに対して実行したい操作に応じて、必要な権限を追加してください。

Amazon AthenaでのIAMポリシーの詳細は、AWSのドキュメントの [Athena でのアイデンティティとアクセス権の管理 (opens in a new tab)](https://docs.aws.amazon.com/ja_jp/athena/latest/ug/security-iam-athena.html) をご参照ください。

## データソースの作成 [](#データソースの作成)

![Amazon Athenaのデータソースの作成画面](/images/amazon_athena/datasource_setting.png)

1. 右上のメニューから「データソース」を選択してデータソース一覧画面に移動します。
1. 「データソースの追加」を選択してデータソースの追加画面に移動します。
1. 「Amazon Athena」を選択して、Amazon Athenaのデータソースの作成画面に移動します。
1. 各設定項目を入力します。
1. 「保存」を選択します。

Amazon Athenaのデータソースには以下の項目を設定します。

### 名前 [](#名前)

データソースの名前を設定します。

### リージョン [](#リージョン)

接続するAmazon Athenaのデータベースのリージョンを設定します。

### データベース名 [](#データベース名)

接続するAmazon Athenaのデータベースの名前です。

### クエリの結果の場所 [](#クエリの結果の場所)

接続するAmazon Athenaのデータベースのクエリ結果の場所です。

例） `s3://bucket-name/prefix/object-name`

### アクセスキー [](#アクセスキー)

発行したIAMユーザーのアクセスキーを設定します。

### シークレットアクセスキー [](#シークレットアクセスキー)

発行したIAMユーザーのシークレットアクセスキーを設定します。

## データソースの編集 [](#データソースの編集)

1. 右上のメニューから「データソース」を選択してデータソース一覧画面に移動します。
1. 編集するデータソースを選択してデータソースの編集画面に移動します。
1. 各設定項目を入力します。
1. 「保存」を選択します。

## データソースの削除 [](#データソースの削除)

![データソースの削除](/images/datasource/delete.png)

1. 右上のメニューから「設定」を選択してプロジェクト設定画面に移動します。
1. 「データソース設定」を選択してデータソース設定画面に移動します。
1. 削除するデータソースの行の右端の3点リーダから「削除する」を選択します。
1. 表示される画面で「OK」を選択します。

[Amazon Athena](/action/datasources/amazon_athena/) [アクションの設定](/action/datasources/amazon_athena/action_setting/)
---
[アクション](/action/)

データソース別の設定

Amazon S3

# Amazon S3

Amazon S3アクションでは、ファイルのアップロードとダウンロードができます。

## Amazon S3のデータソースに接続する

1. 右上のメニューから「データソース」を選択する

2. 「データソースの追加」をクリックする

3. データソースの種類の中から「 Amazon S3 」を選択する

![データソースの選択](/images/awss3_integration/select.png)

4. データソースへの接続に必要な情報を入力して保存する

![データソースの接続設定](/images/awss3_integration/connection.png)

### IAMユーザーの作成 [](#iamユーザーの作成)

上記の `4` のステップでは、Amazon S3の操作に必要な認証情報を登録します。

AWSのコンソール上でIAMユーザーを作成しアクセスキーを発行したうえで、そのアクセスキーとシークレットキーを登録してください。

アクセスキー発行の詳しい方法については、 [IAM ユーザーのアクセスキーの管理 (opens in a new tab)](https://docs.aws.amazon.com/ja_jp/IAM/latest/UserGuide/id_credentials_access-keys.html) をご参照ください。

### 必要なポリシーの割り当て [](#必要なポリシーの割り当て)

IAMユーザーには、アクションで実行したい操作に応じて、下記の権限を持ったIAMポリシーを割り当てる必要があります。

- アップロード： `s3:PutObject`
- ダウンロード： `s3:GetObject`
- オブジェクトの一覧取得： `s3:ListBucket`

IAMポリシーの詳しい作成方法に関しては、 [IAM でのポリシーとアクセス許可 (opens in a new tab)](https://docs.aws.amazon.com/ja_jp/IAM/latest/UserGuide/access_policies.html) をご参照ください。

### OIDC で接続する [](#oidc-で接続する)

OpenID Connect (OIDC) を使用すると、アクセスキーをベースマキナに渡すことなく、IAMロールの権限でAmazon S3を操作できます。ベースマキナが発行するID Tokenを使って `sts:AssumeRoleWithWebIdentity` を実行し、一時的な認証情報を取得します。

なお、OIDCを利用する場合は、前述のIAMユーザーの作成およびアクセスキーの登録は不要です（認証方式はいずれか一方を選択します）。

以下のTerraformコードで必要なリソースを作成します。 `<BUCKET_NAME>` 、 `<ROLE_NAME>` 、 `<AUDIENCE>` を環境に合わせて置き換えてください。 `<AUDIENCE>` は任意の文字列で、ベースマキナ側の接続設定の「Audience」と同じ値にする必要があります。

既存のバケットを使用する場合は `aws_s3_bucket` の定義を削除し、ポリシーの `Resource` を既存バケットのARNに変更してください。

```
provider "aws" {
  region = "ap-northeast-1"
}
 
# S3 バケット（既存バケットを使う場合は不要）
resource "aws_s3_bucket" "bucket" {
  bucket = "<BUCKET_NAME>"
}
 
# ベースマキナの IdP を信頼する OIDC プロバイダー
data "tls_certificate" "basemachina" {
  url = "https://idp.basemachina.com"
}
 
resource "aws_iam_openid_connect_provider" "basemachina" {
  url            = "https://idp.basemachina.com"
  client_id_list = ["<AUDIENCE>"]
  thumbprint_list = [
    data.tls_certificate.basemachina.certificates[length(data.tls_certificate.basemachina.certificates) - 1].sha1_fingerprint,
  ]
}
 
# ベースマキナが権限借用する IAM ロール
resource "aws_iam_role" "basemachina" {
  name = "<ROLE_NAME>"
 
  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect    = "Allow"
      Principal = { Federated = aws_iam_openid_connect_provider.basemachina.arn }
      Action    = "sts:AssumeRoleWithWebIdentity"
      Condition = {
        StringEquals = {
          "idp.basemachina.com:aud" = "<AUDIENCE>"
        }
      }
    }]
  })
}
 
# バケットの読み書き権限
resource "aws_iam_role_policy" "s3" {
  role = aws_iam_role.basemachina.id
 
  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Effect   = "Allow"
        Action   = ["s3:GetObject", "s3:PutObject"]
        Resource = "${aws_s3_bucket.bucket.arn}/*"
      },
      {
        Effect   = "Allow"
        Action   = "s3:ListBucket"
        Resource = aws_s3_bucket.bucket.arn
      },
    ]
  })
}
```

#### IDトークンのカスタムクレーム [](#idトークンのカスタムクレーム)

ベースマキナが発行するID Tokenには、以下のカスタムクレームが含まれます。

| クレーム | 内容 |
| --- | --- |
| `tenant_subdomain` | ご利用のサブドメイン（ `xxx.basemachina.com` の `xxx` 部分） |
| `project_id` | プロジェクトID |
| `environment_id` | 環境ID |

なお、AWSのIAM信頼ポリシーの条件で利用できるのは `idp.basemachina.com:aud` と `idp.basemachina.com:sub` のみで、上記のカスタムクレームは条件に利用できません。アクセス制御には、ロールを引き受ける際の `aud` （Audience）を使用します。

#### ベースマキナ側の設定 [](#ベースマキナ側の設定)

セットアップ完了後、データソースの接続設定で認証方式として「OIDC」を選択し、以下の情報を入力します。

| 項目 | 値 | 例 |
| --- | --- | --- |
| Audience | OIDCプロバイダーに登録した値と同じ文字列 | `basemachina-s3` |
| IAM ロール ARN | 作成したIAMロールのARN | `arn:aws:iam::123456789012:role/role-name` |

## Amazon S3をアクションで利用する

1. 右上のメニューから「アクション」を選択する

2. 「アクションの追加」をクリックする

3. アクション名やパラメーターを設定する

![データソースの選択](/images/awss3_integration/basic_action.png)

### アップロード [](#アップロード)

![アップロード設定画面](/images/blob_action/upload.png)

1. アクションパラメーターを設定します
  - ファイルパラメーターを **必須** にします
  - またアップロードするファイル名を指定するためにファイル名を入力するためのテキストパラメーターも必須にします
1. バケット名を `test-bucket` のように設定します
1. 実行メソッドを「アップロード」に設定します
1. オブジェクト名（オブジェクトキー）を `images/{{ ファイル名 }}` のように設定します
  - アップロードされるファイルのオブジェクト名となります
1. ファイル内容に使うパラメーターを1で作成したファイルパラメーターに設定します

アクション実行画面でパラメーターとしてファイル名を `test.png` と設定し実行した場合は下記にアップロードされます。

`s3://test-bucket/images/test.png` ### ダウンロード [](#ダウンロード)

![ダウンロード設定画面](/images/blob_action/download.png)

1. アクションパラメーターを設定します
  - ダウンロードするファイル名を指定するためのテキストパラメーターを必須にします
1. バケット名を `test-bucket` のように設定します
1. 実行メソッドを「ダウンロード」に設定します
1. オブジェクト名（オブジェクトキー）を `images/{{ ファイル名 }}` のように設定します
  - ダウンロードされるファイルのオブジェクト名となります

アクション実行画面でパラメーターとしてファイル名を `test.png` と設定し実行した場合は下記のファイルがダウンロードされます。

`s3://test-bucket/images/test.png` ### オブジェクトの一覧 [](#オブジェクトの一覧)

![オブジェクトの一覧設定画面](/images/blob_action/list_object.png)

1. バケット名を入力します。
1. 実行メソッドで「オブジェクトの一覧」を選択します。
1. 必要に応じてオブジェクト名（オブジェクトキー）を入力します。
1. 保存します。

設定したアクションを実行すると、オブジェクトの一覧を取得できます。

指定したオブジェクト名（オブジェクトキー）は、一覧取得時の接頭辞による絞り込みに使われます。

![オブジェクトの一覧の結果画面](/images/blob_action/list_object_result.png)

#### 実行結果の形式 [](#実行結果の形式)

下記の形式のオブジェクトを含んだ配列を返します。

| キー名 | 説明 |
| --- | --- |
| objectKey | オブジェクト名（オブジェクトキー） |
| lastModified | ファイルの更新日時のUnixTimestamp (秒) |
| size | ファイルのバイトサイズ |

### 署名付きURLの発行 [](#署名付きurlの発行)

![オブジェクトの署名付きURL発行の設定画面](/images/blob_action/issue_signed_url.png)

1. バケット名を入力します。
1. 実行メソッドで「署名付きURLの発行」を選択します。
1. オブジェクト名（オブジェクトキー）を入力します。
1. HTTPメソッドを「GET」または「PUT」から選択します。
1. 保存します。

設定したアクションを実行すると、署名付きURLが発行されます。

![オブジェクトの署名付きURL発行の結果画面](/images/blob_action/issue_signed_url_result.png)

#### 実行結果の形式 [](#実行結果の形式-1)

下記の形式のオブジェクトを返します。

| キー名 | 説明 |
| --- | --- |
| signedUrl | 発行した署名付きURL |

発行される署名付きURLの有効期限は24時間です。

ただし、認証方式にOIDCを利用している場合は、署名付きURLの有効期限が一時的な認証情報の寿命（最大1時間）に制限されます。より長期間有効な署名付きURLが必要な場合は、アクセスキーによる認証をご利用ください。

### 便利な使い方 [](#便利な使い方)

「バケット名」と「オブジェクト名（オブジェクトキー）」では、アクションのパラメーターのほかに、 [変数・シークレット](/action/parameter/vars_secrets/) と [事前定義パラメーター](/action/parameter/predefined_parameter/) をご利用いただくことができます。環境に応じて値を変更したい場合などにご利用ください。

書式については [変数・シークレットの使用方法](/action/parameter/vars_secrets/#%E5%A4%89%E6%95%B0%E3%82%B7%E3%83%BC%E3%82%AF%E3%83%AC%E3%83%83%E3%83%88%E3%81%AE%E4%BD%BF%E7%94%A8%E6%96%B9%E6%B3%95) をご覧ください。

[Google スプレッドシート](/action/datasources/googlespreadsheet_integration/) [Google Cloud Storage](/action/datasources/gcs_integration/)
---
[アクション](/action/)

データソース別の設定

BigQuery

# BigQueryアクション

[BigQuery (opens in a new tab)](https://cloud.google.com/bigquery?hl=ja) は、Google Cloudが提供するフルマネージドのデータウェアハウスサービスです。

BigQueryアクションは、ベースマキナからBigQueryのデータセットにSQLを実行できるアクションです。

設定方法は以下をご参照ください。

- [BigQueryデータソースの設定](/action/datasources/bigquery/datasource_setting/)
- [BigQueryアクションの設定](/action/datasources/bigquery/action_setting/)

[各データ型の値の扱い](/action/datasources/amazon_athena/data_type/) [データソースの設定](/action/datasources/bigquery/datasource_setting/)
---
[アクション](/action/)

データソース別の設定

[BigQuery](/action/datasources/bigquery/)

アクションの設定

# BigQueryアクションの設定

※ BigQuery アクションを使用するには事前に BigQuery のデータソースの作成が必要です。
データソースの作成方法は [BigQuery データソースの設定](/action/datasources/bigquery/datasource_setting/) をご参照ください。

BigQuery アクションは以下の手順で設定します。

1. 右上のメニューから「アクション」を選択してアクション一覧画面に移動します。
1. 「アクションの追加」を選択してアクションの作成画面に移動します。
1. 「基本情報の設定」を入力後「次へ」を選択して、「処理の設定」画面に移動します。
1. 「データソース」から事前に作成した BigQuery のデータソースを選択します。

![BigQueryアクションの設定画面](/images/bigquery/action_setting.png)

BigQuery アクションではパラメーターなどの他のアクションと共通の項目に加えて、以下の項目を設定します。

- SQL文のタイトル
- SQL文
- JSON型の値をパースする

## SQL文のタイトル [](#sql文のタイトル)

SQL文のタイトルを設定します。

## SQL文 [](#sql文)

実行するSQL文を設定します。

SQL文は1つの BigQuery アクションに複数設定できます。

※ BigQuery アクションでは、それぞれのSQL文は別のトランザクションで実行されます。

### SQL文内でパラメーターを使用する [](#sql文内でパラメーターを使用する)

SQL文内では `{{ パラメーター名 }}` の形式でパラメーターを使用できます。

例えば、パラメーター名が「メールアドレス」のテキストパラメーターを使って `users` テーブルから特定のユーザーを検索するSQL文は以下です。

```
SELECT * FROM users WHERE email = {{ メールアドレス }};
```

`{{ パラメーター名 }}` の部分はアクションの実行時にプレースホルダーへ置換され、パラメーターの値が入力されてSQL文が実行されます。

パラメーターの種類ごとに、入力される値の形式は以下です。

| 種類 | 入力される値の形式 | 例 |
| --- | --- | --- |
| [テキスト](/action/parameter/text_parameter/) | 文字列（値が未入力の場合は空文字列） | `'test@example.com'` |
| [数値](/action/parameter/number_parameter/) | 数値（値が未入力の場合は `null` ） | `123`, `4.56`, `0`, `null` |
| [真偽値](/action/parameter/bool_parameter/) （フォーマットなし） | 真偽値 | `true`, `false` |
| [真偽値](/action/parameter/bool_parameter/) （フォーマット形式が文字列） | 文字列 | `'有効'`, `'無効'` |
| [日付](/action/parameter/date_parameter/) （unixtimeとして利用するが有効） | 数値（値が未入力の場合は `null` ） | `1672531200000`, `null` |
| [日付](/action/parameter/date_parameter/) （unixtimeとして利用するが無効） | 文字列（値が未入力の場合は空文字列） | `'2023-01-01'`, `'2023-01-01T00:00:00Z'` |
| [配列](/action/parameter/array_parameter/) （フォーマット形式がSQL） | 配列 | `(10,11,12)` |
| [配列](/action/parameter/array_parameter/) （フォーマット形式がJSON） | 文字列 | `'["taro","jiro","saburo"]'` |
| [配列](/action/parameter/array_parameter/) （フォーマット形式が区切り文字） | 文字列 | `'"taro","jiro","saburo"'` （区切り文字が `,` 、引用符が `"` の場合） |
| [タプル](/action/parameter/tuple_parameter/) （フォーマット形式がJSON） | 文字列 | `'["taro",25,"2023-01-01"]'` |
| [タプル](/action/parameter/tuple_parameter/) （フォーマット形式が区切り文字） | 文字列 | `'"taro","jiro","saburo"'` （区切り文字が `,` 、引用符が `"` の場合） |
| [SQL](/action/parameter/sql_parameter/) | プレースホルダーを使用せずに `{{ パラメータ名 }}` が値にそのまま置換されます。 | SQL型のパラメーターのドキュメントをご参照ください |
| JSON値 | BigQuery アクションでは使用できません | - |
| ファイル | BigQuery アクションでは使用できません | - |
| システム値 | BigQuery アクションでは使用できません | - |

## JSON型の値をパースする [](#json型の値をパースする)

アクションの実行結果に含まれるJSON型の列の値を、JavaScriptのオブジェクトや配列などに変換します。

詳細は [JSON型の列の値をJavaScriptの配列やオブジェクトに変換する](/action/datasources/bigquery/data_type/#json%E5%9E%8B%E3%81%AE%E5%88%97%E3%81%AE%E5%80%A4%E3%82%92javascript%E3%81%AE%E9%85%8D%E5%88%97%E3%82%84%E3%82%AA%E3%83%96%E3%82%B8%E3%82%A7%E3%82%AF%E3%83%88%E3%81%AB%E5%A4%89%E6%8F%9B%E3%81%99%E3%82%8B) をご参照ください。

[データソースの設定](/action/datasources/bigquery/datasource_setting/) [各データ型の値の扱い](/action/datasources/bigquery/data_type/)
---
[アクション](/action/)

データソース別の設定

[BigQuery](/action/datasources/bigquery/)

各データ型の値の扱い

# BigQueryアクションでのBigQueryの各データ型の値の扱い

ベースマキナにはアクションの実行結果に対してJavaScriptで処理を書く機能があります。

- [アクションの実行結果の加工スクリプト](/action/transformer_script/action_transform/)
- [ビュー](/view/what_is_view/)
- [JavaScriptアクション](/action/datasources/javascript_action/)

各アクションの実行結果の値は、それに対応するJavaScriptの型へと自動的に変換されます。

以下の表は、上記の機能でBigQueryアクションの結果として使用される、BigQueryのデータ型と、対応するJavaScriptの型の一覧です。

## BigQueryのデータ型のサポート状況 [](#bigqueryのデータ型のサポート状況)

| BigQueryの型 | アクションの実行結果でのJavaScriptの型 | 対応状況 |
| --- | --- | --- |
| `STRING` | `string | null` | 対応 |
| `DATE` | `string | null` | 対応 |
| `DATETIME` | `string | null` | 対応 |
| `TIME` | `string | null` | 対応 |
| `TIMESTAMP` | `string | null` | 対応 |
| `FLOAT64` | `number | null` | 対応 |
| `INT64` | `bigint | null` | 対応 |
| `BOOL` | `boolean | null` | 対応 |
| `JSON` （JSON型の値をパースするが有効） | `Record<string, unknown> | unknown[] | string | number | boolean | null` | 対応 |
| `JSON` （JSON型の値をパースするが無効） | `string | null` | 対応 |
| `GEOGRAPHY` | `string | null` | 未対応 |
| `BYTES` | `string | null` | 未対応 |
| `STRUCT` | `string | null` | 未対応 |
| `NUMERIC` | `string | null` | 未対応 |
| `BIGNUMERIC` | `string | null` | 未対応 |
| `ARRAY` | `string | null` | 未対応 |
| `RANGE` | `string | null` | 未対応 |
| `INTERVAL` | `string | null` | 未対応 |

各データ型の詳細は [BigQueryのデータ型 (opens in a new tab)](https://cloud.google.com/bigquery/docs/reference/standard-sql/data-types) をご参照ください。

## 未対応のデータ型 [](#未対応のデータ型)

対応状況が未対応のデータ型はJavaScriptの型への変換が未対応で、現在は `string | null` に変換されますが、今後別のJavaScriptの型に変更される可能性があります。

なおBigQueryアクションの実行結果に未対応のデータ型の列の値が含まれる場合、アクションの実行結果に以下のメッセージが表示されます。

![未対応のデータ型のメッセージ](/images/bigquery/unsupported_column.png)

## 各データ型の列の値を別のJavaScriptの型に変換する [](#各データ型の列の値を別のjavascriptの型に変換する)

以下は各データ型の列の値を、別のJavaScriptの型として扱いたい場合の変換方法です。

### SQL文でデータ型を変換する [](#sql文でデータ型を変換する)

アクションの実行で共通の変換をする場合は、SQL文内で `CAST` 関数を使ってデータ型を変換する方法が便利です。

例えば、以下のように `STRING` 型の列の値を `FLOAT64` 型に変換すると、
アクションの実行結果のJavaScriptの型は `number | null` になります。

```
SELECT
    -- ここでSTRING型の列「id」の値をFLOAT64型に変換
    CAST(id AS FLOAT64) AS id
FROM
    users;
```

`CAST` 関数の詳細はBigQueryのドキュメントの [Conversion functions (opens in a new tab)](https://cloud.google.com/bigquery/docs/reference/standard-sql/conversion_functions#cast) をご参照ください。

### JavaScriptで値の型を変換する [](#javascriptで値の型を変換する)

各アクション実行ごとに別の変換をしたい場合は、JavaScriptのコード内で値の型を変換できます。

以下は、アクションの実行結果の加工スクリプトで `string | null` 型の値を `number` 型に変換する例です。

```
return [
  {
    success: results[0].success.map((user) => ({
      // `Number()`コンストラクターで`string | null`型の値を`number | null`型に変換
      id: user.id !== null ? Number(user.id) : null,
      name: user.name,
    })),
  },
];
```

### JSON型の列の値をJavaScriptの配列やオブジェクトに変換する [](#json型の列の値をjavascriptの配列やオブジェクトに変換する)

アクションの設定で「JSON型の値をパースする」を有効にすると、JSON型の列の値がJavaScriptのオブジェクトや配列などに変換されます。

例えば `'{"name": "John", "age": 30}'` という値は `{name: "John", age: 30}` というオブジェクトに変換されます。

### `ARRAY`, `STRUCT` 型の列の値をJavaScriptの配列やオブジェクトに変換する [](#arraystruct型の列の値をjavascriptの配列やオブジェクトに変換する)

通常、 `ARRAY`, `STRUCT` 型の列の値は `string | null` に変換されますが、以下の手順でJavaScriptの配列やオブジェクトに変換できます。

1. 「JSON型の値をパースする」を有効にする
1. `TO_JSON` 関数で `ARRAY`, `STRUCT` 型の列の値を `JSON` 型に変換する

```
SELECT
    -- STRUCT型の列「login_user」の値をJSON型に変換
    TO_JSON(login_user)
FROM
    audit_logs;
```

[アクションの設定](/action/datasources/bigquery/action_setting/) [Snowflake](/action/datasources/snowflake/)
---
[アクション](/action/)

データソース別の設定

[BigQuery](/action/datasources/bigquery/)

データソースの設定

# BigQueryデータソースの設定

BigQueryのデータソースは以下の手順で設定します。

## BigQueryのテーブルとサービスアカウントの作成 [](#bigqueryのテーブルとサービスアカウントの作成)

ベースマキナでBigQueryを利用するには、事前にGoogle Cloud上で以下の操作が必要です。

- BigQueryのテーブルの作成
- サービスアカウントの作成とJSONキーの取得

### BigQueryのテーブルの作成 [](#bigqueryのテーブルの作成)

Google Cloudのコンソール上で、ベースマキナから接続するBigQueryのテーブルを作成します。

BigQueryのテーブルの作成方法は、Google Cloudのドキュメントの [Google Cloud コンソールでデータを読み込んでクエリを実行する (opens in a new tab)](https://cloud.google.com/bigquery/docs/quickstarts/load-data-console?hl=ja) をご参照ください。

### サービスアカウントの作成とJSONキーの取得 [](#サービスアカウントの作成とjsonキーの取得)

次に、ベースマキナからBigQueryへ接続するために、サービスアカウントを作成しJSONキーを取得します。

1. Google Cloud Consoleで「IAMと管理」→「サービスアカウント」に移動します。
1. 「サービスアカウントを作成」をクリックします。
1. サービスアカウント名を入力し、「作成して続行」をクリックします。
1. 以下のロールを割り当てます：
  - `BigQuery データ閲覧者` （roles/bigquery.dataViewer）
  - `BigQuery ジョブユーザー` （roles/bigquery.jobUser）
1. 「完了」をクリックしてサービスアカウントを作成します。
1. 作成したサービスアカウントを選択し、「鍵」タブに移動します。
1. 「キーを追加」→「新しい鍵を作成」をクリックします。
1. 「JSON」を選択して「作成」をクリックし、JSONキーファイルをダウンロードします。

サービスアカウントの詳細な設定方法は、Google Cloudのドキュメントの [サービスアカウントの作成と管理 (opens in a new tab)](https://cloud.google.com/iam/docs/creating-managing-service-accounts?hl=ja) をご参照ください。

その他、ベースマキナからBigQueryに対して実行したい操作に応じて、必要な権限を追加してください。

BigQueryでのIAMロールの詳細は、Google Cloudのドキュメントの [BigQuery の IAM ロール (opens in a new tab)](https://cloud.google.com/bigquery/docs/access-control?hl=ja) をご参照ください。

## データソースの作成 [](#データソースの作成)

![BigQueryのデータソースの作成画面](/images/bigquery/datasource_setting.png)

1. 右上のメニューから「データソース」を選択してデータソース一覧画面に移動します。
1. 「データソースの追加」を選択してデータソースの追加画面に移動します。
1. 「BigQuery」を選択して、BigQueryのデータソースの作成画面に移動します。
1. 各設定項目を入力します。
1. 「保存」を選択します。

BigQueryのデータソースには以下の項目を設定します。

### 名前 [](#名前)

データソースの名前を設定します。

### サービスアカウントキー [](#サービスアカウントキー)

ダウンロードしたサービスアカウントのJSONキーファイルの内容を設定します。

JSONキーファイルをテキストエディタで開き、その内容全体をコピーして貼り付けてください。

### Google Cloudプロジェクト ID [](#google-cloudプロジェクト-id)

接続するGoogle CloudプロジェクトのプロジェクトIDを設定します。

## データソースの編集 [](#データソースの編集)

1. 右上のメニューから「データソース」を選択してデータソース一覧画面に移動します。
1. 編集するデータソースを選択してデータソースの編集画面に移動します。
1. 各設定項目を入力します。
1. 「保存」を選択します。

## データソースの削除 [](#データソースの削除)

![データソースの削除](/images/datasource/delete.png)

1. 右上のメニューから「設定」を選択してプロジェクト設定画面に移動します。
1. 「データソース設定」を選択してデータソース設定画面に移動します。
1. 削除するデータソースの行の右端の3点リーダから「削除する」を選択します。
1. 表示される画面で「OK」を選択します。

[BigQuery](/action/datasources/bigquery/) [アクションの設定](/action/datasources/bigquery/action_setting/)
---
[アクション](/action/)

データソース別の設定

Firestore

# Firestore (Datastore)

## Firestore (Datastore) のデータソースに接続する [](#firestore-datastore-のデータソースに接続する)

Firestoreとの連携では、FirestoreまたはFirestoreのDatastoreモードの操作ができます。

1. 右上のメニューから「データソース」を選択する

2. 「データソースの追加」をクリックする

3. データソースの種類の中から「 Firestore 」を選択する

![データソースの選択](/images/firestore_integration/select.png)

4. データソースへの接続に必要な情報を入力して保存する

![データソースの接続設定](/images/firestore_integration/connection.png)

### サービスアカウントキーの保存 [](#サービスアカウントキーの保存)

上記の `4` のステップでは、データベースの操作のために必要なサービスアカウントキーを保存します。

Google Cloudコンソール上で発行し、JSON形式でダウンロードしたファイルの内容をフォームに貼り付けて保存してください。

サービスアカウントキー発行の詳しい方法については、 [Googleのドキュメント (opens in a new tab)](https://cloud.google.com/iam/docs/creating-managing-service-account-keys) を参照ください。

### 必要なロールの割り当て [](#必要なロールの割り当て)

サービスアカウントには、下記 [FirestoreのIAMロール (opens in a new tab)](https://cloud.google.com/firestore/docs/security/iam#predefined_roles) のいずれかの割り当てが必要となります。

Firestoreに関連するIAMロールは、Google Cloudコンソール上では `Cloud Datastore` となっている点にご注意ください。

- 読み書き両方： `Cloud Datastore ユーザー`
- 読み込みのみ： `Cloud Datastore 閲覧者`

もし割り当てがまだの場合は、Google Cloudコンソールの `IAMと管理` の [IAMの設定 (opens in a new tab)](https://console.cloud.google.com/iam-admin/iam) から割り当ててください。

## Firestore (Datastore) をアクションで利用する [](#firestore-datastore-をアクションで利用する)

Firestoreアクションは、実行内容をJavaScriptのコードとして記述します。
コードは、ベースマキナのアプリケーション本体から隔離された環境下のNode.jsインスタンス上で実行されます。

コード内では、 [`Firebase Admin SDK` (opens in a new tab)](https://firebase.google.com/docs/admin/setup) および、 [`Cloud Datastore Node.js Client` (opens in a new tab)](https://cloud.google.com/nodejs/docs/reference/datastore/latest) の、初期化済みのクライアントを変数として利用できます。

これらのSDKを通じて取得した、配列またはObjectを `return` 文で返すことで、アクションの実行結果を返すことができます。

Firestoreアクションは、AsyncFunctionとして実行されるため、コードのトップレベルで `await` を使用できます。

### Firestoreの操作を記述する [](#firestoreの操作を記述する)

Firestoreの操作では、 `db` 変数と `firestore` 変数を使用します。
それぞれの変数の型の詳細は下記のGoogle CloudおよびFirebaseのドキュメントでご確認いただけます。

- `db`: [Firestore class (opens in a new tab)](https://googleapis.dev/nodejs/firestore/latest/Firestore.html)
- `firestore`: [firestore module (opens in a new tab)](https://firebase.google.com/docs/reference/admin/node/firebase-admin.firestore?hl=en)

操作の具体的な例については、 [Firebaseのドキュメント (opens in a new tab)](https://firebase.google.com/docs/firestore/quickstart) の各項目の `Node.js` タブをご参照ください。

いくつか例を示します。

#### ユーザーの一覧を取得する [](#ユーザーの一覧を取得する)

```
const collection = await db.collection("users").get();
const users = collection.docs.map((doc) => {
  return {
    id: doc.id,
    ...doc.data(),
  };
});
return users;
```

#### ユーザーを追加し、結果を取得する [](#ユーザーを追加し結果を取得する)

```
const res = await db.collection("users").add({
  name: {{ name }},
  email: {{ email }},
  createdAt: firestore.Timestamp.now(),
});
const user = await db.collection("users").doc(res.id).get();
return {
  id: res.id,
  ...user.data(),
};
```

### Datastoreの操作を記述する [](#datastoreの操作を記述する)

Datastoreの操作では、 `datastore` 変数を使用します。
変数の型の詳細は下記のGoogle Cloudのドキュメントでご確認いただけます。

- `datastore`: [Datastore class (opens in a new tab)](https://googleapis.dev/nodejs/datastore/latest/Datastore.html), [(親class) DatastoreRequest class (opens in a new tab)](https://googleapis.dev/nodejs/datastore/latest/DatastoreRequest.html)

操作の具体的な例については、下記リポジトリのサンプルコードをご参照ください。
[https://github.com/googleapis/nodejs-datastore/tree/main/samples (opens in a new tab)](https://github.com/googleapis/nodejs-datastore/tree/main/samples)

いくつか例を示します。

#### ユーザーの一覧を取得する [](#ユーザーの一覧を取得する-1)

```
const query = datastore.createQuery("User");
const [users] = await datastore.runQuery(query);
return users;
```

#### ユーザーを追加し、追加した情報を返す [](#ユーザーを追加し追加した情報を返す)

```
const userKey = datastore.key('User');
const user = {
    key: userKey,
    data: [
        {
            name: 'name',
            value: {{ name }},
        },
        {
            name: 'email',
            value: {{ email }},
        },
        {
            name: 'createdAt',
            value: new Date(),
        }
    ]
}
await datastore.save(user);
return user;
```

[PostgreSQL](/action/datasources/postgresql_integration/) [HTTP API](/action/datasources/httpapi_integration/)
---
[アクション](/action/)

データソース別の設定

Google Cloud Storage

# Google Cloud Storage

Google Cloud Storageアクションでは、ファイルのアップロードとダウンロードができます。

## Google Cloud Storageのデータソースに接続する [](#google-cloud-storageのデータソースに接続する)

1. 右上のメニューから「データソース」を選択する

2. 「データソースの追加」をクリックする

3. データソースの種類の中から「 Google Cloud Storage 」を選択する

![データソースの選択](/images/gcs_integration/select.png)

4. データソースへの接続に必要な情報を入力して保存する

![データソースの接続設定](/images/gcs_integration/connection.png)

### サービスアカウントの作成 [](#サービスアカウントの作成)

上記の `4` のステップでは、Google Cloud Storageの操作に必要な認証情報を登録します。

Google Cloudコンソール上でサービスアカウントを作成し、JSON形式のサービスアカウントキーをダウンロードします。そのファイルの内容を登録してください。

サービスアカウント作成の詳しい方法については、Google Cloudドキュメントの [サービスアカウントを作成する (opens in a new tab)](https://cloud.google.com/iam/docs/creating-managing-service-accounts?hl=ja) をご参照ください。

### 必要なロールの割り当て [](#必要なロールの割り当て)

サービスアカウントには、下記の権限を与える必要があります。

- アップロード： `storage.objects.create` （既存のオブジェクトを上書きする場合には `storage.objects.delete` も必要です）
- ダウンロード： `storage.objects.get`
- オブジェクトの一覧取得： `storage.objects.list`

ロールの割り当ての詳しい方法に関しては、Google Cloudドキュメントの [サービスアカウントに対するアクセス権の管理 (opens in a new tab)](https://cloud.google.com/iam/docs/granting-roles-to-service-accounts?hl=ja) をご参照ください。

### Workload Identity Federation で接続する

[Workload Identity Federation (opens in a new tab)](https://cloud.google.com/iam/docs/workload-identity-federation?hl=ja) を使用すると、サービスアカウントキーをベースマキナに渡すことなく、そのサービスアカウントの権限でGoogle Cloud Storageを操作できます。

以下のTerraformコード（Terraform v1.14.7 / Google provider v7.23.0で動作確認済み）で必要なリソースを作成します。 `<PROJECT_ID>` 、 `<BUCKET_NAME>` 、 `<SA_NAME>` を環境に合わせて置き換えてください。

既存のバケットを使用する場合は `google_storage_bucket` の定義を削除し、 `google_storage_bucket_iam_member` の `bucket` を既存バケット名に変更してください。

```
provider "google" {
  project = "<PROJECT_ID>"
}
 
data "google_project" "project" {}
 
# GCS バケット（既存バケットを使う場合は不要）
resource "google_storage_bucket" "bucket" {
  name     = "<BUCKET_NAME>"
  location = "asia-northeast1"
 
  uniform_bucket_level_access = true
}
 
# ベースマキナが権限借用するサービスアカウント
resource "google_service_account" "sa" {
  account_id   = "<SA_NAME>"
  display_name = "<SA_NAME>"
}
 
# サービスアカウントにバケットの読み書き権限を付与
resource "google_storage_bucket_iam_member" "object_admin" {
  bucket = google_storage_bucket.bucket.name
  role   = "roles/storage.objectAdmin"
  member = "serviceAccount:${google_service_account.sa.email}"
}
 
# Workload Identity Federation Pool
resource "google_iam_workload_identity_pool" "pool" {
  workload_identity_pool_id = "basemachina"
  display_name              = "BaseMachina"
}
 
# Workload Identity Federation Pool Provider
resource "google_iam_workload_identity_pool_provider" "provider" {
  workload_identity_pool_id          = google_iam_workload_identity_pool.pool.workload_identity_pool_id
  workload_identity_pool_provider_id = "basemachina"
  display_name                       = "BaseMachina"
 
  oidc {
    issuer_uri = "https://idp.basemachina.com"
  }
 
  attribute_mapping = {
    "google.subject"       = "assertion.sub"
    "attribute.project_id" = "assertion.project_id"
  }
}
 
# サービスアカウントの権限借用を許可
resource "google_service_account_iam_member" "workload_identity_user" {
  service_account_id = google_service_account.sa.name
  role               = "roles/iam.workloadIdentityUser"
  member             = "principalSet://iam.googleapis.com/projects/${data.google_project.project.number}/locations/global/workloadIdentityPools/${google_iam_workload_identity_pool.pool.workload_identity_pool_id}/*"
}
 
# 署名付き URL 発行用の signBlob 権限（最小権限のカスタムロール）
resource "google_project_iam_custom_role" "sign_blob" {
  role_id     = "customSignBlob"
  title       = "Custom Sign Blob"
  description = "Allows signing blobs with service account keys"
  permissions = ["iam.serviceAccounts.signBlob"]
}
 
resource "google_service_account_iam_member" "sign_blob" {
  service_account_id = google_service_account.sa.name
  role               = "projects/${data.google_project.project.project_id}/roles/${google_project_iam_custom_role.sign_blob.role_id}"
  member             = "serviceAccount:${google_service_account.sa.email}"
}
```

#### IDトークンのカスタムクレーム [](#idトークンのカスタムクレーム)

ベースマキナが発行するID Tokenには、以下のカスタムクレームが含まれます。 `attribute_mapping` や `attribute_condition` で利用できます。

| クレーム | 内容 |
| --- | --- |
| `tenant_subdomain` | ご利用のサブドメイン（ `xxx.basemachina.com` の `xxx` 部分） |
| `project_id` | プロジェクトID |
| `environment_id` | 環境ID |

#### ベースマキナ側の設定 [](#ベースマキナ側の設定)

セットアップ完了後、データソースの接続設定で認証方式として「Workload Identity Federation」を選択し、以下の情報を入力します。

| 項目 | 値 | 例 |
| --- | --- | --- |
| プロバイダー | `projects/<PROJECT_NUMBER>/locations/global/workloadIdentityPools/<POOL_ID>/providers/<PROVIDER_ID>` | `projects/123456789/locations/global/workloadIdentityPools/basemachina/providers/basemachina` |
| サービスアカウント | `<SA_NAME>@<PROJECT_ID>.iam.gserviceaccount.com` | `basemachina@my-project.iam.gserviceaccount.com` |

## Google Cloud Storageをアクションで利用する [](#google-cloud-storageをアクションで利用する)

1. 右上のメニューから「アクション」を選択する

2. 「アクションの追加」をクリックする

3. アクション名やパラメーターを設定する

![データソースの選択](/images/gcs_integration/basic_action.png)

### アップロード [](#アップロード)

![アップロード設定画面](/images/blob_action/upload.png)

1. アクションパラメーターを設定します
  - ファイルパラメーターを **必須** にします
  - またアップロードするファイル名を指定するためにファイル名を入力するためのテキストパラメーターも必須にします
1. バケット名を `test-bucket` のように設定します
1. 実行メソッドを「アップロード」に設定します
1. オブジェクト名（オブジェクトキー）を `images/{{ ファイル名 }}` のように設定します
  - アップロードされるファイルのオブジェクト名となります
1. ファイル内容に使うパラメーターを1で作成したファイルパラメーターに設定します

アクション実行画面でパラメーターとしてファイル名を `test.png` と設定し実行した場合は下記にアップロードされます。

`gs://test-bucket/images/test.png` ### ダウンロード [](#ダウンロード)

![ダウンロード設定画面](/images/blob_action/download.png)

1. アクションパラメーターを設定します
  - ダウンロードするファイル名を指定するためのテキストパラメーターを必須にします
1. バケット名を `test-bucket` のように設定します
1. 実行メソッドを「ダウンロード」に設定します
1. オブジェクト名（オブジェクトキー）を `images/{{ ファイル名 }}` のように設定します
  - ダウンロードされるファイルのオブジェクト名となります

アクション実行画面でパラメーターとしてファイル名を `test.png` と設定し実行した場合は下記のファイルがダウンロードされます。

`gs://test-bucket/images/test.png` ### オブジェクトの一覧 [](#オブジェクトの一覧)

![オブジェクトの一覧設定画面](/images/blob_action/list_object.png)

1. バケット名を入力します。
1. 実行メソッドで「オブジェクトの一覧」を選択します。
1. 必要に応じてオブジェクト名（オブジェクトキー）を入力します。
1. 保存します。

設定したアクションを実行すると、オブジェクトの一覧を取得できます。

指定したオブジェクト名（オブジェクトキー）は、一覧取得時の接頭辞による絞り込みに使われます。

![オブジェクトの一覧の結果画面](/images/blob_action/list_object_result.png)

#### 実行結果の形式 [](#実行結果の形式)

下記の形式のオブジェクトを含んだ配列を返します。

| キー名 | 説明 |
| --- | --- |
| objectKey | オブジェクト名（オブジェクトキー） |
| lastModified | ファイルの更新日時のUnixTimestamp (秒) |
| size | ファイルのバイトサイズ |

### 署名付きURLの発行 [](#署名付きurlの発行)

![オブジェクトの署名付きURL発行の設定画面](/images/blob_action/issue_signed_url.png)

1. バケット名を入力します。
1. 実行メソッドで「署名付きURLの発行」を選択します。
1. オブジェクト名（オブジェクトキー）を入力します。
1. HTTPメソッドを「GET」または「PUT」から選択します。
1. 保存します。

設定したアクションを実行すると、署名付きURLが発行されます。

![オブジェクトの署名付きURL発行の結果画面](/images/blob_action/issue_signed_url_result.png)

#### 実行結果の形式 [](#実行結果の形式-1)

下記の形式のオブジェクトを返します。

| キー名 | 説明 |
| --- | --- |
| signedUrl | 発行した署名付きURL |

発行される署名付きURLの有効期限は24時間です。

### 便利な使い方 [](#便利な使い方)

「バケット名」と「オブジェクト名（オブジェクトキー）」では、アクションのパラメーターのほかに、 [変数・シークレット](/action/parameter/vars_secrets/) と [事前定義パラメーター](/action/parameter/predefined_parameter/) をご利用いただくことができます。環境に応じて値を変更したい場合などにご利用ください。

書式については [変数・シークレットの使用方法](/action/parameter/vars_secrets/#%E5%A4%89%E6%95%B0%E3%82%B7%E3%83%BC%E3%82%AF%E3%83%AC%E3%83%83%E3%83%88%E3%81%AE%E4%BD%BF%E7%94%A8%E6%96%B9%E6%B3%95) をご覧ください。

[Amazon S3](/action/datasources/awss3_integration/) [JavaScript](/action/datasources/javascript_action/)
---
[アクション](/action/)

データソース別の設定

Google スプレッドシート

# Google スプレッドシート

## Google スプレッドシート のデータソースに接続する [](#google-スプレッドシート-のデータソースに接続する)

1. 右上のメニューから「データソース」を選択する

2. 「データソースの追加」をクリックする

3. データソースの種類の中から「 Google スプレッドシート 」を選択する

![データソースの選択](/images/googlespreadsheet_integration/select.png)

4. データソースへの接続に必要な情報を入力して保存する

![データソースの接続設定](/images/googlespreadsheet_integration/connection.png)

1. Googleスプレッドシートに接続する

Googleスプレッドシートの情報にアクセスするには、GoogleのOAuth認証をパスする必要があります。

「Googleスプレッドシートに接続する」ボタンを押すと、次のような画面が表示されるので、接続を許可して問題がなければ「続ける」ボタンを押してOAuth認証の画面に移動してスプレッドシートへのアクセスを許可してください。

![Google スプレッドシートに接続する](/images/googlespreadsheet_integration/connect_google.png)

認証のステップが中断されず正しく接続されると、データソースの設定内で接続済みの表示がされるようになります。

![Google スプレッドシートに接続済み](/images/googlespreadsheet_integration/connected.png)

## Google スプレッドシート をアクションで利用する [](#google-スプレッドシート-をアクションで利用する)

1. 右上のメニューから「アクション」を選択する

2. 「アクションの追加」をクリックする

3. アクション名やパラメーターを設定する

![データソースの選択](/images/googlespreadsheet_integration/basic_action.png)

1. シートの操作方法を設定する（共通設定）

Googleスプレッドシートのデータソースを選択した後、「スプレッドシート」と「シート」という2種類のアクセス先情報を設定していただく必要があります。

スプレッドシートはGoogleスプレッドシートの画面上部に位置する、シート全体の名前を表しています。

![スプレッドシート名](/images/googlespreadsheet_integration/spreadsheet_label.png)

シートは画面下部に位置する、個別のシートの名前を表しています。

![シート名](/images/googlespreadsheet_integration/sheet_label.png)

1. シートの操作方法を設定する（読み込み編）

シートの内容を読み込みたい場合は、読み込みたい範囲をA1表記（例：A1:G20）で指定した後、値の表示形式を選択してフォーマットを調整してください。

![読み込み編](/images/googlespreadsheet_integration/googlespreadsheet_read_setting.png)

1. シートの操作方法を設定する（書き込み編）

シートにコンテンツを書き込みたい場合は、追加するデータの形式をフォーム上で設定してください。

![書き込み編](/images/googlespreadsheet_integration/googlespreadsheet_write_setting.png)

設定されている行・列のフォーマットに応じた内容がINSERTされます。

![追加するデータ](/images/googlespreadsheet_integration/append_data.png)

セルに入れたい値を変更する場合は、セルごとにクリックされると開く画面上から設定できます。

ここで `{{ 変数名 }}` と入力した場合は、他のアクション実行と同様に実行時の引数を受け渡して入力できます。

![セル編集](/images/googlespreadsheet_integration/edit_cell.png)

[gRPC](/action/datasources/grpc_integration/) [Amazon S3](/action/datasources/awss3_integration/)
---
[アクション](/action/)

データソース別の設定

gRPC

# gRPC

## gRPC のデータソースに接続する [](#grpc-のデータソースに接続する)

1. 右上のメニューから「データソース」を選択する

2. 「データソースの追加」をクリックする

3. データソースの種類の中から「 gRPC 」を選択する

![データソースの選択](/images/grpc_integration/select.png)

4. データソースへの接続に必要な情報を入力して保存する

![データソースの接続設定](/images/grpc_integration/connection.png)

1. サービス情報取得のための設定をする

ベースマキナは、gRPCメソッドの一覧を取得するためにステップ4で選択したサービス情報の取得先を使用します。

![サービス情報の取得先](/images/grpc_integration/connection_method.png)

**リフレクションを選択した場合**

gRPCサーバーのリフレクションを有効化する必要があります。お手数ですが [こちらの例 (opens in a new tab)](https://github.com/grpc/grpc/blob/master/doc/server-reflection.md#known-implementations) などをご参考に有効化してください。

**Protocol Buffers定義ファイルを選択した場合**

gRPCサーバーのリフレクションの有効化は不要です。

代わりに、アクションの設定前にProtocol Buffers定義ファイルをAPI経由でアップロードしていただく必要があります。
詳しい方法については [Protocol Buffers 定義ファイルの準備](/action/datasources/grpc_integration/#%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB%E3%82%92%E3%82%B3%E3%83%B3%E3%83%91%E3%82%A4%E3%83%AB%E3%81%99%E3%82%8B) をご参照ください。

アップロードが完了すると、データソースの編集ページにて、利用するProtocol Buffers定義ファイルのバージョンを指定できるようになります。

![gRPCアクション](/images/grpc_integration/select_protoset_version.png)

### 共通 メタデータ を設定する [](#共通propsheadernameを設定する)

アクション実行時に自動的に付与される共通 メタデータ を設定できます。

すべてのアクションに同じ メタデータ を設定する必要があるようなケースでご利用いただけます。

共通 メタデータ では、 [変数・シークレット](/action/parameter/vars_secrets/) をご利用いただくことができます。環境に応じて共通 メタデータ の内容を変えたい場合や、秘匿情報を含めたい場合にご利用ください。

書式については [変数・シークレットの使用方法](/action/parameter/vars_secrets/#%E5%A4%89%E6%95%B0%E3%82%B7%E3%83%BC%E3%82%AF%E3%83%AC%E3%83%83%E3%83%88%E3%81%AE%E4%BD%BF%E7%94%A8%E6%96%B9%E6%B3%95) をご覧ください。

![共通メタデータの設定フォーム](/images/grpc_integration/common_metadata.png)

### 認証設定 [](#認証設定)

gRPCアクションでは、認証形式として認証用アクションを選択できます。

#### 認証用アクションの設定 [](#認証用アクションの設定)

認証用アクションを設定すると、アクションの実行前に別のアクションを実行し、その結果を任意の メタデータ に設定できます。

例えば、事前にアクセストークンを取得するためのアクションを実行し、結果から取得したトークンを共通の メタデータ として使えます。

![認証用アクションの設定フォーム](/images/grpc_integration/auth_action_form.png)

アクションの実行結果は、 メタデータ に設定したい文字列を `return` するJavaScriptコードを記述することで処理します。

このJavaScriptコードの書き方は [アクションの結果表示のカスタマイズ](/action/transformer_script/action_transform/) と共通しているので、アクションの実行ページで事前に動作内容を確認できます。

## gRPC をアクションで利用する [](#grpc-をアクションで利用する)

1. 右上のメニューから「アクション」を選択する

2. 「アクションの追加」をクリックする

3. アクション名やパラメーターを設定する

![データソースの選択](/images/grpc_integration/basic_action.png)

1. リクエスト方法を登録する

gRPCメソッドは、データソースの設定を利用して取得したメソッド名の一覧から選択します。

streaming
RPCは現在ベースマキナのサポート対象外となっているため、gRPCメソッド一覧に表示されません。

リクエストボディはJSONとして設定します。 アクション実行時には、ここで設定したJSONに対してアクションパラメーターを展開した結果を、
Protocol Buffersのメッセージに変換してgRPCサーバーに送信します。

![gRPCアクション](/images/grpc_integration/grpc_setting.png)

リクエストでrepeatedのmessageを送信したい場合は、JavaScriptアクションと組み合わせて実現できます。詳しくは [アクションに関する質問](/faq/action_questions/) を参照してください。

# Protocol Buffers定義ファイルを選択した場合の設定方法

## ファイルをコンパイルする [](#ファイルをコンパイルする)

gRPCアクションでは、リフレクションのかわりにコンパイル済みのProtocol Buffers定義ファイルからメソッドの一覧を取得できます。

例： `api.proto`

ファイルをコンパイルするには、次のように `protoc` コマンドに `-o` オプションと `--include_imports` オプションを付与して実行してください。

```
syntax = "proto3";

package api;

service Service {
  rpc Method (Request) returns (Response) {}
}

message Request {}

message Response {
  string message = 1;
}
```

```
$ protoc -o out.protoset --include_imports api.proto
```

`protoc` によって生成された `out.protoset` がコンパイル済みProtocol Buffers定義ファイルです。

このファイルをベースマキナへアップロードすることで、リフレクションを使わずにgRPCアクションを実行できます。

## ファイルをアップロードする [](#ファイルをアップロードする)

コンパイル済みProtocol Buffers定義ファイル（以下、protosetファイル）は、API経由でベースマキナにアップロードできます。

アップロードされたprotosetファイルはバージョン管理され、過去にアップロードされたものも使用できます。

デフォルト値は、 **常に最新のバージョンを利用する** に設定されています。

アップロード方法は下記の通りです。

### protosetアップロードAPIのURL [](#protosetアップロードapiのurl)

下記URLにPOSTメソッドでリクエストを送信してください。

- [https://api.basemachina.com/v1/upload\_protoset (opens in a new tab)](https://api.basemachina.com/v1/upload_protoset)

### HTTP Header [](#http-header)

- `X-Basemachina-Grpc-Api-Access-Token` ヘッダーに、gRPC APIアクセストークンを設定してください。
  - アクセストークンは、 [プロジェクトの設定](/admin/user_management/project_settings/) の **gRPC API** メニューを選択すると取得できます。

### リクエストボディの形式 [](#リクエストボディの形式)

multipart/form-data形式で、下記の2つを送信してください。

- `params`: JSON形式のパラメータ
- `file`: protosetファイル

#### パラメータの形式 [](#パラメータの形式)

下記項目を含んだJSONを指定してください。

- environmentId（必須）
  - 環境のID。
  - アップロードしたprotosetファイルを使用したい環境のIDを指定してください。
  - gRPCデータソースの編集画面で、 **サービス情報の取得先** に **Protocol Buffers 定義ファイル** を指定すると表示されます。

![環境ID](/images/grpc_protoset/params_environment_id.png)

- resourceId（必須）
  - gRPCデータソースのID。
  - gRPCデータソースの編集画面で、 **サービス情報の取得先** に **Protocol Buffers 定義ファイル** を指定すると表示されます。

![データソースID](/images/grpc_protoset/params_data_source_id.png)

- name（任意）
  - protosetファイルのバージョンにつける名前。
  - 指定しなかった場合も、アップロードした時間で識別可能です。

![protosetファイル名](/images/grpc_protoset/params_name.png)

**パラメータの設定例**

```
{
  "environmentId": "ccp9ee76i1ea3prs2f50",
  "resourceId": "c8uo2q7kobjglbr9u6vg",
  "name": "version 1"
}
```

### アップロード例 [](#アップロード例)

cURLでアップロードするサンプルを掲載します。
実際に使用する場合は、 `{{ }}` で囲った箇所を必要な値に置き換えて実行してください。

```
curl --location --request POST 'https://api.basemachina.com/v1/upload_protoset' \
--header 'X-Basemachina-Grpc-Api-Access-Token: {{ gRPC APIアクセストークン }}' \
--form 'params="{
  \"environmentId\": \"{{ 環境ID }}\",
  \"resourceId\": \"{{ gRPCデータソースID }}\"
}"' \
--form 'file=@"{{ protosetファイルのパス }}"'
```

[GraphQL](/action/datasources/httpapi_integration/request_types/graphql/) [Google スプレッドシート](/action/datasources/googlespreadsheet_integration/)
---
[アクション](/action/)

データソース別の設定

HTTP API

# HTTP APIアクション

HTTP APIアクションは、ベースマキナから任意のHTTP APIに対してリクエストを送信できるアクションです。

REST API・GraphQLサーバー・各種SaaSのWebhookなどへのリクエストを、共通ヘッダーや認証情報をデータソースとして管理したうえで実行できます。

設定方法は以下をご参照ください。

- [HTTP APIデータソースの設定](/action/datasources/httpapi_integration/datasource_setting/)
- [HTTP APIアクションの設定](/action/datasources/httpapi_integration/action_setting/)

リクエストタイプ別の設定は以下をご参照ください。

- [なし](/action/datasources/httpapi_integration/request_types/none/)
- [JSON](/action/datasources/httpapi_integration/request_types/json/)
- [raw](/action/datasources/httpapi_integration/request_types/raw/)
- [form-data](/action/datasources/httpapi_integration/request_types/form_data/)
- [x-www-form-urlencoded](/action/datasources/httpapi_integration/request_types/x_www_form_urlencoded/)
- [GraphQL](/action/datasources/httpapi_integration/request_types/graphql/)

[Firestore](/action/datasources/firestore_integration/) [データソースの設定](/action/datasources/httpapi_integration/datasource_setting/)
---
[アクション](/action/)

データソース別の設定

[HTTP API](/action/datasources/httpapi_integration/)

アクションの設定

# HTTP APIアクションの設定

HTTP APIアクションは以下の手順で設定します。

1. 右上のメニューから「アクション」を選択する

2. 「アクションの追加」をクリックする

3. アクション名やパラメーターを設定する

![データソースの選択](/images/httpapi_integration/basic_action.png)

1. 「データソース」で先ほど追加したHTTP APIのデータソースを選択します。
1. 以下の項目を設定し、リクエスト内容を入力します。

![HTTP APIアクションの設定画面](/images/httpapi_integration/httpapi_setting.png)

各項目では、アクションのパラメーターを `{{ パラメーター名 }}` の書式で埋め込めます。URL・ヘッダーの値・クエリパラメーターの値・リクエストボディのいずれにも利用できます。

アクションのパラメーターに加えて、 [変数・シークレット](/action/parameter/vars_secrets/) を `{{ vars.変数名 }}` ・ `{{ secrets.シークレット名 }}` の書式で埋め込めます。データソース側で [認証用アクション](/action/datasources/httpapi_integration/datasource_setting/#%E8%AA%8D%E8%A8%BC%E5%BD%A2%E5%BC%8F) を設定している場合は、その実行結果を `{{ authToken }}` として参照できます。

![パラメーターを埋め込んだURL・ヘッダー・クエリパラメーター・リクエストボディの例](/images/httpapi_integration/applied_parameters.png)

## HTTPメソッド [](#httpメソッド)

リクエストに使用するHTTPメソッドを以下から選択します。

- `GET`
- `POST`
- `PUT`
- `PATCH`
- `DELETE`
- `HEAD`
- `PURGE`

## URL [](#url)

リクエスト先のパスを入力します。データソースで設定した「データソースのURL」と連結されてリクエストが送信されます。

URLにはパスパラメーターとして、アクションのパラメーターを埋め込めます。

例： `/v1/users/{{ user_id }}`

URL末尾にクエリパラメーターを記述しても送信されません。クエリパラメーターは下記の「クエリパラメーター」のフォームから設定してください。

## ヘッダー [](#ヘッダー)

アクション固有のリクエストヘッダーを「キー」「値」のペアで設定します。複数のヘッダーを追加できます。

データソースの「共通ヘッダー」と組み合わせて送信されます。

## クエリパラメーター [](#クエリパラメーター)

URLに付与するクエリパラメーターを「キー」「値」のペアで設定します。複数のクエリパラメーターを追加できます。

設定した内容は `?key1=value1&key2=value2` の形式でURLに付与されてリクエストが送信されます。

## リクエストタイプ [](#リクエストタイプ)

リクエストボディの形式を以下から選択します。

| リクエストタイプ | 用途 |
| --- | --- |
| [なし](/action/datasources/httpapi_integration/request_types/none/) | リクエストボディを送信しない、または共通ヘッダーで指定した任意の `Content-Type` でrawボディを送信する |
| [JSON](/action/datasources/httpapi_integration/request_types/json/) | `application/json` 形式のボディを送信する |
| [raw](/action/datasources/httpapi_integration/request_types/raw/) | 任意のテキスト形式のボディをそのまま送信する |
| [form-data](/action/datasources/httpapi_integration/request_types/form_data/) | `multipart/form-data` 形式でボディを送信する。ファイル送信や配列送信に対応 |
| [x-www-form-urlencoded](/action/datasources/httpapi_integration/request_types/x_www_form_urlencoded/) | `application/x-www-form-urlencoded` 形式のボディを送信する |
| [GraphQL](/action/datasources/httpapi_integration/request_types/graphql/) | GraphQLサーバー向けにQueryとVariablesを送信する |

各リクエストタイプの詳細は、表中のリンク先のページをご参照ください。

## リクエストボディ [](#リクエストボディ)

選択した「リクエストタイプ」に応じて、リクエストボディの入力フォームが切り替わります。

HTTP APIアクションにおけるアクションパラメーターの埋め込みは基本的に単純な文字列置換となります。
そのため、複数行入力を有効にしたテキスト型パラメーターをJSONのリクエストボディに埋め込むと、改行がそのまま送信され、以下のように文字列中に改行を含む不正なJSONが生成されてエラーとなる場合があります。

```
{
  "detail": "行1
行2"
}
```

複数行の文字列を扱う場合は、テキスト型パラメーターの設定画面で「改行文字を指定する」を有効にし改行文字を `\\n` に設定するか、 [JSON値](/action/parameter/json_parameter/) （種類：テキスト）をご利用ください。

リクエストボディでオブジェクトの配列を送信したい場合は、JavaScriptアクションと組み合わせて実現できます。詳しくは [アクションに関する質問](/faq/action_questions/) をご参照ください。

## 200系以外のレスポンスステータスコードを実行エラーとして扱う [](#200系以外のレスポンスステータスコードを実行エラーとして扱う)

「200系以外のレスポンスステータスコードを実行エラーとして扱う」を有効にすると、アクション実行時のHTTPレスポンスステータスコードが200系以外だった場合に、アクションを実行エラーとして扱います。

初期設定では有効になっています。

実行エラーの場合、レスポンスの内容は `results[0].failure` に格納されます。

[データソースの設定](/action/datasources/httpapi_integration/datasource_setting/) [なし](/action/datasources/httpapi_integration/request_types/none/)
---
[アクション](/action/)

データソース別の設定

[HTTP API](/action/datasources/httpapi_integration/)

データソースの設定

# HTTP APIデータソースの設定

HTTP APIのデータソースは以下の手順で設定します。

## データソースの作成 [](#データソースの作成)

1. 右上のメニューから「データソース」を選択する

2. 「データソースの追加」をクリックする

3. データソースの種類の中から「 HTTP API 」を選択する

![データソースの選択](/images/httpapi_integration/select.png)

4. データソースへの接続に必要な情報を入力して保存する

![データソースの接続設定](/images/httpapi_integration/connection.png)

HTTP APIのデータソースには以下の項目を設定します。

### 名前 [](#名前)

データソースの名前を設定します。

### データソースのURL [](#データソースのurl)

リクエスト先のURL（ベースURL）を設定します。

アクション側のURL欄に入力したパスは、ここで設定したデータソースのURLに連結されて送信されます。

例えば、データソースのURLに `https://api.example.com` 、アクションのURLに `/v1/users` を設定すると、 `https://api.example.com/v1/users` にリクエストが送信されます。

### 共通ヘッダー [](#共通ヘッダー)

### 共通 ヘッダー を設定する [](#共通propsheadernameを設定する)

アクション実行時に自動的に付与される共通 ヘッダー を設定できます。

すべてのアクションに同じ ヘッダー を設定する必要があるようなケースでご利用いただけます。

共通 ヘッダー では、 [変数・シークレット](/action/parameter/vars_secrets/) をご利用いただくことができます。環境に応じて共通 ヘッダー の内容を変えたい場合や、秘匿情報を含めたい場合にご利用ください。

書式については [変数・シークレットの使用方法](/action/parameter/vars_secrets/#%E5%A4%89%E6%95%B0%E3%82%B7%E3%83%BC%E3%82%AF%E3%83%AC%E3%83%83%E3%83%88%E3%81%AE%E4%BD%BF%E7%94%A8%E6%96%B9%E6%B3%95) をご覧ください。

![共通ヘッダーの設定フォーム](/images/httpapi_integration/common_header.png)

下記の「認証用アクション」を設定している場合は、共通ヘッダーの値で `{{ authToken }}` と書くことでその実行結果を埋め込めます。

例： `Authorization: Bearer {{ authToken }}`

### 認証形式 [](#認証形式)

HTTP APIアクションでは、認証形式として「なし」「Basic認証」「認証用アクション」のいずれかを選択できます。

#### なし [](#なし)

認証情報をリクエストに付与しません。共通ヘッダーで独自の認証ヘッダー（例： `Authorization: Bearer ...` ）を設定したい場合などに選択します。

#### Basic認証 [](#basic認証)

Basic認証を使用するには、認証形式として「Basic認証」を選択したうえで、ユーザー名・パスワードを入力します。

![Basic認証の設定フォーム。ユーザー名とパスワードの入力欄がある](/images/httpapi_integration/basic_auth.png)

#### 認証用アクションの設定 [](#認証用アクションの設定)

認証用アクションを設定すると、アクションの実行前に別のアクションを実行し、その結果を任意の HTTPヘッダー に設定できます。

例えば、事前にアクセストークンを取得するためのアクションを実行し、結果から取得したトークンを共通の HTTPヘッダー として使えます。

![認証用アクションの設定フォーム](/images/httpapi_integration/auth_action_form.png)

アクションの実行結果は、 HTTPヘッダー に設定したい文字列を `return` するJavaScriptコードを記述することで処理します。

このJavaScriptコードの書き方は [アクションの結果表示のカスタマイズ](/action/transformer_script/action_transform/) と共通しているので、アクションの実行ページで事前に動作内容を確認できます。

認証用アクションのフォームでは、以下の3項目を設定します。

- **認証用アクション**: 認証情報を取得するために実行するアクションを選択します。
- **認証ヘッダー名**: 認証結果を埋め込むヘッダー名を指定します（例： `authorization` ）。
- **認証ヘッダーの値を返すJavaScriptコード**: 認証用アクションの実行結果から、ヘッダーに設定する値を組み立てるJavaScriptコードを記述します。デフォルトでは `` return `Bearer ${results[0].success.token}` `` が入力されています。

設定した認証用アクションは、アクション実行前に自動的に実行され、その結果は共通ヘッダーやアクション側の入力欄で `{{ authToken }}` として参照できます。

## データソースの編集 [](#データソースの編集)

1. 右上のメニューから「データソース」を選択してデータソース一覧画面に移動します。
1. 編集するデータソースを選択してデータソースの編集画面に移動します。
1. 各設定項目を入力します。
1. 「保存」を選択します。

## データソースの削除 [](#データソースの削除)

![データソースの削除](/images/datasource/delete.png)

1. 右上のメニューから「設定」を選択してプロジェクト設定画面に移動します。
1. 「データソース設定」を選択してデータソース設定画面に移動します。
1. 削除するデータソースの行の右端の3点リーダから「削除する」を選択します。
1. 表示される画面で「OK」を選択します。

[HTTP API](/action/datasources/httpapi_integration/) [アクションの設定](/action/datasources/httpapi_integration/action_setting/)
---
[アクション](/action/)

データソース別の設定

[HTTP API](/action/datasources/httpapi_integration/)

リクエストタイプ別の設定

form-data

# リクエストタイプ：form-data

リクエストタイプとして「form-data」を選択すると、 `multipart/form-data` 形式のリクエストボディを送信できます。

ファイルのアップロードや、配列値の送信などに利用します。

form-dataのリクエストボディは「キー」と「値の種類」「値」のセットで入力します。値の種類は以下から選択できます。

| 値の種類 | 用途 |
| --- | --- |
| 文字列 | 通常のテキスト値を送信する。 `{{ パラメーター名 }}` の書式でパラメーターを埋め込める |
| ファイル | [ファイルパラメーター](/action/parameter/file_parameter/) または「子要素がファイル型の配列パラメーター」を指定してファイルを送信する |
| 配列 | フォーマット形式が `form-data` の [配列パラメーター](/action/parameter/array_parameter/) を指定して、複数値を送信する |

![リクエストタイプにform-dataを選択し、キー・値の種類・値を入力するフォーム](/images/httpapi_integration/request_body_form_data.png)

## ファイルを送信する [](#ファイルを送信する)

値の種類で「ファイル」を選択し、表示されるセレクトボックスからファイルパラメーターを指定します。

![リクエストタイプにform-dataを選択して、ファイルパラメーターを指定する](/images/httpapi_integration/form_data.png)

リクエストタイプを「form-data」に設定した場合、HTTPリクエスト自体のContent-Typeは
`multipart/form-data` となります。
ただし、multipart/form-data内のファイル要素のContent-Typeは、現在はファイルの内容に関わらず
`application/octet-stream` となります。

## 配列を送信する [](#配列を送信する)

複数の値をまとめて送信する場合は、値の種類で「配列」を選び、フォーマット形式に `form-data` を設定した [配列パラメーター](/action/parameter/array_parameter/) を指定します。

配列の各要素は、同じキーのform-dataフィールドとして個別に送信されます。

「配列のキー形式」では、各要素を送信するときのキーに `[]` をつけるかどうかを選択できます。

- `[]あり` : `key[]: 1` 、 `key[]: 2` 、 `key[]: 3`
- `[]なし` : `key: 1` 、 `key: 2` 、 `key: 3`

![値の種類で「配列」を選択した状態で表示される、配列のキー形式（\[\]あり / \[\]なし）の選択UI](/images/httpapi_integration/request_body_form_data_array.png)

form-dataで送信できるのは、文字列・数値・日付を要素とする配列です。オブジェクトの配列を送信したい場合は、JavaScriptアクションと組み合わせて実現できます。詳しくは [アクションに関する質問](/faq/action_questions/) をご参照ください。

[raw](/action/datasources/httpapi_integration/request_types/raw/) [x-www-form-urlencoded](/action/datasources/httpapi_integration/request_types/x_www_form_urlencoded/)
---
[アクション](/action/)

データソース別の設定

[HTTP API](/action/datasources/httpapi_integration/)

リクエストタイプ別の設定

GraphQL

# リクエストタイプ：GraphQL

リクエストタイプとして「GraphQL」を選択すると、GraphQLサーバーとの通信に使いやすい形式でリクエストを送信できます。

「GraphQL」を選択すると、QueryとVariablesを入力するフィールドがそれぞれ表示されます。

![リクエストタイプにGraphQLを選択した状態のフォーム](/images/httpapi_integration/graphql.png)

GraphQLサーバーへのリクエストは、QueryとVariablesの入力内容をもとにJSON形式で組み立てられて送信されます。

Variablesは省略可能で、初期値は空のオブジェクト `{}` です。

Query・Variablesのいずれにも、他のリクエストタイプと同様に `{{ パラメーター名 }}` の書式でアクションのパラメーターを埋め込めます。

例えば、以下のようにVariablesの `id` キーに、 `"{{ id }}"` としてパラメーターを渡せます。

```
{
  "id": "{{ id }}"
}
```

[x-www-form-urlencoded](/action/datasources/httpapi_integration/request_types/x_www_form_urlencoded/) [gRPC](/action/datasources/grpc_integration/)
---
[アクション](/action/)

データソース別の設定

[HTTP API](/action/datasources/httpapi_integration/)

リクエストタイプ別の設定

JSON

# リクエストタイプ：JSON

リクエストタイプとして「JSON」を選択すると、 `application/json` 形式のリクエストボディを送信できます。

リクエストボディには、送信したいJSONを記述します。アクションのパラメーターは `{{ パラメーター名 }}` の書式で埋め込めます。

```
{
  "name": "{{ name }}",
  "age": {{ age }}
}
```

![リクエストタイプにJSONを選択し、リクエストボディにJSONを記述した入力例](/images/httpapi_integration/request_body_json.png)

HTTP APIアクションのパラメーターの埋め込みは単純な文字列置換のため、複数行入力を有効にしたテキスト型パラメーターをそのまま埋め込むと改行がそのまま挿入され、不正なJSONになる場合があります。

複数行の文字列を扱う場合は、テキスト型パラメーターの設定画面で「改行文字を指定する」を有効にし改行文字を `\\n` に設定するか、 [JSON値](/action/parameter/json_parameter/) （種類：テキスト）をご利用ください。

オブジェクトの配列を送信したい場合は、JavaScriptアクションと組み合わせて実現できます。詳しくは [アクションに関する質問](/faq/action_questions/) をご参照ください。

[なし](/action/datasources/httpapi_integration/request_types/none/) [raw](/action/datasources/httpapi_integration/request_types/raw/)
---
[アクション](/action/)

データソース別の設定

[HTTP API](/action/datasources/httpapi_integration/)

リクエストタイプ別の設定

なし

# リクエストタイプ：なし

リクエストタイプとして「なし」を選択すると、HTTPリクエストにリクエストボディを含めずに送信できます。

`GET` や `HEAD` など、リクエストボディを必要としないHTTPメソッドを使う場合に選択します。

リクエストタイプを「なし」にした場合は、リクエストボディの入力フォームは表示されません。

![リクエストタイプに「なし」を選択した状態のフォーム](/images/httpapi_integration/request_body_none.png)

任意の `Content-Type` でリクエストボディを送信したい場合は、 [raw](/action/datasources/httpapi_integration/request_types/raw/) を選択して、データソースの [共通ヘッダー](/action/datasources/httpapi_integration/datasource_setting/#%E5%85%B1%E9%80%9A%E3%83%98%E3%83%83%E3%83%80%E3%83%BC) もしくはアクションの [ヘッダー](/action/datasources/httpapi_integration/action_setting/#%E3%83%98%E3%83%83%E3%83%80%E3%83%BC) で `Content-Type` を指定してください。

[アクションの設定](/action/datasources/httpapi_integration/action_setting/) [JSON](/action/datasources/httpapi_integration/request_types/json/)
---
[アクション](/action/)

データソース別の設定

[HTTP API](/action/datasources/httpapi_integration/)

リクエストタイプ別の設定

raw

# リクエストタイプ：raw

リクエストタイプとして「raw」を選択すると、任意のテキスト形式のリクエストボディをそのまま送信できます。

JSON以外のテキスト形式（XML・プレーンテキスト・YAMLなど）をリクエストボディとして送りたい場合に使用します。

リクエストボディの `Content-Type` はリクエストに含まれないため、必要に応じてデータソースの [共通ヘッダー](/action/datasources/httpapi_integration/datasource_setting/#%E5%85%B1%E9%80%9A%E3%83%98%E3%83%83%E3%83%80%E3%83%BC) もしくはアクションの [ヘッダー](/action/datasources/httpapi_integration/action_setting/#%E3%83%98%E3%83%83%E3%83%80%E3%83%BC) で明示的に設定してください。

例： `Content-Type: application/xml`

リクエストボディには、送信したいテキストを記述します。他のリクエストタイプと同様に、 `{{ パラメーター名 }}` の書式でアクションのパラメーターを埋め込めます。

![リクエストタイプにrawを選択し、リクエストボディにXMLを記述した入力例](/images/httpapi_integration/request_body_raw.png)

[JSON](/action/datasources/httpapi_integration/request_types/json/) [form-data](/action/datasources/httpapi_integration/request_types/form_data/)
---
[アクション](/action/)

データソース別の設定

[HTTP API](/action/datasources/httpapi_integration/)

リクエストタイプ別の設定

x-www-form-urlencoded

# リクエストタイプ：x-www-form-urlencoded

リクエストタイプとして「x-www-form-urlencoded」を選択すると、 `application/x-www-form-urlencoded` 形式のリクエストボディを送信できます。

OAuthのトークン取得エンドポイントなど、 `key1=value1&key2=value2` 形式のリクエストボディを受け付けるAPIで利用します。

リクエストボディは「キー」と「値」のペアで入力します。複数のペアを追加できます。

値には `{{ パラメーター名 }}` の書式でアクションのパラメーターを埋め込めます。

![リクエストタイプにx-www-form-urlencodedを選択し、キーと値のペアを入力するフォーム](/images/httpapi_integration/request_body_x_www_form_urlencoded.png)

[form-data](/action/datasources/httpapi_integration/request_types/form_data/) [GraphQL](/action/datasources/httpapi_integration/request_types/graphql/)
---
[アクション](/action/)

データソース別の設定

JavaScript

# JavaScriptアクション

※ [（旧）JavaScriptアクション](/deprecated/javascript_action/) は廃止予定です。今後はこちらのJavaScriptアクションをご利用ください。

JavaScriptアクションは、任意のJavaScriptをサーバー上で実行するアクションです。

コード内で別のアクションの実行も可能で、以下のようなワークフローを作成できます。

- ファイルをストレージにアップロードするアクションを実行後、その結果のファイルパスをデータベースに保存するアクションを実行する
- ユーザーのデータを作成するアクションを実行後、その結果を元にslackへ通知するアクションを実行する

## 設定方法 [](#設定方法)

1. 右上のメニューから「アクション」を選択してアクション一覧画面に移動します。
1. 「アクションの追加」を選択してアクションの作成画面に移動します。
1. 「基本情報の設定」を入力後「次へ」を選択して、「処理の設定」画面に移動します。
1. 「データソース」から「JavaScript」を選択します。

JavaScriptアクションではパラメーターなどの他のアクションと共通の項目に加えて、「コード」を設定します。

コードでは、アクションの処理をJavaScriptの関数または非同期関数として記述します。

以下は、パラメーターで受け取った `firstName` と `lastName` を大文字のフルネームに変換する例です。

```
/** @type { import("@basemachina/action").Handler } */
export default (
  // 第1引数からパラメーターの値を参照する
  { firstName, lastName },
) => {
  // firstNameとlastNameを結合
  const fullName = `${firstName}_${lastName}`;
 
  // 大文字に変換
  const upperCaseFullName = fullName.toUpperCase();
 
  // 結果を返す
  return upperCaseFullName;
};
```

![\`firstName\`と\`lastName\`を大文字のフルネームに変換するJavaScriptアクションの例](/images/javascript_action/convert_to_fullname_action.png)

他のアクションと同様に、変数・シークレットなどの [事前定義パラメーター](/action/parameter/predefined_parameter/) も使用できます。

```
/** @type { import("@basemachina/action").Handler } */
export default (
  { customerId },
  // 第2引数から事前定義パラメーターの値を参照する
  // vars.XXX, currentUser.email, environment.idのように参照できます
  { vars, secrets, currentUser, environment },
) => {
  const customerPageUrl = `https://example.com/environments/${vars.ENVIRONMENT_ID}/${customerId}`;
  return customerPageUrl;
};
```

### パラメーターの型 [](#パラメーターの型)

| 種類 | 型 | 説明 | 例 |
| --- | --- | --- | --- |
| テキスト | `string` | - | `{ company_name: '株式会社ベースマキナ' }` |
| 数値 | `number | null` | - | `{ user_id: 123 }` |
| 数値 (必須) | `number` | - | `{ user_id: 123 }` |
| 日付（unixtimeとして利用する） | `number | null` | 「時刻を含める」が無効な場合、選択された日付の00:00:00のunixtimeが渡ってきます。 | `{ deleted: 1672531200 }` |
| 日付（日付の形式） | `string` | 選択した日付の形式の文字列で渡ってきます。 例では'YYYY-MM-DD'の形式を使っています。 | `{ deleted: '2023-01-01' }` |
| ファイル | `File | null` | `File` は `name` ・ `type` ・ `size` ・ `lastModified` のプロパティと、 `slice()` ・ `arrayBuffer()` ・ `bytes()` ・ `text()` のメソッドに対応しております。 `stream()` には対応しておりません。 後方互換のため、内容をバイト列（ `ArrayBuffer` ）で直接参照できる `buffer` プロパティにも対応していますが、非推奨です。 | `{ upload_text: new File(['test'], 'test.txt', { type: 'text/plain' }) }` |
| ファイル (必須) | `File` | - | `{ upload_text: new File(['test'], 'test.txt', { type: 'text/plain' }) }` |
| 真偽値（文字列フォーマット） | `string` | 「真の場合の値」または「偽の場合の値」が渡ってきます。 | `{ checked: '有効' }` |
| 真偽値（フォーマットなし） | `boolean` | 真偽値がそのまま渡ってきます。 | `{ checked: true }` |
| システム値 | `string` | - | `{ offset: '20' }` |
| 配列（フォーマットなし） | `Array` | 各要素の種類の型は、各種類の型と同じです。 | `{ user_ids: [10, 11, 12]  }` |
| 配列（JSON） | `string` | 詳しくは [配列パラメーター#JSON](/action/parameter/array_parameter/#json) をご参照ください。 | `{ user_names: '["taro","jiro","saburo"]' }` |
| 配列（区切り文字） | `string` | 詳しくは [配列パラメーター#区切り文字](/action/parameter/array_parameter/#%E5%8C%BA%E5%88%87%E3%82%8A%E6%96%87%E5%AD%97) をご参照ください。 | `{ user_names: '"taro","jiro","saburo"' }` |
| タプル（フォーマットなし） | `Array` | 各要素の型が入ったタプル型として渡ってきます。 | `{ values: ['taro', 25, '2023-01-01'] }` |
| タプル（JSON） | `string` | 詳しくは [タプルパラメーター#JSON](/action/parameter/tuple_parameter/#json) をご参照ください。 | `{ values: '["taro",25,"2023-01-01"]' }` |
| タプル（区切り文字） | `string` | 詳しくは [タプルパラメーター#区切り文字](/action/parameter/tuple_parameter/#%E5%8C%BA%E5%88%87%E3%82%8A%E6%96%87%E5%AD%97) をご参照ください。 | `{ values: '"taro","jiro","saburo"' }` |
| JSON値 | - | JavaScriptアクションでは使用できません | - |
| SQL | - | JavaScriptアクションでは使用できません | - |

## JavaScriptアクションで別のアクションを実行する [](#javascriptアクションで別のアクションを実行する)

JavaScriptアクションでは、コード内で別のアクションの実行もできます。

別のアクションの実行には `executeAction` 関数を使用します。

`executeAction` 関数経由でのアクションの実行でも、ログイン中のユーザーが実行権限を持っているか検証されるため安心してご利用いただけます。

以下は、商品の画像ファイルを保存するアクションの例です。

最初にストレージへ画像ファイルをアップロードするアクションを実行し、その後保存したファイルのパスをDBへ保存するアクションを実行しています。

```
// executeAction関数をインポート
import { executeAction } from "@basemachina/action";
 
/** @type { import("@basemachina/action").Handler } */
export default async ({ id, image }) => {
  // ①ストレージに画像ファイルをアップロード
  const uploadResults = await executeAction("upload-product-image", {
    id: id,
    image: image,
  });
 
  // ②保存した画像ファイルのストレージのパスをDBに保存
  const insertResults = await executeAction("insert-product-image", {
    id: id,
    // ①のアクションの結果の画像ファイルのパスを使用する
    path: uploadResults[0].success.objectKey,
  });
  return insertResults[0].success;
};
```

詳細は [`executeAction`](/action/datasources/javascript_action/builtin_functions/execute_action/) をご参照ください。

### JavaScriptアクションからしか実行できないアクションを作成する [](#javascriptアクションからしか実行できないアクションを作成する)

JavaScriptアクションから実行するアクションを、アクション実行画面などから直接実行できないようにする [実行権限](/action/action_permission/) の設定も可能です。

#### 設定方法 [](#設定方法-1)

1. 右上のメニューから「アクション」を選択してアクション一覧画面に移動します。
1. 実行権限を制限するアクションを選択して、アクション実行画面に移動します。
1. 「編集」を選択してアクションの編集画面に移動します。
1. 「権限設定」ステップを選択して、アクションの権限設定画面に移動します。
1. 「権限設定」で「実行権限を制限する」を選択します。
1. 「実行権限のあるユーザー・グループ・アクション」で、このアクションを実行できるJavaScriptアクションを選択します。
1. 保存します。

![JavaScriptアクションの実行権限設定画面](/images/javascript_action/permission.png)

ログインユーザーが実行権限を持たないアクションはアクション一覧画面に表示されないため、実行権限をJavaScriptアクションのみに設定したアクションは、全ユーザーのアクション一覧画面に表示されません。

再度設定を変更する場合は「非表示のアクションを表示する」を有効にすると、アクション一覧画面に表示され実行画面や編集画面へ移動できるようになります。

![非表示のアクションを表示するボタン](/images/javascript_action/display_hide_action_toggle.png)

[Google Cloud Storage](/action/datasources/gcs_integration/) [エラーハンドリング](/action/datasources/javascript_action/error_handlings/)
---
[アクション](/action/)

データソース別の設定

[JavaScript](/action/datasources/javascript_action/)

組み込み関数

createActionJob

# createActionJob

`createActionJob` はアクションを [ジョブ](/action/jobs/) として実行する関数です。

`createActionJob` 関数経由でのアクションのジョブとしての実行でも、ログイン中のユーザーが実行権限を持っているか検証されます。
例外として、ユーザー自身は権限を持っていなくても、 [呼び出し元のJavaScriptアクションが許可されている](/action/datasources/javascript_action/#javascript%E3%82%A2%E3%82%AF%E3%82%B7%E3%83%A7%E3%83%B3%E3%81%8B%E3%82%89%E3%81%97%E3%81%8B%E5%AE%9F%E8%A1%8C%E3%81%A7%E3%81%8D%E3%81%AA%E3%81%84%E3%82%A2%E3%82%AF%E3%82%B7%E3%83%A7%E3%83%B3%E3%82%92%E4%BD%9C%E6%88%90%E3%81%99%E3%82%8B) 場合には実行できます。

## 基本的な使い方 [](#基本的な使い方)

以下は実行に時間のかかるアクションをジョブとして実行している例です。

```
import { createActionJob } from "@basemachina/action";
 
/** @type { import("@basemachina/action").Handler } */
export default async ({ reports }) => {
  const results = await createActionJob("create_reports", { reports });
 
  if (!results[0].failure) {
    throw new Error("レポート作成ジョブの作成に失敗しました");
  }
 
  return `レポート作成ジョブを作成しました: ${results[0].success.actionJobId}`;
};
```

オプションで実行日時を指定してジョブの実行の予約もできます。

```
import { createActionJob } from "@basemachina/action";
 
/** @type { import("@basemachina/action").Handler } */
export default async ({ reports }) => {
  const results = await createActionJob(
    "create_reports",
    { reports },
    // 2024年10月1日22時に実行
    { scheduledAt: "2024-10-01 22:00:00" },
  );
 
  if (!results[0].failure) {
    throw new Error("レポート作成ジョブの作成に失敗しました");
  }
 
  return `レポート作成ジョブを作成しました: ${results[0].success.actionJobId}`;
};
```

## 詳細なインターフェース [](#詳細なインターフェース)

### 引数 [](#引数)

| 引数名 | 型 | 必須 ・ 任意 | 説明 | 例 |
| --- | --- | --- | --- | --- |
| `actionId` | `string` | 必須 | 実行するアクションのID、または識別子。 | `'c3hc2ii23akg0sokf9j0'`, `'get-user'` |
| `args` | `object` | 任意 | アクションを実行するための引数で、 キーがパラメータ名、値がパラメータに渡す値のオブジェクト。 | `{ username: 'JohnDoe' }` |
| `options` | `object` | 任意 | ジョブの詳細設定。 | `{ scheduledAt: 1609459200 }` |
| `options.scheduledAt` | `Date | string | number` | 任意 | ジョブの予約実行日時。 `string` は `Date` 型に変換できる値、 `number` はUnixTimestamp (秒)を入力してください。日時は現在から30日以内の値を指定できます。 | `new Date()`, `'2024-10-01'`, `1609459200` |

なおパラメータの種類ごとに `args` へ渡せる値の型は以下です。

| 種類 | 型 | 説明 | 例 |
| --- | --- | --- | --- |
| テキスト | `string | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ company_name: '株式会社ベースマキナ' }` |
| 数値 | `number | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ user_id: 123 }` |
| 日付 | `Date | string | number | null | undefined` | `string` は `Date` 型に変換できる値、 `number` はUnixTimestamp (秒)を入力してください。 `null` や `undefined` の場合は未入力として扱われます。 | `{ created: '2023-01-01', updated: new Date(), deleted: 1609459200 }` |
| ファイル | `File | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ upload_text: new File(['test'], 'test.txt', { type: 'text/plain' }) }` |
| 真偽値 | `boolean | null | undefined` | `null` や `undefined` の場合は `false` として扱われます。 | `{ checked: true }` |
| JSON値 | `string | number | Date | null | undefined` | JSON値の種類ごとに型が異なります。 テキストなら `string | null | undefined` 、数値なら `number | null | undefined` 、日付なら `string | number | Date | null | undefined` を渡せます。 日付の場合 `string` は `Date` 型に変換できる値、 `number` はUnixTimestamp (秒)を入力してください。 `null` や `undefined` の場合は `null` として扱われます。 | `{ company_name: '株式会社ベースマキナ', user_id: 123, created: '2023-01-01', deleted: null }` |
| SQL | `string | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ query: 'SELECT * FROM users;' }` |
| システム値 | `string | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ offset: '20' }` |
| 配列 | `Array | null | undefined` | 各要素の種類の型は、各種類の型と同じです。 `null` や `undefined` の場合は空配列として扱われます。 | `{ user_ids: [10, 11, 12] }` |
| タプル | `Array` | 各要素の種類の型は、各種類の型と同じです。 | `{ id_and_name: [123, 'taro'] }` |

### 戻り値 [](#戻り値)

| プロパティ名 | 型 | 説明 | 例 |
| --- | --- | --- | --- |
| `actionJobId` | `string` | 作成したジョブのID。 | `cpt8gkab5gv1ibk8r5h0` |

[executeAction](/action/datasources/javascript_action/builtin_functions/execute_action/) [createReviewRequest](/action/datasources/javascript_action/builtin_functions/create_review_request/)
---
[アクション](/action/)

データソース別の設定

[JavaScript](/action/datasources/javascript_action/)

組み込み関数

createReviewRequest

# createReviewRequest

`createReviewRequest` は、アクションのレビュー依頼を作成する関数です。

※レビュー依頼を作成するには、事前に対象のアクションに [レビュー設定](/action/review/) が必要です。

## 基本的な使い方 [](#基本的な使い方)

```
import { createReviewRequest } from "@basemachina/action";
 
/** @type { import("@basemachina/action").Handler } */
export default async ({ message }) => {
  const { reviewRequestId } = await createReviewRequest(
    "review-test",
    { message },
    { description: "内容を確認してください" },
  );
  return { reviewRequestId };
};
```

## 詳細なインターフェース [](#詳細なインターフェース)

### 引数 [](#引数)

| 引数名 | 型 | 必須 ・ 任意 | 説明 | 例 |
| --- | --- | --- | --- | --- |
| `actionId` | `string` | 必須 | 実行するアクションのID、または識別子。 | `'c3hc2ii23akg0sokf9j0'`, `'get-user'` |
| `args` | `object` | 任意 | アクションを実行するための引数で、 キーがパラメータ名、値がパラメータに渡す値のオブジェクト。 | `{ username: 'JohnDoe' }` |
| `options` | `object` | 任意 | レビュー依頼の詳細設定。 | `{ description: 'レビュー依頼の説明' }` |
| `options.description` | `string` | 任意 | レビュー依頼の説明。最大文字数は1000文字です。指定しない場合、 [レビュー設定](/action/review/#%E3%83%AC%E3%83%93%E3%83%A5%E3%83%BC%E4%BE%9D%E9%A0%BC%E3%81%AE%E3%83%87%E3%83%95%E3%82%A9%E3%83%AB%E3%83%88%E8%A8%AD%E5%AE%9A) のデフォルト値が使用されます。 | `'レビュー依頼の説明'` |
| `options.neverExpires` | `boolean` | 任意 | レビュー依頼の期限を無期限に指定します。 `expiresIn` と同時に指定することはできません。指定しない場合、 [レビュー設定](/action/review/#%E3%83%AC%E3%83%93%E3%83%A5%E3%83%BC%E4%BE%9D%E9%A0%BC%E3%81%AE%E3%83%87%E3%83%95%E3%82%A9%E3%83%AB%E3%83%88%E8%A8%AD%E5%AE%9A) のデフォルト値が使用されます。 | `true`, `false` |
| `options.expiresIn` | `Date | string | number` | 任意 | レビュー依頼の期限。 `string` は `Date` 型に変換できる値、 `number` はUnixTimestamp (秒)を入力してください。時間は過去に設定できません。また、 `neverExpires` と同時に指定できません。 | `new Date()`, `'2030-01-01'`, `1893456000` |
| `options.autoExecuteOnApproval` | `boolean` | 任意 | 承認されたら自動で実行するかどうか（依頼者の権限で実行されます）。指定しない場合、 [レビュー設定](/action/review/#%E6%89%BF%E8%AA%8D%E5%BE%8C%E3%81%AE%E8%87%AA%E5%8B%95%E5%AE%9F%E8%A1%8C) の「承認後の自動実行」の設定に従います。「必ず手動で実行」が設定されたアクションで `true` を、「必ず承認と同時に実行する」が設定されたアクションで `false` を指定するとエラーになります。 | `true`, `false` |

なおパラメータの種類ごとに `args` へ渡せる値の型は以下です。

| 種類 | 型 | 説明 | 例 |
| --- | --- | --- | --- |
| テキスト | `string | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ company_name: '株式会社ベースマキナ' }` |
| 数値 | `number | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ user_id: 123 }` |
| 日付 | `Date | string | number | null | undefined` | `string` は `Date` 型に変換できる値、 `number` はUnixTimestamp (秒)を入力してください。 `null` や `undefined` の場合は未入力として扱われます。 | `{ created: '2023-01-01', updated: new Date(), deleted: 1609459200 }` |
| ファイル | `File | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ upload_text: new File(['test'], 'test.txt', { type: 'text/plain' }) }` |
| 真偽値 | `boolean | null | undefined` | `null` や `undefined` の場合は `false` として扱われます。 | `{ checked: true }` |
| JSON値 | `string | number | Date | null | undefined` | JSON値の種類ごとに型が異なります。 テキストなら `string | null | undefined` 、数値なら `number | null | undefined` 、日付なら `string | number | Date | null | undefined` を渡せます。 日付の場合 `string` は `Date` 型に変換できる値、 `number` はUnixTimestamp (秒)を入力してください。 `null` や `undefined` の場合は `null` として扱われます。 | `{ company_name: '株式会社ベースマキナ', user_id: 123, created: '2023-01-01', deleted: null }` |
| SQL | `string | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ query: 'SELECT * FROM users;' }` |
| システム値 | `string | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ offset: '20' }` |
| 配列 | `Array | null | undefined` | 各要素の種類の型は、各種類の型と同じです。 `null` や `undefined` の場合は空配列として扱われます。 | `{ user_ids: [10, 11, 12] }` |
| タプル | `Array` | 各要素の種類の型は、各種類の型と同じです。 | `{ id_and_name: [123, 'taro'] }` |

### 戻り値 [](#戻り値)

| プロパティ名 | 型 | 説明 | 例 |
| --- | --- | --- | --- |
| `reviewRequestId` | `string` | 作成したレビュー依頼のID。 | `cpt8gkab5gv1ibk8r5h0` |

[createActionJob](/action/datasources/javascript_action/builtin_functions/create_action_job/) [wait](/action/datasources/javascript_action/builtin_functions/wait/)
---
[アクション](/action/)

データソース別の設定

[JavaScript](/action/datasources/javascript_action/)

組み込み関数

executeAction

# executeAction

`executeAction` はアクションを実行する関数です。

アクションの実行結果の値をパラメーターの値として別のアクションを実行するなどのワークフローを作成できます。

`executeAction` 関数経由でのアクションの実行でも、ログイン中のユーザーが実行権限を持っているか検証されます。
例外として、ユーザー自身は権限を持っていなくても、 [呼び出し元のJavaScriptアクションが許可されている](/action/datasources/javascript_action/#javascript%E3%82%A2%E3%82%AF%E3%82%B7%E3%83%A7%E3%83%B3%E3%81%8B%E3%82%89%E3%81%97%E3%81%8B%E5%AE%9F%E8%A1%8C%E3%81%A7%E3%81%8D%E3%81%AA%E3%81%84%E3%82%A2%E3%82%AF%E3%82%B7%E3%83%A7%E3%83%B3%E3%82%92%E4%BD%9C%E6%88%90%E3%81%99%E3%82%8B) 場合には実行できます。

## 基本的な使い方 [](#基本的な使い方)

以下は、商品の画像ファイルを保存するアクションの例です。

最初にストレージへ画像ファイルをアップロードするアクションを実行し、その後保存したファイルのパスをDBへ保存するアクションを実行しています。

```
// executeAction関数をインポート
import { executeAction } from "@basemachina/action";
 
/** @type { import("@basemachina/action").Handler } */
export default async ({ id, image }) => {
  // ①ストレージに画像ファイルをアップロード
  const uploadResults = await executeAction("upload-product-image", {
    id: id,
    image: image,
  });
 
  // ②保存した画像ファイルのストレージのパスをDBに保存
  const insertResults = await executeAction("insert-product-image", {
    id: id,
    // ①のアクションの結果の画像ファイルのパスを使用する
    path: uploadResults[0].success.objectKey,
  });
  return insertResults[0].success;
};
```

## 詳細なインターフェース [](#詳細なインターフェース)

### 引数 [](#引数)

| 引数名 | 型 | 必須 | 説明 | 例 |
| --- | --- | --- | --- | --- |
| `actionId` | `string` | ✓ | 実行するアクションのID、または識別子。 | `c3hc2ii23akg0sokf9j0`, `get-user` |
| `args` | `object` |  | アクションを実行するための引数で、 キーがパラメータ名、値がパラメータに渡す値のオブジェクトです。 | `{ username: 'JohnDoe' }` |
| `options` | `object` |  | アクションの実行オプションを指定するオブジェクトです。 | `{ throwOnFailure: true }` |

なおパラメータの種類ごとに `args` のプロパティの値に渡せる値の型は以下です。

| 種類 | 型 | 説明 | 例 |
| --- | --- | --- | --- |
| テキスト | `string | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ company_name: '株式会社ベースマキナ' }` |
| 数値 | `number | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ user_id: 123 }` |
| 日付 | `Date | string | number | null | undefined` | `string` は `Date` 型に変換できる値、 `number` はUnixTimestamp (秒)を入力してください。 `null` や `undefined` の場合は未入力として扱われます。 | `{ created: '2023-01-01', updated: new Date(), deleted: 1609459200 }` |
| ファイル | `File | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ upload_text: new File(['test'], 'test.txt', { type: 'text/plain' }) }` |
| 真偽値 | `boolean | null | undefined` | `null` や `undefined` の場合は `false` として扱われます。 | `{ checked: true }` |
| JSON値 | `string | number | Date | null | undefined` | JSON値の種類ごとに型が異なります。 テキストなら `string | null | undefined` 、数値なら `number | null | undefined` 、日付なら `string | number | Date | null | undefined` を渡せます。 日付の場合 `string` は `Date` 型に変換できる値、 `number` はUnixTimestamp (秒)を入力してください。 `null` や `undefined` の場合は `null` として扱われます。 | `{ company_name: '株式会社ベースマキナ', user_id: 123, created: '2023-01-01', deleted: null }` |
| SQL | `string | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ query: 'SELECT * FROM users;' }` |
| システム値 | `string | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ offset: '20' }` |
| 配列 | `Array | null | undefined` | 各要素の種類の型は、各種類の型と同じです。 `null` や `undefined` の場合は空配列として扱われます。 | `{ user_ids: [10, 11, 12] }` |
| タプル | `Array` | 各要素の種類の型は、各種類の型と同じです。 | `{ id_and_name: [123, 'taro'] }` |

#### options [](#options)

| プロパティ名 | 型 | デフォルト | 説明 |
| --- | --- | --- | --- |
| `throwOnFailure` | `boolean` | `false` | `true` に設定すると、アクションの実行に失敗した場合に `ExecuteActionFailureError` を `cause` に持つエラーをthrowします。詳細は [ExecuteActionFailureError](/action/datasources/javascript_action/builtin_functions/execute_action/#executeactionfailureerror) を参照してください。 |

### 戻り値 [](#戻り値)

| プロパティ名 | 型 | 説明 | 例 |
| --- | --- | --- | --- |
| `results` | `Array` | アクションの実行結果の配列。各要素には `success` と `failure` のプロパティが含まれます。 | `[{"success":[{"id":1,"name":"山田太郎"}]}]` |

## アクションの実行失敗のハンドリング [](#アクションの実行失敗のハンドリング)

パラメーターの型チェック、実行権限チェックなどのアクション実行の事前バリデーションおよび、システム起因のエラー以外でアクションの実行に失敗した場合、結果の `failure` プロパティに失敗の内容が設定されます。

通常は、このプロパティの有無を確認することで、アクションの実行失敗をハンドリングできます。

### 基本的なハンドリングの例 [](#基本的なハンドリングの例)

以下は、failureプロパティを使った基本的なハンドリングの例です。

```
import { executeAction } from "@basemachina/action";
 
/** @type { import("@basemachina/action").Handler } */
export default async ({ id, image }) => {
  const uploadResults = await executeAction("upload-product-image", {
    id,
    image,
  });
 
  // failureプロパティの有無を確認
  if (uploadResults[0].failure) {
    throw new Error("画像のアップロードに失敗しました");
  }
 
  return uploadResults[0].success;
};
```

### 複数のアクションを実行する場合の課題 [](#複数のアクションを実行する場合の課題)

複数のアクションを順番に実行するワークフローにおいては、各アクションの実行後に毎回 `failure` プロパティの確認が必要になります。

```
import { executeAction } from "@basemachina/action";
 
/** @type { import("@basemachina/action").Handler } */
export default async ({ id, image }) => {
  // ①ストレージへの画像ファイルのアップロード
  const uploadResults = await executeAction("upload-product-image", {
    id,
    image,
  });
  if (uploadResults[0].failure) {
    throw new Error("画像のアップロードに失敗しました");
  }
 
  // ②DBへの画像ファイルのパスの保存
  const insertResults = await executeAction("insert-product-image", {
    id,
    path: uploadResults[0].success.objectKey,
  });
  if (insertResults[0].failure) {
    throw new Error("画像パスの保存に失敗しました");
  }
 
  return insertResults[0].success;
};
```

### throwOnFailureオプションでハンドリングを簡潔にする [](#throwonfailureオプションでハンドリングを簡潔にする)

上記のようなコードを冗長と感じる場合は、 `options` 引数の `throwOnFailure` プロパティを活用できます。

`throwOnFailure` を `true` に設定することで、アクションの実行失敗時に自動的にエラーをthrowするため、毎回 `failure` プロパティを確認する必要がなくなります。

上記の例で `throwOnFailure` オプションを使用すると、以下のとおり簡潔に記述できます。

```
import { executeAction } from "@basemachina/action";
 
/** @type { import("@basemachina/action").Handler } */
export default async ({ id, image }) => {
  // ①ストレージへの画像ファイルのアップロードに失敗した場合は自動的にエラーをthrow
  const uploadResults = await executeAction(
    "upload-product-image",
    { id, image },
    { throwOnFailure: true },
  );
 
  // ②DBへの画像ファイルのパスの保存に失敗した場合は自動的にエラーをthrow
  const insertResults = await executeAction(
    "insert-product-image",
    { id, path: uploadResults[0].success.objectKey },
    { throwOnFailure: true },
  );
 
  return insertResults[0].success;
};
```

## ExecuteActionFailureError [](#executeactionfailureerror)

`throwOnFailure` オプションを `true` に設定した場合、アクションの実行失敗時に `ExecuteActionFailureError` を `cause` に持つエラーがthrowされます。

このエラーには、失敗した結果と、すべての実行結果（成功したものも含む）の両方が含まれます。

### 使用例: 画像アップロードの失敗理由の詳細を返す [](#使用例-画像アップロードの失敗理由の詳細を返す)

画像をストレージにアップロードし、そのパスをDBへ保存するワークフローにおいて、画像のアップロードが失敗した場合に詳細な情報を構造化して返すケースを考えてみましょう。

```
import {
  executeAction,
  ExecuteActionFailureError,
  ResultError,
} from "@basemachina/action";
 
/** @type { import("@basemachina/action").Handler } */
export default async ({ id, image }) => {
  // ①ストレージに画像をアップロードする
  const uploadedPath = await (async () => {
    try {
      const uploadResults = await executeAction(
        "upload-product-image",
        { id, image },
        { throwOnFailure: true },
      );
      return uploadResults[0].success.objectKey;
    } catch (err) {
      if (err.cause instanceof ExecuteActionFailureError) {
        throw new ResultError({
          message: "画像のアップロードに失敗しました",
          id,
          errorDetail: err.cause.failureResult.failure,
        });
      }
      throw err;
    }
  })();
 
  // ②保存した画像ファイルのストレージのパスをDBに保存
  const insertResults = await executeAction("insert-product-image", {
    id,
    path: uploadedPath,
  });
  return insertResults[0].success;
};
```

このように、 `ExecuteActionFailureError` と `ResultError` を使うことで、詳細なエラー情報を構造化して返せます。

`ResultError` の詳細については、 [ResultErrorのドキュメント](/action/datasources/javascript_action/error_handlings/#resulterror) を参照してください。

### ExecuteActionFailureErrorのプロパティ [](#executeactionfailureerrorのプロパティ)

| プロパティ名 | 型 | 説明 |
| --- | --- | --- |
| `failureResult` | Object | 失敗したアクションの結果。 `failure` プロパティにエラー内容が含まれます。 |
| `results` | Array | アクションのすべての実行結果の配列。成功した結果と失敗した結果の両方が含まれます。 |

`failureResult` は、 `results` 配列のなかで最初に失敗した結果と同じオブジェクトです。

### 注意事項 [](#注意事項)

- `ExecuteActionFailureError` は `cause` プロパティに格納されているため、 `instanceof` による判定には `err.cause` を使用してください。
- パラメーターの型チェック、実行権限チェックなどのアクション実行の事前バリデーションで失敗した場合は、 `ExecuteActionFailureError` を含むエラーはthrowされません。

[エラーハンドリング](/action/datasources/javascript_action/error_handlings/) [createActionJob](/action/datasources/javascript_action/builtin_functions/create_action_job/)
---
[アクション](/action/)

データソース別の設定

[JavaScript](/action/datasources/javascript_action/)

組み込み関数

wait

# wait

`wait` は指定した時間だけ処理を待機する関数です。

## 基本的な使い方 [](#基本的な使い方)

```
import { wait, executeAction } from "@basemachina/action";
 
/** @type { import("@basemachina/action").Handler } */
export default async ({ emails }) => {
  for (const email of emails) {
    //  DBにユーザーのデータを作成するアクションを実行
    await executeAction("create-user", { email });
 
    // DBの負荷を下げるために1秒待機
    await wait(1000);
  }
 
  return "ユーザーを作成しました";
};
```

## 詳細なインターフェース [](#詳細なインターフェース)

### 引数 [](#引数)

| 引数名 | 型 | 説明 | 例 |
| --- | --- | --- | --- |
| `milliseconds` | `number` | 待機する時間をミリ秒で指定します。 | `1000` |

### 戻り値 [](#戻り値)

戻り値はありません。

[createReviewRequest](/action/datasources/javascript_action/builtin_functions/create_review_request/) [型定義ファイルのダウンロード](/action/datasources/javascript_action/download_dts_file/)
---
[アクション](/action/)

データソース別の設定

[JavaScript](/action/datasources/javascript_action/)

型定義ファイルのダウンロード

# `@basemachina/action` の型定義ファイルのダウンロード

JavaScriptアクションで使用できる `@basemachina/action` の型定義ファイルはダウンロードが可能です。

手元のエディターでJavaScriptアクションのコードを編集する場合などにご活用ください。

**※この機能は将来、別の機能による代替または廃止になる可能性があります。**

![「JavaScriptアクションの型定義ファイルのダウンロード」ボタン](/images/download_js_action_dts_file.png)

## ダウンロード方法 [](#ダウンロード方法)

以下の手順でダウンロードできます。

1. 右上のメニューから「設定」を選択します。
1. サイドバーのメニューから「開発設定」を選択します。
1. 「JavaScriptアクションの型定義ファイルのダウンロード」ボタンをクリックすると、ダウンロードできます。

## Handlers型の使用方法 [](#handlers型の使用方法)

JavaScriptアクションで設定するコードに型を指定する場合は、 `Handlers` 型を使用して型を指定できます。
（ブラウザのエディターで使用する `Handler` 型は使用できません）

```
// Handlers型のキーには、JavaScriptアクションのIDまたは識別子を指定します
/** @type { import("@basemachina/action").Handlers["getCustomerPageUrl"] } */
export default (
  { customerId },
  { vars, secrets, currentUser, environment },
) => {
  const customerPageUrl = `https://example.com/environments/${vars.ENVIRONMENT_ID}/${customerId}`;
  return customerPageUrl;
};
```

[wait](/action/datasources/javascript_action/builtin_functions/wait/) [Amazon Athena](/action/datasources/amazon_athena/)
---
[アクション](/action/)

データソース別の設定

[JavaScript](/action/datasources/javascript_action/)

エラーハンドリング

# JavaScriptアクションのエラーハンドリング

## エラーの返し方の基本 [](#エラーの返し方の基本)

JavaScriptアクションは、正常終了する場合に `return` を、異常終了する場合に `throw` を使って実行結果を返すことができます。

例えば、アクションへの入力値が想定しない値だった場合に、処理を打ち切りたいケースがあるでしょう。

その場合、Errorを `throw` することで、アクションの実行結果を失敗として返せます。

以下は、ユーザー取得アクションを実行し、ユーザーが見つからなかった場合にエラーを `throw` するJavaScriptアクションの例です。

```
import { executeAction } from "@basemachina/action";
 
// 指定されたユーザーの投稿を作成するアクション
export default async ({ userId, post }) => {
  const getUserResults = await executeAction("getUser", { userId });
  // 不正な入力だったら、処理を中断する
  if (!getUserResults[0].success.length < 1) {
    throw new Error("ユーザーが見つかりませんでした");
  }
 
  // ユーザーが見つかった場合は、投稿を作成する
  await executeAction("createPost", { userId, post });
};
```

このとき、 `throw` されたエラーは以下のように実行結果に表示されます。

![エラーの表示](/images/javascript_action/error_handlings/error_display.png)

アクションの結果加工スクリプトや、executeAction関数の結果としては、 `failure` キーに同様の文字列が設定された形で取得できます。

![エラー結果の形式](/images/javascript_action/error_handlings/error_result_format.png)

一般的なユースケースでは、文字情報としてエラーの内容を伝達できれば問題ありませんが、場合によっては、任意の形式のObjectとして結果を返したいこともあるでしょう。
そうしたケースでは、 [ResultError](/action/datasources/javascript_action/error_handlings/#resulterror) を活用できます。

## ジョブからエラーを返した場合の挙動 [](#ジョブからエラーを返した場合の挙動)

ジョブとして実行したJavaScriptアクションからエラーが `throw` された場合は、ステータスが「実行完了」ではなく「エラー」となります。
「エラー」で終了したジョブの結果を閲覧すると、通常のアクション実行時と同じ形式でエラー情報が表示されます。

## 組み込み関数のエラー [](#組み込み関数のエラー)

JavaScriptアクションから呼び出す組み込み関数は、エラーを `throw` することがあります。

例えば、 `executeAction` 関数を呼び出すときに、引数や、ユーザーの実行権限に問題がある場合にエラーが発生します。

![executeActionによる権限エラーの表示](/images/javascript_action/error_handlings/execute_action_error_example.png)

また、ネットワークの問題などの、システム要因のエラーが発生することもあります。

基本的に、組み込み関数から発生するエラーは、その原因についての情報を含める形で `throw` されるため、明示的にハンドリングせずとも、エラー原因の特定に利用できます。
そのうえで、リトライ処理の実装などのためにエラーハンドリングを明示的にしたい場合は、組み込み関数の呼び出しを `try-catch` のブロックで囲んでください。

## ResultError [](#resulterror)

`ResultError` は、 `throw` することで、エラーの内容を任意の形式のObjectとして返すことができるクラスです。

文字情報だけでは情報の視認性に欠ける場合や、別のJavaScriptアクションや加工スクリプト、ビューなどから結果を扱いにくいようなケースで活用できます。

本ページ冒頭の例で、ユーザーの存在有無による判定をしていましたが、これに加えてユーザーの属性による判定を加えるケースについて考えてみましょう。

下記の例では、ユーザーのステータスと、年齢による判定をしています。

```
import { executeAction } from "@basemachina/action";
 
const isValidUser = (user) => {
  if (user.status !== "ACTIVE") {
    return false;
  }
  if (user.age < 20) {
    return false;
  }
  return true;
};
 
// 指定されたユーザーの投稿を作成するアクション
export default async ({ userId, post }) => {
  const getUserResults = await executeAction("getUser", { userId });
  if (!getUserResults[0].success.length < 1) {
    throw new Error("ユーザーが見つかりませんでした");
  }
  const user = getUserResults[0].success[0];
  if (!isValidUser(user)) {
    throw new Error("ユーザーが有効ではありません");
  }
  // ...
  await executeAction("createPost", { userId, post });
};
```

ここで、「ユーザーが有効ではありません」という文字列で結果を返していますが、「ステータス」か、「年齢」のどちらに問題があったのか読み取ることができません。

このような場合に、 `ResultError` を使うことで、より詳細な情報をエラーに追加できます。

```
import { executeAction, ResultError } from "@basemachina/action";
// ...
export default async ({ userId, post }) => {
  // ...
  if (!isValidUser(user)) {
    throw new ResultError({
      message: "ユーザーが有効ではありません",
      user: {
        status: user.status,
        age: user.age,
      },
    });
  }
```

このとき、アクションの実行結果の表示は次のようになります。

![ResultErrorの表示](/images/javascript_action/error_handlings/result_error_display.png)

詳細な情報が表示されたことで、ユーザーのステータスに問題があったことを突き止めるのが簡単になりました。
エラーの詳細を含む文字列を組み立ててErrorを `throw` するよりも、ResultErrorを使った方が手軽にエラーに詳細情報を付加できます。

アクションの結果加工スクリプトや、executeAction関数の結果としては、 `failure` キーにResultErrorのコンストラクタへ渡したObjectが設定された形で取得できます。

![エラー結果の形式](/images/javascript_action/error_handlings/result_error_result_format.png)

ジョブの実行に失敗したときの詳細な状況を記録するなどといった、デバッグ目的にも活用できます。

ResultErrorを使って返すことのできる値の種類は、基本的にJavaScriptアクション成功時に返すことのできる値の種類と同じですが、現在 `File` および `Blob` はサポートされていません。

[JavaScript](/action/datasources/javascript_action/) [executeAction](/action/datasources/javascript_action/builtin_functions/execute_action/)
---
[アクション](/action/)

データソース別の設定

MySQL

# MySQL

## MySQLのデータソースに接続する [](#mysqlのデータソースに接続する)

1. 右上のメニューから「データソース」を選択する

2. 「データソースの追加」をクリックする

3. データソースの種類の中から「 MySQL 」を選択する

![データソースの選択](/images/mysql_integration/select.png)

4. データソースへの接続に必要な情報を入力して保存する

![データソースの接続設定](/images/mysql_integration/connection.png)

## MySQLをアクションで利用する [](#mysqlをアクションで利用する)

1. 右上のメニューから「アクション」を選択してアクション一覧画面に移動します。
1. 「アクションの追加」を選択してアクションの作成画面に移動します。
1. 「基本情報の設定」を入力後「次へ」を選択して、「処理の設定」画面に移動します。
1. 「データソース」で先ほど追加したデータソースを選択します。
1. 以下の項目を設定します。

- SQL文のタイトル
- クエリの種類
- SQL文

![SQLアクションの設定画面](/images/sql_action/setting.png)

### SQL文のタイトル [](#sql文のタイトル)

SQL文のタイトルを入力します。

設定したSQLのタイトルは、 [結果表示のカスタマイズ](/action/transformer_script/action_transform/) で使用できます。

### クエリの種類 [](#クエリの種類)

SQL文で実行するクエリの種類を以下の2つから選択します。

- 読み込み：SELECT文などの読み込みの場合
- 書き込み：INSERT文、UPDATE文、DELETE文などの書き込みの場合

### SQL文 [](#sql文)

実行するSQL文を入力します。

SQL文は複数個入力できて、それらのSQL文は1つのトランザクションで実行されます。

## SQLのIN/VALUESで配列を使用する場合 [](#sqlのinvaluesで配列を使用する場合)

以下のようにSQL文のINやVALUESで配列を使用する場合は、配列パラメーターが利用できます。

- INで特定の列の値が配列の中に含まれているかどうかを確認する

```
SELECT * FROM table1 WHERE column1 IN {{ array_parameter }};
```

- VALUEで複数の行をバルクインサート（一括で挿入）する

```
INSERT INTO table1 (column1) VALUES {{ array_parameter }};
```

詳細は [配列パラメーターのフォーマット形式SQL](/action/parameter/array_parameter/#sql) をご参照ください。

## NULL値を文字列に変換する [](#null値を文字列に変換する)

アクションの設定で「NULL値を文字列に変換する」オプションを有効にすると、SQLの実行結果に含まれる `NULL` 値は文字列の `"NULL"` に変換されます。
無効にすると、JavaScriptの `null` として扱われます。デフォルト値は「無効」になります。

なお、オプション導入前の MySQL アクションでは `NULL` 値は一律で文字列に変換されていましたので、導入前に作られたアクションについてはすべて有効になっております。

[アクション](/action/) [PostgreSQL](/action/datasources/postgresql_integration/)
---
[アクション](/action/)

データソース別の設定

PostgreSQL

# PostgreSQL

## PostgreSQL のデータソースに接続する [](#postgresql-のデータソースに接続する)

1. 右上のメニューから「データソース」を選択する
1. 「データソースの追加」をクリックする
1. データソースの種類の中から「PostgreSQL」を選択する

![データソースの選択](/images/postgresql_integration/select.png)

1. データソースへの接続に必要な情報を入力して保存する

以下の項目が設定できます。

- 名前
- ホスト
- ポート番号
- データベース名
- ユーザー名
- パスワード
- アプリケーション名
- 接続タイムアウト
- SSLを利用して接続する

### クライアント証明書を使用した SSL 接続 [](#クライアント証明書を使用した-ssl-接続)

SSLを利用して接続する場合、クライアント証明書を使用した接続も可能です。

クライアント証明書を使用した接続をする場合、以下の項目を設定してください。

- server-ca.pemファイル内の認証局（CA）証明書
- client-cert.pemファイル内のクライアントの公開鍵証明書
- client-key.pemファイル内のクライアントの秘密鍵

## PostgreSQL をアクションで利用する [](#postgresql-をアクションで利用する)

1. 右上のメニューから「アクション」を選択してアクション一覧画面に移動します。
1. 「アクションの追加」を選択してアクションの作成画面に移動します。
1. 「基本情報の設定」を入力後「次へ」を選択して、「処理の設定」画面に移動します。
1. 「データソース」で先ほど追加したデータソースを選択します。
1. 以下の項目を設定します。

- SQL文のタイトル
- クエリの種類
- SQL文

![SQLアクションの設定画面](/images/sql_action/setting.png)

### SQL文のタイトル [](#sql文のタイトル)

SQL文のタイトルを入力します。

設定したSQLのタイトルは、 [結果表示のカスタマイズ](/action/transformer_script/action_transform/) で使用できます。

### クエリの種類 [](#クエリの種類)

SQL文で実行するクエリの種類を以下の2つから選択します。

- 読み込み：SELECT文などの読み込みの場合
- 書き込み：INSERT文、UPDATE文、DELETE文などの書き込みの場合

### SQL文 [](#sql文)

実行するSQL文を入力します。

SQL文は複数個入力できて、それらのSQL文は1つのトランザクションで実行されます。

## SQLのIN/VALUESで配列を使用する場合 [](#sqlのinvaluesで配列を使用する場合)

以下のようにSQL文のINやVALUESで配列を使用する場合は、配列パラメーターが利用できます。

- INで特定の列の値が配列の中に含まれているかどうかを確認する

```
SELECT * FROM table1 WHERE column1 IN {{ array_parameter }};
```

- VALUEで複数の行をバルクインサート（一括で挿入）する

```
INSERT INTO table1 (column1) VALUES {{ array_parameter }};
```

詳細は [配列パラメーターのフォーマット形式SQL](/action/parameter/array_parameter/#sql) をご参照ください。

## NULL値を文字列に変換する [](#null値を文字列に変換する)

アクションの設定で「NULL値を文字列に変換する」オプションを有効にすると、SQLの実行結果に含まれる `NULL` 値は文字列の `"NULL"` に変換されます。
無効にすると、JavaScriptの `null` として扱われます。デフォルト値は「無効」になります。

なお、オプション導入前の PostgreSQL アクションでは `NULL` 値は一律で文字列に変換されていましたので、導入前に作られたアクションについてはすべて有効になっております。

[MySQL](/action/datasources/mysql_integration/) [Firestore](/action/datasources/firestore_integration/)
---
[アクション](/action/)

データソース別の設定

Snowflake

# Snowflakeアクション

[Snowflake (opens in a new tab)](https://www.snowflake.com/ja/) は、クラウドネイティブなデータウェアハウスサービスです。

Snowflakeアクションは、ベースマキナからSnowflakeのデータベースにSQLを実行できるアクションです。

設定方法は以下をご参照ください。

- [Snowflakeデータソースの設定](/action/datasources/snowflake/datasource_setting/)
- [Snowflakeアクションの設定](/action/datasources/snowflake/action_setting/)

[各データ型の値の扱い](/action/datasources/bigquery/data_type/) [データソースの設定](/action/datasources/snowflake/datasource_setting/)
---
[アクション](/action/)

データソース別の設定

[Snowflake](/action/datasources/snowflake/)

アクションの設定

# Snowflakeアクションの設定

※ Snowflake アクションを使用するには事前に Snowflake のデータソースの作成が必要です。
データソースの作成方法は [Snowflake データソースの設定](/action/datasources/snowflake/datasource_setting/) をご参照ください。

Snowflake アクションは以下の手順で設定します。

1. 右上のメニューから「アクション」を選択してアクション一覧画面に移動します。
1. 「アクションの追加」を選択してアクションの作成画面に移動します。
1. 「基本情報の設定」を入力後「次へ」を選択して、「処理の設定」画面に移動します。
1. 「データソース」から事前に作成した Snowflake のデータソースを選択します。

![Snowflakeアクションの設定画面](/images/snowflake/action_setting.png)

Snowflake アクションではパラメーターなどの他のアクションと共通の項目に加えて、以下の項目を設定します。

- SQL文のタイトル
- SQL文
- JSON型の値をパースする

## SQL文のタイトル [](#sql文のタイトル)

SQL文のタイトルを設定します。

## SQL文 [](#sql文)

実行するSQL文を設定します。

SQL文は1つの Snowflake アクションに複数設定できます。

※ Snowflake アクションでは、それぞれのSQL文は別のトランザクションで実行されます。

### SQL文内でパラメーターを使用する [](#sql文内でパラメーターを使用する)

SQL文内では `{{ パラメーター名 }}` の形式でパラメーターを使用できます。

例えば、パラメーター名が「メールアドレス」のテキストパラメーターを使って `users` テーブルから特定のユーザーを検索するSQL文は以下です。

```
SELECT * FROM users WHERE email = {{ メールアドレス }};
```

`{{ パラメーター名 }}` の部分はアクションの実行時にプレースホルダーへ置換され、パラメーターの値が入力されてSQL文が実行されます。

パラメーターの種類ごとに、入力される値の形式は以下です。

| 種類 | 入力される値の形式 | 例 |
| --- | --- | --- |
| [テキスト](/action/parameter/text_parameter/) | 文字列（値が未入力の場合は空文字列） | `'test@example.com'` |
| [数値](/action/parameter/number_parameter/) | 数値（値が未入力の場合は `null` ） | `123`, `4.56`, `0`, `null` |
| [真偽値](/action/parameter/bool_parameter/) （フォーマットなし） | 真偽値 | `true`, `false` |
| [真偽値](/action/parameter/bool_parameter/) （フォーマット形式が文字列） | 文字列 | `'有効'`, `'無効'` |
| [日付](/action/parameter/date_parameter/) （unixtimeとして利用するが有効） | 数値（値が未入力の場合は `null` ） | `1672531200000`, `null` |
| [日付](/action/parameter/date_parameter/) （unixtimeとして利用するが無効） | 文字列（値が未入力の場合は空文字列） | `'2023-01-01'`, `'2023-01-01T00:00:00Z'` |
| [配列](/action/parameter/array_parameter/) （フォーマット形式がSQL） | 配列 | `(10,11,12)` |
| [配列](/action/parameter/array_parameter/) （フォーマット形式がJSON） | 文字列 | `'["taro","jiro","saburo"]'` |
| [配列](/action/parameter/array_parameter/) （フォーマット形式が区切り文字） | 文字列 | `'"taro","jiro","saburo"'` （区切り文字が `,` 、引用符が `"` の場合） |
| [タプル](/action/parameter/tuple_parameter/) （フォーマット形式がJSON） | 文字列 | `'["taro",25,"2023-01-01"]'` |
| [タプル](/action/parameter/tuple_parameter/) （フォーマット形式が区切り文字） | 文字列 | `'"taro","jiro","saburo"'` （区切り文字が `,` 、引用符が `"` の場合） |
| [SQL](/action/parameter/sql_parameter/) | プレースホルダーを使用せずに `{{ パラメータ名 }}` が値にそのまま置換されます。 | SQL型のパラメーターのドキュメントをご参照ください |
| JSON値 | Snowflake アクションでは使用できません | - |
| ファイル | Snowflake アクションでは使用できません | - |
| システム値 | Snowflake アクションでは使用できません | - |

[データソースの設定](/action/datasources/snowflake/datasource_setting/) [各データ型の値の扱い](/action/datasources/snowflake/data_type/)
---
[アクション](/action/)

データソース別の設定

[Snowflake](/action/datasources/snowflake/)

各データ型の値の扱い

# SnowflakeアクションでのSnowflakeの各データ型の値の扱い

ベースマキナにはアクションの実行結果に対してJavaScriptで処理を書く機能があります。

- [アクションの実行結果の加工スクリプト](/action/transformer_script/action_transform/)
- [ビュー](/view/what_is_view/)
- [JavaScriptアクション](/action/datasources/javascript_action/)

各アクションの実行結果の値は、それに対応するJavaScriptの型へと自動的に変換されます。

以下の表は、上記の機能でSnowflakeアクションの結果として使用される、Snowflakeのデータ型と、対応するJavaScriptの型の一覧です。

| Snowflakeのデータ型 | アクションの実行結果でのJavaScriptの型 | 対応状況 |
| --- | --- | --- |
| `FLOAT` `FLOAT4` `FLOAT8` `DOUBLE` `DOUBLE PRECISION` `REAL` | `number | null` | 対応 |
| `VARCHAR` `CHAR` `CHARACTER` `STRING` `TEXT` | `string | null` | 対応 |
| `BOOLEAN` | `boolean | null` | 対応 |
| `DATE` `DATETIME` `TIME` `TIMESTAMP` `TIMESTAMP_LTZ` `TIMESTAMP_NTZ` `TIMESTAMP_TZ` | `string | null` | 対応 |
| `INT` `INTEGER` `BIGINT` `SMALLINT` `TINYINT` `BYTEINT` | `bigint | null` | 対応 |
| `NUMBER` `DECIMAL` `NUMERIC` （scaleが0の場合。例： `NUMBER(38, 0)` ） | `bigint | null` | 対応 |
| `NUMBER` `DECIMAL` `NUMERIC` （scaleが0以外の場合） | `string | null` | 未対応 |
| `BINARY` `VARBINARY` | `string | null` | 未対応 |
| `VARIANT` `OBJECT` `ARRAY` `MAP` | `string | null` | 未対応 |
| `GEOGRAPHY` `GEOMETRY` | `string | null` | 未対応 |
| `VECTOR` | `string | null` | 未対応 |

各データ型の詳細はSnowflakeのドキュメントの [Snowflakeのデータ型 (opens in a new tab)](https://docs.snowflake.com/ja/sql-reference-data-types) をご参照ください。

## 未対応のデータ型 [](#未対応のデータ型)

対応状況が未対応のデータ型はJavaScriptの型への変換が未対応で、現在は `string | null` に変換されますが、今後別のJavaScriptの型に変更される可能性があります。

なおSnowflakeアクションの実行結果に未対応のデータ型の列の値が含まれる場合、アクションの実行結果に以下のメッセージが表示されます。

![未対応のデータ型のメッセージ](/images/snowflake/unsupported_column.png)

## 各データ型の列の値を別のJavaScriptの型に変換する [](#各データ型の列の値を別のjavascriptの型に変換する)

以下は各データ型の列の値を、別のJavaScriptの型として扱いたい場合の変換方法です。

### SQL文でデータ型を変換する [](#sql文でデータ型を変換する)

アクションの実行で共通の変換をする場合は、SQL文内で `CAST` 関数を使ってデータ型を変換する方法が便利です。

例えば、以下のように `NUMBER` 型の列の値を `VARCHAR` 型に変換すると、
アクションの実行結果のJavaScriptの型は `string | null` になります。

```
SELECT
    -- ここでVARCHAR型の列「id」の値をVARCHAR型に変換
    CAST(id AS VARCHAR)
FROM
    users;
```

`CAST` 関数の詳細はSnowflakeのドキュメントの [CAST、 :: (opens in a new tab)](https://docs.snowflake.com/ja/sql-reference/functions/cast) をご参照ください。

### JavaScriptで値の型を変換する [](#javascriptで値の型を変換する)

各アクション実行ごとに別の変換をしたい場合は、JavaScriptのコード内で値の型を変換できます。

以下は、アクションの実行結果の加工スクリプトで `string | null` 型の値を `number` 型に変換する例です。

```
return [
  {
    success: results[0].success.map((user) => ({
      // `Number()`コンストラクターで`string | null`型の値を`number | null`型に変換
      id: user.id !== null ? Number(user.id) : null,
      name: user.name,
    })),
  },
];
```

[アクションの設定](/action/datasources/snowflake/action_setting/) [パラメーターとは](/action/parameter/action_parameter/)
---
[アクション](/action/)

データソース別の設定

[Snowflake](/action/datasources/snowflake/)

データソースの設定

# Snowflakeデータソースの設定

Snowflakeのデータソースは以下の手順で設定します。

## Snowflakeのキーペア認証用に公開/秘密鍵ペアの生成 [](#snowflakeのキーペア認証用に公開秘密鍵ペアの生成)

ベースマキナでSnowflakeを利用するには、事前に以下の操作が必要です。

- キーペア認証用に公開/秘密鍵ペアの生成とSnowflakeユーザーへの割り当て

### キーペア認証用に公開/秘密鍵ペアの生成とSnowflakeユーザーへの割り当て [](#キーペア認証用に公開秘密鍵ペアの生成とsnowflakeユーザーへの割り当て)

次に、ベースマキナからSnowflakeへキーペア認証で接続するために、公開/秘密鍵ペアを生成しSnowflakeユーザーへの割り当てします。

キーペア認証用に公開/秘密鍵ペアの生成とSnowflakeユーザーへの割り当ては、Snowflakeのドキュメントの [キーペア認証とキーペアローテーション (opens in a new tab)](https://docs.snowflake.com/ja/user-guide/key-pair-auth) をご参照ください。

暗号化された秘密鍵は未対応のため、非暗号化バージョンの秘密鍵を生成してください。

## データソースの作成 [](#データソースの作成)

![Snowflakeのデータソースの作成画面](/images/snowflake/datasource_setting.png)

1. 右上のメニューから「データソース」を選択してデータソース一覧画面に移動します。
1. 「データソースの追加」を選択してデータソースの追加画面に移動します。
1. 「Snowflake」を選択して、Snowflakeのデータソースの作成画面に移動します。
1. 各設定項目を入力します。
1. 「保存」を選択します。

Snowflakeのデータソースには以下の項目を設定します。

### 名前 [](#名前)

データソースの名前を設定します。

### アカウント識別子 [](#アカウント識別子)

接続するSnowflakeアカウントの識別子を設定します。

### ユーザー名 [](#ユーザー名)

公開キーを割り当てた、接続に利用するSnowflakeユーザーの名前を設定します。

### 秘密鍵 [](#秘密鍵)

生成した秘密鍵を設定します。

## データソースの編集 [](#データソースの編集)

1. 右上のメニューから「データソース」を選択してデータソース一覧画面に移動します。
1. 編集するデータソースを選択してデータソースの編集画面に移動します。
1. 各設定項目を入力します。
1. 「保存」を選択します。

## データソースの削除 [](#データソースの削除)

![データソースの削除](/images/datasource/delete.png)

1. 右上のメニューから「設定」を選択してプロジェクト設定画面に移動します。
1. 「データソース設定」を選択してデータソース設定画面に移動します。
1. 削除するデータソースの行の右端の3点リーダから「削除する」を選択します。
1. 表示される画面で「OK」を選択します。

[Snowflake](/action/datasources/snowflake/) [アクションの設定](/action/datasources/snowflake/action_setting/)
---
[アクション](/action/)

設定内容のダウンロード

# アクションの設定内容のダウンロード

アクションの設定内容はJSON形式のファイルでダウンロードできます。

**※この機能は将来、別の機能による代替または廃止になる可能性があります。**

![アクションの設定内容のダウンロード](/images/download_action_settings.png)

## ダウンロード方法 [](#ダウンロード方法)

以下の手順でダウンロードできます。

1. 右上のメニューから「設定」を選択します。
1. サイドバーのメニューから「開発設定」を選択します。
1. 「全アクションの設定内容のダウンロード」ボタンをクリックすると、ダウンロードできます。

以下がダウンロードできるJSONファイルの例です。（一部のキーのみ抜粋）

```
{
  "actions": [
    {
      "id": "aaabbbcccddd",
      "class": "restapi",
      "name": "ユーザー一覧の取得",
      "parameters": [
        {
          "name": "id",
          "rootElement": {
            "inputType": "TEXT",
            "required": false
          }
        }
        // ...
      ],
      "permissions": [
        {
          "target": {
            "targetID": "bbbcccdddeee",
            "name": "安戸 民太郎",
            "unit": "USER"
          }
        }
        // ...
      ],
      "reviewSetting": {
        "id": "cccdddeeefff",
        "name": "開発責任者レビュー"
      }
    }
    // ...
  ],
  "review_settings": [
    {
      "id": "cccdddeeefff",
      "name": "開発責任者レビュー",
      "environmentReviewSettings": [
        {
          "environment": {
            "id": "dddeeefffggg",
            "name": "本番環境"
          },
          "userGroupApprovalConditions": [
            {
              "userGroup": {
                "id": "ggghhhiiijjj",
                "name": "開発責任者"
              },
              "requiredCount": 1
            }
          ]
        }
        // ...
      ]
    }
    // ...
  ]
}
```

[一括実行](/action/batch/) [ビュー](/view/)
---
[アクション](/action/)

結果のダウンロード

# 結果のダウンロード

アクションの実行結果はファイルでダウンロードできます。

ファイルのフォーマットはCSVまたはJSONをサポートしています。

ダウンロードは、アクションを実行した結果の右側にあるメニューからできます。

![１つの結果ダウンロード](/images/download_result/single.png)

複数の実行結果が表示されるアクションを実行した後は、すべての結果のファイルをZIPファイルに圧縮したものをダウンロードできます。

![すべての結果ダウンロード](/images/download_result/all.png)

また、HTTP APIアクションの結果が、 `application/octet-stream` などのプレビュー不可能なデータ形式だった場合、データをダウンロードするためのボタンが表示されます。

## CSV形式のオプション [](#csv形式のオプション)

CSV形式でダウンロードする際、以下のオプションを設定できます。

- **BOMを付与する**: ファイルの先頭にBOM（Byte Order Mark）を付与します。Excelなどで開く際に文字化けを防ぐことができます。
- **ヘッダーを含める**: CSVファイルの最初の行に列名を含めます。
- **文字列の値を常にダブルクォーテーションで囲む**: すべての文字列をダブルクォーテーション（ `"` ）で囲みます。オフの場合は、カンマ（ `,` ）、改行（ `\n` ）、ダブルクォーテーション（ `"` ）を含む文字列のみが囲まれます。

[画像や動画の表示](/action/action_media_result/) [ジョブ](/action/jobs/)
---
[アクション](/action/)

有効化設定

# アクションの有効化設定

## 有効化設定とは [](#有効化設定とは)

アクションは、 [環境](/admin/environment/what_is_environment/) ごとに有効/無効状態を切り替えることができます。

無効化されたアクションは、その環境では実行できなくなり、アクション一覧からも非表示となります。

![無効化されたアクションの実行フォーム。「このアクションは現在の環境では無効になっているため、ご利用いただけません。」と記載](/images/environment_action_settings/disabled_action_execution_form.png)

### アクション作成時のデフォルト設定 [](#アクション作成時のデフォルト設定)

[開発環境](/admin/environment/development_environment/) が設定されている場合、アクション作成時のデフォルト設定は開発環境以外で「無効」となります。
そのため、開発環境以外では実行できない状態となります。

開発環境にてアクションの設定、および動作確認が完了したら、アクションのバージョン/有効化設定画面から他の環境でも有効化してください。

また、新規に環境を作った場合、新しい環境ではすべてのアクションがデフォルトで「無効」となります。

開発環境が設定されていない場合、アクションおよび環境作成時のデフォルト設定は全環境で「有効」となります。

## 有効化設定の変更方法 [](#有効化設定の変更方法)

有効化設定 は、アクションのバージョン/有効化設定画面および、アクションのバージョン/有効化一括設定画面にて変更できます。

### アクションのバージョン/有効化設定画面 [](#アクションのバージョン有効化設定画面)

アクション実行画面の「バージョン/有効化設定」ボタンをクリックすると、アクションのバージョン/有効化設定画面に移動します。

![アクションのバージョン/有効化設定画面への移動のための導線](/images/environment_action_settings/link_to_update_environment_action_settings_primary_column_environment.png)

この画面では、選択したアクションの、各環境におけるバージョン/有効化設定をまとめて変更できます。

![アクションのバージョン/有効化設定画面](/images/environment_action_settings/update_environment_action_settings_primary_column_environment.png)

### アクションのバージョン/有効化一括設定画面 [](#アクションのバージョン有効化一括設定画面)

アクション一覧画面の三点リーダーのメニューから「アクションのバージョン/有効化一括設定」をクリックすると一括設定画面に移動します。

![アクションのバージョン/有効化一括設定画面への移動のための導線。三点リーダーのメニューを開くボタンが指し示されている](/images/environment_action_settings/link_to_update_environment_action_settings_primary_column_action_01.png)

![アクションのバージョン/有効化一括設定画面への移動のための導線。三点リーダーのメニューを開いた結果、「アクションのバージョン/有効化一括設定」のリンクが表示されている様子](/images/environment_action_settings/link_to_update_environment_action_settings_primary_column_action_02.png)

この画面では、現在利用中の環境の、各アクションのバージョン/有効化設定をまとめて変更できます。

![アクションのバージョン/有効化一括設定画面](/images/environment_action_settings/update_environment_action_settings_primary_column_action.png)

[アクションの通知設定](/action/notification/action_notification/) [バージョン管理](/action/versions/)
---
[アクション](/action/)

ジョブ

# ジョブ

## ジョブとは [](#ジョブとは)

アクションは基本的に実行した画面で即座に結果が反映されます。しかし、ビジネスの要件によって必ずしも短時間ですべてのオペレーションが終わるわけではありません。
時間がかかるオペレーションに利用できるのがジョブです。通常のアクションの実行とは異なって、非同期的に実行します。結果は後から確認できます。

ジョブで実行できるオペレーションの最大時間は30分です。

## ジョブを実行する [](#ジョブを実行する)

通常のアクションと同様にアクションの詳細ページから実行できます。

![ジョブとして実行する](/images/jobs_execution.png)

選択肢の中から「ジョブとして実行する」を選択するとボタンの表記が変わります。そしてもう一度「ジョブとして実行する」ボタンをクリックすると非同期でアクションが実行されます。

クリック後、自動的にジョブの詳細ページへ移動されます。詳細ページではジョブに関する情報を確認できます。

![実行者](/images/jobs_left.png)

詳細ページ左側では、ジョブが誰によって、どのアクションが非同期で実行されたのか確認できます。

![ステータス](/images/jobs_right.png)

詳細ページ右側では、ジョブのステータスはどのような状態か、いつ実行されたのかといった情報を確認できます。またここからベースとなったアクションの詳細ページへジャンプできます。

ジョブのステータスは以下の通りです。

| ステータス | 説明 |
| --- | --- |
| 待機中です | ジョブがまだ実行されていません。キャンセルができます。 |
| 実行中です | ジョブが実行中です。キャンセルができます。 |
| 正常に終了しました | ジョブの実行が完了し、実行結果を確認できます。 |
| キャンセルされました | お客さまによるキャンセルとシステムのタイムアウトによるキャンセルの2つが存在します。 |
| 実行時にエラーが発生しました | アクションの実行でエラーが発生しています。何度試しても解消しない場合は大変ご不便をおかけいたしますが、お問い合わせください。 |

### 実行した結果を確認する [](#実行した結果を確認する)

ベースマキナではジョブの実行結果を1週間保持します。この間はジョブの詳細ページでいつでも確認できます。

期限を超えると下記画像のようなメッセージが表示されます。この期間以上記録を残したい場合は結果をダウンロードし、手元に残しておくことを推奨しています。

![](/images/jobs_expired.png)

## ジョブ実行結果の閲覧制限 [](#ジョブ実行結果の閲覧制限)

アクションごとに、ジョブのパラメーターや実行結果の閲覧範囲を制限できます。

### 閲覧制限の種類 [](#閲覧制限の種類)

| 設定値 | 説明 |
| --- | --- |
| 全員が閲覧可能 | 全ユーザーがジョブ実行結果の詳細を閲覧できる |
| 実行者のみ | ジョブを実行したユーザーのみがジョブ実行結果の詳細を閲覧できる |

### 閲覧制限を設定する [](#閲覧制限を設定する)

アクションの編集画面にある権限ステップで、ジョブ実行結果の閲覧制限を設定できます。

![ジョブ結果の閲覧制限の設定画面](/images/job_result_visibility_restriction.png)

新規作成時のデフォルトは「実行者のみ」です。

この設定を変更できるロールは以下の通りです。

- プロジェクト管理者
- 開発責任者
- アクション運用責任者

### 閲覧権限がない場合の表示 [](#閲覧権限がない場合の表示)

閲覧権限がないジョブの場合、以下のように表示されます。

- **ジョブ一覧**: 閲覧権限のないジョブでも、ジョブ一覧には表示されます
- **ジョブ詳細**: ステータスや実行日時などのメタデータは表示されますが、パラメータと結果は「閲覧権限がありません」というメッセージに置き換えられます

[結果のダウンロード](/action/download_result/) [予約実行](/action/scheduled_jobs/)
---
[アクション](/action/)

JWT認証

# JWT認証

JWT認証はデータソースに届くリクエストがベースマキナからのアクション実行のリクエストであることを検証できる機能です。

アクション実行時に発行されるトークンをリクエスト情報に含めることで、データソース側で検証できます。

各種クラウドのJWT認証機能での利用も可能です。

## 対応しているデータソース [](#対応しているデータソース)

現在はHTTP APIデータソースのみ対応しています。

もし他のデータソースで使用したい場合はご連絡いただければ幸いです。

## 設定例 [](#設定例)

以下では、Amazon API Gatewayの [JWT Authorizer (opens in a new tab)](https://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/http-api-jwt-authorizer.html) で利用する場合の設定例を紹介します。

### HTTP APIデータソースの設定 [](#http-apiデータソースの設定)

HTTP APIデータソースの共通ヘッダーに、JWT認証用のヘッダーを設定します。

1. HTTP APIデータソースの編集画面を開く
1. 共通ヘッダーに以下のように設定する
  - ヘッダー名： `Authorization`
  - 値： `Bearer {{ authToken }}`

![HTTP APIデータソースの共通ヘッダー設定画面。Authorizationヘッダーに Bearer {{ authToken }} を設定](/images/action_jwt_authentication/common_header_setting.png)

`{{ authToken }}` は [事前定義パラメーター](/action/parameter/predefined_parameter/) で、アクション実行時に自動的にトークンに置換されます。

また他の事前定義パラメーターと同様に、アクションのヘッダーやクエリパラメーター、リクエストボディなどでも使用できます。

### Amazon API GatewayのJWT Authorizerの設定

JWT Authorizerを以下のように設定します。

![AWS API GatewayのJWT Authorizer設定画面](/images/action_jwt_authentication/aws_jwt_authorizer.png)

- **名前** ： `ベースマキナ用`
  - 任意の名前を設定してください。
- **ID ソース** ： `$request.header.Authorization`
  - データソースやアクションの設定に合わせて設定してください。
- **発行者 URL** ： `https://idp.basemachina.com`
- **対象者** ： `https://<ベースマキナの企業アカウントのサブドメイン>.basemachina.com`
  - 詳細な設定方法は「 [aud](/action/jwt_authentication/#aud) 」で後述します。

### アクションを実行する [](#アクションを実行する)

設定したデータソースを使用するアクションを作成し実行すると、共通ヘッダーで設定した `{{ authToken }}` がトークンに置き換わり、JWT Authorizerで認証されます。

## トークンの仕様 [](#トークンの仕様)

以下はリクエスト情報に含まれるトークンの仕様です。

### アルゴリズム [](#アルゴリズム)

アルゴリズムは `RS256` です。

### クレーム [](#クレーム)

#### iss [](#iss)

発行者のURLです。

常に `"https://idp.basemachina.com"` が設定されています。

#### exp [](#exp)

トークンの有効期限です。
有効期限は発行から1分間で、 `1764514800` のようなUNIXタイムスタンプの値が設定されています。

#### aud [](#aud)

対象者を識別する値です。

以下の内容の配列が設定されており、いずれかのURLと対象者との一致を検証することで、許可する範囲をカスタマイズできます。

```
[
  "https://{企業アカウントのサブドメイン}.basemachina.com",
  "https://{企業アカウントのサブドメイン}.basemachina.com/projects/{プロジェクトID}",
  "https://{企業アカウントのサブドメイン}.basemachina.com/projects/{プロジェクトID}/environments/{環境ID}"
]
```

例えば、企業アカウント内の全プロジェクトの全環境からのリクエストを許可する場合は、許可する対象者を `"https://{企業アカウントのサブドメイン}.basemachina.com"` に設定します。

また、特定の環境からのリクエストのみを許可する場合は、以下のように設定して実現できます。

`"https://{企業アカウントのサブドメイン}.basemachina.com/projects/{プロジェクトID}/environments/{環境ID}"`

## 公開鍵の取得 [](#公開鍵の取得)

トークンの検証に必要な公開鍵は、以下のURLから取得できます。

```
https://idp.basemachina.com/.well-known/jwks.json
```

またOpenID Connect（OIDC）Discoveryドキュメントは以下のURLから取得できます。

```
https://idp.basemachina.com/.well-known/openid-configuration
```

[実行権限](/action/action_permission/) [レビュー設定](/action/review/)
---
[アクション](/action/)

通知設定

# 通知設定

アクションの実行後にSlackへ通知できます。

ベースマキナとSlackを連携するだけで、以下の機能が利用できるようになります。チャンネルやユーザーを個別に連携する必要はありません。

- **チャンネル選択**: 連携したワークスペースのチャンネル一覧から選択できます
- **メンション機能**: 通知時に特定のユーザーをメンションできます
- **メッセージのカスタマイズ**: 通知メッセージをカスタマイズできます
- **環境別設定**: 環境ごとに異なる通知先を設定できます
- **見た目のカスタマイズ**: 通知の通知者名とアイコンを環境ごとに変更できます

Slack連携を利用するには、以下の設定が必要です。

1. [Slack連携](/action/notification/slack_integration/): 企業アカウントとSlackワークスペースを連携する
1. [通知方法の管理](/action/notification/notification_methods/): 通知先のチャンネルを設定する
1. [アクションの通知設定](/action/notification/action_notification/): アクションごとに通知を設定する

[レビュー設定](/action/review/) [Slack連携](/action/notification/slack_integration/)
---
[アクション](/action/)

[通知設定](/action/notification/)

アクションの通知設定

# アクションの通知設定

アクションごとに、実行成功時やエラー時の通知を設定できます。

## 前提条件 [](#前提条件)

アクションの通知設定をするには、以下の準備が完了している必要があります。

- [Slack連携](/action/notification/slack_integration/) が完了していること
- [通知方法](/action/notification/notification_methods/) が作成されていること

（旧）JavaScriptアクションでは通知設定は利用できません。通知機能を利用するには、 [JavaScriptアクション](/action/javascript_action/) への移行をご検討ください。

## 必要なロール [](#必要なロール)

アクションの通知設定をするには、以下のいずれかのロールが設定されたグループに所属している必要があります。

- プロジェクト管理者
- 開発責任者
- 開発者

ロールの詳細は [グループ](/admin/user_management/project_group/) をご覧ください。

## 通知設定の方法 [](#通知設定の方法)

1. アクションの編集画面を開きます。
1. 「通知設定」のステップに進みます。
1. 「成功時の通知」または「エラー時の通知」を設定します。

![アクション編集画面の通知設定ステップ](/images/action_notification/action_notification_step.png)

### 成功時の通知 [](#成功時の通知)

「成功時の通知を有効にする」をONにすると、アクションの実行が成功したときに通知を送信します。

### エラー時の通知 [](#エラー時の通知)

「エラー時の通知を有効にする」をONにすると、アクションの実行中にエラーが発生した場合に通知を送信します。

HTTP
APIアクションでHTTPステータスコードによるエラー判定をするには、 [「200系以外のレスポンスステータスコードを実行エラーとして扱う」](/action/datasources/httpapi_integration/#200%E7%B3%BB%E4%BB%A5%E5%A4%96%E3%81%AE%E3%83%AC%E3%82%B9%E3%83%9D%E3%83%B3%E3%82%B9%E3%82%B9%E3%83%86%E3%83%BC%E3%82%BF%E3%82%B9%E3%82%B3%E3%83%BC%E3%83%89%E3%82%92%E5%AE%9F%E8%A1%8C%E3%82%A8%E3%83%A9%E3%83%BC%E3%81%A8%E3%81%97%E3%81%A6%E6%89%B1%E3%81%86) を有効にしてください。

## 設定項目 [](#設定項目)

各通知設定では、以下の項目を設定できます。

### 通知方法 [](#通知方法)

[通知方法の管理](/action/notification/notification_methods/) で作成した通知方法を選択します。選択した通知方法の環境ごとの通知先チャンネルが表示されます。

### メンション先ユーザー [](#メンション先ユーザー)

通知メッセージでメンションするユーザーを選択します。複数のユーザーを選択できます。

ベースマキナと同じメールアドレスのSlackユーザーが存在するプロジェクトユーザーから選択できます。メンションはメッセージの先頭に表示されます。

### メッセージのカスタマイズ [](#メッセージのカスタマイズ)

「成功時のメッセージをカスタマイズする」または「エラー時のメッセージをカスタマイズする」をONにすると、通知メッセージをカスタマイズできます。

メッセージは [Slackの書式（mrkdwn形式） (opens in a new tab)](https://api.slack.com/reference/surfaces/formatting) で記述できます。また、 [事前定義パラメーター](/action/parameter/predefined_parameter/) とアクションのパラメーターを使用して動的な値を埋め込めます。

通知メッセージでのみ使用できる値は以下のとおりです。

- `{{ action.results }}` - 全実行結果の配列
- `{{ action.success }}` - 1つ目の実行結果（ `action.results[0].success` と同等、成功時のみ）
- `{{ action.failure }}` - 1つ目の失敗内容（ `action.results[0].failure` と同等、エラー時のみ）
- `{{ action.metadata }}` - 1つ目の実行結果のメタデータ（ `action.results[0].metadata` と同等）

MySQLなどのSQLアクションでは複数のクエリを登録でき、それぞれのクエリに対応する実行結果が返ってきます。2つ目以降の実行結果を使用する場合は `action.results[1].success` のようにアクセスしてください。

これらのパラメーターではプロパティアクセスとインデックスアクセスが使用できます。

- プロパティアクセス： `{{ action.success.someKey }}`
- インデックスアクセス： `{{ action.success.data[0] }}`

存在しないパラメーターを指定した場合、エラーメッセージが表示されます。

### パラメーターの値の表示形式 [](#パラメーターの値の表示形式)

パラメーターの値は、種類に応じて以下のように表示されます。

| 種類 | 表示形式 |
| --- | --- |
| テキスト | 値がそのまま表示されます。空の場合は `(未入力)` と表示されます。選択肢が設定されている場合は、選択肢のラベルが表示されます。 |
| 数値 | 値が数値として表示されます。未入力の場合は `(未入力)` と表示されます。選択肢が設定されている場合は、選択肢のラベルが表示されます。 |
| SQL | テキストと同様に表示されます。 |
| （非推奨）システム値 | テキストと同様に表示されます。 |
| 真偽値 | フォーマット形式が「文字列」の場合は設定した「真の場合の値」または「偽の場合の値」が表示されます。「フォーマットなし」の場合は `true` または `false` が表示されます。 |
| 日付 | 設定した日付の形式で表示されます。「unixtimeとして利用する」が有効な場合は数値として表示されます。未入力の場合は `(未入力)` と表示されます。 |
| ファイル | `ファイルパラメーターの値は表示できません` と表示されます。 |
| JSON値 | `null` の場合は `null` と表示されます。それ以外は、設定した「JSON値の種類」（テキスト、数値、日付）に応じて表示されます。 |
| 配列 | 各要素が「要素の種類」に応じて変換され、カンマ区切りで表示されます。空配列の場合は `(未入力)` と表示されます。 |
| タプル | 各要素が「要素の種類」に応じて変換され、カンマ区切りで表示されます。 |

### 実行結果の値の表示形式 [](#実行結果の値の表示形式)

実行結果へのアクセス（ `{{ action.success }}` 、 `{{ action.success.key }}` 、 `{{ action.success[0] }}` など）では、値の型に応じて以下のように表示されます。

| 値の型 | 表示形式 |
| --- | --- |
| 文字列 | 値がそのまま表示されます。 |
| 数値 | 数値が文字列に変換されて表示されます。 `NaN` や `Infinity` もそのまま表示されます。 |
| 真偽値 | `true` または `false` が表示されます。 |
| オブジェクト | JSON文字列に変換されて表示されます（例: `{"key":"value"}` ）。循環参照など文字列化できない場合はエラーメッセージが表示されます。 |
| 配列 | JSON文字列に変換されて表示されます（例: `[1,2,3]` ）。 |
| null | `null` と表示されます。 |
| ファイル（Blob） | 「〜の値はファイルのため通知で表示できません」というエラーメッセージが表示されます。 |

## 通知メッセージの設定例 [](#通知メッセージの設定例)

以下に、通知メッセージのカスタマイズ例を紹介します。

### 基本的な設定例 [](#基本的な設定例)

#### 実行者と環境を含む通知 [](#実行者と環境を含む通知)

```
{{ currentUser.name }} が {{ action.name }} を実行しました。
環境: {{ environment.name }}
```

#### パラメーターを含む通知 [](#パラメーターを含む通知)

アクションに `userName` と `newStatus` というパラメーターがある場合の例です。

```
ユーザー「{{ userName }}」のステータスを「{{ newStatus }}」に更新しました。
実行者: {{ currentUser.name }}
```

### 実行結果を使った設定例 [](#実行結果を使った設定例)

#### HTTP APIの結果を表示 [](#http-apiの結果を表示)

HTTP APIアクションで `{"user": {"id": 123, "name": "田中太郎"}}` のようなレスポンスが返る場合の例です。

```
ユーザー情報を取得しました。
- ID: {{ action.success.user.id }}
- 名前: {{ action.success.user.name }}
```

#### 配列データの表示 [](#配列データの表示)

HTTP APIアクションで `{"items": [{"name": "商品A"}, {"name": "商品B"}]}` のようなレスポンスが返る場合の例です。

```
最初の商品: {{ action.success.items[0].name }}
```

### エラー時の通知例 [](#エラー時の通知例)

エラー時の通知では `{{ action.failure }}` を使用してエラー内容を表示できます。

#### 基本的なエラー通知 [](#基本的なエラー通知)

```
アクション「{{ action.name }}」の実行に失敗しました。
エラー内容: {{ action.failure }}
実行者: {{ currentUser.name }}
環境: {{ environment.name }}
```

#### エラー詳細へのネストアクセス [](#エラー詳細へのネストアクセス)

エラーが `{"message": "ユーザーが見つかりません", "code": "USER_NOT_FOUND"}` のような構造の場合、プロパティにアクセスできます。

```
エラーが発生しました。
メッセージ: {{ action.failure.message }}
エラーコード: {{ action.failure.code }}
```

### JavaScriptアクションとの組み合わせ [](#javascriptアクションとの組み合わせ)

より高度な通知をする場合、 [JavaScriptアクション](/action/javascript_action/) でデータを加工し、その結果を通知メッセージで使用できます。

#### データの集計 [](#データの集計)

売上データを集計して通知する例です。

**JavaScriptアクションのコード:**

```
import { executeAction } from "@basemachina/action";
 
/** @type { import("@basemachina/action").Handler } */
export default async () => {
  // 売上データを取得するアクションを実行
  const result = await executeAction("get-sales-data");
  const sales = result[0].success;
 
  const total = sales.reduce((sum, s) => sum + s.amount, 0);
  const count = sales.length;
 
  return {
    summary: `${count}件の売上、合計${total.toLocaleString()}円`,
    topSale: sales.sort((a, b) => b.amount - a.amount)[0],
  };
};
```

**通知メッセージ:**

```
本日の売上レポート
{{ action.success.summary }}
最高額: {{ action.success.topSale.amount }}円（{{ action.success.topSale.customerName }}様）
```

#### 条件に応じたメッセージ [](#条件に応じたメッセージ)

在庫数に応じて表示内容を変える例です。

**JavaScriptアクションのコード:**

```
import { executeAction } from "@basemachina/action";
 
/** @type { import("@basemachina/action").Handler } */
export default async ({ productId }) => {
  // 在庫数を取得するアクションを実行
  const result = await executeAction("get-stock-count", { productId });
  const stock = result[0].success.count;
 
  let status;
  if (stock === 0) {
    status = "在庫切れ";
  } else if (stock < 10) {
    status = "在庫僅少";
  } else {
    status = "在庫あり";
  }
 
  return { productId, stock, status };
};
```

**通知メッセージ:**

```
商品ID: {{ action.success.productId }}
ステータス: {{ action.success.status }}
現在の在庫数: {{ action.success.stock }}
```

#### 複数データソースの統合 [](#複数データソースの統合)

ユーザー情報と注文情報を1つの通知にまとめる例です。

**JavaScriptアクションのコード:**

```
import { executeAction } from "@basemachina/action";
 
/** @type { import("@basemachina/action").Handler } */
export default async ({ userId }) => {
  // ユーザー情報を取得
  const userResult = await executeAction("get-user", { userId });
  const user = userResult[0].success;
 
  // 注文情報を取得
  const ordersResult = await executeAction("get-orders", { userId });
  const orders = ordersResult[0].success;
 
  const totalSpent = orders.reduce((sum, o) => sum + o.total, 0);
 
  return {
    userName: user.name,
    email: user.email,
    orderCount: orders.length,
    totalSpent: totalSpent.toLocaleString(),
  };
};
```

**通知メッセージ:**

```
顧客情報サマリー
- 名前: {{ action.success.userName }}
- メール: {{ action.success.email }}
- 注文回数: {{ action.success.orderCount }}回
- 累計購入額: {{ action.success.totalSpent }}円
```

#### エラーハンドリングと通知 [](#エラーハンドリングと通知)

複数のアクションを実行するワークフローで、どのステップで失敗したかを通知する例です。 [ResultError](/action/datasources/javascript_action/error_handlings/#resulterror) を使って構造化されたエラー情報を返します。

**JavaScriptアクションのコード:**

```
import { executeAction, ResultError } from "@basemachina/action";
 
/** @type { import("@basemachina/action").Handler } */
export default async ({ userId, imageFile }) => {
  // ステップ1: 画像をアップロード
  const uploadResult = await executeAction("upload-image", { imageFile });
  if (uploadResult[0].failure) {
    throw new ResultError({
      step: "画像アップロード",
      message: "画像のアップロードに失敗しました",
      detail: uploadResult[0].failure,
    });
  }
 
  // ステップ2: ユーザー情報を更新
  const imagePath = uploadResult[0].success.path;
  const updateResult = await executeAction("update-user-image", {
    userId,
    imagePath,
  });
  if (updateResult[0].failure) {
    throw new ResultError({
      step: "ユーザー情報更新",
      message: "ユーザー情報の更新に失敗しました",
      detail: updateResult[0].failure,
    });
  }
 
  return { userId, imagePath };
};
```

**エラー時の通知メッセージ:**

```
ワークフローでエラーが発生しました。
失敗したステップ: {{ action.failure.step }}
エラー内容: {{ action.failure.message }}
詳細: {{ action.failure.detail }}
```

## 通知の送信が失敗した場合 [](#通知の送信が失敗した場合)

Slackへの通知送信が失敗した場合、アクションを実行したユーザーへメールで通知が送信されます。

[通知方法の管理](/action/notification/notification_methods/) [有効化設定](/action/enablement_settings/)
---
[アクション](/action/)

[通知設定](/action/notification/)

通知方法の管理

# 通知方法の管理

通知方法は、Slackチャンネルへの通知先を環境ごとに設定したものです。アクションの通知設定で使用します。

## 前提条件 [](#前提条件)

通知方法を管理するには、 [Slack連携](/action/notification/slack_integration/) が完了している必要があります。

## 必要なロール [](#必要なロール)

通知方法を管理するには、以下のいずれかのロールが設定されたグループに所属している必要があります。

- プロジェクト管理者
- 開発責任者
- アクション運用責任者

ロールの詳細は [グループ](/admin/user_management/project_group/) をご覧ください。

## 通知方法の追加 [](#通知方法の追加)

1. 右上のメニューから「設定」を選択してプロジェクト設定画面に移動します。
1. 左のサイドバーから「通知設定」を選択します。
1. 右上の「追加」ボタンを選択します。
1. 以下の項目を入力します。
  - **名前**: 通知方法の名前を入力します。
  - **環境ごとの通知先チャンネル**: 各環境の通知先Slackチャンネルを選択します。
1. 「保存」ボタンを選択します。

![通知方法の追加フォーム](/images/action_notification/notification_method_form.png)

パブリックチャンネルと、BaseMachinaのSlackアプリが追加されているプライベートチャンネルから選択できます。「通知しない」を選択した環境では、その通知方法を使用しても通知が送信されません。

## 通知方法の編集 [](#通知方法の編集)

1. プロジェクト設定画面の「通知設定」にアクセスします。
1. 編集したい通知方法の行を選択します。
1. 内容を編集して「保存」ボタンを選択します。

## 通知方法の削除 [](#通知方法の削除)

1. プロジェクト設定画面の「通知設定」にアクセスします。
1. 削除したい通知方法の行の「削除」ボタンを選択します。
1. 確認画面で「削除」を選択します。

通知方法を削除すると、その通知方法を使用しているアクションの通知設定が無効になります。

## 通知の見た目のカスタマイズ [](#通知の見た目のカスタマイズ)

Slackへ届く通知の通知者名とアイコンを、通知方法と環境の組み合わせごとに変更できます。

たとえばアカウント登録の通知とアカウント削除の通知を別の見た目にすると、通知の内容をひと目で見分けられます。

設定していない場合はベースマキナのSlackアプリの名前とアイコンで通知が届きます。

見た目のカスタマイズには、Slackアプリの `chat:write.customize` 権限が必要です。2026年8月12日以前に連携したワークスペースでは、再連携するまで設定した見た目が反映されません。再連携の手順は [Slack連携](/action/notification/slack_integration/) をご覧ください。

### 設定方法 [](#設定方法)

1. 通知方法の追加または編集のフォームで、「環境ごとの通知先チャンネル」の対象の環境に通知先のチャンネルを選択します。
1. 同じ環境に表示される「通知の見た目」のボタンを選択します。
1. 「カスタマイズする」を選択し、通知者名とアイコンを設定します。
1. プレビューで表示を確認し、「適用」ボタンを選択します。
1. 通知方法のフォームで「保存」ボタンを選択します。

見た目は環境ごとに設定します。ある環境で設定した内容は、ほかの環境には反映されません（近日中に環境間の設定のコピー機能を追加予定です）。

### 通知者名 [](#通知者名)

Slackの通知で送信者として表示される名前です。

### アイコン [](#アイコン)

Slackの通知で送信者のアイコンとして表示される画像です。

- PNG形式またはJPEG形式の画像を利用できます。GIF形式やSVG形式は利用できません。
- ファイルサイズは1MB以下にしてください。
- アップロードした画像は加工されずにそのまま使われるため、正方形の画像をご利用ください（近日中に画像の切り抜き機能を追加予定です）。

## 次のステップ [](#次のステップ)

通知方法を追加したら、 [アクションの通知設定](/action/notification/action_notification/) で各アクションに通知を設定できます。

[レビュー依頼・承認のSlack連携](/action/notification/review_slack/) [アクションの通知設定](/action/notification/action_notification/)
---
[アクション](/action/)

[通知設定](/action/notification/)

レビュー依頼・承認のSlack連携

# レビュー依頼・承認のSlack連携

[レビュー設定](/action/review/) を使ったアクションのレビュー依頼を、SlackのDMとSlackアプリのホームタブで受け取り、Slack上で承認・却下まで完結できる機能です。

これまでレビュー依頼の確認・承認には、承認者がベースマキナのWeb画面を開く必要がありました。この機能を使うと、承認者は自分宛てのレビュー依頼をSlackで受け取り、そのまま承認・却下できます。Slackとの連携は次の2つで構成されます。

- **DM通知**: レビュー依頼の作成・リマインド・承認・却下のタイミングで、対象のユーザーにSlackのDMが届きます。
- **ホームタブ**: Slackアプリのホームタブで、自分宛てのレビュー依頼と自分が出したレビュー依頼を一覧で確認できます。

この機能は、既存のSlack通知機能には影響しません。

## 前提条件 [](#前提条件)

この機能を利用するには、以下の設定が必要です。

- **Slackワークスペースとの連携**: 企業アカウントとSlackワークスペースが連携されている必要があります。連携の手順は [Slack連携](/action/notification/slack_integration/) を参照してください。
- **ユーザーとSlackアカウントの紐づけ**: 承認者・依頼者のベースマキナユーザーとSlackアカウントがメールアドレスで紐づいている必要があります。紐づけはSlack連携時に自動で完了します。
- **Slackプロフィールでのメールアドレス公開**: Slackプロフィールでメールアドレスが非公開になっていると、ベースマキナユーザーを特定できず利用できません。

## レビュー依頼のDM通知 [](#レビュー依頼のdm通知)

レビュー依頼に関する以下のイベントが発生すると、対象のユーザーにSlackのDMが届きます。

| 種別 | 通知タイミング | 宛先 | 主な内容 | ボタン |
| --- | --- | --- | --- | --- |
| 依頼到着 | レビュー依頼の作成時 | 対象の全レビュアー | ホームタブの「承認待ち」と同じカード（アクション名・依頼者・依頼日時・期限・実行引数など） | 承認・却下 |
| リマインド | 期限が近づいたとき | まだ承認していないレビュアー | ホームタブの「承認待ち」と同じカード（アクション名・依頼者・依頼日時・期限・実行引数など） | 承認・却下 |
| 承認 | レビューが承認されたとき | 依頼者 | 承認者・アクション名・プロジェクト名 / 環境名 | 詳細を開く |
| 却下 | レビューが却下されたとき | 依頼者 | 却下者・却下理由・アクション名・プロジェクト名 / 環境名 | 詳細を開く |

- 「依頼到着」「リマインド」のDMにある「承認」「却下」ボタンを選択すると、後述のホームタブと同じ承認・却下の画面が開き、そのまま処理できます。
- 「承認」「却下」のDMにある「詳細を開く」を選択すると、Web画面の該当レビュー依頼が開きます。

## ホームタブで表示される内容 [](#ホームタブで表示される内容)

承認者がSlackアプリのホームタブを開くと、その人がアクセスできるプロジェクト・環境のレビュー依頼が表示されます。「承認待ち」「自分が出したレビュー依頼」の2つのタブを上部のボタンで切り替えて確認できます。どちらのタブも、依頼はプロジェクト・環境ごとにまとめて表示されます。

### 承認待ち [](#承認待ち)

自分がレビュアーとして設定されているレビュー依頼が表示されます。各レビュー依頼のカードには以下が表示されます。

- アクション名（Web画面の該当レビュー依頼へのリンク）
- プロジェクト名 / 環境名
- 依頼者
- 依頼日時
- 期限
- アクションの実行引数（引数名と値）
- 承認条件の状況（承認者・ユーザーグループごとの承認状況）。承認パターンが複数ある場合は「または」で区切って表示されます
- 「承認」「却下」ボタン

### 自分が出したレビュー依頼 [](#自分が出したレビュー依頼)

自分が依頼したレビュー依頼のうち、まだ承認・却下されていない確認中のものが一覧で表示されます。

表示されるのは、ログイン中のSlackユーザーに紐づくベースマキナユーザーがアクセスできるプロジェクト・環境のレビュー依頼のみです。各タブとも最大20件まで表示されます。すべてを確認するには、各プロジェクト・環境の「プロジェクト名
/ 環境名」のリンクからWeb画面のレビュー依頼一覧を開いてください。

## レビューを承認・却下する [](#レビューを承認却下する)

1. DMまたはホームタブの「承認待ち」から、対象のレビュー依頼の「承認」または「却下」ボタンを選択します。
1. コメント入力用の画面が開きます。
  - **承認**: コメントの入力は任意です。
  - **却下**: 却下理由のコメント入力が必須です。
1. 「承認する」または「却下する」を選択すると、レビュー依頼が処理されます。

承認・却下が完了すると、ホームタブの「承認待ち」から該当のレビュー依頼が消えます。

すでに承認・却下されたレビュー依頼を再度処理しようとすると、処理済みである旨のメッセージが表示されます。

レビュー依頼の詳細を確認したい場合は、カードのアクション名を選択するとWeb画面の該当レビュー依頼が開きます。

## 必要な権限 [](#必要な権限)

- **Slack上でのレビュー承認・却下**: Slackで承認・却下できるのは、対象のレビュー設定で承認者として設定されたユーザーと、承認者に設定されたグループのメンバーです。Web画面での承認と同じ権限で動作します。
- **Slackワークスペースの連携設定**: 連携の設定には [企業アカウントの管理者権限](/admin/user_management/tenant_role/) が必要です。

## 必要なSlackアプリ権限 [](#必要なslackアプリ権限)

この機能では、 [Slack連携](/action/notification/slack_integration/) で使用する権限に加えて、以下の権限を使用します。

- [`chat:write` (opens in a new tab)](https://api.slack.com/scopes/chat:write) / [`im:write` (opens in a new tab)](https://api.slack.com/scopes/im:write): レビュアー・依頼者へのDM送信に使用します。
- [`app_home:write` (opens in a new tab)](https://api.slack.com/scopes/app_home:write): ホームタブの表示更新に使用します。

## うまく表示されないとき [](#うまく表示されないとき)

ホームタブでレビュー依頼を確認できないときは、表示される案内に応じて以下を確認してください。

| 状況 | 原因と対処 |
| --- | --- |
| Slackのメールアドレスを取得できない | Slackプロフィールでメールアドレスが非公開になっています。プロフィール設定でメールアドレスを公開してください。 |
| メールアドレスに紐づくユーザーが見つからない | Slackのメールアドレスに紐づくベースマキナユーザーが存在しません。別のメールアドレスで登録している場合は、Slackプロフィールのメールアドレスを合わせるか、管理者にアカウント作成を依頼してください。 |
| ワークスペースが連携されていない | 企業アカウントの管理者がSlack連携を設定していません。 [Slack連携](/action/notification/slack_integration/) を設定してください。 |

## 関連ページ [](#関連ページ)

- [レビュー設定](/action/review/)
- [Slack連携](/action/notification/slack_integration/)

[Slack連携](/action/notification/slack_integration/) [通知方法の管理](/action/notification/notification_methods/)
---
[アクション](/action/)

[通知設定](/action/notification/)

Slack連携

# Slack連携

ベースマキナとSlackワークスペースを連携することで、アクションの実行後にSlackへ通知できます。

## 前提条件 [](#前提条件)

Slack連携を設定するには、 [企業アカウントの管理者権限](/admin/user_management/tenant_role/) が必要です。

## Slackワークスペースとの連携 [](#slackワークスペースとの連携)

1. [企業アカウント設定 (opens in a new tab)](https://basemachina.com/settings) にアクセスします。
1. 左のサイドバーから「通知設定」を選択します。
1. 「Add to Slack」ボタンを選択します。
1. Slackの認証画面でワークスペースを選択し、アクセスを許可します。

連携が完了すると、連携先のワークスペース名が表示されます。

![Slack連携画面](/images/action_notification/slack_integration.png)

1つの企業アカウントにつき、1つのSlackワークスペースと連携できます。

## 連携の解除 [](#連携の解除)

1. [企業アカウント設定 (opens in a new tab)](https://basemachina.com/settings) の「通知設定」にアクセスします。
1. 「連携を解除」ボタンを選択します。

連携を解除すると、設定済みの通知方法やアクション通知設定は無効になります。

## ユーザーとSlackアカウントの紐づけ [](#ユーザーとslackアカウントの紐づけ)

Slack連携すると、ベースマキナのユーザーとSlackアカウントが自動的に紐づけられます。紐づけの対象は、メールアドレスが一致するユーザー同士です。

紐づけが完了したユーザーは、 [アクションの通知設定](/action/notification/action_notification/) でメンション先として選択できます。

紐づけはSlack連携時に自動で完了します。連携後に追加されたユーザーも、ベースマキナへの初回ログイン時に自動で紐づけられます。

## 必要な権限 [](#必要な権限)

Slack連携では、以下のSlackアプリ権限を使用します。

- [`chat:write` (opens in a new tab)](https://api.slack.com/scopes/chat:write)
- [`chat:write.public` (opens in a new tab)](https://api.slack.com/scopes/chat:write.public)
- [`chat:write.customize` (opens in a new tab)](https://api.slack.com/scopes/chat:write.customize)
- [`channels:read` (opens in a new tab)](https://api.slack.com/scopes/channels:read)
- [`users:read` (opens in a new tab)](https://api.slack.com/scopes/users:read)
- [`users:read.email` (opens in a new tab)](https://api.slack.com/scopes/users:read.email)
- [`groups:read` (opens in a new tab)](https://api.slack.com/scopes/groups:read)

## 次のステップ [](#次のステップ)

Slack連携が完了したら、 [通知方法の管理](/action/notification/notification_methods/) で通知先のチャンネルを設定してください。

[通知設定](/action/notification/) [レビュー依頼・承認のSlack連携](/action/notification/review_slack/)
---
[アクション](/action/)

パラメーター

パラメーターとは

# パラメーターとは

アクションの実行時、任意の値を実行時の引数（以下パラメーター）として渡すことができます。

設定したパラメーターは、アクションの実行内容に相当するSQLやAPI呼び出しのなかで、 `{{ パラメーター名 }}` の形式で利用できます。

## パラメーターの追加方法 [](#パラメーターの追加方法)

パラメーターはアクション設定画面の **基本情報の設定** から追加できます。

![パラメーター追加](/images/action_parameter/add_parameter.png)

パラメーター名とその種類（後述）を設定することで、アクション実行画面で設定したパラメーターを入力するフォームの入力欄が生成されます。

![パラメーター追加](/images/action_parameter/added_parameter.png)

## パラメーターの種類 [](#パラメーターの種類)

パラメーターは入力形式に応じて異なるフォームを生成できるように、いくつかの種類が用意されています。

**種類** という表記がされた項目をクリックすると、種類の詳細を設定する画面が表示されます。

[各データ型の値の扱い](/action/datasources/snowflake/data_type/) [テキスト](/action/parameter/text_parameter/)
---
[アクション](/action/)

パラメーター

配列

# 配列

配列は複数の値をまとめて送信する場合に設定するパラメーターの種類です。

![配列パラメーターを使ったアクションの実行](/images/action_parameter/array_exec.png)

配列のパラメーターには以下の項目を設定できます。

- 要素の種類
- フォーマット形式
- 最小要素数
- 最大要素数
- 初期値

![配列パラメーターの編集](/images/action_parameter/array_edit.png)

## 要素の種類 [](#要素の種類)

配列の要素の種類は以下から選択できます。

- [文字列](/action/parameter/text_parameter/)
- [数値](/action/parameter/number_parameter/)
- [日付](/action/parameter/date_parameter/)
- [配列](/action/parameter/array_parameter/)
- [タプル](/action/parameter/tuple_parameter/)

さらに要素の種類ごとに **入力必須かどうか** や **正規表現による入力値チェック** などを設定できます。

要素の種類ごとに設定できる項目は、各種パラメーターのドキュメントをご参照ください。

### 配列の要素の種類が配列/タプルの場合 [](#配列の要素の種類が配列タプルの場合)

要素の種類で配列/タプルを設定すると階層構造のある配列を設定できます。

階層構造のある配列の場合は、配列内の配列の要素の種類を以下から選択できます。

- 文字列
- 数値
- 日付

また、配列内のタプルの要素は以下の種類を選択できます。

- 文字列
- 数値
- 日付
- 真偽値

階層構造のある配列の場合でも要素の種類ごとに、 **入力必須かどうか** や **正規表現による入力値チェック** などを設定できます。

## フォーマット形式 [](#フォーマット形式)

配列を送信する際のフォーマット形式を以下から選択できます。

- フォーマットなし
- JSON
- 区切り文字
- SQL
- form-data

### フォーマットなし [](#フォーマットなし)

配列の形式のまま送信されます。

**フォーマットなし** は以下のデータソースでのみ利用できます。

- [JavaScript](/action/datasources/javascript_action/)

### JSON [](#json)

配列をJSON形式に変換した文字列が送信されます。

| 要素の種類 | 送信される文字列 | 説明 |
| --- | --- | --- |
| テキスト | `["a","b"]` |  |
| 数値 | `[1,2]` | 各要素は二重引用符なしで送信されます |
| 日付（unixtime として利用する場合） | `["1672498800","1672585200"]` |  |
| 日付（unixtime として利用しない場合） | `["2023-01-01","2023-01-02"]` | 各要素は設定した日付の形式で送信されます |
| 真偽値 | `["有効","無効"]` （ `有効` 、 `無効` は設定した真、偽の値） | 各要素は設定した真、偽の値が送信されます |
| 配列 | `[["a","b"],["c","d"]]` | 配列内の配列は二重引用符なしで送信されます |

### 区切り文字 [](#区切り文字)

- 区切り文字
- 引用符

を設定でき、設定内容に基づいて配列を変換した文字列が送信されます。

```
// （例）引用符に `"`、区切り文字に `,` を設定した場合に、送信される文字列
"a","b","c"
```

### SQL [](#sql)

SQL文内で使用できる配列の形式で送信されます。

**SQL** は以下のデータソースでのみ利用できます。

- [MySQL](/action/datasources/mysql_integration/)
- [PostgreSQL](/action/datasources/postgresql_integration/)

フォーマット形式でSQLを選択した場合、 **展開先** を以下から選択します。

- IN
- VALUES

#### IN [](#in)

パラメータの値を、SQL文内で以下のようにIN句の値として利用する場合に選択します。

```
SELECT * FROM table1 WHERE column1 IN {{ array_parameter }};
```

配列の要素の種類がテキストや数値の場合、アクション実行時に上記のSQL文から以下のようなSQL文が生成されます。

```
SELECT * FROM table1 WHERE column1 IN (?, ?, ?);
```

また配列の要素の種類が配列/タプルの場合、アクション実行時に上記のSQL文から以下のようなSQL文が生成されます。

```
SELECT * FROM table1 WHERE column1 IN ((?, ?, ?), (?, ?, ?));
```

#### VALUES [](#values)

パラメーターの値を、SQL文内で以下のようにVALUES句の値として利用する場合に選択します。

```
INSERT INTO table1 (column1) VALUES {{ array_parameter }};
```

VALUESは配列の要素の種類が配列/タプルの場合のみ利用できます。

アクション実行時に上記のSQL文から以下のようなSQL文が生成されます。

```
INSERT INTO table1 (column1) VALUES (?, ?, ?), (?, ?, ?);
```

#### 例）MySQL の IN 句で利用する場合 [](#例mysql-の-in-句で利用する場合)

1. アクションの追加画面または編集画面から **処理の設定** 画面に移動します。
1. **データソースの選択** から **MySQL** のデータソースを選択します。
1. パラメーターを追加し種類を **配列** 、フォーマット形式を **SQL** 、展開先を **IN** に設定し、任意の要素の種類を設定します。
1. SQL文を入力しIN句で `{{ パラメーター名 }}` の形式で配列のパラメーターを利用します。

![配列パラメーターの編集](/images/action_parameter/array_raw_edit.png)

1. アクションを保存します。
1. アクションの実行画面で配列のパラメーターに値を入力して実行すると、入力した値がIN句に展開されてSQLが実行されます。

### form-data [](#form-data)

配列の各要素を、 `multipart/form-data` の同一キーのフィールドとして個別に送信します。

**form-data** は以下のデータソースでのみ利用できます。

- [HTTP API](/action/datasources/httpapi_integration/)

form-dataを選択した場合、配列の要素の種類は文字列・数値・日付のみ設定できます。

各要素を送信するときのキーの形式（ `key[]` のように `[]` をつけるかどうか）は、HTTP APIアクションのリクエストボディの設定で選択します。設定方法は [HTTP API](/action/datasources/httpapi_integration/) を参照してください。

## 最小要素数 [](#最小要素数)

入力できる最小要素数を設定できます。

## 最大要素数 [](#最大要素数)

入力できる最大要素数を設定できます。

[真偽値](/action/parameter/bool_parameter/) [タプル](/action/parameter/tuple_parameter/)
---
[アクション](/action/)

パラメーター

真偽値

# 真偽値

値を真・偽の2値で表現したいときに設定するパラメータの種類です。2つのフォーマット形式が用意されており、それに応じて実行時の引数の値が変わります。このページでは各フォーマットの利用例を示します。

## 文字列フォーマット [](#文字列フォーマット)

真の場合・偽の場合のそれぞれに対応する文字列の値を設定します。

下記の例では、ユーザーのプラン情報を使った検索で、プレミアム会員かどうかの値を真偽値として扱う例を示しています。

![文字列フォーマットの真偽値の編集](/images/action_parameter/bool_input_edit.png)

![文字列フォーマットの真偽値の利用](/images/action_parameter/bool_input_action_config.png)

アクション実行時は、真偽値のパラメータはチェックボックス形式で表示され、チェックされているときは真の場合の値、チェックされていないときは偽の場合の値が入力されます。

![文字列フォーマットの真偽値の入力](/images/action_parameter/bool_input_exec.png)

## フォーマットなし [](#フォーマットなし)

真偽値がそのまま実行時の引数として渡されます。以下のデータソースでのみ利用可能です。

- MySQL
- PostgreSQL
- JavaScript

MySQLのusersテーブルからメールアドレスが認証済みのユーザーの一覧を取得する例を示します。

![フォーマットなしの真偽値の編集](/images/action_parameter/bool_raw_input_edit.png)

![フォーマットなしの真偽値の利用](/images/action_parameter/bool_raw_input_action_config.png)

アクション実行時は、真偽値のパラメータはチェックボックス形式で表示され、チェックされているときは `true` 、チェックされていないときは `false` が入力されます。

![フォーマットなしの真偽値の入力](/images/action_parameter/bool_raw_input_exec.png)

[ファイル](/action/parameter/file_parameter/) [配列](/action/parameter/array_parameter/)
---

---
[アクション](/action/)

パラメーター

ファイル

# ファイル

ファイルアップロードする形式で値として扱う場合に設定するパラメーターの種類です。

![ファイルパラメーターの設定画面](/images/action_parameter/file.png)

ファイルパラメーターには以下の項目を設定できます。

- 入力を必須にする
- 最大ファイルサイズ
- 説明

## 入力を必須にする [](#入力を必須にする)

値の入力を必須にするかどうかを設定できます。

## 最大ファイルサイズ [](#最大ファイルサイズ)

ファイルの最大サイズを設定できます。

## 説明 [](#説明)

パラメーターの説明を設定できます。

---

ファイルパラメーターでは他のパラメーターの場合と異なり、 `{{ パラメーター名 }}` のような値の利用はできません。

例えばHTTP APIアクションのform-dataの場合は、以下のようにキーとファイルパラメーターを紐づけます。

![ファイルのリクエストへの紐付け](/images/action_parameter/file_request_setting.png)

実行画面ではファイルアップロード用のフォームが表示されます。

![ファイルのフォーム](/images/action_parameter/file_upload_form.png)

[日付](/action/parameter/date_parameter/) [真偽値](/action/parameter/bool_parameter/)
---
[アクション](/action/)

パラメーター

JSON値

# JSON値

JSONのなかで使う値を設定するパラメーターの種類です。

JSON値は、値をJSONとして有効な形にエンコードしてから送信されます。

テキスト型の値であれば、ダブルクオートを付与し、改行文字や文字列中のダブルクオートをエスケープしたうえで送信されますし、数値型の値であればダブルクオートを付与せずそのまま送信されます。

また、値を入力したくない場合に、空文字や0ではなく `null` を値として設定できます。

JSON値のパラメーターでは、置き換え方法が異なる点と `null` 値の扱い以外、他の種類のパラメーターとほぼ同様に扱うことができます。

「JSON値の種類」という選択肢のなかで、「テキスト・数値・日付」の3種類から値の種類を選択できます。

ただし、「入力必須かどうか」は項目として選べません。

これは他の種類のパラメーターと異なり、 `null` を入力可能にするのがJSON値の役割の1つであるためです。

![JSON](/images/action_parameter/json.png)

JSON値は種類に応じて以下のように置き換えられます。

| 型 | 値 |
| --- | --- |
| 文字列 | 入力値にダブルクオートを付与し、改行文字や文字列中のダブルクオートをエスケープした文字列 |
| 数値 | 入力値そのままの文字列 |
| 日付 | ダブルクオートを付与した文字列 |
| 日付(UnixTime) | 入力値そのままの文字列 |

文字列や日付（Unixtime以外）の値には、自動でダブルクオートがつき、文字列内の改行やダブルクオートもJSON仕様に従ってエスケープされます。

実際にJSON値を使用したリクエストの設定例は、以下の通りです。

![JSON](/images/action_parameter/json_request_body.png)

実行画面、ならびに実行結果は以下のようになります。

「値にnullを設定する」というトグルが表示され、ONにされた値は送信時に `null` が設定されます。

![JSON](/images/action_parameter/json_example_1.png)

![JSON](/images/action_parameter/json_example_2.png)

#### URLパラメーターによる初期値の設定 [](#urlパラメーターによる初期値の設定)

アクションの実行結果の加工スクリプトの [`linkToAction` 関数](/action/transformer_script/builtin_functions/link_to_action/) などで、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` として扱われます。

![JSON URL Param](/images/action_parameter/json_url_param.png)

[タプル](/action/parameter/tuple_parameter/) [SQL](/action/parameter/sql_parameter/)
---
[アクション](/action/)

パラメーター

マスターデータ取得設定

# マスターデータ取得設定

マスターデータ取得設定は **アクションの実行結果から動的な選択肢** を生成し、別のアクションのパラメーターの入力に使用できる機能です。

例えばデータベースに保存されているユーザーIDをパラメーターに入力する場合、ユーザーの一覧を返すアクションの結果から値がユーザーID、ラベルがユーザー名の選択肢を生成して入力できます。

## マスターデータ取得設定の設定方法 [](#マスターデータ取得設定の設定方法)

マスターデータ取得設定一覧画面からマスターデータ取得設定の追加、更新、削除ができます。

1. 右上のメニューから「設定」を選択します。
1. 左のサイドバーから「マスターデータ取得設定」を選択して、マスターデータ取得設定一覧画面に移動します。

![マスターデータ取得設定一覧画面](/images/action_parameter/master_data_fetch_setting/list.png)

### マスターデータ取得設定を追加する [](#マスターデータ取得設定を追加する)

右上の「追加」ボタンをクリックして作成画面に移動します。

マスターデータ取得設定では以下の項目を設定します。

- 名前
- 値の種類
- アクション
- アクションのパラメーター
- 変換スクリプト

マスターデータ取得設定による選択肢は設定したアクション、アクションのパラメーター、変換スクリプトを使って選択肢を使用するタイミングで動的に生成されます。

#### 名前 [](#名前)

マスターデータ取得設定の名前を入力します。

#### 値の種類 [](#値の種類)

マスターデータ取得設定を使用するアクションのパラメーターの種類に合わせて値の種類を選択します。

| 値の種類 | マスターデータ取得設定を使用できるパラメーターの種類 |
| --- | --- |
| テキスト | テキスト、JSON 値（種類が「テキスト」）、配列（要素の種類が「テキスト」）、タプル（要素の種類が「テキスト」） |
| 数値 | 数値、JSON 値（種類が「数値」）、配列（要素の種類が「数値」）、タプル（要素の種類が「数値」） |

#### アクション [](#アクション)

選択肢の取得元アクションとそのパラメーターの値を入力します。

![マスターデータ取得設定で生成した選択肢](/images/action_parameter/master_data_fetch_setting/setting_form.png)

#### 変換スクリプト [](#変換スクリプト)

アクションとパラメータの値を入力してアクションを実行すると結果が表示され、実行結果からマスターデータへの変換スクリプトが入力できるようになります。

変換スクリプトでは、JavaScriptで実行結果から `{label: string, value: string | number }` 型の配列を返す処理を入力します。

※ `value` の型は値の種類が「テキスト」の場合は `string` 、値の種類が「数値」の場合は `number` を返してください。

変換スクリプトを入力すると選択肢となる変換結果が表示されます。

![マスターデータ取得設定の変換スクリプトと変換結果](/images/action_parameter/master_data_fetch_setting/transformer_script.png)

---

すべての設定項目の入力が終わったら「保存」をクリックします。

### マスターデータ取得設定を使用する [](#マスターデータ取得設定を使用する)

アクション設定画面の「処理の設定」でパラメーターにマスターデータ取得設定を使用できます。

1. メニューから「アクション」を選択します。
1. 「アクションの追加」またはアクション一覧から編集するアクションを選択して、アクション設定画面に移動します。
1. 「処理の設定」のマスターデータ取得設定を使用するパラメーターの詳細設定画面に移動します。
1. マスターデータ取得設定が使用できる「種類」を選択します。
1. 「複数の選択肢を用意する」を選択します。
1. 「選択肢にマスターデータ取得設定を使う」を選択します。
1. 「マスターデータ取得設定」を選択します。
1. 保存します。

![パラメータ編集画面でマスターデータ取得設定を使用する](/images/action_parameter/master_data_fetch_setting/parameter_edit.png)

アクション実行画面に移動すると、マスターデータ取得設定を使用したパラメーターの入力項目はセレクトボックスになり、クリックするとマスターデータ取得設定の選択肢が表示されます。

※選択肢はアクション実行画面を開いたタイミングで設定されたマスターデータ取得アクションを実行し生成されます。そのため、設定時とアクション実行結果が異なると、場合によっては設定時の変換結果と選択肢の内容に差異が生じます。

![マスターデータ取得設定で生成した選択肢](/images/action_parameter/master_data_fetch_setting/exec_action_form.png)

### マスターデータ取得設定を更新する [](#マスターデータ取得設定を更新する)

マスターデータ取得設定一覧から更新したいマスターデータ取得設定をクリックすると、更新画面に移動できます。

マスターデータ取得設定の追加時と同様に設定項目を編集して「保存」をクリックします。

### マスターデータ取得設定を削除する [](#マスターデータ取得設定を削除する)

マスターデータ取得設定一覧から削除するマスターデータ取得設定にカーソルをホバーし、右端に表示されるボタンをクリックして「削除する」をクリックします。

![マスターデータ取得設定の削除](/images/action_parameter/master_data_fetch_setting/delete.png)

[複数の選択肢](/action/parameter/select_parameter/) [事前定義パラメーター](/action/parameter/predefined_parameter/)
---
[アクション](/action/)

パラメーター

数値

# 数値

数値で値を扱う場合に設定するパラメーターの種類です。

![数値パラメーターの設定画面](/images/action_parameter/number.png)

数値パラメーターには以下の項目を設定できます。

- 最小値
- 最大値
- 入力を必須にする
- 複数の選択肢を用意する
- 初期値
- 説明

## 最小値 [](#最小値)

入力できる値の最小値を設定できます。

## 最大値 [](#最大値)

入力できる値の最大値を設定できます。

## 入力を必須にする [](#入力を必須にする)

値の入力を必須にするかどうかを設定できます。

## 複数の選択肢を用意する [](#複数の選択肢を用意する)

値を入力する際の選択肢を設定できます。

詳細は [複数の選択肢](/action/parameter/select_parameter/) をご参照ください。

## 初期値 [](#初期値)

パラメーターの値の初期値を設定できます。

## 説明 [](#説明)

パラメーターの説明を設定できます。

[テキスト](/action/parameter/text_parameter/) [日付](/action/parameter/date_parameter/)
---
[アクション](/action/)

パラメーター

事前定義パラメーター

# 事前定義パラメーター

事前定義パラメーターは、ログイン情報や [変数・シークレット](/action/parameter/vars_secrets/) などの各アクションで共通して使用できるパラメーターです。

通常のパラメーターと同様に、HTTP APIのヘッダーの値などに `{{ currentUser.email }}` や `{{ secrets.API_TOKEN }}` と設定することで参照できます。

![事前定義パラメータの設定](/images/predefined_parameter/completion_items.png)

## 事前定義パラメーターの一覧 [](#事前定義パラメーターの一覧)

| パラメータ名 | 設定される値 |
| --- | --- |
| `currentUser.email` | アクションを実行した（ [ジョブ](/action/jobs/) の場合はジョブを作成した）ユーザーのメールアドレス |
| `currentUser.id` | アクションを実行した（ [ジョブ](/action/jobs/) の場合はジョブを作成した）ユーザーのID |
| `currentUser.name` | アクションを実行した（ [ジョブ](/action/jobs/) の場合はジョブを作成した）ユーザーの名前 |
| `reviewRequest.url` | レビュー依頼の詳細画面のURL。レビュー承認後に実行した場合に設定されます。（現在、レビュー承認後にジョブで実行した場合には設定されませんが今後対応予定です） |
| `job.url` | ジョブの詳細画面のURL。ジョブとして実行した場合に設定されます。 |
| `project.name` | アクションの実行に使用したプロジェクトの名前 |
| `environment.id` | アクションの実行に使用した環境のID |
| `environment.name` | アクションの実行に使用した環境の名前 |
| `action.name` | 実行したアクションの名前 |
| `action.url` | 実行したアクションの実行画面のURL |
| `authToken` | アクション実行時に発行されるトークン。詳細は [JWT認証](/action/jwt_authentication/) をご覧ください。 |
| `vars.変数名` | 設定した変数の値 |
| `secrets.シークレット名` | 設定したシークレットの値 |

変数・シークレットの設定方法は [こちら](/action/parameter/vars_secrets/) をご覧ください。

[マスターデータ取得設定](/action/parameter/master_data_fetch_setting/) [変数・シークレット](/action/parameter/vars_secrets/)
---
[アクション](/action/)

パラメーター

複数の選択肢

# 複数の選択肢

**テキスト** と **数値** のパラメーターには選択肢を設定できます。

![アクションパラメータ編集画面での選択肢の設定](/images/action_parameter/multi_select.png)

選択肢には送信される値とラベル（任意）を設定できます。

ラベルを設定すると実行画面のセレクトボックスの選択肢にはラベルが、ラベルが未設定の場合は値が表示されます。

![セレクトボックスに表示される選択肢](/images/action_parameter/multi_select_form.png)

またマスターデータ取得設定を使用すると、データベースに保存されている値やAPIのレスポンスの値から選択肢を生成できます。

設定方法は [こちら](/action/parameter/master_data_fetch_setting/) をご覧ください。

[SQL](/action/parameter/sql_parameter/) [マスターデータ取得設定](/action/parameter/master_data_fetch_setting/)
---
[アクション](/action/)

パラメーター

SQL

# SQL

SQL系のアクションを実行するときに設定するパラメーターの種類です。

通常のパラメーターは、SQLアクションへの埋め込みで、自動的にプレースホルダーへ置換され安全に実行されます。

SQL形式のパラメーターは、アクション実行時にSQLの実行内容そのものを変更できます。下記の項目を設定できます。

- 入力必須かどうか
- 初期値
- 選択形式にする場合の選択候補

![SQL](/images/action_parameter/sql.png)

例えば、下記のようなMySQLアクションが存在するとします。

![SQL](/images/action_parameter/sql_example_1.png)

この時、下記のようにパラメーターを設定すると、実行されるSQLは次の内容になります。

![SQL](/images/action_parameter/sql_example_2.png)

![SQL](/images/action_parameter/sql_example_3.png)

SELECT文のテーブル名に相当する箇所が、SQL形式のパラメーターによって置き換えられています。

[JSON値](/action/parameter/json_parameter/) [複数の選択肢](/action/parameter/select_parameter/)
---
[アクション](/action/)

パラメーター

テキスト

# テキスト

テキストは文字列を扱う場合に設定するパラメーターの種類です。

![テキストパラメーターの設定画面](/images/action_parameter/text.png)

テキストパラメーターには以下の項目を設定できます。

- 複数行入力する
- 最小文字数
- 最大文字数
- 正規表現
- 正規表現のエラーメッセージ
- 入力を必須にする
- 複数の選択肢を用意する
- 初期値
- 説明

## 複数行入力する [](#複数行入力する)

複数行の文字列を入力できるかどうかを設定できます。

有効にすると「改行文字を指定する」を設定できます。

### 改行文字を指定する [](#改行文字を指定する)

改行文字を指定するかどうかを設定できます。

有効にすると「改行文字」を設定できます。

#### 改行文字 [](#改行文字)

改行文字を任意の文字に指定できます。
（指定しない場合の改行文字はLF（ `\n` ）です）

![テキストパラメーターの複数行テキストの設定画面](/images/action_parameter/text_multiline.png)

例えば、改行文字を `\r\n` と設定しアクションの実行画面で以下のパラメータの値を入力します。

```
こんにちは
さようなら
```

そしてアクションを実行すると、以下の値がパラメータの値として送信されます。

```
こんにちは\r\nさようなら
```

複数行入力が有効なテキストパラメーターに入力された値をJSON文字列内に埋め込むとき、改行文字を明示的に指定しないとJSONとして不正な形式になります。
この場合は、改行文字を `\\n`
に設定するか、 [JSON値](/action/parameter/json_parameter/) （種類：テキスト）を利用してください。

## 最小文字数 [](#最小文字数)

入力できる最小文字数を設定できます。

## 最大文字数 [](#最大文字数)

入力できる最大文字数を設定できます。

## 正規表現 [](#正規表現)

入力された値をバリデーションする正規表現を設定できます。

## 正規表現のエラーメッセージ [](#正規表現のエラーメッセージ)

入力された値が正規表現と一致しない場合に表示するエラーメッセージを設定できます。

## 入力を必須にする [](#入力を必須にする)

値の入力を必須にするかどうかを設定できます。

## 複数の選択肢を用意する [](#複数の選択肢を用意する)

値を入力する際の選択肢を設定できます。

詳細は [複数の選択肢](/action/parameter/select_parameter/) をご参照ください。

## 初期値 [](#初期値)

パラメーターの値の初期値を設定できます。

## 説明 [](#説明)

パラメーターの説明を設定できます。

[パラメーターとは](/action/parameter/action_parameter/) [数値](/action/parameter/number_parameter/)
---
[アクション](/action/)

パラメーター

タプル

# タプル

タプルは異なる種類の複数の値をまとめて送信する場合に設定するパラメーターの種類です。

![タプルパラメーターを使ったアクションの実行](/images/action_parameter/tuple_exec.png)

タプルのパラメーターには以下の項目を設定できます。

- フォーマット形式
- タプルの要素
- 初期値

![タプルパラメーターの編集](/images/action_parameter/tuple_edit.png)

## タプルの要素 [](#タプルの要素)

タプルの要素には以下の項目を設定できます。

- ラベル
- 要素の種類

### ラベル [](#ラベル)

アクションの実行フォームに表示されるラベルを設定できます。

### 要素の種類 [](#要素の種類)

要素の種類は以下から選択できます。

- [文字列](/action/parameter/text_parameter/)
- [数値](/action/parameter/number_parameter/)
- [日付](/action/parameter/date_parameter/)
- [真偽値](/action/parameter/bool_parameter/)

さらに要素の種類ごとに **入力必須かどうか** や **正規表現による入力値チェック** などを設定できます。

要素の種類ごとに設定できる項目は、各種パラメーターのドキュメントをご参照ください。

## フォーマット形式 [](#フォーマット形式)

タプルを送信する際のフォーマット形式を以下から選択できます。

- フォーマットなし
- JSON
- 区切り文字

### フォーマットなし [](#フォーマットなし)

タプルの形式のまま送信されます。

**フォーマットなし** は以下のデータソースでのみ利用できます。

- [JavaScript](/action/datasources/javascript_action/)

### JSON [](#json)

配列をJSON形式に変換した文字列が送信されます。

（例）要素の種類が文字列、数値、日付（unixtimeとして利用する）、日付（unixtimeとして利用しない）、真偽値（ `有効` は設定した真の値）の場合に送信される文字列の場合。

```
["a",1,"1672498800","2023-01-01","有効"]
```

| 要素の種類 | 説明 |
| --- | --- |
| テキスト |  |
| 数値 | 各要素は二重引用符なしで送信されます |
| 日付（unixtime として利用する場合） |  |
| 日付（unixtime として利用しない場合） | 各要素は設定した日付の形式で送信されます |
| 真偽値 | 各要素は設定した真、偽の値が送信されます |

### 区切り文字 [](#区切り文字)

- 区切り文字
- 引用符

を設定でき、設定内容に基づいてタプルを変換した文字列が送信されます。

（例）要素の種類が文字列、数値、日付（unixtimeとして利用する）、日付（unixtimeとして利用しない）、真偽値（ `有効` は設定した真の値）で、引用符に `"` 、区切り文字に `,` を設定した場合にの場合に送信される文字列の場合。

```
"a","1","1672498800","2023-01-01","有効"
```

[配列](/action/parameter/array_parameter/) [JSON値](/action/parameter/json_parameter/)
---
[アクション](/action/)

パラメーター

変数・シークレット

# 変数・シークレット

変数・シークレットは、環境ごとに値を保存して、複数のアクションの設定で使い回せる機能です。

変数・シークレットは、名前に `vars` および `secrets` と言う接頭辞をつける形で、アクションのパラメーター同様、アクションの設定内で使用できます。また、HTTP APIの共通ヘッダー、gRPCの共通メタデータでも同様の形式で使用できます。

例えば、 `API_TOKEN` シークレットを登録すると、HTTP APIのヘッダーの値などに `{{ secrets.API_TOKEN }}` と設定することで参照できます。

![変数・シークレット設定画面](/images/action_vars_secrets/vars_secrets_list.png)

また、登録した変数は、アクションの加工スクリプトおよびビューのコード内で、BaseMachinaContextを経由して値を取得できます。
シークレットはアクション実行時のみ使用可能で、加工スクリプトおよびビューのコード内では使用できません。
詳細については、アクションの [結果の加工に使える値](/action/transformer_script/action_transform_parameters/#basemachinacontext%E3%83%99%E3%83%BC%E3%82%B9%E3%83%9E%E3%82%AD%E3%83%8A%E3%81%AE%E3%81%94%E5%88%A9%E7%94%A8%E7%8A%B6%E6%B3%81%E8%A8%AD%E5%AE%9A%E6%83%85%E5%A0%B1%E3%81%AB%E9%96%A2%E3%81%99%E3%82%8B%E5%80%A4) と、ビューの [useBaseMachinaContext](/view/function/view_use_basemachina_context/) のドキュメントを参照ください。

## 変数とシークレットの違いについて [](#変数とシークレットの違いについて)

変数とシークレットの機能上の違いは、値の暗号化の有無です。

変数は、値が平文で保存され、その内容を変数・シークレット設定画面上で確認できます。

シークレットは、値が暗号化したうえで保存され、アクションの実行時のみに復号して使用されます。保存した後は、内容を変数・シークレット設定画面上で確認できません。

## 変数・シークレットの作成方法 [](#変数シークレットの作成方法)

変数・シークレットの作成は、プロジェクト設定画面の "変数・シークレット" 設定からできます。

変数・シークレットの保存先は、現在選択中の環境となります。アクションの実行時に環境別の値を使用するには、それぞれの環境に同名の変数・シークレットを作成してください。

### 変数を作成する [](#変数を作成する)

変数・シークレット設定画面から変数の追加ボタンをクリックします。

![変数・シークレット設定画面の変数作成画面への導線](/images/action_vars_secrets/create_var.png)

変数の名前と、値を入力して保存します。保存すると、名前に含まれる半角英字は自動的に大文字に変換されます。

![変数作成画面](/images/action_vars_secrets/create_var_page.png)

### シークレットを作成する [](#シークレットを作成する)

変数・シークレット設定画面からシークレットの追加ボタンをクリックします。

![変数・シークレット設定画面のシークレット作成画面への導線](/images/action_vars_secrets/create_secret.png)

シークレットの名前と、値を入力して保存します。変数同様、保存すると、名前に含まれる半角英字は自動的に大文字に変換されます。

![シークレット作成画面](/images/action_vars_secrets/create_secret_page.png)

## 変数・シークレットの編集、削除 [](#変数シークレットの編集削除)

変数・シークレットの編集、削除は、設定画面に表示される一覧の行の右端の3点リーダからできます。

![変数・シークレットの編集、削除](/images/action_vars_secrets/var_secret_edit_delete.png)

## 変数・シークレットの使用方法 [](#変数シークレットの使用方法)

変数・シークレットは、アクションの設定内でパラメーターを使用できる箇所および、HTTP APIの共通ヘッダー、gRPCの共通メタデータの設定内で、パラメーターと同様の形式で使用できます。

書式は以下のとおりです。

- 変数： `{{ vars.変数名 }}`
- シークレット： `{{ secrets.シークレット名 }}`

上記の `変数名` 、 `シークレット名` の部分を実際の名前に置き換えて使用してください。

指定された変数、シークレットが現在使用中の環境に存在しなかった場合、アクションの実行に失敗します。

### HTTP APIアクションの例 [](#http-apiアクションの例)

変数として `USER_EMAIL` を、 シークレットとして `USER_PASSWORD` を登録したとき、これらはHTTP APIアクションの設定で下記のように使用できます。

- リクエストタイプ： `form-data`
- フォームデータ
  - キー: `email`, 値： `{{ vars.USER_EMAIL }}`
  - キー: `password`, 値： `{{ secrets.USER_PASSWORD }}`

form-data以外で使用したい場合も、パラメーターを使用できる箇所で同様の設定が可能です。

![フォームデータへの変数・シークレットの設定](/images/action_vars_secrets/http_api_example.png)

## 変数・シークレットを環境ごとに切り替える [](#変数シークレットを環境ごとに切り替える)

アクション実行時に、変数・シークレットを別環境のものに切り替えたいときは、通常通りメニューバーから使用したい環境を選択してください。

![環境切り替えのUI](/images/action_vars_secrets/switch_environment.png)

## 補足 [](#補足)

### 監査ログについて [](#監査ログについて)

変数・シークレットは、アクションのパラメーターに設定された引数とは異なり、 `監査ログのストリーミング` 機能による記録の対象となりません。

[事前定義パラメーター](/action/parameter/predefined_parameter/) [結果を加工する](/action/transformer_script/action_transform/)
---
[アクション](/action/)

レビュー設定

# レビュー設定

レビュー設定はアクションの実行前に他のユーザーによるレビューを必須にできる機能です。

承認に必要な条件は柔軟に設定でき、例えば以下のような条件を設定できます。

- 特定のユーザーからの承認を必須にする
- 特定のグループのユーザー最低○人からの承認を必須にする

こうした条件は承認パターンとして複数設定でき、そのうちどれか1つのパターンを満たせば承認されます。

またレビューを有効化するかどうかや、承認条件は環境ごとに別の設定が可能で、例えば本番環境ではレビューを有効、開発環境ではレビューを無効といった設定ができます。

## レビュー設定の作成 [](#レビュー設定の作成)

レビュー設定はプロジェクト設定のレビュー設定から作成できます。

1. 右上のメニューから「設定」を選択します。
1. 左のサイドバーから「レビュー設定」を選択してレビュー設定の一覧画面に移動します。
1. 「追加」ボタンを選択して、レビュー設定の作成画面に移動します。

![レビュー設定の設定画面](/images/review_setting/setting_form.png)

レビュー設定では以下の項目を設定します。

- 名前
- 各環境の設定
  - レビューを有効化する
  - 承認条件
  - 自身のレビュー依頼を承認可能にする
  - 自身のレビュー依頼を自動承認する
  - 承認者もアクションを実行可能にする
  - 承認後の自動実行
  - レビュー依頼のデフォルト設定

### 名前 [](#名前)

レビュー設定の名前です。

---

以下は各環境ごとに設定する項目です。

### レビューを有効化する [](#レビューを有効化する)

その環境でレビューを有効化するかどうかを設定します。

有効化すると以下の項目が設定できるようになります。

#### 承認条件 [](#承認条件)

承認に必要なユーザー・グループは、承認パターンとして設定します。承認パターンは「承認パターンを追加（または）」ボタンから複数設定でき、そのうちどれか1つのパターンを満たすと承認されます。1つのパターンに複数の承認者を設定した場合は、そのパターン内の承認者全員の承認が必要です。

グループを承認者に設定する場合は、そのグループのうち最低何人の承認が必要なのかも設定できます。

承認パターンは最低1つ必要で、各パターンには承認者を1人以上設定する必要があります。

#### 自身のレビュー依頼を承認可能にする [](#自身のレビュー依頼を承認可能にする)

レビュー依頼者が自分自身のレビュー依頼を承認できるかどうかを設定します。

「自身のレビュー依頼を承認可能にする」が無効の場合、レビュー依頼者は自分のレビュー依頼を承認できません。承認者として設定された他のユーザーのみが承認できます。

#### 自身のレビュー依頼を自動承認する [](#自身のレビュー依頼を自動承認する)

レビュー依頼作成時、自分自身が承認者の場合に自動で承認するかどうかを設定します。

この設定は「自身のレビュー依頼を承認可能にする」が有効な場合にのみ設定できます。

#### 承認者もアクションを実行可能にする [](#承認者もアクションを実行可能にする)

レビュー依頼の承認後に、承認者もアクションを実行可能にするかどうかを設定します。

「承認者もアクションを実行可能にする」が無効な場合、アクションを実行できるのはレビュー依頼を作成したユーザーのみです。

「承認者もアクションを実行可能にする」が有効な場合でも、承認者がアクションの実行権限を持っていない場合はアクションを実行できません。

#### 承認後の自動実行 [](#承認後の自動実行)

レビュー依頼が承認されたとき、アクションを自動で実行するかどうかを設定します。

![レビュー設定フォームの承認後の自動実行](/images/review/auto_execute_on_approval_setting.png)

| 選択肢 | 挙動 |
| --- | --- |
| 必ず手動で実行 | 承認されてもアクションは自動で実行されません。 [承認後の実行](/action/review/#%E6%89%BF%E8%AA%8D%E5%BE%8C%E3%81%AE%E5%AE%9F%E8%A1%8C) の記載に従って手動で実行します |
| レビュー依頼ごとに選択（デフォルトでOFF） | レビュー依頼の作成者が、レビュー依頼フォームの「承認後に自動実行する」で自動実行するかどうかを依頼ごとに選択できます。初期値は無効です |
| レビュー依頼ごとに選択（デフォルトでON） | レビュー依頼の作成者が、レビュー依頼フォームの「承認後に自動実行する」で自動実行するかどうかを依頼ごとに選択できます。初期値は有効です |
| 必ず承認と同時に実行する | すべてのレビュー依頼で、承認の完了と同時にアクションが自動で実行されます。レビュー依頼の作成者は自動実行するかどうかを変更できません |

「レビュー依頼ごとに選択」を設定した場合は、レビュー依頼フォームに「承認後に自動実行する」が表示されます。「必ず手動で実行」を設定した場合、レビュー依頼フォームに「承認後に自動実行する」は表示されません。

![レビュー依頼フォームの承認後に自動実行するトグル](/images/review/auto_execute_on_approval_toggle.png)

「承認後の自動実行」の設定は、レビュー依頼の作成時点の内容がレビュー依頼ごとに適用されます。設定を変更しても、作成済みのレビュー依頼には反映されません。

自動実行では、レビュー依頼の作成者の権限でアクションが実行されます。作成者のユーザーが無効化されているなど、作成者がアクションを実行できない状態になっている場合、アクションは自動で実行されません。この場合、レビュー依頼は承認された状態のまま維持され、 [承認後の実行](/action/review/#%E6%89%BF%E8%AA%8D%E5%BE%8C%E3%81%AE%E5%AE%9F%E8%A1%8C) の記載に従って手動で実行できます。

自動実行されたアクションは [ジョブ](/action/jobs/) として非同期に実行されます。実行結果はジョブの一覧、またはジョブの詳細画面から確認できます。

組み込み関数 `createReviewRequest` （ [ビュー](/view/code_editor/function/view_create_review_request/) ・ [JavaScriptアクション](/action/datasources/javascript_action/builtin_functions/create_review_request/) ）や [公開API](/public_api/) で作成するレビュー依頼でも、自動実行するかどうかを依頼ごとに指定できます。指定には `options.autoExecuteOnApproval` （公開APIでは `auto_execute_on_approval` ）を使用します。指定しない場合は「承認後の自動実行」の設定に従います。

#### レビュー依頼のデフォルト設定 [](#レビュー依頼のデフォルト設定)

レビュー依頼を作成する際に、入力フォームに自動で入力されるデフォルト値を設定できます。

##### レビュー依頼の説明 [](#レビュー依頼の説明)

レビュー依頼作成時に「説明」欄に自動入力される文章を設定します。

##### レビュー期限を設定しない [](#レビュー期限を設定しない)

有効にすると、レビュー依頼作成時に「有効期限を設定しない」がデフォルトで有効になります。

レビュー依頼作成時にこの設定を変更して、有効期限を設定できます。

## アクションのレビュー設定 [](#アクションのレビュー設定)

アクションの編集画面の「レビュー設定」のタブで、アクションにレビュー設定を紐づけられます。

レビューが有効化されている環境で、アクションの実行権限を持ったユーザーがアクション実行画面に移動すると、アクションの実行フォームの代わりにレビュー依頼フォームが表示されます。

レビューが有効化されている環境では、レビューが承認されてからでなければアクションを実行できません。

![レビュー依頼のフォーム](/images/review/review_request_form.png)

なお、実行権限を持たないユーザーはレビューを依頼できません。

実行権限の設定とレビューの設定の対応関係は、以下のとおりです。

|  | 誰でも実行できる | 実行権限を設定する |
| --- | --- | --- |
| レビュー無効 | すべての人が即実行できる | 実行権限のある人は即実行できる。実行権限のない人は何もできない |
| レビュー有効 | 誰でもレビュー依頼ができる | 実行権限のある人はレビュー依頼ができる。実行権限のない人は何もできない |

## 確認と実行 [](#確認と実行)

自分に依頼されたレビュー、または自分が他の人に依頼したレビューの履歴は専用の画面で確認できます。

画面上部のメニューからレビュー依頼のアイコンをクリックして、レビューの一覧画面に移動してください。

レビュー依頼ごとの詳細画面に行くとレビューを出した人や確認状況を見ることができます。

![レビュー依頼のアイコン](/images/review/nav_icon.png)

詳細画面では依頼時点で入力されたパラメーターの値の情報などを確認したうえで、承認・却下、そして承認後の実行などができます。

![レビュー依頼の詳細画面](/images/review/review_history.png)

### 承認・却下 [](#承認却下)

レビュー依頼をされたユーザーは、画面右上のボタンから、コメントをつけて承認または却下できます。

また承認済みのレビュー依頼の却下も可能です。

レビューを依頼したユーザーは、それらのコメントを後から確認することで、なぜレビューが承認・却下されたのかを知ることができます。

![レビュー依頼の承認と却下](/images/review/approval_form.png)

### 承認後の実行 [](#承認後の実行)

レビュー依頼が承認されると「承認者もアクションを実行可能にする」が有効な場合はレビュー依頼の作成者と承認者が、無効な場合はレビュー依頼の作成者のみが、アクションを実行できます。

承認済みのレビュー依頼は、 [有効期限](/action/review/#%E6%9C%89%E5%8A%B9%E6%9C%9F%E9%99%90) をすぎた後もアクションを実行できます。

「承認後に自動実行する」が有効なレビュー依頼では、承認が完了すると自動でアクションが実行されます。詳しくは [承認後の自動実行](/action/review/#%E6%89%BF%E8%AA%8D%E5%BE%8C%E3%81%AE%E8%87%AA%E5%8B%95%E5%AE%9F%E8%A1%8C) をご覧ください。

![レビュー依頼の承認後の実行](/images/review/review_status.png)

### 取り下げ [](#取り下げ)

レビューを依頼したユーザーは、画面右上の「取り下げる」ボタンから、レビュー依頼の取り下げができます。

取り下げたレビュー依頼は、承認・却下のいずれもできなくなります。

![レビュー依頼の取り下げ](/images/review/self_reject.png)

### 有効期限 [](#有効期限)

レビューを依頼する際に、有効期限を設定できます。有効期限は承認の締め切りです。

**承認されないまま有効期限をすぎたレビュー依頼は、保存されていたパラメーターの値の情報が破棄され、承認・却下のいずれもできなくなります** 。

有効期限をすぎる前に承認されたレビュー依頼は、有効期限をすぎた後もアクションの実行や却下ができます。

[JWT認証](/action/jwt_authentication/) [通知設定](/action/notification/)
---
[アクション](/action/)

予約実行

# 予約実行

予約実行は、アクションの実行を特定の日時に予約できる機能です。

夜間や休日にアクションを実行したい場合や、指定した日時に必ず実行したいアクションを事前に予約したい場合などでご活用いただけます。

## 予約実行する [](#予約実行する)

1. アクションの詳細ページで「実行を予約する」を選択します。

![「実行を予約する」の選択](/images/action_schedule_jobs/select_button.png)

1. 予約日時を設定します。現在時刻から最大で1か月先までの日時を設定できます。

![予約日時の入力](/images/action_schedule_jobs/schedule_time_field.png)

1. 「実行を予約する」をクリックして予約完了です。

予約を完了するとジョブ詳細ページに移動して、予約したジョブの詳細を確認できます。

※予約したアクションは、指定した日時に [ジョブ](/action/jobs/) で実行されます。

## 予約した結果を確認する [](#予約した結果を確認する)

1. アクションの一覧画面から右上の「ジョブ一覧」ボタンをクリックして、ジョブ一覧画面に移動します。
1. ジョブ一覧画面から予約したジョブをクリックして、ジョブ詳細ページに移動して予約実行した結果を確認できます。

![予約日時の入力](/images/action_schedule_jobs/result.png)

ジョブの詳細ページでは、以下の情報を確認できます。

- ジョブのステータス
- 予約時に設定したアクションのパラメーターの値
- アクションの実行結果

ジョブのステータスは以下の通りです。

| ステータス | 説明 |
| --- | --- |
| 待機中です | ジョブがまだ実行されていません。キャンセルができます。 |
| 実行中です | ジョブが実行中です。キャンセルができます。 |
| 正常に終了しました | ジョブの実行が完了し、実行結果を確認できます。 |
| キャンセルされました | お客さまによるキャンセルとシステムのタイムアウトによるキャンセルの2つが存在します。 |
| 実行時にエラーが発生しました | アクションの実行でエラーが発生しています。何度試しても解消しない場合は大変ご不便をおかけいたしますが、お問い合わせください。 |

## 予約したアクションの実行時に通知する [](#予約したアクションの実行時に通知する)

プロジェクトの設定でアクション実行時の通知設定をしている場合は、予約したアクションの実行時に通知が届きます。

通知は以下の3種類です。

- 実行開始時
- 実行完了時
- 実行エラー時

アクション実行時の通知設定の方法は、 [通知設定](/admin/action/notification/) をご覧ください。

[ジョブ](/action/jobs/) [定期実行](/action/cron_jobs/)
---
[アクション](/action/)

結果表示のカスタマイズ

結果を加工する

# 結果を加工する

アクションの実行結果は加工して表示できます。アクションを実行後に表示される「結果表示のカスタマイズ」をクリックして開始します。

![結果表示のカスタマイズ](/images/action_transform/start.png)

クリックすると画面下に結果の加工スクリプト（JavaScript）を編集するエディタが表示されます。

1. 左の欄には今まで保存したスクリプトの一覧が表示されます。名前がついてない場合はデフォルトで割り当てられたIDが名前になります。
1. 中央ではスクリプトの名前とそのコードを編集するエディタが表示されます。
1. 右の欄では実行して得られた内容をスクリプトのオブジェクト構造として表示します。コードを編集するときに活用いただけます。

![スクリプトの編集](/images/action_transform/edit_script.png)

スクリプトは各項目を編集して少し待機すると自動で保存され、実行済みの結果に反映されます。次の画像では表示されているラベルを日本語へ変換するスクリプトを記述し反映しています。

![スクリプトの保存](/images/action_transform/save_script.png)

次回から同じアクションを実行し、結果の表示に同じスクリプトを適用する場合は「常にこのスクリプトを加工に使用する」を有効にします。有効になった証として左の欄に緑色でチェックが入ります。

![スクリプトをデフォルトで利用する](/images/action_transform/save_default.png)

実行結果内にある `null` を表示したい場合は、「nullを表示する」を有効にします。新規作成したスクリプトではデフォルトで有効になっています。
また、「結果表示のカスタマイズ」を開いていない場合は常に有効になっています。

![nullを表示する](/images/action_transform/display_null.png)

「結果表示のカスタマイズ」の画面は右上のバツボタンをクリックするかEscキーを入力することで閉じることができます。

[変数・シークレット](/action/parameter/vars_secrets/) [結果の加工に使える値](/action/transformer_script/action_transform_parameters/)
---
[アクション](/action/)

結果表示のカスタマイズ

結果の加工に使える値

# 結果の加工に使える値

アクションの実行結果は加工の加工に使える値は以下の通りです。

## results（アクションの実行結果） [](#resultsアクションの実行結果)

`results` にはアクションの実行結果が格納されています。

![resultsの取得結果](/images/action_transform_parameters/results_response.png)

例えば単一のユーザー情報を取得するアクションがあったとします。アクション実行成功時に、そのレスポンスの中に入っている `id` を取得したい場合は、 `results[0].success.id` と記述します。

![resultsの使用例](/images/action_transform_parameters/results_usage.png)

ご覧の通り、この値は配列形式になっています。これは通常のMySQLやPostgreSQLなど、一部のデータソースの種類に紐づくアクションは実行結果が複数個になる可能性があるためです。

また、 `success` と記載されているとおり、実行成功時にのみ値が格納されます。実行失敗時には `failure` に値（例：エラー文言）が格納されます。

## basemachinaContext（ベースマキナのご利用状況・設定情報に関する値） [](#basemachinacontextベースマキナのご利用状況設定情報に関する値)

`basemachinaContext` にはベースマキナのご利用状況・設定情報に関する値が格納されています。

| プロパティ名 | 型 | 説明 | 例 |
| --- | --- | --- | --- |
| `user` | `object` | 現在のユーザーに関する情報を含むオブジェクト。 `id`, `email`, `name`, `groups`, `isTenantAdmin` のプロパティを含みます。 | 詳細は後述します。 |
| `environment` | `object` | 現在の環境に関する情報を含むオブジェクト。 `id`, `name` のプロパティを含みます。 | `{ id: '1', name: 'Environment Name' }` |
| `environmentVariables` | `object` | キーが環境変数の名前、値が環境変数の値のオブジェクト。 | `{ USER_NAME: 'example-user', PROJECT: 'example-project' }` |
| `groups` | `Array` | 現在のプロジェクトに存在するグループに関する情報を含むオブジェクトの配列。各オブジェクトは `id`, `name` のプロパティを含みます。 | `[{ id: '1', name: 'Group1' }, { id: '2', name: 'Group2' }]` |

なお、 `user` プロパティのオブジェクトの各プロパティは以下の通りです。

| プロパティ名 | 型 | 説明 | 例 |
| --- | --- | --- | --- |
| `id` | `string` | ユーザーのID | `'1'` |
| `email` | `string` | ユーザーのメールアドレス | `'user@example.com'` |
| `name` | `string` | ユーザー名 | `'User Name'` |
| `groups` | `Array` | ユーザーが所属するグループに関する情報を含むオブジェクトの配列。 | `[{ id: '1', name: 'Group1' }]` |
| `isTenantAdmin` | `boolean` | ユーザーが企業アカウント管理者であれば `true` です。 | `true` |

## experimental（試験的に導入されている値） [](#experimental試験的に導入されている値)

`experimental` の値は、アクションの実行結果を加工するために有用な一方で、今後、破壊的変更がありえます。

具体的な内容は以下のとおりです。

### args（アクション実行時に入力した引数の値） [](#argsアクション実行時に入力した引数の値)

`args` にはアクション実行時に入力した引数の値が格納されています。アクション実行のフォームで入力した値が、そのまま `args` に格納されます。

![argsの入力情報](/images/action_transform_parameters/args_input.png)

![argsの取得結果](/images/action_transform_parameters/args_response.png)

[結果を加工する](/action/transformer_script/action_transform/) [ページネーション](/action/transformer_script/pagination/)
---
[アクション](/action/)

結果表示のカスタマイズ

組み込み関数

image

# image

`image` 関数は、画像の表示方法を指定できる関数です。
画像サイズの指定および、拡張子のないURL（自動的に画像表示されないもの）に対する画像表示に使えます。

## 基本的な使い方 [](#基本的な使い方)

以下は、アクションの実行結果から画像のURLを取得し、表示サイズを設定して表示する例です。

### 使用例 [](#使用例)

```
const src = results[0].success.imageURL;
return {
  widthのみ指定: image({ src, width: 200 }),
  heightのみ指定: image({ src, height: 100 }),
  両方指定: image({ src, width: 200, height: 100 }),
};
```

### 表示結果 [](#表示結果)

![image関数の使用例の表示結果](/images/action_transform/builtin_functions/image.png)

---

`width` と `height` のどちらかのみを指定した場合は、画像の縦横比率を維持したまま表示されます。

`width` ・ `height` をどちらも指定しない場合、画像は画面幅に応じて自動的に拡大縮小されます。サイズを固定したい場合は `width` または `height` にピクセル値を指定してください。

## 詳細なインターフェース [](#詳細なインターフェース)

```
function image(params: {
  src: string;
  width?: string | number;
  height?: string | number;
});
```

### 引数 [](#引数)

#### `params.src: string` [](#paramssrc-string)

- 画像のURLを指定します。

#### `params.width?: string | number` [](#paramswidth-string--number)

- 画像の幅を指定します。数値の場合はピクセル単位で指定します。
- 例
  - `"100px"`
  - `100`

#### `params.height?: string | number` [](#paramsheight-string--number)

- 画像の高さを指定します。数値の場合はピクセル単位で指定します。
- 例
  - `"100px"`
  - `100`

[linkToURL](/action/transformer_script/builtin_functions/link_to_url/) [実行権限](/action/action_permission/)
---
[アクション](/action/)

結果表示のカスタマイズ

組み込み関数

linkToAction

# linkToAction

`linkToAction` 関数は、別のアクションの実行画面へ移動できるリンクを表示できる関数です。

## 基本的な使い方 [](#基本的な使い方)

ユーザーの一覧を表示するアクションの実行結果に、ユーザーの詳細を表示するアクションへ移動できるリンクを表示する例を考えます。

移動先のユーザーの詳細を表示するアクションは、以下のようなユーザーのIDをパラメーターとして受け取るアクションです。

![linkToAction関数の使用例の移動先のアクション](/images/action_transform/builtin_functions/link_to_action_target_action.png)

### 使用例 [](#使用例)

以下がユーザーの一覧を表示するアクションに設定するスクリプトです。

```
const users = results[0].success;
return [
  {
    success: users.map((user) => ({
      名前: linkToAction(
        user.name,
        // ユーザーの詳細を表示するアクションの識別子を設定
        "get-user-detail",
        // 移動時にアクションを実行するように設定
        true,
        // ユーザーの詳細を表示するアクションへ渡すパラメータの値を設定
        { userId: user.id },
      ),
      メールアドレス: user.email,
    })),
  },
];
```

### 表示結果 [](#表示結果)

![linkToAction関数の使用例の表示結果](/images/action_transform/builtin_functions/link_to_action.png)

---

表示されたリンクをクリックすると、ユーザーの詳細を表示するアクションのページに移動します。

```
// 移動時にアクションを実行するように設定
true,
```

使用例のコードの上記の部分で、第3引数の `openAndRun` に `true` を設定しているので、ページ移動時にユーザーの詳細を表示するアクションが実行され、以下のように実行結果のみが表示されます。

![linkToAction関数の使用例の移動先のアクションの実行結果](/images/action_transform/builtin_functions/link_to_action_target_action_result.png)

## 詳細なインターフェース [](#詳細なインターフェース)

```
function linkToAction(
  title: string,
  actionId: string,
  openAndRun?: boolean,
  params?: object,
);
```

### 引数 [](#引数)

#### `title: string` [](#title-string)

- リンクとして表示するテキストです

#### `actionId: string` [](#actionid-string)

- 移動先のアクションIDまたは識別子です
- 例
  - `"get-user-detail"`
  - `"u8a64fnmekufv3j2om"`
- アクションのIDまたは識別子は、アクションの実行画面の編集ボタンの下から確認できます

![アクションIDまたは識別子の確認方法](/images/link_to_action/copy_id.png)

#### `openAndRun?: boolean` [](#openandrun-boolean)

- 移動時にアクションを実行するかどうかを指定します
- デフォルト値は `false` です

#### `params?: object` [](#params-object)

- 移動先のアクションへ渡すパラメータです。キーがパラメータ名、値がパラメータに渡す値のオブジェクトです。
- 例
  - `{ userID: 1 }`
- アクションのパラメータの種類ごとに渡せる値の型は以下です（ただし、ファイル型は未対応です）

| 種類 | 型 | 説明 | 例 |
| --- | --- | --- | --- |
| テキスト | `string | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ company_name: '株式会社ベースマキナ' }` |
| 数値 | `number | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ user_id: 123 }` |
| 日付 | `Date | string | number | null | undefined` | `string` は `Date` 型に変換できる値、 `number` はUnixTimestamp (秒)を入力してください。 `null` や `undefined` の場合は未入力として扱われます。 | `{ created: '2023-01-01', updated: new Date(), deleted: 1609459200 }` |
| 真偽値 | `boolean | null | undefined` | `null` や `undefined` の場合は `false` として扱われます。 | `{ checked: true }` |
| JSON値 | `string | number | Date | null | undefined` | JSON値の種類ごとに型が異なります。 テキストなら `string | null | undefined` 、数値なら `number | null | undefined` 、日付なら `string | number | Date | null | undefined` を渡せます。 日付の場合 `string` は `Date` 型に変換できる値、 `number` はUnixTimestamp (秒)を入力してください。 `null` や `undefined` の場合は `null` として扱われます。 | `{ company_name: '株式会社ベースマキナ', user_id: 123, created: '2023-01-01', deleted: null }` |
| SQL | `string | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ query: 'SELECT * FROM users;' }` |
| システム値 | `string | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ offset: '20' }` |
| 配列 | `Array | null | undefined` | 各要素の種類の型は、各種類の型と同じです。 `null` や `undefined` の場合は空配列として扱われます。 | `{ user_ids: [10, 11, 12] }` |
| タプル | `Array` | 各要素の種類の型は、各種類の型と同じです。 | `{ id_and_name: [123, 'taro'] }` |

[ページネーション](/action/transformer_script/pagination/) [linkToView](/action/transformer_script/builtin_functions/link_to_view/)
---
[アクション](/action/)

結果表示のカスタマイズ

組み込み関数

linkToActionGroup

# linkToActionGroup

`linkToActionGroup` 関数は、別のアクショングループへ移動できるリンクを表示できる関数です。

## 基本的な使い方 [](#基本的な使い方)

ユーザーの一覧を表示するアクションの実行結果に、ユーザーを編集するアクショングループへ移動できるリンクを表示する例を考えます。

移動先のアクショングループは、ユーザーの更新とユーザーの削除の2つのアクションが設定されたアクショングループです。

![linkToActionGroup関数の使用例の移動先のアクショングループ](/images/action_transform/builtin_functions/link_to_action_group_target_action_group.png)

### 使用例 [](#使用例)

以下がユーザーの一覧を表示するアクションに設定するスクリプトです。

```
const users = results[0].success;
return [
  {
    success: users.map((user) => ({
      名前: linkToActionGroup(
        user.name,
        // ユーザーの詳細を表示するアクションの識別子を設定
        "get-user-detail",
        // ユーザーの詳細を表示するアクションへ渡すパラメータの値を設定
        {
          id: user.id,
          name: user.name,
          email: user.email,
        },
      ),
      メールアドレス: user.email,
    })),
  },
];
```

### 表示結果 [](#表示結果)

![linkToActionGroup関数の使用例の表示結果](/images/action_transform/builtin_functions/link_to_action_group.png)

## 詳細なインターフェース [](#詳細なインターフェース)

```
function linkToActionGroup(
  title: string,
  actionGroupId: string,
  params?: object,
);
```

### 引数 [](#引数)

#### `title: string` [](#title-string)

- リンクとして表示するテキストです

#### `actionGroupId: string` [](#actiongroupid-string)

- 移動先のアクショングループIDです
- アクショングループIDは、アクショングループの詳細画面の編集ボタンの下から確認できます

![アクショングループIDの確認方法](/images/link_to_action_group/copy_id.png)

#### `params?: object` [](#params-object)

- 移動先のアクショングループのアクションへ渡すパラメータです。キーがパラメータ名、値がパラメータに渡す値のオブジェクトです。
- 例
  - `{ id: 1 }`
- アクションのパラメータの種類ごとに渡せる値の型は以下です（ただし、ファイル型は未対応です）

| 種類 | 型 | 説明 | 例 |
| --- | --- | --- | --- |
| テキスト | `string | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ company_name: '株式会社ベースマキナ' }` |
| 数値 | `number | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ user_id: 123 }` |
| 日付 | `Date | string | number | null | undefined` | `string` は `Date` 型に変換できる値、 `number` はUnixTimestamp (秒)を入力してください。 `null` や `undefined` の場合は未入力として扱われます。 | `{ created: '2023-01-01', updated: new Date(), deleted: 1609459200 }` |
| 真偽値 | `boolean | null | undefined` | `null` や `undefined` の場合は `false` として扱われます。 | `{ checked: true }` |
| JSON値 | `string | number | Date | null | undefined` | JSON値の種類ごとに型が異なります。 テキストなら `string | null | undefined` 、数値なら `number | null | undefined` 、日付なら `string | number | Date | null | undefined` を渡せます。 日付の場合 `string` は `Date` 型に変換できる値、 `number` はUnixTimestamp (秒)を入力してください。 `null` や `undefined` の場合は `null` として扱われます。 | `{ company_name: '株式会社ベースマキナ', user_id: 123, created: '2023-01-01', deleted: null }` |
| SQL | `string | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ query: 'SELECT * FROM users;' }` |
| システム値 | `string | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ offset: '20' }` |
| 配列 | `Array | null | undefined` | 各要素の種類の型は、各種類の型と同じです。 `null` や `undefined` の場合は空配列として扱われます。 | `{ user_ids: [10, 11, 12] }` |
| タプル | `Array` | 各要素の種類の型は、各種類の型と同じです。 | `{ id_and_name: [123, 'taro'] }` |

[linkToView](/action/transformer_script/builtin_functions/link_to_view/) [linkToURL](/action/transformer_script/builtin_functions/link_to_url/)
---
[アクション](/action/)

結果表示のカスタマイズ

組み込み関数

linkToURL

# linkToURL

`linkToURL` 関数は、任意のURLへ移動できるリンクを表示できる関数です。

## 基本的な使い方 [](#基本的な使い方)

以下は、ユーザーの公開プロフィールへのリンクを設定する例です。

### 使用例 [](#使用例)

```
const user = results[0].success;
return {
  ID: user.id,
  名前: user.name,
  プロフィール: linkToURL("開く", `https://example.com/users/${user.id}`),
};
```

### 表示結果 [](#表示結果)

![linkToURL関数の使用例の表示結果](/images/link_to_url/exec_result.png)

---

`linkToURL` 関数で表示したリンクのURLは、クリックすると新しいタブで開かれます。

## 詳細なインターフェース [](#詳細なインターフェース)

```
function linkToURL(title: string, url: string | URL);
```

### 引数 [](#引数)

#### `title: string` [](#title-string)

- リンクとして表示するテキストです。

#### `url: string | URL` [](#url-string--url)

- 移動先のURLです。

[linkToActionGroup](/action/transformer_script/builtin_functions/link_to_action_group/) [image](/action/transformer_script/builtin_functions/image/)
---
[アクション](/action/)

結果表示のカスタマイズ

組み込み関数

linkToView

# linkToView

`linkToView` 関数は、ビューの閲覧画面へ移動できるリンクを表示できる関数です。

## 基本的な使い方 [](#基本的な使い方)

ユーザーの一覧を表示するアクションの実行結果に、ユーザーの詳細を表示するビューへ移動できるリンクを表示する例を考えます。

移動先のユーザーの詳細を表示するビューは、
以下のようなURLパラメーターから取得したユーザーのIDを使ってユーザー情報を取得するアクションを実行して表示するビューです。

```
import { Heading, Text, VStack, ButtonGroup, Button } from "@chakra-ui/react";
import { useExecuteAction, useURLQueries } from "@basemachina/view";
 
const App = () => {
  // URLパラメーターを取得
  const query = useURLQueries();
  // アクションでユーザーの詳細情報を取得
  const { data, loading } = useExecuteAction("get-user-detail", {
    // アクションのパラメーターにユーザーIDを渡す
    userID: query.userID,
  });
  if (loading) return <LoadingIndicator />;
 
  const user = data?.results[0].success;
  return (
    <VStack spacing="1rem">
      <Heading>{user.name}</Heading>
      <VStack spacing="0.5rem">
        <Text>{user.email}</Text>
        <Text>{user.createdAt}登録</Text>
      </VStack>
      <ButtonGroup spacing="2">
        <Button colorScheme="blue">編集する</Button>
        <Button colorScheme="red">削除する</Button>
      </ButtonGroup>
    </VStack>
  );
};
 
export default App;
```

![linkToView関数の使用例の移動先のビュー](/images/action_transform/builtin_functions/link_to_view_target_view.png)

### 使用例 [](#使用例)

以下がユーザーの一覧を表示するアクションに設定するスクリプトです。

```
const users = results[0].success;
return [
  {
    success: users.map((user) => ({
      名前: linkToView(
        user.name,
        // ユーザーの詳細を表示するビューの識別子を設定
        "get-user-detail",
        // ユーザーの詳細を表示するビューのURLパラメーターに渡す値を設定
        { userId: user.id },
      ),
      メールアドレス: user.email,
    })),
  },
];
```

### 表示結果 [](#表示結果)

![linkToView関数の使用例の表示結果](/images/action_transform/builtin_functions/link_to_view.png)

---

表示されたリンクをクリックすると、ユーザーの詳細を表示するビューのページに移動します。

## 詳細なインターフェース [](#詳細なインターフェース)

```
function linkToView(title: string, viewId: string, params?: object);
```

### 引数 [](#引数)

#### `title: string` [](#title-string)

- リンクとして表示するテキストです。

#### `viewId: string` [](#viewid-string)

- 移動先のビューのIDまたは識別子です。
- 例
  - `"get-user-detail"`
  - `"u8a64fnmekufv3j2om"`

#### `params?: object` [](#params-object)

- 移動先のビューに渡すURLパラメーターです。キーがパラメータ名、値がパラメータに渡す値のオブジェクトです。

[linkToAction](/action/transformer_script/builtin_functions/link_to_action/) [linkToActionGroup](/action/transformer_script/builtin_functions/link_to_action_group/)
---
[アクション](/action/)

結果表示のカスタマイズ

ページネーション

# ページネーション

アクションの実行結果を取得する際に、ページネーションで結果を都度を設定できます。

ページネーションに必要な作業はページネーション時に利用するパラメーターを定義すること、そしてそのパラメーターを使って **結果表示のカスタマイズ** でページネーションを設定することです。

## ページネーションの種類 [](#ページネーションの種類)

ページネーションの方式にはいくつか種類があります。

- オフセット式ページネーション
- カーソル式ページネーション

データソースのインターフェースに合わせてどちらをご利用するかお選びください。

## オフセット式ページネーション [](#オフセット式ページネーション)

オフセット式ページネーションは、ページごとのデータ数と開始地点を使ってページネーションをするパターンです。

このパターンは通常、MySQLやPostgreSQLなどの、SQLを実行するアクションでご利用いただくものとなります。

HTTP APIやgRPCなどのアクションでご利用いただく場合は、APIがオフセットとページサイズの値を受け付けられる実装となっている必要があります。

**パラメーターの設定**

オフセット式の場合、2つの数値パラメーターを用意します。

- オフセット値を入力するパラメーター
- ページサイズの値を入力するパラメーター

これらの値は前後のページへ移動するたびにベースマキナ上で値が更新されます。

下記の例ではSQLのアクションにオフセット式ページネーションのパラメーターを利用しています。

それぞれ `offset`, `limit` という値で取り扱っています。

![オフセットのパラメーター](/images/pagination/offset_parameters.png)

**ページネーション設定の紐づけ**

ページネーションの設定は **結果表示のカスタマイズ** からできます。

初期状態ではページネーションはしない設定が適用されています。

オフセット式ページネーションを選択すると、「ページサイズ」（ページごとのデータ数）の設定欄と、パラメーターを紐づける選択欄が表示されます。

さきほどパラメーターの設定で用意したパラメーターを選び、移動時に計算されたページネーション関連の値がアクションへ受け渡されるようにしてください。

![ページネーションの設定欄](/images/pagination/offset_set.png)

**ページネーションの動作**

ページネーションの設定を保存したあと、ページを再読み込みしてアクションを再実行するとページネーションが有効になった状態で結果を見られます。

結果一覧のテーブルの下部に、ページネーション用のカーソルが表示されます。左右の矢印を押すとパラメーターに渡される値が変わり、前後のページに移動できます。

オフセット形式の場合は現在のページ番号を保持しているため、それもカーソルとともに表示されます。

![ページネーションの設定欄](/images/pagination/offset_footer.png)

## カーソル式ページネーション [](#カーソル式ページネーション)

カーソル式ページネーションは、パフォーマンスに優れているページネーションの方法でデータの数が多いときによく使われ、Infinite ScrollやAPIなどで使用されることもあります。

なお、このページネーション方法を取る場合はユーザーの皆さまのAPI側の実装がカーソルの値を受け付けられることが前提です。

**パラメーターの設定**

カーソル式の場合は以下の2通りのどちらかの移動形式を取ります。

- 後方向に次々にページ移動する
- 前後のページに移動する

**後方向に次々にページ移動する場合**

次のページ移動に使うカーソル文字列を受け付ける値をテキストパラメーターとして用意します。

**前後のページに移動する場合**

上記に加えて、前方向のページ移動に使うカーソル文字列を受け付ける値をテキストパラメーターとして用意します。

![カーソルのパラメーター](/images/pagination/cursor_parameters.png)

**ページネーション設定の紐づけ**

ページネーションの設定は結果表示のカスタマイズからできます。

カーソル式ページネーションを選択すると、必須・任意両方の設定値の入力欄が表示されます。

後方向には必ずページ移動できることを想定しているので、以下の3つの値は必須です。

- 次ページの有無
- 次ページのカーソル
- 次ページのカーソルを入力するパラメーター

また、前方向にも移動したい場合は以下の3つの値も設定してください。

- 前ページの有無
- 前ページのカーソル
- 前ページのカーソルを入力するパラメーター

「次ページのカーソル」のように入力欄が2つ並んでいる設定箇所は、左側が入力値を計算するためのJavaScriptの入力欄、右側が現在表示されている実行結果から値を実際に抜き出してきたときの実行結果を表しています。

そのため、初期状態では右欄の表示が `null` になっています。

実際の設定例として、簡易的に30件ずつ値が返ってくるページネーションを想定します。

![カーソルのJSの設定欄](/images/pagination/cursor_exec.png)

次ページの有無には30件ちょうどで値が返ってくる場合であれば次のページが存在すると仮定してJavaScriptの条件文を設定します。

次に、「次ページのカーソル」にはカーソルとして配列の末尾のIDを指定しています。

このように毎回返ってくるレスポンスの内容を、次のページネーションの情報として受け渡すことができます。

なお、どのようなレスポンスをもとにしてJavaScriptを書けばよいか知りたい方は、 [結果の加工](/action/transformer_script/action_transform/) と同様に **結果の加工スクリプト** のタブの **加工前のデータ** をご確認ください。

最後に、JavaScript経由で取得されたカーソル文字列をどのパラメーターに紐づけるかを設定します。

さきほどパラメーターの設定で用意したパラメーターを選び、移動時に計算されたページネーション関連の値がアクションへ受け渡されるようにしてください。

![カーソルのパラメーターの設定欄](/images/pagination/cursor_set.png)

**ページネーションの動作**

ページネーションの設定を保存したあと、ページを再読み込みしてアクションを再実行するとページネーションが有効になった状態で結果を見られます。

オフセット式とは異なり、現在のページ番号を保持していないため、次ページの有無と前ページの有無のフラグ値に応じたカーソルの矢印のみが表示されます。

[結果の加工に使える値](/action/transformer_script/action_transform_parameters/) [linkToAction](/action/transformer_script/builtin_functions/link_to_action/)
---

---
[アクション](/action/)

バージョン管理

# バージョン管理

## バージョン管理とは [](#バージョン管理とは)

アクションを作成・更新すると、設定内容が「バージョン」として保存されます。

バージョン管理機能を利用すると、次のように [環境](/admin/environment/what_is_environment/) ごとに異なるバージョンのアクションを使うことができます。これにより、アクションのリリースを安全に進められます。

- 開発環境：常に最新のバージョンを使用して開発
- 検証環境：リリース候補のバージョンで動作確認
- 本番環境：動作確認済みの安定したバージョンを固定して使用

## バージョン管理の事前準備 [](#バージョン管理の事前準備)

バージョン管理機能を使用するには、プロジェクト設定で「開発環境」を指定する必要があります。開発環境として指定された環境でのみ、アクションの編集やバージョンの設定が可能になります。詳細は、 [開発環境](/admin/environment/development_environment/) を参照してください。

## 機能説明 [](#機能説明)

### バージョンが作成されるタイミング [](#バージョンが作成されるタイミング)

開発環境が設定されたプロジェクトでは、アクションを保存するたびに自動的に新しいバージョンが作成されます。

### バージョン管理されるアクションの設定項目 [](#バージョン管理されるアクションの設定項目)

現在、バージョンごとに保存される設定項目は以下の通りです。

- 名前
- パラメーター
- 紐づくデータソースと処理の内容

今後、結果表示のカスタマイズ（加工スクリプトとページネーションの設定）もバージョン管理の対象となる予定です。

以下の設定項目はバージョン管理の対象には含まれません。バージョンによらず、常に最新の設定が適用されます。

- 識別子
- 説明
- ジョブ実行を優先的に表示する
- 権限設定
- レビュー設定

### バージョン管理ができる権限 [](#バージョン管理ができる権限)

プロジェクト管理者、開発責任者、開発者はバージョン管理ができます。詳しくは [プロジェクトの各設定の管理権限](/authorities/#%E3%83%97%E3%83%AD%E3%82%B8%E3%82%A7%E3%82%AF%E3%83%88%E3%81%AE%E5%90%84%E8%A8%AD%E5%AE%9A%E3%81%AE%E7%AE%A1%E7%90%86%E6%A8%A9%E9%99%90) をご参照ください。

## 設定方法 [](#設定方法)

バージョン設定 は、アクションのバージョン/有効化設定画面および、アクションのバージョン/有効化一括設定画面にて変更できます。

### アクションのバージョン/有効化設定画面 [](#アクションのバージョン有効化設定画面)

アクション実行画面の「バージョン/有効化設定」ボタンをクリックすると、アクションのバージョン/有効化設定画面に移動します。

![アクションのバージョン/有効化設定画面への移動のための導線](/images/environment_action_settings/link_to_update_environment_action_settings_primary_column_environment.png)

この画面では、選択したアクションの、各環境におけるバージョン/有効化設定をまとめて変更できます。

![アクションのバージョン/有効化設定画面](/images/environment_action_settings/update_environment_action_settings_primary_column_environment.png)

### アクションのバージョン/有効化一括設定画面 [](#アクションのバージョン有効化一括設定画面)

アクション一覧画面の三点リーダーのメニューから「アクションのバージョン/有効化一括設定」をクリックすると一括設定画面に移動します。

![アクションのバージョン/有効化一括設定画面への移動のための導線。三点リーダーのメニューを開くボタンが指し示されている](/images/environment_action_settings/link_to_update_environment_action_settings_primary_column_action_01.png)

![アクションのバージョン/有効化一括設定画面への移動のための導線。三点リーダーのメニューを開いた結果、「アクションのバージョン/有効化一括設定」のリンクが表示されている様子](/images/environment_action_settings/link_to_update_environment_action_settings_primary_column_action_02.png)

この画面では、現在利用中の環境の、各アクションのバージョン/有効化設定をまとめて変更できます。

![アクションのバージョン/有効化一括設定画面](/images/environment_action_settings/update_environment_action_settings_primary_column_action.png)

### バージョンを環境別に切り替える [](#バージョンを環境別に切り替える)

![バージョン設定画面のバージョンのセレクトボックス](/images/action_versions/version_select_box.png)

環境・アクションごとに使用するバージョンを切り替えることができます。開発環境では、常に最新バージョンが使用される設定で固定されており、変更はできません。

バージョン名は作成された日時で表示されます。今後、バージョン名を変更できる機能を追加予定です。

過去のバージョンの設定内容は現在ご確認いただけません。こちらも今後、機能追加により改善予定です。

#### 常に最新のバージョンを使う [](#常に最新のバージョンを使う)

デフォルトの設定です。アクションが更新されるたびに自動で最新のバージョンが適用されるため、都度バージョンを切り替えることなく開発を進めることができます。

#### 特定のバージョンを使う [](#特定のバージョンを使う)

特定のバージョンを選択して使用できます。これにより、テスト済みの安定したバージョンを本番環境に適用するなど、段階的なリリースを安全に進められます。

## ジョブ、レビュー依頼で利用されるバージョン [](#ジョブレビュー依頼で利用されるバージョン)

ジョブ作成やレビュー依頼作成の時点のバージョン設定が適用されます。作成後にアクションのバージョン設定が更新されても、すでに作成されたジョブやレビュー依頼には適用されません。

[有効化設定](/action/enablement_settings/) [アクションのコピー](/action/copy_action/)
---

---
管理設定

アクション実行の設定

IPホワイトリスト

# IPホワイトリスト

皆さまが自社で管理しているAPIやデータベースにアクセスする場合、ファイアーウォールの設定でベースマキナからのアクセスを許可していただく必要があります。

ベースマキナからのアクセス元は、IPアドレス `34.85.43.93` です。

データソースを登録する際には、このIPアドレスからのアクセスが許可された経路からリクエストがされる設定になっているかご確認ください。

## Google Cloudのデータソースに関する注意 [](#google-cloudのデータソースに関する注意)

ベースマキナがサポートするデータソースのうち、Google Cloudが提供する以下のものにアクセス制限を入れる際に注意点があります。

- Google Cloud Storage
- Firestore
- BigQuery

これらのデータソースへの接続は例外的に上述の `34.85.43.93` というIPアドレスからのアクセスにはなりません。
これらへのアクセスにはGoogleのAPIを利用しており、ベースマキナからのGoogle APIへのアクセスはGoogle Cloudの内部ネットワーク通信となります。

よって、Google Cloudの [Access Context Manager (opens in a new tab)](https://cloud.google.com/access-context-manager/docs/overview?hl=ja) などを利用してこれらのデータソースにアクセス制限をかけている場合、
ベースマキナが利用しているGoogle Cloudプロジェクトからのリクエストや、ベースマキナのサーバーが所属するVPCネットワークからのリクエストに対する許可が必要になることがあります。

- **Google CloudプロジェクトのID**: `863409197690`
- **VPCネットワークの識別子**: `projects/basemachina/global/networks/basemachina-network`

[プロジェクトの作成・更新](/admin/user_management/project_settings/) [通知設定](/admin/action/notification/)
---
管理設定

アクション実行の設定

通知設定

# 通知設定

アクションの実行時やレビュー依頼などが発生したタイミングで送られるSlack・メール通知を設定できます。

通知設定は [プロジェクトの設定](/admin/user_management/project_settings/) の環境設定から適用できます。

環境ごとに通知先が異なるケースを想定しており、通知先を指定しない場合は通知が送られません。

![modal](/images/notification/modal.png)

## Slackの通知設定 [](#slackの通知設定)

### チャンネルIDの確認方法 [](#チャンネルidの確認方法)

Slack上でチャンネルの設定の画面内にチャンネルIDが表示されます。

![チャンネルID](/images/notification/channel_id.png)

### アクション実行時 [](#アクション実行時)

アクション実行時に誰がどのアクションを実行したのかをSlackに通知できます。

指定されたURLに対してアクション実行後にWebhookでリクエストを送信します。

![メッセージ内容](/images/notification/webhook_message.png)

### レビュー関連 [](#レビュー関連)

以下レビュー関連の操作をした際にSlackへ通知できます。

- レビュー依頼の作成時
- レビュー承認時
- レビュー却下時
- レビュー承認条件の完了時
- レビュー期限が迫ったとき

### エラー関連 [](#エラー関連)

定期実行によって自動で実行されたジョブが失敗したときに、エラーをSlackに送信できます。

詳しくは [定期実行](/action/cron_jobs/) をご覧ください。

## メールの通知設定 [](#メールの通知設定)

アクション実行やレビュー依頼があったときにメールで通知できます。

通知が不要な場合は画面中央部のトグルをOFFにしてください。

[IPホワイトリスト](/admin/action/ip_whitelist/) [監査ログ](/admin/security/audit_log/)
---
管理設定

環境

環境別の利用制限

# 環境別の利用制限

環境別の利用制限機能は、環境ごとに利用できるユーザー・グループを制限できる機能です。

利用制限を設定すると、設定したユーザー・グループ以外のユーザーはその環境にアクセスできなくなり、環境切り替えメニューにも表示されなくなります。

例えば、本番環境のデータを特定のユーザーだけに閲覧・操作させたい場合などに利用できます。

## 環境別の利用制限の設定方法 [](#環境別の利用制限の設定方法)

プロジェクト設定の環境設定から設定できます。

1. 右上のメニューから「設定」を選択します。
1. 左のサイドバーから「環境設定」を選択して環境一覧画面に移動します。
1. 環境一覧から利用制限を設定したい環境を選択します。

利用制限では以下の項目を設定します。

- 利用制限を有効にする
- 利用できるユーザー・グループ

### 利用制限を有効にする [](#利用制限を有効にする)

利用制限を有効にするかどうかを設定します。

### 利用できるユーザー・グループ [](#利用できるユーザーグループ)

利用制限を有効にすると、利用できるユーザー・グループを設定できます。

![環境別の利用制限の利用できるユーザー・グループの選択画面](/images/environment/access_control/accessible_actors.png)

---

すべての設定項目の入力が終わったら「保存」をクリックします。

## 利用制限されている環境にアクセスした場合 [](#利用制限されている環境にアクセスした場合)

利用制限されている環境にアクセスすると、以下のような画面が表示されます。

![環境別の利用制限された環境にアクセスした場合の画面](/images/403.png)

[環境別のデータソース設定](/admin/environment/datasource/) [環境別のIPアドレス制限](/admin/environment/ip_restriction/)
---
管理設定

環境

環境別のデータソース設定

# 環境別のデータソース設定

データソースの情報は環境ごとに設定できます。

環境ごとに別の情報を設定すると、本番環境と開発環境で同じアクションを別のデータベースに対して実行するといったことができます。

## 環境別のデータソース設定の方法 [](#環境別のデータソース設定の方法)

データソースを作成すると作成時の環境にのみ設定が登録されます。

![データソースの作成](/images/environment/datasource/create.png)

環境を切り替えると別の環境の設定ができます。

![環境を切り替える](/images/environment/switch_environment.png)

環境への設定が完了すると「環境ごとの設定状況」にチェックマークがつきます。

![データソースへの環境の設定の登録](/images/environment/datasource/update.png)

## データソースに使用中の環境での設定がされていない場合 [](#データソースに使用中の環境での設定がされていない場合)

アクションに紐づくデータソースへ、現在使用中の環境の設定がされていない場合はアクションを実行できません。

![環境設定の存在しないアクション](/images/environment/datasource/action_unavailable.png)

[開発環境](/admin/environment/development_environment/) [環境別の利用制限](/admin/environment/access_control/)
---
管理設定

環境

開発環境

# 開発環境

開発環境とは、アクションを開発するための環境です。開発環境が指定されていると、アクションの編集やバージョンの設定は開発環境に指定された環境でのみ許可され、他の環境ではアクションの実行だけができます。

プロジェクト設定の「環境設定」で、「開発環境」を指定できます。

⚠️

開発環境を一度指定すると未指定の状態に戻すことができません。ご注意ください。

![開発環境の設定](/images/environment/development_environment/setting.png)

なお、開発環境では常にアクションの最新バージョンが使用されます。アクションを保存するたびに新しいバージョンが自動的に作成され、それが即座に適用されます。

バージョン管理機能に関する詳細は、 [バージョン管理](/action/versions/) を参照してください。

[環境とは](/admin/environment/what_is_environment/) [環境別のデータソース設定](/admin/environment/datasource/)
---
管理設定

環境

環境別のIPアドレス制限

# 環境別のIPアドレス制限

環境別のIPアドレス制限は、各環境ごとにベースマキナへのアクセスを一部のIPアドレスからのみに制限できる機能です。

制限はホワイトリスト形式です。

## 環境別のIPアドレス制限の設定方法 [](#環境別のipアドレス制限の設定方法)

プロジェクト設定のネットワーク設定から設定できます。

1. 左上の環境切り替えメニューからIPアドレス制限を設定したい環境を選択します。

![環境を切り替える](/images/environment/switch_environment.png)

1. 右上のメニューから「設定」を選択します。
1. 左のサイドバーから「ネットワーク設定」を選択してネットワーク設定画面に移動します。
1. IPアドレス制限を設定します。

利用制限では以下の項目を設定します。

- IPアドレス制限を有効にする
- アクセスできるIPアドレスの一覧
  - IPアドレス（CIDR形式）
  - 備考

許可するIPアドレスはCIDR表記による範囲指定となります。
具体的なIPアドレス1つのみを許可したいケースでは、CIDRのサブネットマスク部分を `/32` としてください。

![環境別IPアドレス制限の設定画面](/images/environment/ip_restriction/form.png)

---

すべての設定項目の入力が終わったら「保存」をクリックします。

## 企業アカウント単位でIPアドレス制限が設定されている場合 [](#企業アカウント単位でipアドレス制限が設定されている場合)

ベースマキナでは [企業アカウント単位でもIPアドレス制限が設定](/admin/security/ip_restriction/) できます。

企業アカウント単位と環境別のIPアドレス制限が両方設定されている場合、両方で許可されているIPアドレスからのみアクセスできます。

## 許可されていないIPアドレスでアクセスした場合 [](#許可されていないipアドレスでアクセスした場合)

IPアドレス制限が設定されている環境に許可されていないIPアドレスでアクセスすると、以下のような画面が表示されます。

![IPアドレス制限が設定されている環境に許可されていないIPアドレスでアクセスした場合の画面](/images/403.png)

[環境別の利用制限](/admin/environment/access_control/) [SQLのアクションで前のクエリの結果を使用する](/tips/sql_previous_result/)
---
管理設定

環境

環境とは

# 環境とは

環境とは、アクションの設定などを、本番環境・開発環境といった複数の環境で使い回し、切り替えて使うことができる機能です。

例えば、HTTP APIアクションの設定を複数環境で使い回したい場合、HTTP APIデータソースにそれぞれの環境でのホスト名などの接続情報を登録することで実現できます。

環境は、プロジェクトごとに任意の数を作成して切り替えることができます。

## 環境の作成・編集方法 [](#環境の作成編集方法)

環境は、プロジェクト設定画面の"環境設定"から作成・編集できます。

![環境設定](/images/environment/environment_setting.png)

環境を作成するには、右上の"追加"ボタンをクリックしてください。

![環境を作成する](/images/environment/create_environment.png)

ここでは、下記の項目を設定できます。

- 名前（必須）
  - 環境の名前です。使用中の環境名や、切り替え時の選択肢に表示されます。
- メニューバーの背景色（必須）
  - この環境を選択したときに表示される、ベースマキナの画面上部のメニューバーの背景色です。
- Slack Webhook URL（任意）
  - この環境でのSlack通知先のWebhook URLです。
  URLは `https://hooks.slack.com/` から始まるフォーマットです。
  Webhook URLの取得方法については [こちら (opens in a new tab)](https://api.slack.com/messaging/webhooks) をご覧ください。
- アクション実行の通知先SlackチャンネルID（任意）
  - この環境でアクションが実行された際に通知されるチャンネルです。
  設定がなければSlack Webhook URLに設定されているデフォルトのチャンネルに通知されます。
  チャンネルIDの確認方法は [こちら](/admin/action/notification/)
- レビュー関連の通知先SlackチャンネルID（任意）
  - この環境でレビュー依頼などが実行された際に通知されるチャンネルです。
  設定がなければSlack Webhook URLに設定されているデフォルトのチャンネルに通知されます。

設定した内容は、環境一覧のメニュー内の導線から編集できます。

![環境を編集する](/images/environment/edit_environment.png)

すべてのプロジェクトには、初めから"初期環境"と言う名前の環境が存在していますが、この環境を編集して名前を変えることも可能です。

使わなくなった環境は、無効化できます。
無効化された環境は、環境切り替えのメニューに表示されなくなります。
ただし、無効化された設定は削除されず、同じ画面上で再び有効化できます。

## 環境IDの確認 [](#環境idの確認)

環境IDは、以下のいずれかの方法で確認できます。

### 管理画面のURLから [](#管理画面のurlから)

メニューバーから対象の環境に切り替えて任意のページを開くと、ブラウザのURLに含まれる `/environments/` 配下の値が環境IDです。

```
https://{企業アカウントのサブドメイン}.basemachina.com/projects/{プロジェクトID}/environments/{環境ID}/...
```

### 公開APIから [](#公開apiから)

[公開API](/public_api/) の `GET /projects/{project_id}/environments` （ [APIリファレンス](/public_api/reference/) ）で、プロジェクトに紐づく **有効化されている環境** の一覧を取得できます。レスポンスの `data[].id` が環境IDです。CI/CDやスクリプトから動的に環境IDを参照したい場合に便利です。

環境IDは、 [`bm sync <環境ID>`](/code_management/cli/sync/) による他環境への同期や、公開APIのURLパス、 [アクションのJWT認証](/action/jwt_authentication/) の `aud` クレームなどで使用します。

## 環境の切り替え方法 [](#環境の切り替え方法)

メニューバーに表示されている環境名をクリックすると、切り替え可能な環境の一覧が表示されます。
ここから、使用したい環境を選択してください。
選択すると、メニューバーの背景色が環境に合わせて変化します。

![環境を切り替える](/images/environment/switch_environment.png)

環境を切り替えると、アクションの実行などは切り替え後の環境の設定に従います。

## 環境に紐づく設定 [](#環境に紐づく設定)

環境には、下記の設定を紐づけることができます。

- [データソースの設定](/admin/environment/datasource/)
- アクションの設定
  - [使用するバージョン](/action/versions/)
  - [有効化設定](/action/enablement_settings/)
- bridgeの設定
- Slack Webhook URLの設定
- [利用制限](/admin/environment/access_control/)

また、下記のデータは、環境に紐づいて作成されます。

- ジョブ
- レビュー依頼

例えば、"開発環境"で作成されたジョブの情報を、"本番環境"で閲覧する、といった操作はできない点にご注意ください。

## 監査ログ [](#監査ログ)

アクション実行の監査ログに、そのアクションを実行した環境の名前が記録されます。

詳細は [監査ログ](/admin/security/audit_log/) をご覧ください。

[認証ポリシー](/admin/security/auth_policies/) [開発環境](/admin/environment/development_environment/)
---
管理設定

セキュリティ・監査

監査ログ

# 監査ログ

監査ログでは、ベースマキナ上での操作の記録を確認できます。

監査ログの記録方法には以下の2つがあります。

- 通常の監査ログ
- 監査ログストリーミング

通常の監査ログは、自動的に記録されます。特別な設定する必要はありません。
記録された監査ログの内容は、 [CSVファイルを出力](/admin/security/audit_log/csv_download/) して確認できます。

監査ログストリーミングは、アクションの引数などのセンシティブな情報を含めた監査ログを記録します。記録先として、お客さまご自身で管理しているクラウドストレージを指定いただきます。
詳しくは、 [監査ログのストリーミング](/admin/security/audit_log/streaming/) をご覧ください。

[通知設定](/admin/action/notification/) [CSVファイル出力](/admin/security/audit_log/csv_download/)
---
管理設定

セキュリティ・監査

[監査ログ](/admin/security/audit_log/)

CSVファイル出力

# 監査ログのCSVファイル出力

[監査ログ (opens in a new tab)](https://basemachina.com/settings/audit-log) のページから請求できます。

監査ログは、記録されてから少なくとも5年間保持されます。「ダウンロードリンクを請求する」をクリックすると請求したお客さまのメールアドレス宛に、監査ログが記録されたCSVファイルをダウンロードできるリンクが送信されます。

![ダウンロードリンクを請求する](/images/audit_log.png)

## 監査ログの内容 [](#監査ログの内容)

| 列名 | 列が出力される操作 | 内容 |
| --- | --- | --- |
| bmrn\_class\_id | アクションの実行、作成、更新、削除 | アクションのデータソースのID |
| bmrn\_class | アクションの実行、作成、更新、削除 | アクションのデータソースの種類 |
| bmrn\_resource | アクションの実行、作成、更新、削除 | アクションのデータソースの名前 |
| client\_ip | すべての操作 | 操作元のIPアドレス |
| context\_id | すべての操作 | 操作のID |
| message | すべての操作 | 操作の種類 |
| username | ユーザーによる操作 | 操作したユーザーの名前 |
| email | ユーザーによる操作 | 操作したユーザーのメールアドレス |
| project | プロジェクト内でのすべての操作 | 操作したプロジェクトの名前 |
| environment | 環境内でのすべての操作 | 操作した環境の名前 |
| action\_id | アクションの実行、作成、更新、削除、定期実行の作成、定期実行のアクション更新 | アクションのID |
| action\_updated\_at | アクションの実行、作成、更新、削除、定期実行の作成、定期実行のアクション更新 | アクションの最終更新日時 |
| action\_created\_at | アクションの実行、作成、更新、削除、定期実行の作成、定期実行のアクション更新 | アクションの作成日時 |
| action\_name | アクションの実行、作成、更新、削除、定期実行の作成、定期実行のアクション更新 | アクションの名前 |
| action\_display\_id | アクションの実行、作成、更新、削除、定期実行の作成、定期実行のアクション更新 | アクションの識別子 |
| status | アクションの実行 | 実行結果（ `success` ：成功、 `failure` ：実行の失敗（クエリエラー、タイムアウト、切断など）、 `system_error` ：ベースマキナ側のシステムエラー） |
| failure\_message | アクションの実行 | 失敗時のエラーメッセージ（ `status` が `failure` のときのみ出力） |
| review\_id | レビュー依頼の作成、承認、却下、レビュー依頼を使ったアクションの実行 | レビュー依頼のID |
| review\_description | レビュー依頼の作成 | レビュー依頼の詳細 |
| review\_expires\_in | レビュー依頼の作成、承認、却下 | レビュー依頼の有効期限 |
| review\_created\_at | レビュー依頼の作成、承認、却下 | レビュー依頼の作成日時 |
| review\_setting\_id | レビュー設定の作成、更新 | レビュー設定のID |
| review\_setting\_name | レビュー設定の作成、更新 | レビュー設定の名前 |
| environment\_review\_settings | レビュー設定の作成、更新 | 環境ごとのレビュー設定の配列。各環境の承認条件や承認パターンなどの設定内容が含まれます |
| datasource-id | データソースの作成、更新、削除 | データソースのID |
| datasource-name | データソースの作成、更新、削除 | データソースの名前 |
| datasource-class | データソースの作成、更新、削除 | データソースの種類 |
| view-id | ビューの作成、更新、削除 | ビューのID |
| view-display\_id | ビューの作成、更新、削除 | ビューの識別子 |
| view-name | ビューの作成、更新、削除 | ビューの名前 |
| target\_environment-id | 環境別利用制限の更新 | 環境のID |
| target\_environment-name | 環境別利用制限の更新 | 環境の名前 |
| target\_environment-access\_control\_enabled | 環境別利用制限の更新 | 環境の利用制限が有効かどうか |
| is\_tenant\_admin | ユーザーの更新 | ユーザーが企業アカウントの管理者かどうか |
| project\_users | プロジェクトユーザーの作成、削除 | プロジェクトユーザーのID、名前、メールアドレスの配列 |
| target\_users | ユーザーの作成、削除、環境別利用制限の更新 | ユーザーのID、名前、メールアドレスの配列 |
| target\_user\_groups | 環境別利用制限の更新 | グループのID、名前、ロールの配列 |
| user\_group\_assignments | プロジェクトユーザーのグループの更新 | プロジェクトユーザーと所属グループの配列 |
| project\_service\_accounts | プロジェクトのサービスアカウントの作成、削除 | サービスアカウントのID、名前、メールアドレスの配列 |
| service\_accounts | サービスアカウントの作成、更新、削除、サービスアカウントのグループ割り当て | サービスアカウントのID、名前、メールアドレスの配列 |
| target\_user-id | ユーザーの更新 | ユーザーのID |
| target\_user-name | ユーザーの更新 | ユーザーの名前 |
| target\_user-email | ユーザーの更新 | ユーザーのメールアドレス |
| target\_user\_group-id | グループの作成、更新、削除 | グループのID |
| target\_user\_group-name | グループの作成、更新、削除 | グループの名前 |
| target\_user\_group-admin\_roles | グループの作成、更新、削除 | グループのロールの配列 |
| environment\_action\_settings | 環境別アクション設定の作成、更新 | 環境、アクション、アクションバージョン、有効化設定の配列 |
| environment\_view\_settings | 環境別ビュー設定の作成、更新 | 環境、ビュー、ビューバージョン、有効化設定の配列 |
| actions | アクションの識別子の更新 | アクションのID、名前、識別子、作成日時、最終更新日時の配列 |
| notification\_method-id | 通知方法の作成、更新、削除 | 通知方法のID |
| notification\_method-name | 通知方法の作成、更新、削除 | 通知方法の名前 |
| environment\_slack\_notification\_methods | 通知方法の作成、更新 | 環境ごとのSlack通知設定の配列 |
| action\_notification\_settings-on\_success-enabled | アクションの作成、更新 | 成功時のアクション通知設定が有効かどうか |
| action\_notification\_settings-on\_success-notification\_method\_id | アクションの作成、更新 | 成功時の通知方法ID |
| action\_notification\_settings-on\_success-mention\_target\_user\_ids | アクションの作成、更新 | 成功時のメンション対象ユーザーIDの配列 |
| action\_notification\_settings-on\_error-enabled | アクションの作成、更新 | エラー時のアクション通知設定が有効かどうか |
| action\_notification\_settings-on\_error-notification\_method\_id | アクションの作成、更新 | エラー時の通知方法ID |
| action\_notification\_settings-on\_error-mention\_target\_user\_ids | アクションの作成、更新 | エラー時のメンション対象ユーザーIDの配列 |
| job\_detail\_visibility | アクションの更新 | アクション実行履歴の詳細の公開範囲 |
| slack\_workspace-workspace\_name | Slack連携、Slack連携解除 | Slackワークスペースの名前 |
| action\_cron\_job-id | 定期実行の作成、一時停止、再開、無効化、スケジュール更新、名前更新、アクション更新、再実行 | 定期実行のID |
| action\_cron\_job-name | 定期実行の作成、一時停止、再開、無効化、スケジュール更新、名前更新、アクション更新、再実行 | 定期実行の名前 |
| action\_cron\_job-schedule | 定期実行の作成、スケジュール更新 | 定期実行のスケジュール（cron式） |
| action\_cron\_job-scheduled\_at | 定期実行の再実行 | 再実行対象のスケジュール日時 |
| service\_account-id | サービスアカウントによる操作、サービスアカウントのOIDC信頼ポリシーの更新 | サービスアカウントのID |
| service\_account-name | サービスアカウントによる操作、サービスアカウントのOIDC信頼ポリシーの更新 | サービスアカウントの名前 |
| service\_account-email | サービスアカウントのOIDC信頼ポリシーの更新 | サービスアカウントのメールアドレス |
| oidc\_trust\_policies | サービスアカウントのOIDC信頼ポリシーの更新 | OIDC信頼ポリシーのID、発行者、オーディエンス、Bound claimsの配列 |
| timestamp | すべての操作 | 操作日時 |

配列はJSON形式の配列をCSVエンコードした形式です。

```
"[{""id"":""aaabbbccc"",""name"":""taro"",""email"":""taro@example.com""}]"
```

GoogleスプレッドシートにインポートするとJSON形式の配列で入力されます。

![配列をGoogleスプレッドシートにインポートした例](/images/audit_log/csv_to_gssheets.png)

[監査ログ](/admin/security/audit_log/) [ストリーミング](/admin/security/audit_log/streaming/)
---
管理設定

セキュリティ・監査

[監査ログ](/admin/security/audit_log/)

検索

# 監査ログの検索

通常の監査ログには検索機能がありません。出力されたCSVファイルをお手元で絞り込み検索していただく必要があります。

監査ログストリーミングの出力結果は、アクションを使って検索できます。

監査ログに対してSQL文を実行できるため、特定の条件に一致するログのみの検索や、ログの加工などが可能です。

- [Amazon S3にストリーミングした監査ログをAmazon Athenaアクションで検索する](/admin/security/audit_log/search/s3/)

※現在はAmazon S3にストリーミングした監査ログのみ対応しています。

[ストリーミング](/admin/security/audit_log/streaming/) [Amazon S3](/admin/security/audit_log/search/s3/)
---
管理設定

セキュリティ・監査

[監査ログ](/admin/security/audit_log/)

[検索](/admin/security/audit_log/search/)

Amazon S3

# Amazon S3に保存した監査ログをAmazon Athenaアクションで検索する

以下の手順で、監査ログストリーミングでAmazon S3に保存した監査ログをAmazon Athenaアクションで検索できます。

## 事前準備 [](#事前準備)

監査ログストリーミングに設定するバケットをAmazon S3で作成し、作成したバケットをベースマキナで監査ログのストリーミング先として設定します。

監査ログストリーミングの設定方法の詳細は [監査ログのAmazon S3へのストリーミング](/admin/security/audit_log/#amazon-s3%E3%81%B8%E3%81%AE%E3%82%B9%E3%83%88%E3%83%AA%E3%83%BC%E3%83%9F%E3%83%B3%E3%82%B0) をご参照ください。

## 1. Amazon Athenaデータソースを設定する

Amazon Athenaでデータベースを作成し、作成したデータベースをベースマキナのデータソースとして設定します。

データソースの設定方法の詳細は [Amazon Athenaデータソースの設定](/action/datasources/amazon_athena/datasource_setting/) をご参照ください。

## 2. Amazon Athenaでテーブルを作成する

Amazon Athenaで、2で作成したデータベースに1で作成したAmazon S3のバケットを使ってテーブルを作成します。

テーブルの例は [テーブルの例](/admin/security/audit_log/search/s3/#%E3%83%86%E3%83%BC%E3%83%96%E3%83%AB%E3%81%AE%E4%BE%8B) をご参照ください。

テーブルの作成方法の詳細はAmazon Athenaのドキュメントの [Athena でテーブルを作成する (opens in a new tab)](https://docs.aws.amazon.com/ja_jp/athena/latest/ug/creating-tables.html) をご参照ください。

## 3. Amazon Athenaアクションを設定する

1で設定したデータソースと、2で作成したテーブルに対してクエリを実行するSQL文を設定したアクションを作成します。

```
SELECT *
FROM your_table_name
-- 監査ログの種類を指定
WHERE audit_log_type = 'execute_action'
AND partition_date > '2025-01-01'
ORDER BY timestamp DESC
LIMIT 1000;
```

アクションの設定方法の詳細は [Amazon Athenaアクションの設定](/action/datasources/amazon_athena/action_setting/) をご参照ください。

## 4. アクションを実行する [](#4-アクションを実行する)

アクションを実行すると、設定したSQL文が実行され、監査ログのデータが取得できます。

![監査ログを取得するアクションの実行結果](/images/audit_log/athena_result.png)

さらに `{id=aaabbbcccdddeee, name=開発環境}` のような文字列のAthenaの `MAP` や `ARRAY` 型の列の値は、
以下のようにCAST関数でJSON型に変換するとJavaScriptのオブジェクトや配列などに変換できます。

```
SELECT
    CAST(action AS JSON) AS action,
    CAST(environment AS JSON) AS environment
FROM your_table_name
WHERE audit_log_type = 'execute_action'
AND partition_date > '2025-01-01'
ORDER BY timestamp DESC
LIMIT 1000;
```

![JSON型に変換した監査ログを取得するアクションの実行結果](/images/audit_log/athena_result_json.png)

詳細は [`ARRAY`, `ROW`, `MAP` 型の列の値をJavaScriptの配列やオブジェクトに変換する](/action/datasources/amazon_athena/data_type/#arrayrowmap%E5%9E%8B%E3%81%AE%E5%88%97%E3%81%AE%E5%80%A4%E3%82%92javascript%E3%81%AE%E9%85%8D%E5%88%97%E3%82%84%E3%82%AA%E3%83%96%E3%82%B8%E3%82%A7%E3%82%AF%E3%83%88%E3%81%AB%E5%A4%89%E6%8F%9B%E3%81%99%E3%82%8B) をご参照ください。

---

## テーブルの例 [](#テーブルの例)

以下は監査ログの形式に合わせたテーブルの例です。

```
-- your_bucket_nameには監査ログストリーミングに設定したAmazon S3のバケットの名前を指定してください。
-- your_database_nameには1で作成したデータベースの名前を指定してください。
-- your_table_nameは任意の名前を指定してください。
CREATE EXTERNAL TABLE IF NOT EXISTS `your_database_name`.`your_table_name` (
    `timestamp` string,
    `message` string,
    `arguments` array<struct<name:string,value:string,type:string>>,
    `bmrn` struct<resource:string,class:string,class_id:string>,
    `action` struct<id:string,name:string,display_id:string,created_at:string,updated_at:string>,
    `action_version` struct<version_type:string,id:string,name:string>,
    `status` string,
    `failure_message` string,
    `tenant_id` string,
    `client_ip` string,
    `context_id` string,
    `user` struct<id:string,name:string,email:string>,
    `project` struct<id:string,name:string>,
    `environment` struct<id:string,name:string>
)
PARTITIONED BY (
    `partition_date` string,
    `audit_log_type` string
)
ROW FORMAT SERDE
    'org.openx.data.jsonserde.JsonSerDe'
WITH SERDEPROPERTIES (
    'ignore.malformed.json' = 'FALSE',
    'dots.in.keys' = 'FALSE',
    'case.insensitive' = 'TRUE',
    'mapping' = 'TRUE'
)
STORED AS INPUTFORMAT
    'org.apache.hadoop.mapred.TextInputFormat'
OUTPUTFORMAT
    'org.apache.hadoop.hive.ql.io.HiveIgnoreKeyTextOutputFormat'
LOCATION
    's3://your_bucket_name/'
TBLPROPERTIES (
    'classification' = 'json',
    'projection.enabled' = 'true',
    'projection.partition_date.format' = 'yyyy-MM-dd',
    'projection.partition_date.interval' = '1',
    'projection.partition_date.interval.unit' = 'DAYS',
    'projection.partition_date.type' = 'date',
    'projection.partition_date.range' = '2023-01-01,NOW',
    -- もしパフォーマンスが悪い場合は'injected'から'enum'への変更をお試しください
    -- https://docs.aws.amazon.com/ja_jp/athena/latest/ug/partition-projection-supported-types.html
    'projection.audit_log_type.type' = 'injected',
    'storage.location.template' = 's3://your_bucket_name/${partition_date}/${audit_log_type}'
);
```

💡

上記のテーブル定義は、保存先のパス形式が「日付 / 種別」（デフォルト）の場合の例です。「種別 / 日付」に変更している場合は、 `storage.location.template` を以下のように変更してください。

```
's3://your_bucket_name/${audit_log_type}/${partition_date}'
```

パス形式の詳細は [保存先のパス形式の変更](/admin/security/audit_log/streaming/#%E4%BF%9D%E5%AD%98%E5%85%88%E3%81%AE%E3%83%91%E3%82%B9%E5%BD%A2%E5%BC%8F%E3%81%AE%E5%A4%89%E6%9B%B4) をご参照ください。

## 監査ログの種類ごとの列の定義 [](#監査ログの種類ごとの列の定義)

以下は監査ログの種類（ `audit_log_type` ）ごとの列の定義です。

使用する監査ログの種類に合わせて必要な列の定義をテーブルに追加してご使用ください。

### すべての操作で共通 [](#すべての操作で共通)

```
`timestamp` string,
`message` string,
`tenant_id` string,
`client_ip` string,
`context_id` string,
`user` struct<id:string,name:string,email:string>,
`service_account` struct<id:string,name:string>,
```

操作の実行者がユーザーの場合は `user` 、サービスアカウントの場合は `service_account` が出力されます。

### プロジェクト内のすべての操作で共通 [](#プロジェクト内のすべての操作で共通)

```
`project` struct<id:string,name:string>
```

### 環境内のすべての操作で共通 [](#環境内のすべての操作で共通)

```
`environment` struct<id:string,name:string>
```

### `execute_action` [](#execute_action)

```
`arguments` array<struct<name:string,value:string,type:string>>,
`bmrn` struct<resource:string,class:string,class_id:string>,
`action` struct<id:string,name:string,display_id:string,created_at:string,updated_at:string>,
`action_version` struct<version_type:string,id:string,name:string>,
`status` string,
`failure_message` string,
```

### `create_review_request` [](#create_review_request)

```
`arguments` array<struct<name:string,value:string,type:string>>,
`action` struct<id:string,name:string,display_id:string,created_at:string,updated_at:string>,
`review_setting` struct<id:string,name:string>,
`review_request` struct<id:string,description:string,created_at:string,expires_in:string>,
```

### `approve_review_request`, `reject_review_request` [](#approve_review_requestreject_review_request)

```
`action` struct<id:string,name:string,display_id:string,created_at:string,updated_at:string>,
`review_request` struct<id:string,created_at:string,expires_in:string>,
`status` string,
```

### `execute_action_with_review_request` [](#execute_action_with_review_request)

```
`arguments` array<struct<name:string,value:string,type:string>>,
`action` struct<id:string,name:string,display_id:string,created_at:string,updated_at:string>,
`review_request` struct<id:string>,
```

### `create_datasource`, `update_datasource`, `delete_datasource` [](#create_datasourceupdate_datasourcedelete_datasource)

```
`datasource` struct<id:string,name:string,class:string>,
```

### `create_action` [](#create_action)

```
`bmrn` struct<resource:string,class:string,class_id:string>,
`action` struct<id:string,name:string,display_id:string,created_at:string,updated_at:string>,
`review_setting` struct<id:string,name:string>,
`notification_settings` struct<on_success:struct<enabled:boolean,notification_method_id:string,mention_target_user_ids:array<string>>,on_error:struct<enabled:boolean,notification_method_id:string,mention_target_user_ids:array<string>>>,
```

### `update_action` [](#update_action)

```
`bmrn` struct<resource:string,class:string,class_id:string>,
`action` struct<id:string,name:string,display_id:string,created_at:string,updated_at:string>,
`review_setting` struct<id:string,name:string>,
`notification_settings` struct<on_success:struct<enabled:boolean,notification_method_id:string,mention_target_user_ids:array<string>>,on_error:struct<enabled:boolean,notification_method_id:string,mention_target_user_ids:array<string>>>,
`job_detail_visibility` string,
```

### `delete_action` [](#delete_action)

```
`bmrn` struct<resource:string,class:string,class_id:string>,
`action` struct<id:string,name:string,display_id:string,created_at:string,updated_at:string>,
```

### `update_action_display_ids` [](#update_action_display_ids)

```
`actions` array<struct<id:string,name:string,display_id:string,created_at:string,updated_at:string>>,
```

### `create_or_update_environment_action_settings` [](#create_or_update_environment_action_settings)

```
`environment_action_settings` array<struct<environment:struct<id:string,name:string>,action_version:struct<version_type:string,id:string,name:string>,enabled:boolean,action:struct<id:string,name:string,display_id:string,created_at:string,updated_at:string>>>,
```

### `create_view`, `update_view`, `delete_view` [](#create_viewupdate_viewdelete_view)

```
`view` struct<id:string,name:string,display_id:string>,
```

### `create_users`, `delete_users` [](#create_usersdelete_users)

```
`target_users` array<struct<id:string,name:string,email:string>>,
```

### `update_user` [](#update_user)

```
`target_user` struct<id:string,name:string,email:string>,
`is_tenant_admin` boolean,
```

### `create_project_users`, `delete_project_users` [](#create_project_usersdelete_project_users)

```
`project_users` array<struct<id:string,name:string,email:string>>,
```

### `create_service_accounts`, `update_service_accounts`, `delete_service_accounts` [](#create_service_accountsupdate_service_accountsdelete_service_accounts)

```
`service_accounts` array<struct<id:string,name:string,email:string>>,
```

### `create_project_service_accounts`, `delete_project_service_accounts` [](#create_project_service_accountsdelete_project_service_accounts)

```
`project_service_accounts` array<struct<id:string,name:string,email:string>>,
```

### `assign_service_accounts_to_user_group` [](#assign_service_accounts_to_user_group)

```
`service_accounts` array<struct<id:string,name:string,email:string>>,
`user_group` struct<id:string,name:string,admin_roles:array<string>>,
```

### `update_service_account_oidc_trust_policies` [](#update_service_account_oidc_trust_policies)

```
`service_account` struct<id:string,name:string,email:string>,
`oidc_trust_policies` array<struct<id:string,issuer:string,audience:string,bound_claims:array<struct<claim_key:string,claim_pattern:string>>>>,
```

### `create_user_group`, `update_user_group`, `delete_user_group` [](#create_user_groupupdate_user_groupdelete_user_group)

```
`target_user_group` struct<id:string,name:string,admin_roles:array<string>>,
```

### `assign_users_to_user_group` [](#assign_users_to_user_group)

```
`users` array<struct<id:string,name:string,email:string>>,
`user_group` struct<id:string,name:string,admin_roles:array<string>>,
```

### `update_user_group_assignments` [](#update_user_group_assignments)

```
`user_group_assignments` array<struct<user:struct<id:string,name:string,email:string>,user_groups:array<struct<id:string,name:string,admin_roles:array<string>>>>>,
```

### `create_review_setting`, `update_review_setting` [](#create_review_settingupdate_review_setting)

```
`review_setting` struct<id:string,name:string>,
`environment_review_settings` array<struct<environment:struct<id:string,name:string>,self_approval_enabled:boolean,approver_execution_enabled:boolean,user_approval_conditions:array<struct<user:struct<id:string,name:string,email:string>>>,user_group_approval_conditions:array<struct<user_group:struct<id:string,name:string>,required_count:integer>>,approval_patterns:array<struct<user_approvers:array<struct<user:struct<id:string,name:string,email:string>>>,user_group_approvers:array<struct<user_group:struct<id:string,name:string>,min_approvals:integer>>>>,auto_self_approval_enabled:boolean,auto_execute_on_approval_policy:struct<policy_type:string,default_enabled:boolean>>>,
```

承認条件は `approval_patterns` に出力されます。いずれかのパターンを満たすと承認され、1つのパターン内の承認者はすべての承認が必要です。 `user_approvers` はユーザー、 `user_group_approvers` はグループの承認者で、グループの `min_approvals` はそのグループに必要な最低承認人数です。 `user_approval_conditions` と `user_group_approval_conditions` は後方互換のために残しているフィールドです。

### `delete_review_setting` [](#delete_review_setting)

```
`review_setting_id` string,
```

### `update_environment_access_control` [](#update_environment_access_control)

```
`target_environment` struct<id:string,name:string,access_control_enabled:boolean>,
`target_users` array<struct<id:string,name:string,email:string>>,
`target_user_groups` array<struct<id:string,name:string,admin_roles:array<string>>>,
```

### `login_succeeded` [](#login_succeeded)

[すべての操作で共通](/admin/security/audit_log/search/s3/#%E3%81%99%E3%81%B9%E3%81%A6%E3%81%AE%E6%93%8D%E4%BD%9C%E3%81%A7%E5%85%B1%E9%80%9A) の列の定義のみです。ユーザーのログインの場合は `user` 、サービスアカウントのログインの場合は `service_account` が出力されます。

### `connect_slack`, `disconnect_slack` [](#connect_slack-disconnect_slack)

```
`slack_workspace` struct<workspace_name:string>,
```

### `create_slack_notification_method`, `update_slack_notification_method` [](#create_slack_notification_method-update_slack_notification_method)

```
`notification_method` struct<id:string,name:string>,
`environment_slack_notification_methods` array<struct<environment:struct<id:string,name:string>,channel_id:string>>,
```

### `delete_notification_method` [](#delete_notification_method)

```
`notification_method` struct<id:string,name:string>,
```

### `create_action_cron_job` [](#create_action_cron_job)

```
`action_cron_job` struct<id:string,name:string>,
`action_cron_job_schedule` string,
`action` struct<id:string,name:string,display_id:string,created_at:string,updated_at:string>,
```

### `pause_action_cron_job`, `resume_action_cron_job`, `deactivate_action_cron_job`, `update_action_cron_job_name` [](#pause_action_cron_job-resume_action_cron_job-deactivate_action_cron_job-update_action_cron_job_name)

```
`action_cron_job` struct<id:string,name:string>,
```

### `update_action_cron_job_schedule` [](#update_action_cron_job_schedule)

```
`action_cron_job` struct<id:string,name:string>,
`action_cron_job_schedule` string,
```

### `update_action_cron_job_action` [](#update_action_cron_job_action)

```
`action_cron_job` struct<id:string,name:string>,
`action` struct<id:string,name:string,display_id:string,created_at:string,updated_at:string>,
```

### `rerun_scheduled_action_cron_job` [](#rerun_scheduled_action_cron_job)

```
`action_cron_job` struct<id:string,name:string>,
`action_cron_job_scheduled_at` string,
```

[検索](/admin/security/audit_log/search/) [SAML SSO](/admin/security/saml/)
---
管理設定

セキュリティ・監査

[監査ログ](/admin/security/audit_log/)

ストリーミング

# 監査ログのストリーミング

ベースマキナの画面上で操作するたびに監査ログをストリーミングできます。

ストリーミングされる監査ログは通常ベースマキナ内に保存される監査ログの内容に加えて、アクション実行時の引数の入力値など、より詳細な情報を含んでいます。

また、有効期限もお客さまのストレージの設定に依存するため、より長期間にわたって監査ログを保存できます。

社内にのみ保存したい情報を含めてこまめに監査ログを自動で保存したい場合にお使いいただけます。

設定すると、以下の `/2024-08-16/execute_action/2024-08-16T00:02:01.122Z.json` のように、日付、操作の種類、実行時間をキーとしたJSONファイルが保存されます。保存先のパス形式は [設定で変更](/admin/security/audit_log/streaming/#%E4%BF%9D%E5%AD%98%E5%85%88%E3%81%AE%E3%83%91%E3%82%B9%E5%BD%A2%E5%BC%8F%E3%81%AE%E5%A4%89%E6%9B%B4) できます。

![S3 Saved JSON](/images/audit_log/streaming_saved_json.png)

現在、ストリーミング先はAmazon S3および、Google Cloud
Storageのみ指定が可能です。他のストレージへのストリーミングをご希望の場合はご要望の連絡をいただければ幸いです。

## Amazon S3へのストリーミング

Amazon S3へストリーミングするには、以下の手順を実行してください。

1. Amazon S3のバケットを作成します。

![S3バケットの作成](/images/audit_log/streaming_s3_bucket.png)

1. Amazon S3のバケットに対してPutObject権限を持ったIAMユーザーの作成

ポリシーを定義して `PutObject` の権限を持ったIAMユーザーを作成し、S3バケットに監査ログをストリーミングする権限を用意します。

![PutObjectPolicy](/images/audit_log/streaming_policy.png)

1. アクセスキー・シークレットの発行

IAMユーザーのセキュリティ認証情報から「アクセスキーを作成」し、アクセスキーとシークレットキーを取得します。

![PutObjectPolicy](/images/audit_log/streaming_keygen.png)

1. ベースマキナの [監査ログ (opens in a new tab)](https://basemachina.com/settings/audit-log) のページから、Amazon S3へのストリーミングを設定します。

![S3 Streaming Form](/images/audit_log/streaming_s3_form.png)

## Google Cloud Storageへのストリーミング [](#google-cloud-storageへのストリーミング)

Google Cloud Storageへストリーミングするには、以下の手順を実行してください。

1. GCSのバケットを作成します。
1. GCSにファイルアップロードするためのサービスアカウントを作成し、ロールを割り当てます。
  - サービスアカウントには、 `storage.objects.create` の権限が必要となります。
  - サービスアカウント作成の手順については、 [Google Cloud Storage連携](/action/datasources/gcs_integration/#%E3%82%B5%E3%83%BC%E3%83%93%E3%82%B9%E3%82%A2%E3%82%AB%E3%82%A6%E3%83%B3%E3%83%88%E3%81%AE%E4%BD%9C%E6%88%90) のドキュメントを参照ください。
1. サービスアカウントキーをダウンロードします。
1. ベースマキナの [監査ログ (opens in a new tab)](https://basemachina.com/settings/audit-log) のページから、GCSへのストリーミングを設定します。

![GCS Streaming Form](/images/audit_log/streaming_gcs_form.png)

## 保存先のパス形式の変更 [](#保存先のパス形式の変更)

ストリーミング設定フォームの「保存先のパス形式」から、ログファイルの保存先パスの形式を変更できます。

| パス形式 | パスの例 |
| --- | --- |
| 日付 / 種別（デフォルト） | `2026-01-28/approve_review_request/2026-01-28T10:30:45.123Z.json` |
| 種別 / 日付 | `approve_review_request/2026-01-28/2026-01-28T10:30:45.123Z.json` |

パス形式を選択すると、フォーム内にパスの例がプレビュー表示されます。

⚠️

パス形式を変更しても、変更前のログは以前のパス形式のまま残ります。変更後に保存されるログのみ新しいパス形式が適用されます。

[CSVファイル出力](/admin/security/audit_log/csv_download/) [検索](/admin/security/audit_log/search/)
---
管理設定

セキュリティ・監査

認証ポリシー

# 認証ポリシー

認証ポリシーを使うと、許可するログイン方法のセットを名前付きで定義し、ユーザーに割り当てられます。ほとんどのメンバーではSAML SSOによるログインのみを許可したいが、一部のユーザーのみメール/パスワードによるログインも許可したい、といったように、ユーザーの属性ごとにログイン方法を分けて運用できます。

各ユーザーは必ず1つの認証ポリシーに所属し、そのポリシーで許可されたログイン方法だけでログインできます。

## 必要なロール [](#必要なロール)

認証ポリシーの作成・編集・削除や、ユーザーへの割り当てができるのは、企業アカウント管理者のみです。

- [企業アカウントの管理者権限](/admin/user_management/tenant_role/)

## ログイン方法の種類 [](#ログイン方法の種類)

認証ポリシーでは、次の3種類のログイン方法を組み合わせて許可できます。各ポリシーには少なくとも1つのログイン方法を許可する必要があります。

| ログイン方法 | 説明 |
| --- | --- |
| メール / パスワード | メールアドレスとパスワードでログインします。 |
| Google | Googleアカウントでログインします。 |
| SAML SSO | 企業アカウントで設定済みのIdP経由でログインします。 |

SAML SSOを許可するには、あらかじめ企業アカウントのセキュリティ設定でSAMLを設定しておく必要があります。SAMLが未設定の場合、ポリシー編集画面でSAML SSOは選択できません。

- [SAML SSO](/admin/security/saml/)

## デフォルトのポリシー [](#デフォルトのポリシー)

企業アカウントには、あらかじめデフォルトのポリシーが1つ用意されています。新しいポリシーを作成するまでは、すべてのユーザーがこのポリシーに所属します。デフォルトのポリシーは名前や許可するログイン方法を変更できます。

## 認証ポリシーを作成する [](#認証ポリシーを作成する)

[企業アカウント設定のセキュリティ画面 (opens in a new tab)](https://basemachina.com/settings/security) から認証ポリシーの一覧を開き、「ポリシーを追加」を選びます。

![認証ポリシー一覧と「ポリシーを追加」ボタン](/images/auth_policies/policy_list.png)

1. ポリシー名を入力します。
1. 許可するログイン方法を選択します（少なくとも1つ）。
1. 「ポリシーを作成」を選びます。

ポリシーを作成したあとは、編集画面からユーザーを追加します。

![ポリシー作成フォーム](/images/auth_policies/create_form.png)

## 認証ポリシーを編集する [](#認証ポリシーを編集する)

一覧でポリシーを選ぶと編集画面が開きます。ポリシー名と許可するログイン方法を変更し、「変更を保存」を選びます。変更は、そのポリシーに所属するすべてのユーザーにすぐ反映されます。

![ポリシー編集画面](/images/auth_policies/edit_screen.png)

⚠️

あるログイン方法を許可から外すと、その方法でしかログインできないユーザーはログインできなくなる場合があります。許可するログイン方法を変更する際は、所属ユーザーが他の許可された方法でログインできるか確認してください。

## ポリシー単位で多要素認証を必須にする [](#ポリシー単位で多要素認証を必須にする)

多要素認証（MFA）を必須にするかどうかは、認証ポリシーごとに設定できます。企業アカウント全体で一律に決まるのではなく、ユーザーが所属する認証ポリシーによって、多要素認証が必須かどうかが決まります。

### 有効にする [](#有効にする)

ポリシー編集画面で「多要素認証を必須にする」をオンにし、「変更を保存」を選びます。

![ポリシー編集画面の「多要素認証を必須にする」設定](/images/auth_policies/policy_mfa_toggle.png)

オンにすると、そのポリシーに所属するユーザーは次回ログイン時に認証アプリの登録とワンタイムコードの入力が必須になります。

ポリシー一覧では、多要素認証が必須のポリシーに「多要素認証必須」バッジが表示されます。

![認証ポリシー一覧の「多要素認証必須」バッジ](/images/auth_policies/policy_mfa_badge.png)

### 無効にする [](#無効にする)

「多要素認証を必須にする」をオフにして保存すると、確認画面が表示されます（ワンタイムコードの入力は不要です）。解除すると、そのポリシーに所属するユーザーは、次回以降のログインで多要素認証を求められなくなります。

認証アプリの登録、ログイン時のワンタイムコードの入力、登録状態の確認とリセットの操作は、 [多要素認証（MFA）](/admin/security/mfa/) と共通です。

## ユーザーをポリシーに割り当てる [](#ユーザーをポリシーに割り当てる)

各ユーザーは1つの認証ポリシーに所属します。割り当ては次のいずれかの方法でできます。

### ユーザーの招待時に割り当てる [](#ユーザーの招待時に割り当てる)

新しいユーザーを招待するときに、所属させる認証ポリシーを選択します。認証ポリシーの選択は必須です。

- [企業アカウントのユーザー管理](/admin/user_management/tenant_add_new_user/)

### ユーザーの編集画面で変更する [](#ユーザーの編集画面で変更する)

ユーザーの編集画面で「認証ポリシー」を選び直すと、そのユーザーの所属ポリシーを変更できます。

### ポリシー編集画面からまとめて移動する [](#ポリシー編集画面からまとめて移動する)

ポリシー編集画面の「所属ユーザー」で「ユーザーを追加」を選ぶと、他のポリシーに所属しているユーザーを、このポリシーへまとめて移動できます。一覧から対象のユーザーをチェックして「移動」を選ぶと、選択したユーザーの所属ポリシーが現在のポリシーから移動します。

![ユーザー追加（移動）モーダル](/images/auth_policies/add_user_modal.png)

## 認証ポリシーを削除する [](#認証ポリシーを削除する)

ポリシー編集画面の「ポリシーを削除」から削除できます。

ポリシーを削除できるのは、所属ユーザーがいない場合のみです。所属ユーザーがいる場合は、先に所属ユーザーを別のポリシーへ移動してください。

![ポリシー削除の確認モーダル](/images/auth_policies/delete_modal.png)

## 企業アカウントの認証設定との関係 [](#企業アカウントの認証設定との関係)

認証ポリシーで許可できるログイン方法は、企業アカウント全体の認証設定で有効になっている方法の範囲内です。たとえばSAML SSOは、企業アカウントでSAMLを設定していないと許可できません。

[IPアドレス制限](/admin/security/ip_restriction/) [環境とは](/admin/environment/what_is_environment/)
---
管理設定

セキュリティ・監査

IPアドレス制限

# IPアドレス制限

ベースマキナへのアクセスを一部のIPアドレスからのみに制限できます。制限はホワイトリスト形式です。

- 許可するIPアドレス（CIDR表記）
- 詳細（IPアドレスの説明）

の組み合わせを複数登録できます。

許可するIPアドレスはCIDR表記による範囲指定となります。
具体的なIPアドレス1つのみを許可したいケースでは、CIDRのサブネットマスク部分を `/32` としてください。

![IPアドレス制限](/images/ip_restriction/form.png)

[こちら (opens in a new tab)](https://basemachina.com/settings/security) から設定が可能です。

IPアドレス制限は企業アカウント管理者のみ設定できます。

指定のIPアドレス以外からのアクセスだった場合、同じ企業アカウントのユーザーであってもアクション実行をはじめとする各種画面には移動できません。

また [環境別のIPアドレス制限](/admin/environment/ip_restriction/) の設定も可能です。

企業アカウント単位と環境別のIPアドレス制限が両方設定されている場合、両方で許可されているIPアドレスからのみアクセスできます。

[多要素認証（MFA）](/admin/security/mfa/) [認証ポリシー](/admin/security/auth_policies/)
---
管理設定

セキュリティ・監査

多要素認証（MFA）

# 多要素認証（MFA）

多要素認証（MFA）は、ログイン時にパスワードやGoogleログインなどの認証に加えて、認証アプリのワンタイムコード（TOTP）の入力を求める仕組みです。認証情報が漏えいした場合でも、不正なログインを防ぎやすくなります。

多要素認証を必須にするかどうかは、認証ポリシーごとに設定します。ユーザーは、自身が所属する認証ポリシーの設定に従って多要素認証を求められます。

ワンタイムコードの生成にはGoogle Authenticatorなどの認証アプリ（TOTPに対応したもの）を利用します。

## 必要なロール [](#必要なロール)

認証ポリシーでの多要素認証の設定や、ユーザーの登録状態の確認・リセットができるのは、企業アカウント管理者のみです。

- [企業アカウントの管理者権限](/admin/user_management/tenant_role/)

## 多要素認証を必須にする [](#多要素認証を必須にする)

認証ポリシーの編集画面で「多要素認証を必須にする」をオンにすると、そのポリシーに所属するユーザーは次回ログイン時に認証アプリの登録とワンタイムコードの入力を求められます。設定手順や解除方法の詳細は、認証ポリシーのドキュメントを参照してください。

- [ポリシー単位で多要素認証を必須にする](/admin/security/auth_policies/)

## ユーザーの認証アプリの登録 [](#ユーザーの認証アプリの登録)

多要素認証が必須のユーザーは、認証アプリが未登録の場合、ログイン後に登録画面が表示されます。

1. 認証アプリ（Google Authenticator等）で画面に表示されたQRコードを読み取ります。QRコードを読み取れない場合は、画面に表示されたキーを認証アプリに手動で入力します。
1. 認証アプリに表示された6桁のワンタイムコードを入力して、設定を完了します。

⚠️

ワンタイムコードは表示されてから5
分以内に入力してください。時間を過ぎた場合は、ログインからやり直してください。

## ログイン時の認証 [](#ログイン時の認証)

認証アプリの登録が済んだユーザーは、以降のログインでパスワードやGoogleログインなどによる認証のあとに、認証アプリに表示されている6桁のワンタイムコードの入力を求められます。コードの確認が完了してはじめてログインが完了します。

## ユーザーの登録状態の確認とリセット [](#ユーザーの登録状態の確認とリセット)

[ユーザー管理画面 (opens in a new tab)](https://basemachina.com/settings/users) のユーザー一覧には「多要素認証」の列が表示され、各ユーザーが認証アプリを登録済みか（ `登録済み` / `未登録` ）を確認できます。

認証アプリを登録済みのユーザーは、ユーザー行のメニューから「多要素認証をリセット」を実行できます。リセットすると、対象のユーザーは次回ログイン時に認証アプリの再登録が必要になります。端末の紛失や機種変更などで認証アプリが使えなくなったユーザーの登録をやり直す際に利用します。

[SAML SSO](/admin/security/saml/) [IPアドレス制限](/admin/security/ip_restriction/)
---
管理設定

セキュリティ・監査

SAML SSO

# SAML SSO

[こちら (opens in a new tab)](https://basemachina.com/settings/security) からSAMLの設定が可能です。

SAMLを設定できるのは企業アカウント管理者のみです。

ACSのURLやエンティティIDはご利用中のIDプロバイダの指示に従ってご利用ください。

![saml設定画面](/images/saml/saml.png)

ご利用中のIDプロバイダで提供されているSSO URL、エンティティID、X.509証明書の内容をそれぞれコピーして設定を保存します。

設定後、SAML SSOを利用したベースマキナへの認証をご利用できます。

![IDプロバイダ設定画面](/images/saml/id_provider.png)

[Amazon S3](/admin/security/audit_log/search/s3/) [多要素認証（MFA）](/admin/security/mfa/)
---
管理設定

組織やユーザーの設定

グループ

# グループ

「グループ」はプロジェクトユーザーをグルーピングして管理する機能です。

プロジェクトユーザーにグループを設定すると、以下ができるようになります。

- グループ単位でアクションの実行権限や承認条件などを設定する。
- グループに「開発者」などのロールを設定して、アクションや環境の設定ができるユーザーを制限する。

## グループ管理のページへ移動する [](#グループ管理のページへ移動する)

1. 右上のメニューから「設定」を選択してプロジェクト設定画面に移動します。
1. 左のサイドバーから「グループ管理」を選択してグループ管理画面に移動します。

![グループ管理ページ](/images/admin/user_management/project_group/groups.png)

## グループを追加する [](#グループを追加する)

1. 右上の「追加」ボタンからグループ作成画面に移動します。
1. 各項目を入力して保存します。

グループでは以下の項目を設定します。

- 名前
- ロール

ロールの詳細は「 [ロール](/admin/user_management/project_group/#%E3%83%AD%E3%83%BC%E3%83%AB) 」をご参照ください。

![グループの設定フォーム](/images/admin/user_management/project_group/setting_form.png)

## プロジェクトユーザーにグループを設定する [](#プロジェクトユーザーにグループを設定する)

1. プロジェクトユーザー一覧のユーザーのサブメニューから「グループを変更する」を選択して、グループ管理画面に移動します。

![プロジェクトユーザーの一覧](/images/admin/user_management/project_users/table.png)

1. グループを選択して保存します。

![プロジェクトユーザーのグループ設定](/images/admin/user_management/project_users/update_groups.png)

またグループの一覧から、特定のグループに所属するユーザーをまとめて変更できます。

1. グループ一覧のグループのサブメニューから「ユーザーを管理する」を選択して、グループのユーザー管理画面に移動します。

![グループ一覧のグループのサブメニュー](/images/admin/user_management/project_group/groups_submenu.png)

1. ユーザーを選択して保存します。

![グループのユーザー管理](/images/admin/user_management/project_group/group_user_manage.png)

## グループ単位で設定できる機能 [](#グループ単位で設定できる機能)

プロジェクトユーザーにグループを設定すると、各種機能がグループ単位で設定できるようになります。

- [アクションの実行権限](/action/action_permission/)
- [レビューの承認条件](/action/review/)
- [環境の利用制限](/admin/environment/access_control/)
- [ナビゲーション](/navigation/)

## ロール [](#ロール)

ロールを設定するとそのグループに所属するユーザーは、ロールに応じた管理権限を持ちプロジェクト内の設定ができるようになります。

以下がロールと各ロールが持つ管理権限の一覧です。

| 管理権限 | プロジェクト管理者 | プロジェクトユーザー管理者 | インフラ管理者 | 開発責任者 | 開発者 | アクション運用責任者 |
| --- | --- | --- | --- | --- | --- | --- |
| プロジェクトユーザー管理 | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
| グループ管理 | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
| プロジェクトの削除 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| プロジェクト名の変更 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| 環境設定 | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
| ナビゲーション設定 | ✅ | ✅ | ❌ | ✅ | ✅ | ❌ |
| アクション管理 | ✅ | ❌ | ❌ | ✅ | ✅ | ❌ |
| データソース管理 | ✅ | ❌ | ✅ | ✅ | ❌ | ❌ |
| ネットワーク設定 | ✅ | ❌ | ✅ | ✅ | ❌ | ❌ |
| 変数設定 | ✅ | ❌ | ❌ | ✅ | ✅ | ❌ |
| シークレット設定 | ✅ | ❌ | ✅ | ✅ | ❌ | ❌ |
| マスターデータ取得設定の設定 | ✅ | ❌ | ❌ | ✅ | ✅ | ❌ |
| ビュー管理 | ✅ | ❌ | ❌ | ✅ | ✅ | ❌ |
| 実行権限設定 | ✅ | ❌ | ❌ | ✅ | ❌ | ✅ |
| レビュー設定の設定 | ✅ | ❌ | ❌ | ✅ | ❌ | ✅ |
| アクションのバージョン・有効化の設定 | ✅ | ❌ | ❌ | ✅ | ❌ | ✅ |
| ビューのバージョン・有効化の設定 | ✅ | ❌ | ❌ | ✅ | ❌ | ✅ |
| 通知設定 | ✅ | ❌ | ❌ | ✅ | ❌ | ✅ |
| 定期実行の管理 | ✅ | ❌ | ❌ | ✅ | ✅ | ✅ |
| ジョブ結果の閲覧制限設定 | ✅ | ❌ | ❌ | ✅ | ❌ | ✅ |

### プロジェクト管理者 [](#プロジェクト管理者)

「プロジェクト管理者」は他のロールが持つすべての管理権限と「プロジェクト名の変更」「プロジェクトの削除」の管理権限を持つ特別なロールです。

「プロジェクト管理者」のロールは、プロジェクト作成時に自動で作成される「プロジェクト管理者」グループにのみ設定され、他のグループには設定できません。

### 管理権限のないプロジェクトユーザー [](#管理権限のないプロジェクトユーザー)

以下のプロジェクトユーザーは管理権限がないため、アクションの実行やレビューの依頼・承認などの操作のみができます。

- ロールのないグループのみに所属している
- グループに所属していない

[プロジェクトユーザーの管理](/admin/user_management/project_users/) [プロジェクトの作成・更新](/admin/user_management/project_settings/)
---
管理設定

組織やユーザーの設定

プロジェクトの作成・更新

# プロジェクトの作成・更新

## プロジェクトを追加する [](#プロジェクトを追加する)

新規プロジェクトの追加は [プロジェクト管理 (opens in a new tab)](https://basemachina.com/settings/projects) のページからできます。

「追加」をクリックします。

![プロジェクトを追加する](/images/project_settings/project_add.png)

追加したいプロジェクト名を入力して保存します。

![プロジェクトの名前を入力する](/images/project_settings/input_project_name.png)

新規プロジェクトを追加できるのは企業アカウント管理者のみです。

## プロジェクトの設定 [](#プロジェクトの設定)

プロジェクトの設定では以下の項目が設定できます。

- プロジェクト名
- 開発者向けメニューを表示しないグループ

![プロジェクトの設定画面](/images/project_settings/project_settings.png)

### プロジェクト名 [](#プロジェクト名)

プロジェクトの名前を設定できます。

### 開発者向けメニューを表示しないグループ [](#開発者向けメニューを表示しないグループ)

以下の開発者向けメニューへ移動する導線を非表示にするグループを設定できます。

![開発者メニューの一覧](/images/project_settings/developer_menu.png)

- アクション一覧
- ビュー一覧
- アクショングループ一覧
- レビュー依頼一覧

また特定の開発者メニューへ移動する導線のみを表示したい場合は、ナビゲーションをご利用ください。

遷移先の種類が「開発者メニュー」の要素を追加すると、アクション一覧画面などへの導線を表示できます。

ナビゲーションの設定方法は [「ナビゲーション」](/navigation/) をご参照ください。

[グループ](/admin/user_management/project_group/) [IPホワイトリスト](/admin/action/ip_whitelist/)
---
管理設定

組織やユーザーの設定

プロジェクトユーザーの管理

# プロジェクトユーザーの管理

## プロジェクトユーザー管理のページへ移動する [](#プロジェクトユーザー管理のページへ移動する)

1. 右上のメニューから「設定」を選択する
1. 左のサイドバーから「プロジェクトユーザー管理」を選択する

![プロジェクトユーザーの一覧](/images/admin/user_management/project_users/table.png)

## ユーザーをプロジェクトへ追加する [](#ユーザーをプロジェクトへ追加する)

企業アカウントに追加したユーザーをプロジェクトに追加します。

1. 「追加」ボタンからプロジェクトユーザー追加画面に移動します。
1. 追加するユーザーを選択して保存します。

※企業アカウントにユーザーを追加する方法は [「企業アカウントのユーザー管理」](/admin/user_management/tenant_add_new_user/) をご参照ください。

![プロジェクトユーザーの追加](/images/admin/user_management/project_users/create.png)

## プロジェクトユーザーにグループを設定する [](#プロジェクトユーザーにグループを設定する)

プロジェクトユーザーに [グループ](/admin/user_management/project_group/) を設定すると、プロジェクトユーザーの権限管理やグループ単位でのアクションの実行権限や承認条件などが設定できます。

1. プロジェクトユーザー一覧のユーザーのサブメニューから「グループを変更する」を選択して、グループ管理画面に移動します。

![プロジェクトユーザーの一覧](/images/admin/user_management/project_users/table.png)

1. グループを選択して保存します。

![プロジェクトユーザーのグループ設定](/images/admin/user_management/project_users/update_groups.png)

またグループの一覧から、特定のグループに所属するユーザーをまとめて変更できます。

1. グループ一覧のグループのサブメニューから「ユーザーを管理する」を選択して、グループのユーザー管理画面に移動します。

![グループ一覧のグループのサブメニュー](/images/admin/user_management/project_group/groups_submenu.png)

1. ユーザーを選択して保存します。

![グループのユーザー管理](/images/admin/user_management/project_group/group_user_manage.png)

[企業アカウントの管理者権限](/admin/user_management/tenant_role/) [グループ](/admin/user_management/project_group/)
---
管理設定

組織やユーザーの設定

企業アカウントのユーザー管理

# 企業アカウントのユーザー管理

[企業アカウント設定のユーザー管理画面 (opens in a new tab)](https://basemachina.com/settings/users) から企業アカウントのユーザーを管理できます。

![企業アカウントのユーザー管理画面](/images/admin/user_management/tenant_add_new_user/users.png)

## ユーザーを追加する [](#ユーザーを追加する)

ユーザーの追加では以下の項目を設定します。

- 名前
- メールアドレス
- 企業アカウントの管理者フラグ

![企業アカウントへのユーザー追加画面](/images/admin/user_management/tenant_add_new_user/create_users.png)

ユーザーを追加すると設定したメールアドレスに招待メールが送信されます。

![招待メール](/images/admin/user_management/tenant_add_new_user/invitation_mail.png)

招待メールを受け取ったユーザーがメールに記載されたリンクからパスワード設定画面に移動できます。

![パスワード設定画面](/images/admin/user_management/tenant_add_new_user/password_setting.png)

パスワードを設定してログインしたらユーザーの追加が完了です。

※Googleアカウントの場合はOAuthログインが可能です。

[アクションを実行する](/preview/remote_mcp/execute_actions/) [企業アカウントの管理者権限](/admin/user_management/tenant_role/)
---
管理設定

組織やユーザーの設定

企業アカウントの管理者権限

# 企業アカウントの管理者権限

「企業アカウントの管理者権限」を設定すると、企業アカウントのユーザー管理やセキュリティ設定などを特定のユーザーのみが設定できるように制限できます。

## 企業アカウントの管理者のみができること [](#企業アカウントの管理者のみができること)

企業アカウントの管理者のみ以下の操作ができます。

- 企業アカウント設定画面内の操作
  - 企業アカウントのユーザー管理
  - 企業アカウントのセキュリティ設定
  - 決済設定の確認
  - 監査ログの設定・出力
- プロジェクトの作成

## 企業アカウントのユーザーの権限の設定方法 [](#企業アカウントのユーザーの権限の設定方法)

[企業アカウント設定のユーザー管理画面 (opens in a new tab)](https://basemachina.com/settings/users) から各ユーザーの「企業アカウントの管理者権限」を設定できます。

![企業アカウントのユーザー管理画面](/images/admin/user_management/tenant_add_new_user/users.png)

[企業アカウントのユーザー管理](/admin/user_management/tenant_add_new_user/) [プロジェクトユーザーの管理](/admin/user_management/project_users/)
---
AI活用

AI活用とは

# AI活用とは

ベースマキナは、自社のデータを使った社内向けシステムをローコードで作れるサービスです（詳しくは [ベースマキナとは](/) を参照してください）。

このページでは、ベースマキナとAIを組み合わせると、社内の業務でどんなことができるのかを紹介します。

社内システムにAIを取り入れるとき、難しいのはAIそのものよりも「AIに社内のデータをどこまで触らせるか」です。ベースマキナは、AIに任せられる仕事を増やしながら、権限管理・レビュー・監査ログでAIの行動を統制できます。

## ベースマキナとAIでできること [](#ベースマキナとaiでできること)

ベースマキナでは、次の4つの形でAIを活用できます。気になるものから読み進めてください。

| 活用の形 | こんなことができる |
| --- | --- |
| AIエージェントに設定構築を任せる | 社内システムの設定づくりをAIエージェントに手伝ってもらう |
| アクションからLLMを呼び出す | 審査・要約・翻訳などの業務をAIで自動化する |
| AIエージェントにアクションを実行させる | AIエージェントに社内システムの操作を任せる |
| 監査ログをAIで分析する | 蓄積した操作ログをAIで分析し、運用を改善する |

AIに業務を任せるときの安全性については、 [AIを安全に業務へ組み込む仕組み](/ai_integration/#ai%E3%82%92%E5%AE%89%E5%85%A8%E3%81%AB%E6%A5%AD%E5%8B%99%E3%81%B8%E7%B5%84%E3%81%BF%E8%BE%BC%E3%82%80%E4%BB%95%E7%B5%84%E3%81%BF) も参照してください。

## 1. AIエージェントに設定構築を任せる [](#1-aiエージェントに設定構築を任せる)

Claude Code / Codex CLI / Cursorなどの「AIエージェント」（指示を受けてコードを作成・編集するAIツール）に、ベースマキナの設定づくりを任せられます。

たとえば「ユーザーを検索する [アクション](/action/) を追加して」と頼むと、エージェントがアクションの定義やコードを作成し、反映前の差分をプレビューします。設定者は、生成された差分のレビューに集中できます。

この活用には、設定をコードで管理する [コード管理](/code_management/) 機能と、AIエージェント向けの [Agent Skill](/ai_integration/skill/) を使います。

## 2. アクションからLLMを呼び出して業務を自動化する [](#2-アクションからllmを呼び出して業務を自動化する)

ベースマキナでは、SQLの実行やAPI呼び出しといったデータソースへの操作を「 [アクション](/action/) 」という単位で登録します。このアクションのなかで外部のLLM（GeminiやOpenAIなどの大規模言語モデル）を呼び出すと、データの取得からAIによる判断・変換までを1つの処理として自動化できます。

処理の流れは次のとおりです。

1. データベースや管理用APIから必要なデータを取得する
1. 取得したデータと指示文（プロンプト）を組み立てる
1. LLMを呼び出して、審査・要約・翻訳などをさせる
1. 結果を画面に表示する、またはデータベースに保存する

代表的なユースケースは次のとおりです。

| ユースケース | どんな業務を自動化するか |
| --- | --- |
| [コンテンツの審査自動化](/usecase/ai_integration/screening/) | 入稿コンテンツの一次審査をAIにさせ、人の確認の負担を下げる |
| [サポート対応時のユーザーサマリ生成](/usecase/ai_integration/customer_support_summary/) | 問い合わせ対応に必要な情報を集約し、AIに要約させる |
| [マスターデータの多言語翻訳](/usecase/ai_integration/master_data_translator/) | 商品マスターデータをAIで多言語に翻訳する |

LLMを呼び出すアクションの共通的な設定方法は、 [AIプラットフォームへの接続](/usecase/ai_integration/ai_platform_connection/) を参照してください。

これらのアクションを [定期実行](/action/cron_jobs/) すれば、夜間バッチでの翻訳や要約のように、AIを使った処理を定期的に自動実行できます。

## 3. AIエージェントにアクションを実行させる [](#3-aiエージェントにアクションを実行させる)

[公開API](/public_api/) を使うと、AIエージェントがベースマキナのアクションをツールとして実行できます。

![AIエージェントがベースマキナのアクションを実行するデモ動画](/images/ai_integration/ai_action_collaboration.gif)

データソースを直接操作させるのではなくアクションを通すことで、AIエージェントが実行できる操作を、設定者が定義したアクションの範囲に限定できます。認証方法やエンドポイントの詳細は [公開API](/public_api/) を参照してください。

## 4. 監査ログをAIで分析して運用を改善する [](#4-監査ログをaiで分析して運用を改善する)

ベースマキナの [監査ログ](/admin/security/audit_log/) には、アクションの実行や設定変更などの操作が記録されます。蓄積したログをエクスポートして手元のAIに分析させると、運用の改善点を見つけられます。

分析の切り口の例は次のとおりです。

- **利用状況の分析**: どのアクションが誰にどれだけ実行されているかを集計する
- **失敗・エラーの傾向分析**: 実行に失敗したログを、エラーの内容ごとに分類する
- **アクセスパターンの点検**: 通常と異なる時間帯・頻度の実行や、不自然なアクセスを抽出する

ログのエクスポート方法は、 [CSVファイル出力](/admin/security/audit_log/csv_download/) や [ストリーミング](/admin/security/audit_log/streaming/) を参照してください。監査ログの加工はベースマキナ側ではせず、エクスポートしたログを手元のAIやお客さまのシステムで分析します。

## AIを安全に業務へ組み込む仕組み [](#aiを安全に業務へ組み込む仕組み)

AIエージェントに社内システムやデータを操作させる場合、過剰な権限による情報漏洩、不可逆な誤操作、操作内容を追跡できないことがリスクになります。ベースマキナは、これらのリスクを次の機能で抑えます。

| 機能 | AI活用における役割 |
| --- | --- |
| [アクション](/action/) による抽象化 | データソースの接続情報やSQLを直接わたすのではなく、設定者が定義・検証したアクションだけをAIエージェントにわたせる |
| [実行権限](/action/action_permission/) ・ [グループ](/admin/user_management/project_group/) | AIエージェント用のサービスアカウントを、所属グループ単位で最小限の権限に絞れる |
| [レビュー設定](/action/review/) | AIエージェントによる変更や実行に人による承認を挟める。公開APIはレビューが必須のアクションを直接実行できない |
| [監査ログ](/admin/security/audit_log/) | AIエージェントの実行を含むすべての操作を記録し、後から追跡できる |
| [サービスアカウント](/service_account/) | AIエージェントを独立した実行主体として扱い、長期的な認証情報を持たせずに短命なトークンで認証できる |

## 関連情報 [](#関連情報)

- [Agent Skill](/ai_integration/skill/) — コード管理を扱うAgent Skill `bm-code-management` の導入方法
- [コード管理とは](/code_management/) — AIエージェントに任せられるコード管理機能の概要
- [公開APIとは](/public_api/) — アクションを外部から実行する公開APIの概要
- [AI活用のユースケース](/usecase/ai_integration/) — アクションからLLMを呼び出す業務自動化の具体例

[ナビゲーション](/navigation/) [Agent Skill](/ai_integration/skill/)
---
AI活用

Agent Skill

# Agent Skill

[`basemachina/skills` (opens in a new tab)](https://github.com/basemachina/skills) リポジトリで、コード管理を扱う [Agent Skill (opens in a new tab)](https://agentskills.io/specification) `bm-code-management` を公開しています。

## できること [](#できること)

このskillをAIエージェントに導入すると、以下の作業をエージェントに任せられます。

- `defineAction` / `defineConfig` の編集
- JavaScriptアクションのコード本体の作成・編集
- `bm sync --dry` での差分プレビュー

## 対応エージェント [](#対応エージェント)

`bm-code-management` は以下のエージェントに導入できます。

- Claude Code
- Codex CLI
- Cursor
- GitHub Copilot CLI
- Gemini CLI

## 導入方法 [](#導入方法)

`npx skills` を使う場合、以下のコマンドでプロジェクトスコープに `bm-code-management` を導入します。

```
npx skills add basemachina/skills --skill bm-code-management --yes
```

ほかのインストール方法（ `gh skill install` やClaude Code plugin marketplaceなど）や、対応エージェントの最新情報は、 [`basemachina/skills` のREADME (opens in a new tab)](https://github.com/basemachina/skills#readme) を参照してください。

## 関連情報 [](#関連情報)

- [AI活用とは](/ai_integration/) — AIエージェントと組み合わせた活用の全体像
- [コード管理とは](/code_management/) — skillが扱うコード管理機能の概要

[AI活用とは](/ai_integration/) [コード管理とは](/code_management/)
---
コード管理

コード管理とは

# コード管理とは

コード管理は、ベースマキナのアクション・ビューの設定をTypeScriptのコードとしてGitリポジトリで管理できる機能です。

設定内容をコードとして管理することで、以下のメリットがあります。

- **コードレビュー**: 設定変更をPull Requestでレビューできる
- **差分検出**: 設定変更の差分をCI上で自動検出し、PRにコメントとして表示できる
- **環境別の反映**: 開発環境から検証環境、本番環境へ段階的に反映できる
- **型安全な設定**: TypeScriptの型システムにより、設定ミスをコードの記述時に検出できる
- **変更履歴**: Gitの履歴で設定変更の経緯を追跡できる

## 全体像 [](#全体像)

コード管理では、以下のツールを使用します。

| ツール | 説明 |
| --- | --- |
| [`@basemachina/sdk` (opens in a new tab)](https://www.npmjs.com/package/@basemachina/sdk) | `@basemachina/sdk/oac` からアクション・ビューの設定をTypeScriptで記述するためのSDK関数を提供 |
| [`@basemachina/cli` (opens in a new tab)](https://www.npmjs.com/package/@basemachina/cli) | 設定の差分検出・反映や、Web管理アクション・ビューの取り込みを担うCLIツール（ `bm` コマンド） |
| [`basemachina/bm-action` (opens in a new tab)](https://github.com/basemachina/bm-action) | OIDC認証・ `bm sync` の実行・PRへのコメント投稿をまとめて扱うGitHub Actions用のComposite Action |

設定はTypeScriptファイル（ `basemachina.config.ts` ）に記述し、CLIコマンド [`bm sync`](/code_management/cli/sync/) で設定の差分検出や環境間の同期を実行します。Web UIで作成した未取り込みのWeb管理アクション・ビューは、 [`bm pull`](/code_management/cli/pull/) でリポジトリに取り込めます。GitHub Actionsと組み合わせることで、PRのマージをトリガーに自動で設定を反映できます。

## 始めるには [](#始めるには)

1. [始め方](/code_management/getting_started/) に従ってプロジェクトをダウンロードし、リポジトリをセットアップする
1. [設定ファイル](/code_management/configuration/) を編集してアクション・ビューを定義する
1. [CLIコマンド](/code_management/cli/sync/) で差分を確認し、反映する
1. Web UIで作成したアクション・ビューがある場合は [`bm pull`](/code_management/cli/pull/) で取り込む
1. [CI/CDの設定](/code_management/ci_cd/) でGitHub ActionsやGitLab CIを構成する
1. [運用例](/code_management/examples/two_branch/) を参考に開発・運用を進める

## AIエージェントとの連携 [](#aiエージェントとの連携)

コード管理は、AIエージェントと組み合わせて作業を効率化できます。 `defineAction` / `defineConfig` の編集や `bm sync --dry` での差分プレビューを、Agent Skill `bm-code-management` を通じてエージェントに任せられます。

詳しくは [AI活用とは](/ai_integration/) ・ [Agent Skill](/ai_integration/skill/) をご参照ください。

[Agent Skill](/ai_integration/skill/) [始め方](/code_management/getting_started/)
---
コード管理

CI/CDの設定

概要

# CI/CDの設定

CI/CDを使うと、PRやマージリクエスト（MR）の作成・マージをトリガーに、設定の差分検出や反映を自動化できます。コード管理は以下のCIサービスに対応しています。

- [GitHub Actions](/code_management/ci_cd/github_actions/) — 公式のComposite Action `bm-action` でOIDC認証・ `bm sync` 実行・PRコメント投稿を一括で扱う
- [GitLab CI](/code_management/ci_cd/gitlab_ci/) — `id_tokens` でOIDC ID Tokenを取得し、 `bm sync` を実行する

## 認証の考え方 [](#認証の考え方)

どちらのCIでも、 `bm sync` はOIDC ID Tokenを使ってベースマキナの **サービスアカウント** として認証します。CI/CDが発行したID Tokenを環境変数 `BM_OIDC_TOKEN` に設定すると、 `bm sync` がこれを参照します。

あらかじめ [サービスアカウント](/service_account/#oidc%E4%BF%A1%E9%A0%BC%E3%83%9D%E3%83%AA%E3%82%B7%E3%83%BC) に **OIDC信頼ポリシー** を設定し、CI/CDが発行するID Tokenの `Issuer` / `Audience` / `Bound Claims` が整合していることを確認してください。 `Issuer` や `Bound Claims` に設定する具体的な値はCIサービスごとに異なります。詳細は各ページをご参照ください。

`bm sync` は実行環境（GitHub Actions、GitLab CI、ローカル端末など）を自動で検出し、出力形式を切り替えます。GitHub ActionsおよびGitLab CI上では、変更の詳細を `<details>` タグで折り畳んでPRやMRのコメントに貼り付けやすいMarkdown形式で出力します。

## 認証先サービスアカウントの指定 [](#認証先サービスアカウントの指定)

`BM_OIDC_TOKEN` に設定したID Tokenが複数のサービスアカウントの信頼ポリシーに合致しうる場合があります。このとき、環境変数 `BM_SERVICE_ACCOUNT_EMAIL` に認証先のサービスアカウントのメールアドレスを設定すると、どのサービスアカウントとして認証するかを指定できます。省略した場合は、合致した信頼ポリシーのうち最初の1件が選ばれます。複数のポリシーに合致しうる状況では意図しないサービスアカウントとして認証される可能性があるため、 `BM_SERVICE_ACCOUNT_EMAIL` を指定して曖昧さをなくすことを推奨します。

[bm pull](/code_management/cli/pull/) [GitHub Actions](/code_management/ci_cd/github_actions/)
---
コード管理

CI/CDの設定

GitHub Actions

# GitHub Actions

GitHub Actionsを使って、PRの作成やマージをトリガーに設定の差分検出や反映を自動化できます。

公式のComposite Action [`basemachina/bm-action` (opens in a new tab)](https://github.com/basemachina/bm-action) を使うと、OIDC ID Tokenの取得・ [`bm sync`](/code_management/cli/sync/) の実行・PRへのsticky-comment投稿を一括で担えます。

## 概要 [](#概要)

`bm-action` は以下のような自動化に対応しています。

- **PR作成時**: `bm sync --dry` で差分を検出し、PRにsticky-commentとして投稿する
- **PRマージ時**: `bm sync` で設定を開発環境に反映する
- **環境同期時**: `bm sync <環境ID>` で環境間のバージョンと有効化設定を同期する

ブランチ構成や環境の対応は、プロジェクトの運用に合わせて自由に設定できます。具体的な設定例は [運用例](/code_management/examples/two_branch/) をご参照ください。

## 認証 [](#認証)

`bm-action` は内部でGitHub Actionsの [OIDC ID Token (opens in a new tab)](https://docs.github.com/ja/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect) を取得し、ベースマキナのサービスアカウントとして認証します。あらかじめ [サービスアカウント](/service_account/#oidc%E4%BF%A1%E9%A0%BC%E3%83%9D%E3%83%AA%E3%82%B7%E3%83%BC) に **OIDC信頼ポリシー** を設定し、CI/CDが発行するID Tokenの `Issuer` / `Audience` / `Bound Claims` が整合していることを確認してください。

`audience` は `bm-action` の入力必須項目です。OIDC信頼ポリシーで登録した `Audience` と完全に一致する値を渡してください。漏洩したトークンが他の企業アカウントで悪用されるのを防ぐため、企業アカウントごとに固有の値（例： `https://<your-subdomain>.basemachina.com` ）を設定することを推奨します。OIDC信頼ポリシーの設定フォームでは、ご利用の企業アカウントのsubdomainを使った値が初期表示されます。

ローカルから `bm sync` を実行する場合は [`bm login`](/code_management/cli/login/) でブラウザログインし、トークンが `~/.basemachina/credentials.json` に保存されます。CI/CD上は環境変数 `BM_OIDC_TOKEN` が設定されていれば、そちらが優先されます。

## セットアップ [](#セットアップ)

### `bm-action` を使ったワークフロー [](#bm-actionを使ったワークフロー)

`bm-action` を使うと、以下のように数ステップでワークフローを構成できます。

```
name: BaseMachina Sync (dev)
on:
  pull_request:
    branches: [main]
  push:
    branches: [main]
 
permissions:
  contents: read
  id-token: write # OIDC ID Tokenの発行に必須
  pull-requests: write # PRコメントの投稿に必要
  packages: read # @basemachina/cli の取得に必要
 
jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: "22"
      - run: npm ci
      - run: npx tsc --noEmit
      - uses: basemachina/bm-action@v1
        with:
          audience: "https://<your-subdomain>.basemachina.com"
          with-disable: "true"
```

`npx tsc --noEmit` で型チェックを通してから `bm-action` を実行すると、設定ファイルやJavaScriptアクションの型エラーを同期前に検出できます。同じリポジトリで管理しているビューのコード（コード取得設定）も検査したい場合は、 `tsconfig.json` の `include` にビューのファイルを追加してください。設定方法は [コード取得設定との連携](/code_management/examples/view_code_fetch/) をご参照ください。

開発環境への反映時は `with-disable: "true"` を指定すると、設定ファイルから削除されたコード管理のアクション・ビューが開発環境で無効化されます。削除を反映したい運用でのみ指定してください。環境IDを指定した同期では、同期元で無効化されているアクション・ビューも同期先へ無効状態として反映されます。詳しくは [`bm sync` のオプション](/code_management/cli/sync/) をご参照ください。

Web UIで作成した未取り込みのアクション・ビューは、ローカルで [`bm pull`](/code_management/cli/pull/) を実行してリポジトリに取り込み、通常のPRとしてレビューしてください。 `bm-action` は `bm sync` の実行を扱うため、 `bm pull` によるファイル生成は開発者の作業として実施します。

### `bm-action` の入力 [](#bm-actionの入力)

| 入力 | 必須 | デフォルト | 説明 |
| --- | --- | --- | --- |
| `audience` | はい | — | OIDC ID Tokenに要求する `Audience` 。OIDC信頼ポリシーに登録した `Audience` と完全一致させる |
| `environment-id` | いいえ | `""` | 同期先の環境ID。未指定の場合は開発環境への反映 |
| `from` | いいえ | `""` | 同期元の環境ID（環境ID指定時のみ使用可） |
| `working-directory` | いいえ | `"."` | `basemachina.config.ts` が存在するディレクトリ |
| `dry` | いいえ | `"auto"` | dry-run制御。 `auto` は `pull_request` イベント時に自動でdry-run、 `true` で常にdry、 `false` で常時適用 |
| `with-disable` | いいえ | `"false"` | `--with-disable` を付与。開発環境への反映では設定ファイルに存在しないコード管理のアクション・ビューを無効化し、環境ID指定時は同期元の無効状態を同期先へ反映 |

`dry: "auto"` を指定すると、 `pull_request` イベントでは自動的に `bm sync   --dry` が実行され、PRに差分が投稿されます。 `push` イベントでは `bm   sync` が実行され、変更が反映されます。

### Permissions [](#permissions)

呼び出し側のワークフローには、以下のpermissionsが必要です。

```
permissions:
  contents: read # actions/checkout 用
  id-token: write # OIDC ID Token の取得用
  pull-requests: write # sticky-comment の投稿用
  packages: read # @basemachina/cli の取得用
```

## 動作の流れ [](#動作の流れ)

### PR作成時の差分検出 [](#pr作成時の差分検出)

1. PRが作成されると、CIが `bm-action` を実行します。
1. `dry: "auto"` の場合、 `bm sync --dry` が実行されて設定の差分が検出されます。
1. 差分の内容がPRに **sticky-comment** として投稿されます。開発環境への反映では `## bm sync 実行後、以下の変更が適用されます` 、環境への同期では `## bm sync 実行後、以下の変更が同期されます` というヘッダーで表示されます。同じPRで何度CIが走っても、コメントが新規投稿されるのではなく1つのコメントが上書きされます。

これにより、マージ前に設定変更の影響を確認できます。

`bm sync` は実行環境を自動で検出し、GitHub
ActionsおよびGitLab CI上ではPRコメントに貼り付けやすいMarkdown形式（ `<details>` タグで折り畳み可能）で出力します。

### PRマージ時の反映 [](#prマージ時の反映)

1. PRがマージされると、CDが `bm-action` を実行します。
1. `dry: "auto"` の場合、 `push` イベントでは `bm sync` が実行されます。
1. 設定の差分がベースマキナの開発環境に反映されます。

### 環境への同期 [](#環境への同期)

環境IDを `environment-id` に指定すると、 `bm sync <環境ID>` が実行され、環境間のバージョンと有効化設定が同期されます。

```
- uses: basemachina/bm-action@v1
  with:
    audience: "https://<your-subdomain>.basemachina.com"
    environment-id: "${{ vars.BM_PRD_ENV_ID }}"
```

[概要](/code_management/ci_cd/) [GitLab CI](/code_management/ci_cd/gitlab_ci/)
---
コード管理

CI/CDの設定

GitLab CI

# GitLab CI

GitLab CIを使って、マージリクエスト（MR）の作成やマージをトリガーに設定の差分検出や反映を自動化できます。

GitHub Actions向けの公式Composite Action [`bm-action`](/code_management/ci_cd/github_actions/) に相当するツールは、GitLab向けには提供していません。GitLab CIでは、 [`id_tokens` キーワード (opens in a new tab)](https://docs.gitlab.com/ci/secrets/id_token_authentication/) でOIDC ID Tokenを取得し、環境変数 `BM_OIDC_TOKEN` を通じて [`bm sync`](/code_management/cli/sync/) を実行します。

## 認証 [](#認証)

`bm sync` はOIDC ID Tokenを使ってベースマキナの **サービスアカウント** として認証します。GitLab CIでは、 `.gitlab-ci.yml` の `id_tokens` キーワード（GitLab 15.7以降で利用可能）でID Tokenを発行します。

`id_tokens` で発行したID Tokenは、指定した名前の環境変数としてジョブに渡されます。環境変数名を `BM_OIDC_TOKEN` にすると、 `bm sync` がこの環境変数を自動で参照します。

あらかじめ [サービスアカウント](/service_account/#oidc%E4%BF%A1%E9%A0%BC%E3%83%9D%E3%83%AA%E3%82%B7%E3%83%BC) に **OIDC信頼ポリシー** を設定し、GitLabが発行するID Tokenの `Issuer` / `Audience` / `Bound Claims` が整合していることを確認してください。

| 項目 | 設定値 |
| --- | --- |
| `Issuer` | `https://gitlab.com` （GitLab.comの場合。セルフマネージド版はGitLabインスタンスのURL） |
| `Audience` | `id_tokens` の `aud` に指定した値（例： `https://<your-subdomain>.basemachina.com` ） |
| `Bound Claims` | 呼び出し元のプロジェクト・ブランチを特定するclaim（例： `key: sub`, `pattern: project_path:my-group/my-project:ref_type:branch:ref:main` ） |

漏洩したトークンが他の企業アカウントで悪用されるのを防ぐため、 `aud` は企業アカウントごとに固有の値（例： `https://<your-subdomain>.basemachina.com` ）を設定することを推奨します。OIDC信頼ポリシーに登録した `Audience` と完全に一致する値を指定してください。OIDC信頼ポリシーの設定フォームでは、ご利用の企業アカウントのsubdomainを使った値が初期表示されます。

## セットアップ [](#セットアップ)

`.gitlab-ci.yml` に、MR作成時に差分を検出するジョブと、デフォルトブランチへのマージ時に設定を反映するジョブを定義します。

```
default:
  image: node:22
 
stages:
  - sync
 
# MR作成時に差分を検出する（ドライラン）
bm_sync_dry:
  stage: sync
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  id_tokens:
    BM_OIDC_TOKEN:
      aud: "https://<your-subdomain>.basemachina.com"
  script:
    - npm ci
    - npx tsc --noEmit
    - npx bm sync --dry
 
# デフォルトブランチへのマージ時に開発環境へ反映する
bm_sync:
  stage: sync
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  id_tokens:
    BM_OIDC_TOKEN:
      aud: "https://<your-subdomain>.basemachina.com"
  script:
    - npm ci
    - npx tsc --noEmit
    - npx bm sync
```

`npx tsc --noEmit` で型チェックを通してから `bm sync` を実行すると、設定ファイルやJavaScriptアクションの型エラーを同期前に検出できます。同じリポジトリで管理しているビューのコード（コード取得設定）も検査したい場合は、 `tsconfig.json` の `include` にビューのファイルを追加してください。設定方法は [コード取得設定との連携](/code_management/examples/view_code_fetch/) をご参照ください。

開発環境への反映時に設定ファイルから削除されたコード管理のアクション・ビューを無効化したい場合は、 `npx bm sync --with-disable` を指定します。 `--dry` や `--with-disable` などのオプションの詳細は [`bm sync`](/code_management/cli/sync/) をご参照ください。

Web UIで作成した未取り込みのアクション・ビューは、ローカルで [`bm pull`](/code_management/cli/pull/) を実行してリポジトリに取り込み、通常のMRとしてレビューしてください。

## 差分の確認 [](#差分の確認)

`bm sync` は実行環境を自動的に検出します。GitLab CI上では、折り畳み可能なMarkdown（ `<details>` タグ）として差分を出力します。 `bm sync --dry` の実行結果はジョブのログから確認できます。

MRのコメントとして差分を表示したい場合は、 `bm sync --dry` の出力を [`glab` CLI (opens in a new tab)](https://gitlab.com/gitlab-org/cli) やGitLab APIでMRのノートに投稿してください。GitHub Actionsの `bm-action` が担うsticky-comment（同じコメントの上書き投稿）に相当する処理は、GitLab向けには提供していません。

## 環境への同期 [](#環境への同期)

開発環境から検証環境や本番環境へ同期する場合は、 `npx bm sync <環境ID>` を実行します。環境IDは [GitLab CI/CD変数 (opens in a new tab)](https://docs.gitlab.com/ci/variables/) などで管理することを推奨します。

```
script:
  - npm ci
  - npx bm sync "$BM_PRD_ENV_ID"
```

環境間の同期では、同期元で無効化されているアクション・ビューも同期先へ無効状態として反映されます。同期先の指定方法やオプションの詳細は [`bm sync`](/code_management/cli/sync/) をご参照ください。

[GitHub Actions](/code_management/ci_cd/github_actions/) [基本（2ブランチ運用）](/code_management/examples/two_branch/)
---
コード管理

CLIコマンド

bm login

# bm login

ローカル端末からBaseMachina CLIを実行するために、ブラウザでベースマキナへログインするコマンドです。 `bm sync` など、認証が必要なCLIコマンドをローカルで実行する前に使用します。

```
bm login
 
# プロジェクトにインストールしたCLIをnpx経由で実行する場合
npx bm login
```

## 動作 [](#動作)

`bm login` を実行すると、認証用のブラウザが開きます。ブラウザでベースマキナにログインし、認証が完了したらターミナルに戻ってください。

ログインに成功すると、認証情報が `~/.basemachina/credentials.json` に保存されます。以降、ローカル端末でCLIコマンドを実行すると、この認証情報が自動で利用されます。

ローカル端末で `bm   login` を使用する場合、通常は環境変数 `BM_OIDC_TOKEN` を設定する必要はありません。

## CI/CDとの違い [](#cicdとの違い)

`bm login` は、ローカル端末でブラウザログインするためのコマンドです。GitHub ActionsなどのCI/CDでは、公式のComposite Action [`basemachina/bm-action` (opens in a new tab)](https://github.com/basemachina/bm-action) を使えます。自前でCI/CDを構成する場合は、CI/CDが発行したOIDC ID Tokenを環境変数 `BM_OIDC_TOKEN` に設定してください。

環境変数 `BM_OIDC_TOKEN` が設定されている場合は、 `~/.basemachina/credentials.json` よりも `BM_OIDC_TOKEN` が優先されます。

## 公開API呼び出しでの利用 [](#公開api呼び出しでの利用)

`bm login` で取得したJWTは、 [公開API](/public_api/) の `Authorization: Bearer` ヘッダーにそのまま指定できます。ローカル端末から公開APIを検証する具体的な手順は、 [公開APIを認証して呼び出す](/public_api/authentication/) をご参照ください。

## ブラウザが開かない場合 [](#ブラウザが開かない場合)

ブラウザを自動で開けない場合、ターミナルに認証用URLが表示されます。表示されたURLに手動でアクセスしてログインしてください。

ログイン操作が5分以内に完了しない場合はタイムアウトします。その場合は、再度 `bm login` を実行してください。

## オプション [](#オプション)

`bm login` にオプションはありません。

[readFile](/code_management/sdk/read_file/) [bm print-access-token](/code_management/cli/print_access_token/)
---
コード管理

CLIコマンド

bm print-access-token

# bm print-access-token

`bm login` で取得した認証トークンを標準出力に出力するコマンドです。ローカル端末から [公開API](/public_api/) を `curl` などで呼び出す際に、保存済みのJWTを取り出すために使用します。

```
bm print-access-token
 
# 例: 公開APIを呼び出す
export BM_TOKEN=$(bm print-access-token)
curl -H "Authorization: Bearer $BM_TOKEN" https://platform.basemachina.com/public/v1/...
```

## 動作 [](#動作)

`bm print-access-token` は、 `bm login` で `~/.basemachina/credentials.json` に保存されたJWTを、改行付きで標準出力に出力します。標準出力にはトークン以外の情報は含まれないため、 `$(bm print-access-token)` や `bm print-access-token > token.txt` のように、シェルのコマンド置換やリダイレクトでそのまま利用できます。

`bm   print-access-token` が出力するのは `~/.basemachina/credentials.json` に保存されたJWTのみです。環境変数 `BM_OIDC_TOKEN` を参照することはありません。

## ログイン済みでない場合 [](#ログイン済みでない場合)

`~/.basemachina/credentials.json` が存在しない場合や、JSONの内容が不正な場合は、標準エラー出力に以下のメッセージを出力し、終了コード `1` で終了します。

```
認証情報が見つかりません。`bm login` を実行してログインしてください。
```

この場合は `bm login` を実行してログインし直してください。

## トークンの期限切れ [](#トークンの期限切れ)

`bm print-access-token` はトークンの有効期限を検証しません。期限切れのトークンを公開APIに渡すと `401 unauthorized` が返ります。再度 `bm login` を実行すると、新しいJWTが `~/.basemachina/credentials.json` に上書き保存されます。詳細は [公開APIを認証して呼び出す](/public_api/authentication/) をご参照ください。

## オプション [](#オプション)

`bm print-access-token` にオプションはありません。

[bm login](/code_management/cli/login/) [bm sync](/code_management/cli/sync/)
---
コード管理

CLIコマンド

bm pull

# bm pull

Web管理のアクション・ビューと自動生成ファイルを、現在のリポジトリへ取り込むコマンドです。

`bm pull` は、ベースマキナ上に存在するアクション・ビューのうち、設定ファイルにまだ含まれていないWeb管理のものを対象にします。取り込んだ内容はローカルファイルとして生成されるだけで、ベースマキナの環境には反映されません。内容を確認してPRに含め、必要に応じて [`bm sync`](/code_management/cli/sync/) で反映してください。

ローカル端末で実行する場合は、事前に [`bm   login`](/code_management/cli/login/) でログインしてください。 `bm   pull` は書き込み前に対話確認を実施するため、通常はローカル端末で実行します。

```
# Web管理の未取り込みアクションを取り込む
bm pull
 
# 設定ファイルのパスを指定する
bm pull --config apps/admin/basemachina.config.ts
```

## オプション [](#オプション)

| オプション | デフォルト値 | 説明 |
| --- | --- | --- |
| `--config <path>` | `basemachina.config.ts` | 設定ファイルのパス |

## 取り込まれる内容 [](#取り込まれる内容)

`bm pull` は、対象プロジェクトの現在の状態を読み取り、以下のファイルを生成または更新します。

| 対象 | 書き込み方法 | 説明 |
| --- | --- | --- |
| `src/actions/<id>.ts` | 新規作成のみ | Web管理アクションの定義ファイル。すでに同じパスが存在する場合は中断する |
| JavaScriptアクションコード | 新規作成のみ | JavaScriptアクションの場合、 `src/actions/js-action-codes/<id>.js` にコード本体を生成する |
| `src/views/<id>.ts` | 新規作成のみ | Web管理ビューの定義ファイル。すでに同じパスが存在する場合は中断する |
| コードエディターのビューコード | 新規作成のみ | コードエディターのビューの場合、 `src/views/view-codes/<id>.jsx` にコード本体を生成する |
| `src/bm-refs.ts` | 自動更新 | レビュー設定、データソース、グループ、通知方法などを型安全に参照するための定数 |
| `type.d.ts` | 自動更新 | `@basemachina/action` の型登録ファイル |
| 設定ファイル | 追記 | 取り込んだアクションのimportと `actions` 配列、ビューのimportと `views` 配列への追加 |

自動更新対象の `src/bm-refs.ts` と `type.d.ts` は、内容に差分がある場合のみ書き換えられます。アクション・ビューの定義ファイルとコード本体は新規作成のみで、既存ファイルは上書きされません。

## 対象になるアクション [](#対象になるアクション)

`bm pull` の対象になるのは、次の条件を満たすアクションです。

- Web管理のアクションである
- 識別子が設定されている
- 設定ファイルの `actions` 配列に同じ識別子のアクションがまだ含まれていない
- コード管理で生成できるアクション種別である

すでに設定ファイルに含まれているアクションは、Web UIで変更されていても `bm pull` の取り込み対象にはなりません。設定ファイルの内容で戻したい場合は `bm sync` を実行し、Web UIでの変更を反映したい場合は設定ファイルを手動で更新してください。

識別子が未設定のアクションはスキップされます。取り込み後、識別子未設定のWeb管理アクションが残っている場合は、識別子の一括設定画面を開くかどうか確認されます。

## 対象になるビュー [](#対象になるビュー)

ビューの対象条件はアクションとほぼ同じです。

- Web管理のビューである
- 識別子が設定されている
- 設定ファイルの `views` 配列に同じ識別子のビューがまだ含まれていない
- [コード取得設定](/code_management/examples/view_code_fetch/) が有効なコードエディターのビューではない

識別子が未設定のビューと、コード取得設定が有効なビューは、ダウンロードの時点で除外されるため取り込み対象にはならず、実行結果にも表示されません。コード取得設定が有効なビューは、コード管理では扱えないため引き続きWeb UIとコード取得設定で管理してください。

参照しているアクションが削除されている、または参照先のアクションに識別子が設定されていないビューもスキップされますが、こちらは実行結果にスキップ理由として表示されます。

設定ファイルの `views` 配列が1つも存在せず、かつ取り込めるWeb管理のビューが存在する場合、 `bm pull` は実行前に `Web 管理のビュー N 件も取り込みますか？` と確認します。 `n` を選ぶとビューは一切取り込まれず、アクションのみが取り込み対象になります。設定ファイルの `views` 配列にすでに1件でもビューが存在する場合は、この確認は実施されずビューも通常どおり取り込まれます。

## 実行結果の出力 [](#実行結果の出力)

実行すると、取り込み予定の内容がサマリーとして表示されます。

```
## bm pull で以下の変更を取り込みます
 
### 取り込み内容
 
- Web 管理で識別子が設定されているアクション: 1 件
- Web 管理で識別子が設定されているビュー: 1 件
- 書き込み予定ファイル: 4 件
 
<details><summary>Web 管理で識別子が設定されているアクション (1 件)</summary>
 
- ユーザー一覧 (list-users)
 
</details>
 
<details><summary>Web 管理で識別子が設定されているビュー (1 件)</summary>
 
- ユーザー一覧 (user-list)
 
</details>
 
<details><summary>書き込み予定ファイル (4 件)</summary>
 
- src/actions/list-users.ts
- src/views/user-list.ts
- src/views/view-codes/user-list.jsx
- src/bm-refs.ts
 
</details>
```

対象が0件の場合は、該当する `<details>` ブロックの代わりに `Web 管理で識別子が設定されているアクションはありません。` のような文が表示されます。ダウンロードをスキップしたアクション・ビューがある場合は、それぞれ理由付きで別の `<details>` ブロックに表示されます。

内容を確認したあと、 `bm pull の変更を適用しますか？` に `y` または `yes` で回答するとファイルが書き込まれます。 `n` を選ぶか、対話入力できない環境で実行した場合は、変更は適用されません。

## よくある使い方 [](#よくある使い方)

### Web UIで作成したアクションをコード管理に取り込む [](#web-uiで作成したアクションをコード管理に取り込む)

1. Web UIでアクションに識別子を設定する
1. ローカルで `bm pull` を実行する
1. 生成されたファイルと設定ファイルへの追記内容を確認する
1. 必要に応じてリファクタリングや型チェックを実施する
1. PRを作成し、レビュー後に `bm sync` でコード管理へ移行する

### 参照IDの定数を更新する [](#参照idの定数を更新する)

レビュー設定、データソース、グループ、通知方法、マスターデータ取得設定、プロジェクトユーザーなどをWeb UIで追加・変更した場合は、 `bm pull` を実行すると `src/bm-refs.ts` が再生成されます。

```
import { defineAction } from "@basemachina/sdk/oac";
import { dataSources, notificationMethods } from "../bm-refs";
 
export const action = defineAction({
  id: "notify-users",
  name: "ユーザー通知",
  type: "grpc",
  dataSource: dataSources["orders-service"],
  fullMethodName: "orders.OrderService/NotifyUsers",
  notificationSettings: {
    onSuccess: {
      notificationMethodId: notificationMethods["Slack"],
    },
  },
});
```

[bm sync](/code_management/cli/sync/) [概要](/code_management/ci_cd/)
---
コード管理

CLIコマンド

bm sync

# bm sync

設定ファイルの内容をベースマキナの環境に同期するコマンドです。アクション・ビューのどちらも同期対象になります。同期先の環境IDの有無で挙動が変わります。

- **環境ID未指定**: 設定ファイルの内容を **開発環境** に反映します（設定ファイルとベースマキナ上の設定の差分検出・反映）
- **環境ID指定**: 指定した環境に、他環境の [バージョンと有効化設定](/action/enablement_settings/) を同期します

いずれの場合も、実行前に設定内容のバリデーションが実施されます。

ローカル端末で実行する場合は、事前に [`bm   login`](/code_management/cli/login/) でログインしてください。CI/CDで実行する場合は、環境変数 `BM_OIDC_TOKEN` にOIDC
ID
Tokenを設定します。詳しくは [CI/CDの設定](/code_management/ci_cd/) をご参照ください。

```
# 開発環境に反映する（ドライラン）
bm sync --dry
 
# 開発環境に反映する
bm sync
 
# 設定ファイルから削除されたアクション・ビューを開発環境で無効化して反映する
bm sync --with-disable
 
# 開発環境の状態を検証環境に同期する
bm sync <検証環境のID>
 
# 検証環境の状態を本番環境に同期する
bm sync <本番環境のID> --from <検証環境のID>
 
# 同期内容をドライランで確認する
bm sync --dry <環境ID>
```

## オプション [](#オプション)

| オプション | デフォルト値 | 説明 |
| --- | --- | --- |
| 第1引数 | （省略可） | 同期先の環境ID。省略した場合は開発環境への反映になる |
| `--config <path>` | `basemachina.config.ts` | 設定ファイルのパス |
| `--from <environmentId>` | 開発環境のID | 同期元の環境ID。同期先の環境IDを指定したときのみ使用可 |
| `--dry` | （反映する） | 変更を適用せずに実行結果を確認する |
| `--with-disable` | （無効化しない） | 無効化対象のアクション・ビューを反映する（同期先の指定により挙動が変わる。下記参照） |

`--from` は同期先の環境IDを指定したときのみ使用できます。同期先の環境IDを指定せず `--from` を指定するとエラーになります。

`--with-disable` の挙動は同期先の環境IDの有無で変わります。

| 同期先の環境ID | `--with-disable` の挙動 |
| --- | --- |
| 未指定 | 設定ファイルに存在しないアクション・ビューを開発環境で **無効化** する |
| 指定 | 同期元で無効化されているアクション・ビューも同期先に反映する（同期先で **無効化** された状態で同期する） |

## 開発環境への反映（環境ID未指定） [](#開発環境への反映環境id未指定)

同期先の環境IDを指定しないと、設定ファイルの内容を開発環境に反映します。

### 差分検出の仕組み [](#差分検出の仕組み)

設定ファイルとベースマキナ上の設定を、アクション・ビューそれぞれの識別子で突きあわせて比較します。以下はアクションを例にした表ですが、ビューも同じ規則で扱われます。

| 設定ファイル | ベースマキナ上の設定 | 結果 |
| --- | --- | --- |
| 存在する | 存在する（有効） | 内容に差分がある場合は **更新** |
| 存在する | 存在する（開発環境で無効） | **再有効化** （内容に差分がある場合は併せて **更新** ） |
| 存在する | 存在しない | **作成** |
| 存在しない | 存在する | 何もしない（ `--with-disable` 指定時は **開発環境で無効化** ） |

設定ファイルに含まれないアクション・ビューは、デフォルトでは変更されません。 `--with-disable` オプションを指定した場合のみ、設定ファイルに存在しないアクション・ビューが開発環境で無効化されます。

### 管理方法による挙動の違い [](#管理方法による挙動の違い)

ベースマキナのアクション・ビューは、最後に作成・更新した場所によって「コード管理」と「Web管理」のいずれかに分類されます。 `bm sync` はこの管理方法に応じて挙動を切り替えます。

| ベースマキナ上の管理方法 | 設定ファイルに同じ識別子のアクション・ビューが存在する場合 | 設定ファイルに存在しない場合（ `--with-disable` 指定時） |
| --- | --- | --- |
| コード管理 | 内容の差分に応じて **作成・更新** 。差分がなければ変更なし | 開発環境で **無効化** |
| Web管理 | 管理方法を「コード管理」に **移行** （内容に差分があればあわせて更新） | **Web 管理を維持** （引き続きWebで管理される） |

Webで作成・更新されたアクション・ビューを設定ファイルに含めて `bm sync` を実行すると、その管理方法がコード管理に切り替わります。設定ファイルに含めていないWeb管理のアクション・ビューは、 `--with-disable` を指定しても無効化されません。

設定ファイルにまだ含まれていないWeb管理のアクション・ビューをリポジトリに取り込みたい場合は、 [`bm pull`](/code_management/cli/pull/) を使用してください。

### `developmentActions` / `developmentViews` の扱い [](#developmentactions--developmentviewsの扱い)

`defineConfig` の [`developmentActions` / `developmentViews`](/code_management/sdk/define_config/) に指定したアクション・ビューも、開発環境への反映では `actions` / `views` と同じく扱われます。作成・更新・再有効化・無効化のいずれも、同じルールが適用されます。

`developmentActions` / `developmentViews` が他環境への同期では対象外になる挙動については、 [他の環境への同期（環境ID指定）](/code_management/cli/sync/#%E4%BB%96%E3%81%AE%E7%92%B0%E5%A2%83%E3%81%B8%E3%81%AE%E5%90%8C%E6%9C%9F%E7%92%B0%E5%A2%83id%E6%8C%87%E5%AE%9A) を参照してください。

### 開発環境での無効化と再有効化 [](#開発環境での無効化と再有効化)

`--with-disable` による無効化は、 [アクションの有効化設定](/action/enablement_settings/) の開発環境の設定を「無効」に変更する操作です。アクション・ビューのデータ自体は削除されず、識別子も保持されます。

一度無効化されたアクション・ビューを設定ファイルに戻して再度 `bm sync` を実行すると、開発環境で自動的に再有効化されます。これにより、 `git revert` や設定ファイルの巻き戻しで無効化を取り消せます。

他の環境（検証環境・本番環境など）の有効化設定は、 `--with-disable` では変更されません。ほかの環境へ状態を伝播させるには、同期先の環境IDを指定した `bm sync` を使用します。

### 差分の出力内容 [](#差分の出力内容)

開発環境への反映時は、以下のサマリーを出力します。ヘッダーは、 `--dry` 指定時が `## bm sync 実行後、以下の変更が適用されます` 、反映時が `## bm sync が完了しました` です。

```
## bm sync 実行後、以下の変更が適用されます
 
### コード管理のアクション
 
- 作成: N 件
- 更新: N 件
- id 変更: N 件
- 再有効化: N 件
- 開発環境で無効化: N 件
- 変更なし: N 件
 
<details><summary>作成 (1 件)</summary>
 
- ユーザー一覧 (list-users)
 
</details>
 
<details><summary>id 変更 (1 件)</summary>
 
- 顧客検索 (customor-search → customer-search)
 
</details>
 
### Web 管理のアクション
 
- コード管理に移行（変更なし）: N 件
- コード管理に移行（変更あり）: N 件
- Web 管理を維持: N 件
 
### コード管理のビュー
 
- 作成: N 件
- 更新: N 件
- id 変更: N 件
- 再有効化: N 件
- 開発環境で無効化: N 件
- 変更なし: N 件
- スキップ: N 件
 
<details><summary>作成 (1 件)</summary>
 
- ユーザー一覧 (user-list)
 
</details>
 
### Web 管理のビュー
 
- コード管理に移行（変更なし）: N 件
- コード管理に移行（変更あり）: N 件
- Web 管理を維持: N 件
```

0件の項目は行自体が省略されます。 `### Web 管理のアクション` と `### Web 管理のビュー` は、該当するアクション・ビューが1件もない場合は表示されません。さらに `### Web 管理のビュー` は、設定ファイルに `views` （ `developmentViews` を含む）が1件も存在しない場合、対象件数にかかわらずブロックごと表示されません。すべての項目が0件の場合は、本文に `変更はありません` と表示されます。

`### コード管理のビュー` の **スキップ** は、参照しているアクションやビューが同じ `bm sync` で新規作成されるために、今回は作成・更新の対象から除外されたビューの件数です。参照先が作成されたあと、もう一度 `bm sync` を実行すると反映されます。

各ブロックの件数に対応するアクション・ビューの詳細（作成内容、差分、対象の一覧）は、そのブロックの件数の下に続けて表示されます。GitHub ActionsおよびGitLab CI上では `<details>` タグで折り畳み可能なMarkdownとして表示され、その他の環境では `作成 (N 件):` のような見出しと本文のプレーンテキストで表示されます。

`--with-disable` を指定していない状態で無効化対象が存在する場合、コード管理のアクションのブロックに以下の注記が表示されます。この場合も対象一覧は表示されますが、実際の無効化は適用されません。

```
> [!NOTE]
> `--with-disable` が指定されていないため、無効化は適用されません。
```

ドライラン時は、末尾に以下の注記が表示されます。

```
> [!NOTE]
> `--dry` 指定のため、変更は適用されていません
```

## 他の環境への同期（環境ID指定） [](#他の環境への同期環境id指定)

同期先の環境IDを指定すると、同期元環境のバージョンと有効化設定で同期先環境を上書きします。検証環境や本番環境への同期に使用します。

同期元環境は `--from` で指定するか、省略した場合は開発環境になります。

環境IDは、管理画面のURLから読み取るか、 [公開API](/public_api/) の `GET   /projects/{project_id}   /environments` で取得できます。詳しくは [環境IDの確認](/admin/environment/what_is_environment/#%E7%92%B0%E5%A2%83id%E3%81%AE%E7%A2%BA%E8%AA%8D) をご参照ください。

### 同期対象 [](#同期対象)

バージョンと有効化設定は同時に同期されます。以下はアクションを例にした表ですが、ビューも同じ規則で同期されます。

| 同期元の設定 | 同期先の設定 | 動作 |
| --- | --- | --- |
| 有効 | 有効 | バージョンを同期 |
| 有効 | 無効 | **有効化** ＋バージョンを同期 |
| 有効 | 未設定 | **有効化** ＋バージョンを同期 |
| 無効 | 有効 | `--with-disable` 指定時のみ **無効化** ＋バージョンを同期。未指定時は有効状態を維持してバージョンのみ同期 |
| 無効 | 無効 | バージョンを同期 |
| 無効 | 未設定 | `--with-disable` 指定時のみ無効状態で同期。未指定時は同期しない |
| 未設定 | 任意 | 同期しない |

同期元の有効化設定が無効の場合でも、同期対象になったアクション・ビューのバージョンは同期先にコピーされます。これにより、後から同期先を有効化した際に、同期元と同じバージョンで動作することが保証されます。

### `developmentActions` / `developmentViews` の扱い [](#developmentactions--developmentviewsの扱い-1)

`defineConfig` の [`developmentActions` / `developmentViews`](/code_management/sdk/define_config/) に指定したアクション・ビューは、他環境への同期では **対象外** となり、同期先環境には反映されません。「開発環境でのみ動作確認したいアクション・ビューを、検証環境や本番環境には流さない」運用を実現するためのフィールドです。運用フローに組み込んだ例は [実践的な開発フロー](/code_management/examples/three_branch/) をご参照ください。

すでに同期先環境に反映済みのアクション・ビューを `actions` / `views` から `developmentActions` / `developmentViews` に移して同期を実行すると、同期先環境でそのアクション・ビューは無効化されます。

`developmentViews` に指定したビューがベースマキナ上に存在しない場合（idのtypoや削除済みなど）は、 `developmentViews に指定されたビュー「<id>」が見つかりません` というエラーになり、同期は実行されません。

### バージョン指定との関係 [](#バージョン指定との関係)

アクションのバージョンには「特定のバージョン」と「常に最新」の2通りの指定方法があります。環境IDを指定した `bm sync` では、同期先のバージョン指定によって挙動が変わります。

- 同期先が「常に最新」の場合、同期先のバージョン指定は「常に最新」のまま維持されます
- 同期先が「特定のバージョン」または未設定の場合、同期元が「特定のバージョン」なら同じバージョンに設定されます
- 同期先が「特定のバージョン」または未設定の場合、同期元が「常に最新」なら同期時点の最新バージョンに設定されます

### 開発環境への同期は禁止 [](#開発環境への同期は禁止)

開発環境は「設定ファイルからの反映」によって変更される起点であり、他の環境から同期する対象にはなりません。 `bm sync` の同期先に開発環境のIDを指定するとエラーになります。

### 実行結果の出力 [](#実行結果の出力)

他の環境への同期時は、同期内容をセクション別に分類したサマリーが出力されます。ヘッダーは、 `--dry` 指定時が `## bm sync 実行後、以下の変更が同期されます` 、反映時が `## bm sync が完了しました` です。変化の種類に応じて「バージョン変更」「有効化」「無効化」の3つのセクションに分類されます。

```
## bm sync 実行後、以下の変更が同期されます
 
同期元環境: <同期元環境の名前>
同期先環境: <同期先環境の名前>
 
### アクションの同期内容
 
- バージョン変更: N 件
- 有効化: N 件
- 無効化: N 件
 
<details><summary>バージョン変更 (1 件)</summary>
 
- ユーザー一覧 (list-users)
  - v1 → v2
 
</details>
 
<details><summary>有効化 (1 件)</summary>
 
- 新規アクション (new-action): 無効 → 有効
 
</details>
 
### ビューの同期内容
 
- バージョン変更: N 件
- 有効化: N 件
- 無効化: N 件
 
<details><summary>バージョン変更 (1 件)</summary>
 
- ユーザー一覧 (user-list)
  - v1 → v2
 
</details>
```

- 同期元と同期先の有効化設定が同じ（両方有効、または両方無効）場合は **バージョン変更** に分類されます。
- 同期元のみ有効の場合は **有効化** 、同期先のみ有効の場合は **無効化** に分類されます。
- 同期先に未設定のアクション・ビューは、同期先の初期状態を「無効」として扱うため、同期元が有効な場合は **有効化** に分類されます。「追加」というカテゴリは表示されません。
- `### アクションの同期内容` と `### ビューの同期内容` は、それぞれ同期対象が1件もない場合は表示されません。両方とも対象がない場合は、本文に `変更はありません` と表示されます。
- 0件の項目は行自体が省略されます。
- ドライラン時は末尾に「 `--dry` 指定のため、変更は適用されていません」の注記が表示されます。
- 「常に最新」が指定されたアクション・ビューは、同期元のバージョン表記が `常に最新` と表示されます。

### エラーケース [](#エラーケース)

他の環境への同期では、以下のケースがエラーとして扱われます。

| エラー条件 | 出力メッセージの例 |
| --- | --- |
| 同期元環境が見つからない | `同期元環境「<環境ID>」が見つかりません` |
| 同期先環境が見つからない | `同期先環境「<環境ID>」が見つかりません` |
| `--from` 未指定かつ開発環境が設定されていない | ``同期元環境が指定されていません。`--from` で指定するか、プロジェクトに開発環境を設定してください`` |
| 同期元と同期先が同じ環境 | `同期元環境と同期先環境に同じ環境は指定できません` |
| 同期元環境が無効化されている | `同期元環境「<環境ID>」は無効化されています` |
| 同期先環境が無効化されている | `同期先環境「<環境ID>」は無効化されています` |
| 同期先に開発環境を指定 | ``開発環境への同期はサポートされていません。環境IDを指定せずに `bm sync` を使用してください`` |
| `developmentViews` に指定したビューが存在しない | `developmentViews に指定されたビュー「<id>」が見つかりません` |

## 実行環境の自動検出 [](#実行環境の自動検出)

`bm sync` は実行環境（GitHub Actions、GitLab CI、ローカル端末など）を自動検出し、出力形式を切り替えます。GitHub ActionsおよびGitLab CI上では、変更の詳細を `<details>` タグで折り畳んでPRコメントに貼り付けやすい形式で出力します。その他の環境ではプレーンテキストで出力されます。

出力形式を明示的に切り替えるオプションはありません。

[bm print-access-token](/code_management/cli/print_access_token/) [bm pull](/code_management/cli/pull/)
---
コード管理

設定ファイル

# 設定ファイル

コード管理では、TypeScriptで設定を記述します。SDK（ `@basemachina/sdk/oac` ）が提供する関数を使うことで、型安全に設定を定義できます。

ビューの設定も [`defineView`](/code_management/sdk/define_view/) でコード管理の対象にできます。コードエディターのビューのコードは、コード管理のリポジトリに置いて [`readFile`](/code_management/sdk/read_file/) で読み込む方法と、 [コード取得設定](/code_management/examples/view_code_fetch/) でストレージから取得する方法のいずれかで管理できます。

## ダウンロードされるファイル [](#ダウンロードされるファイル)

[始め方](/code_management/getting_started/) でダウンロードしたZIP（ `oac-project.zip` ）には、以下のファイルが含まれます。

```
my-project/
├── basemachina.config.ts          # プロジェクト全体の設定
├── package.json                   # @basemachina/sdk / @basemachina/cli の依存関係
├── tsconfig.json                  # TypeScriptの設定
├── type.d.ts                      # JavaScriptアクション用の型登録
├── .gitignore
└── src/
    ├── bm-refs.ts                 # Web上の設定を参照する自動生成ファイル
    ├── actions/                   # アクション定義
    │   ├── get-users.ts
    │   ├── list-users.ts
    │   └── js-action-codes/       # JavaScriptアクションのコード（JSアクションがある場合）
    │       └── get-user.js
    └── views/                     # ビュー定義（ビューがある場合）
        ├── user-list.ts
        └── view-codes/            # コードエディターのビューのコード
            └── user-list.jsx
```

- アクション定義は `src/actions/` 配下に、アクションの識別子ごとに1ファイルずつ配置されます。
- JavaScriptアクションのコードは `src/actions/js-action-codes/` 配下に、アクションの識別子ごとに `.js` ファイルとして出力されます。
- ビュー定義は `src/views/` 配下に、ビューの識別子ごとに1ファイルずつ配置されます。
- コードエディターのビューのコードは `src/views/view-codes/` 配下に、ビューの識別子ごとに `.jsx` ファイルとして出力されます。
- `src/bm-refs.ts` には、レビュー設定、データソース、グループ、通知方法、マスターデータ取得設定、プロジェクトユーザーなどを型安全に参照するための定数が出力されます。このファイルは [`bm pull`](/code_management/cli/pull/) で再生成されるため、手動で編集しないでください。
- `type.d.ts` には、JavaScriptアクションの型推論に必要な `@basemachina/action` の型登録が出力されます。このファイルも `bm pull` で再生成される自動生成ファイルです。
- `package.json` には、npmで公開されている [`@basemachina/sdk` (opens in a new tab)](https://www.npmjs.com/package/@basemachina/sdk) と [`@basemachina/cli` (opens in a new tab)](https://www.npmjs.com/package/@basemachina/cli) の依存関係が含まれます。
- GitHub Actionsのワークフローファイルは含まれません。CI/CDの設定は、 [CI/CDの設定](/code_management/ci_cd/) を参考に手動で追加してください。

ファイル構造に厳密な規約はありません。設定ファイルに書き出したあとは、機能別のディレクトリに整理し直したり、モノレポの一部として既存リポジトリに同居させたりできます。ただし、 [`bm   pull`](/code_management/cli/pull/) でWeb管理のアクション・ビューを取り込む場合は、 `src/actions/` 、 `src/views/` 、 `src/bm-refs.ts` 、 `type.d.ts` が更新対象になります。取り込んだアクション・ビューのimportと配列への追加は `basemachina.config.ts` に書き込まれます。

## SDK関数 [](#sdk関数)

設定ファイルでは、 `@basemachina/sdk/oac` から以下のSDK関数をインポートして使用します。

- [`defineConfig`](/code_management/sdk/define_config/) - プロジェクト全体の設定を定義する
- [`defineAction`](/code_management/sdk/define_action/) - アクションを定義する
- [`defineView`](/code_management/sdk/define_view/) - ビューを定義する
- [`readFile`](/code_management/sdk/read_file/) - 外部ファイルの内容を読み込む

```
import {
  defineConfig,
  defineAction,
  defineView,
  readFile,
} from "@basemachina/sdk/oac";
```

## `tsconfig.json` [](#tsconfigjson)

ダウンロードしたプロジェクトには `tsconfig.json` が含まれており、SDKの設定を拡張しています。通常は変更不要です。

```
{
  "extends": "@basemachina/sdk/tsconfig.code.json",
  "include": ["basemachina.config.ts", "type.d.ts", "src/**/*.ts"]
}
```

この設定により、JavaScriptアクションのコードで `@basemachina/action` の型定義（パラメーターの型など）が使用可能になります。また、ビューのコードを同じリポジトリに同居させる場合は `@basemachina/view` の型定義も利用できます。

### `@basemachina/sdk` が提供するtsconfigの種類 [](#basemachinasdkが提供するtsconfigの種類)

`@basemachina/sdk` は、用途に応じて3種類のtsconfigを提供しています。基本的にはひな形と同じく `tsconfig.code.json` を継承すれば十分です。

| 名前 | `paths` で解決される型 | 想定用途 |
| --- | --- | --- |
| `@basemachina/sdk/tsconfig.code.json` | `@basemachina/action` 、 `@basemachina/view` | アクションとビューをまとめて管理する場合の標準設定。ひな形の `tsconfig.json` が継承する |
| `@basemachina/sdk/tsconfig.action.json` | `@basemachina/action` のみ | JavaScriptアクションのコードのみを型チェック対象にしたい場合 |
| `@basemachina/sdk/tsconfig.view.json` | `@basemachina/view` のみ | ビューのコードのみを型チェック対象にしたい場合 |

アクションとビューの両方を扱う場合は、 `tsconfig.code.json` を継承するだけで両方の型定義が利用できます。 `tsconfig.action.json` と `tsconfig.view.json` を別々に継承して2つの `tsconfig` を運用する必要はありません。

ビューのコードを同じリポジトリで扱う場合の追加設定（ `jsx` の指定や `react` / `@types/react` のインストール）は、 [コード取得設定との連携](/code_management/examples/view_code_fetch/) をご参照ください。

[始め方](/code_management/getting_started/) [defineConfig](/code_management/sdk/define_config/)
---
コード管理

運用例

実践的な開発フロー

# 実践的な開発フロー

`main` 、 `stg` 、 `prd` の3つのブランチで、開発環境・検証環境・本番環境を管理する運用例です。

開発環境で動作確認を済ませたアクションだけを、検証環境・本番環境へ順に昇格させます。 `defineConfig` の `developmentActions` と `bm sync` の `--from` オプションを組み合わせることで、複数の作業者が並行して開発しても、動作確認前の変更が検証環境・本番環境に混ざりません。

## ブランチと環境の対応 [](#ブランチと環境の対応)

| ブランチ | ベースマキナの環境 | 説明 |
| --- | --- | --- |
| `main` | 開発環境 | 日常的な開発を進めるブランチ |
| `stg` | 検証環境 | 本番環境への同期前に動作を検証するブランチ |
| `prd` | 本番環境 | 本番環境用のブランチ |

この運用では、アクションの動作確認の状態を設定ファイルの2つのフィールドで管理します。

| 設定ファイルのフィールド | アクションの状態 | 反映・同期の範囲 |
| --- | --- | --- |
| `developmentActions` | 動作確認前 | 開発環境にのみ反映される |
| `actions` | 動作確認済み | 開発環境に反映され、検証環境・本番環境への同期対象になる |

## 開発フローの全体像 [](#開発フローの全体像)

`developmentActions` で開発したアクションを開発環境で動作確認し、確認が済んだものだけを `actions` へ移して検証環境・本番環境へ昇格させる流れです。

## 重要な役割を担うオプション [](#重要な役割を担うオプション)

`bm sync <環境ID>` は、同期先の **すべて** のアクションのバージョンと有効化設定を同期元の状態に合わせます。そのため、なにも対策をしないと、動作確認が済んでいないアクションまで検証環境・本番環境へそのまま同期されてしまいます。この運用例では、次の2つのオプションでこれを防ぎます。

### developmentActions [](#developmentactions)

`defineConfig` の `developmentActions` は、開発環境で動作確認中のアクションを他環境への同期から除外するためのフィールドです。

- 開発環境への反映（環境IDを指定しない `bm sync` ）では、 `actions` と同様に反映されます。開発環境での動作確認は通常どおり実行できます
- 他環境への同期（ `bm sync <環境ID>` ）では対象外となり、同期先環境には反映されません

詳細は [`defineConfig`](/code_management/sdk/define_config/) と [`bm sync`](/code_management/cli/sync/) をご参照ください。

### --from [](#--from)

`bm sync <環境ID>` の同期元は、 `--from` を省略すると開発環境になります。本番環境への同期で `--from <検証環境のID>` を指定すると同期元が検証環境になるため、検証環境での確認を通過した状態だけが本番環境へ昇格します。開発環境にしか存在しない変更が、本番環境へ直接同期されることはありません。

⚠️

すでに検証環境・本番環境に反映済みのアクションを `actions` から `developmentActions` に移して `bm sync <環境ID>` を実行すると、同期先環境でそのアクションは無効化されます。

## 作業シナリオ [](#作業シナリオ)

作業者Aが新しいアクション `update-user-status` を、作業者Bが新しいアクション `export-orders` を並行して開発しているとします。

両方を最初から `actions` に入れて `main` にマージしていると、Aの動作確認が完了して `main` を `stg` へマージした時点で、動作確認が済んでいないBのアクションまで検証環境に同期されてしまいます。 `developmentActions` を使うと、次の流れでAのアクションだけを昇格できます。

| ステップ | 操作 | `update-user-status` （A） | `export-orders` （B） |
| --- | --- | --- | --- |
| 1 | AもBも `developmentActions` に追加して `main` へマージ | 開発環境に反映 | 開発環境に反映 |
| 2 | Aが動作確認を完了し、 `actions` へ移すPRを `main` へマージ | `actions` で管理 | `developmentActions` のまま |
| 3 | `main` を `stg` へマージ（ `bm sync <検証環境のID>` ） | 検証環境に同期 | 同期されない |
| 4 | QA確認後、 `stg` を `prd` へマージ（ `bm sync <本番環境のID> --from <検証環境のID>` ） | 本番環境に同期 | 同期されない |

ステップ2時点の `basemachina.config.ts` は次のようになります。

```
import { defineConfig } from "@basemachina/sdk/oac";
import { listUsers } from "./src/actions/list-users";
import { updateUserStatus } from "./src/actions/update-user-status";
import { exportOrders } from "./src/actions/export-orders";
 
export default defineConfig({
  project: {
    id: "your-project-id",
  },
  // 動作確認済み。検証環境・本番環境への同期対象
  actions: [listUsers, updateUserStatus],
  // 動作確認中。開発環境にのみ反映される
  developmentActions: [exportOrders],
});
```

Bの動作確認が完了したら、同様に `exportOrders` を `actions` へ移すPRをマージし、次の昇格PRで検証環境へ同期します。

## 開発環境への変更 [](#開発環境への変更)

### 1. featureブランチで開発 [](#1-featureブランチで開発)

`main` から `feature/xxx` ブランチを作成し、アクションの設定やビューのコードを編集してPRを作成します。動作確認が済むまで検証環境・本番環境に出したくないアクションは、 `actions` ではなく `developmentActions` に指定します。

### 2. CIで差分を確認 [](#2-ciで差分を確認)

PRが作成されると、CIで `bm sync --dry` が実行され、設定の差分がPRにコメントされます。開発環境への反映内容なので、コメントのヘッダーは `## bm sync 実行後、以下の変更が適用されます` です。

### 3. マージして開発環境に反映 [](#3-マージして開発環境に反映)

PRをマージすると、CDで `bm sync` が実行され、アクションの変更がベースマキナの開発環境に反映されます。 `developmentActions` のアクションも、開発環境へは `actions` と同じルールで反映されます。新しいバージョンが作成され、開発環境では常に最新バージョンが使用されるため即時反映されます。設定ファイルから削除されたアクションは、 `--with-disable` 指定時のみ開発環境で無効化されます。

ビューのコードを同じリポジトリで管理している場合は、ワークフローにビューのビルド・アップロード処理を追加します。詳細は [コード取得設定との連携](/code_management/examples/view_code_fetch/) をご参照ください。レビュー設定やデータソースなど、コード管理対象外の設定は引き続きベースマキナの画面から設定してください。

### 4. 開発環境で動作確認 [](#4-開発環境で動作確認)

開発環境でアクションを実行し、動作を確認します。動作確認が済んでいないアクションが `developmentActions` にある状態で昇格PRがマージされても、検証環境には同期されません。

## 検証環境への変更 [](#検証環境への変更)

開発環境で確認が取れたら、検証環境に同期します。

検証環境への変更は、 `main` ブランチを `stg` ブランチへ取り込む昇格PRとして作成します。 `stg` ブランチで設定ファイルやアクションコードを直接編集する運用は避けてください。

### 1. 動作確認済みのアクションをactionsに移す [](#1-動作確認済みのアクションをactionsに移す)

動作確認が済んだアクションを `developmentActions` から `actions` へ移すPRを作成し、 `main` へマージします。

同じ識別子（ `id` ）のアクションを `actions` と `developmentActions` の両方に指定するとバリデーションエラーになります。必ず `developmentActions` から削除したうえで `actions` へ移してください。

### 2. 昇格PRの作成 [](#2-昇格prの作成)

`stg` ブランチに `main` をマージするPRを作成します。

### 3. マージして検証環境に同期 [](#3-マージして検証環境に同期)

PRをマージすると、CDで `bm sync <検証環境のID>` が実行され、検証環境の **すべて** のアクションのバージョンと有効化設定が開発環境の状態に合わせて同期されます。 `developmentActions` のアクションは同期対象外のため、動作確認中のアクションが検証環境に反映されることはありません。

ビューのコードも同じリポジトリで管理している場合は、同じワークフローで検証環境用のストレージへのアップロードも実行できます。

## 本番環境への変更 [](#本番環境への変更)

検証環境で確認が取れたら、本番環境に同期します。

本番環境への変更は、 `stg` ブランチを `prd` ブランチへ取り込む昇格PRとして作成します。

### 1. PRの作成 [](#1-prの作成)

`prd` ブランチに `stg` をマージするPRを作成します。

PR作成時に `bm sync --dry <本番環境のID> --from <検証環境のID>` を実行すると、本番環境への同期内容がPRにコメントされます。環境間の同期内容なので、コメントのヘッダーは `## bm sync 実行後、以下の変更が同期されます` です。

### 2. マージして本番環境に同期 [](#2-マージして本番環境に同期)

PRをマージすると、CDで `bm sync <本番環境のID> --from <検証環境のID>` が実行され、本番環境の **すべて** のアクションのバージョンと有効化設定が検証環境の状態に合わせて同期されます。 `--from <検証環境のID>` により同期元は検証環境になるため、開発環境にしかない変更や `developmentActions` のアクションが本番環境へ直接同期されることはありません。

ビューのコードも同じリポジトリで管理している場合は、同じワークフローで本番環境用のストレージへのアップロードも実行できます。

## コード管理した設定のWeb上での変更 [](#コード管理した設定のweb上での変更)

コード管理している設定は、引き続きWeb上（ベースマキナの管理画面）からも変更できます。

Web上で変更すると、そのアクションの管理方法は一時的に「Web管理」に戻ります。次回の `bm sync` で、設定ファイルに差分があれば「コード管理に移行（変更あり）」として設定を上書きし、差分がなければ「コード管理に移行（変更なし）」として管理方法だけを戻します。

Web UIで新しく作成したアクション・ビューを設定ファイルに取り込みたい場合は、ローカルで [`bm pull`](/code_management/cli/pull/) を実行し、生成されたファイルを通常のPRに含めてレビューします。

コード管理を開始した後は、設定の変更はコードで実施することを推奨します。

⚠️

Web上での変更時には、コード管理されている設定であることを示す警告が表示されます。

## CI/CDの設定例 [](#cicdの設定例)

`developmentActions` を使う場合も、CI/CDの設定に変更は不要です。他環境への同期時の除外は `bm sync` が自動で処理します。

| トリガー | 対象ブランチ | 実行内容 | 説明 |
| --- | --- | --- | --- |
| PR作成時 | `main` | `bm sync --dry` | 開発環境への適用差分をPRにコメント |
| PRマージ時 | `main` | `bm sync` | 設定の差分を開発環境に反映 |
| PRマージ時 | `stg` | `bm sync <stg環境ID>` | 開発環境のバージョンを検証環境に同期 |
| PR作成時 | `prd` | `bm sync --dry <prd環境ID> --from <stg環境ID>` | 本番環境への同期差分をPRにコメント |
| PRマージ時 | `prd` | `bm sync <prd環境ID> --from <stg環境ID>` | 検証環境のバージョンを本番環境に同期 |

### GitHub Actionsの設定ファイル例 [](#github-actionsの設定ファイル例)

以下は `.github/workflows/` に配置するワークフローファイルの例です。公式Composite Action [`basemachina/bm-action` (opens in a new tab)](https://github.com/basemachina/bm-action) を使い、OIDC認証・ `bm sync` 実行・PRコメント投稿を一括で扱います。認証の詳細は [GitHub Actions](/code_management/ci_cd/github_actions/) をご参照ください。

#### 開発環境への反映（ `.github/workflows/sync-dev.yml` ） [](#開発環境への反映githubworkflowssync-devyml)

```
name: Sync to dev
on:
  pull_request:
    branches: [main]
  push:
    branches: [main]
 
permissions:
  contents: read
  id-token: write
  pull-requests: write
  packages: read
 
jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: "22"
      - run: npm ci
      - run: npx tsc --noEmit
      - uses: basemachina/bm-action@v1
        with:
          audience: "https://basemachina.com"
          with-disable: "true"
```

#### 検証環境への同期（ `.github/workflows/sync-stg.yml` ） [](#検証環境への同期githubworkflowssync-stgyml)

```
name: Sync to stg
on:
  push:
    branches: [stg]
 
permissions:
  contents: read
  id-token: write
  pull-requests: write
  packages: read
 
jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: "22"
      - run: npm ci
      - run: npx tsc --noEmit
      - uses: basemachina/bm-action@v1
        with:
          audience: "https://basemachina.com"
          environment-id: "${{ vars.BM_STG_ENV_ID }}"
```

#### 本番環境への同期（ `.github/workflows/sync-prd.yml` ） [](#本番環境への同期githubworkflowssync-prdyml)

```
name: Sync to prd
on:
  pull_request:
    branches: [prd]
  push:
    branches: [prd]
 
permissions:
  contents: read
  id-token: write
  pull-requests: write
  packages: read
 
jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: "22"
      - run: npm ci
      - run: npx tsc --noEmit
      - uses: basemachina/bm-action@v1
        with:
          audience: "https://basemachina.com"
          environment-id: "${{ vars.BM_PRD_ENV_ID }}"
          from: "${{ vars.BM_STG_ENV_ID }}"
```

環境IDは [GitHub Actionsの変数 (opens in a new tab)](https://docs.github.com/ja/actions/learn-github-actions/variables) などで管理することを推奨します。

[基本（2ブランチ運用）](/code_management/examples/two_branch/) [コード取得設定との連携](/code_management/examples/view_code_fetch/)
---
コード管理

運用例

基本（2ブランチ運用）

# 基本（2ブランチ運用）

`main` ブランチと `prd` ブランチの2つで、開発環境と本番環境を管理する運用例です。

検証環境を使わないシンプルな構成で、小規模なプロジェクトに適しています。

## ブランチと環境の対応 [](#ブランチと環境の対応)

| ブランチ | ベースマキナの環境 | 説明 |
| --- | --- | --- |
| `main` | 開発環境 | 日常的な開発を進めるブランチ |
| `prd` | 本番環境 | 本番環境用のブランチ |

## 開発環境への変更 [](#開発環境への変更)

### 1. featureブランチで開発 [](#1-featureブランチで開発)

`main` から `feature/xxx` ブランチを作成し、アクションの設定やビューのコードを編集してPRを作成します。

例えば、「ユーザー一覧ビューのテーブルにユーザーの有効/無効状態を表示する」場合、以下のように変更します。

1. `list-users` アクションのJavaScriptコードを編集して、 `status` を返すようにする
1. `user-list` ビューのTSXコードを編集して、テーブルに稼働状態列を追加する
1. 2ファイルを変更したPRを作成する

### 2. CIで差分を確認 [](#2-ciで差分を確認)

PRが作成されると、CIで `bm sync --dry` が実行され、設定の差分がPRにコメントされます。開発環境への反映内容なので、コメントのヘッダーは `## bm sync 実行後、以下の変更が適用されます` です。

### 3. マージして開発環境に反映 [](#3-マージして開発環境に反映)

PRをマージすると、CDで `bm sync` が実行され、アクションの変更がベースマキナの開発環境に反映されます。新しいバージョンが作成され、開発環境では常に最新バージョンが使用されるため即時反映されます。設定ファイルから削除されたアクションは、 `--with-disable` 指定時のみ開発環境で無効化されます。

ビューのコードを同じリポジトリで管理している場合は、ワークフローにビューのビルド・アップロード処理を追加します。詳細は [コード取得設定との連携](/code_management/examples/view_code_fetch/) をご参照ください。レビュー設定やデータソースなど、コード管理対象外の設定は引き続きベースマキナの画面から設定してください。

## 本番環境への変更 [](#本番環境への変更)

開発環境で確認が取れたら、本番環境に同期します。

本番環境への変更は、 `main` ブランチを `prd` ブランチへ取り込む昇格PRとして作成します。

### 1. PRの作成 [](#1-prの作成)

`prd` ブランチに `main` をマージするPRを作成します。

PR作成時に `bm sync --dry <本番環境のID>` を実行すると、本番環境への同期内容がPRにコメントされます。環境間の同期内容なので、コメントのヘッダーは `## bm sync 実行後、以下の変更が同期されます` です。

### 2. マージして本番環境に同期 [](#2-マージして本番環境に同期)

PRをマージすると、CDで `bm sync <本番環境のID>` が実行され、本番環境の **すべて** のアクションのバージョンと有効化設定が開発環境の状態に合わせて同期されます。

ビューのコードも同じリポジトリで管理している場合は、同じワークフローで本番環境用のストレージへのアップロードも実行できます。詳細は [コード取得設定との連携](/code_management/examples/view_code_fetch/) をご参照ください。

## コード管理した設定のWeb上での変更 [](#コード管理した設定のweb上での変更)

コード管理している設定は、引き続きWeb上（ベースマキナの管理画面）からも変更できます。

Web上で変更すると、そのアクションの管理方法は一時的に「Web管理」に戻ります。次回の `bm sync` で、設定ファイルに差分があれば「コード管理に移行（変更あり）」として設定を上書きし、差分がなければ「コード管理に移行（変更なし）」として管理方法だけを戻します。

Web UIで新しく作成したアクション・ビューを設定ファイルに取り込みたい場合は、ローカルで [`bm pull`](/code_management/cli/pull/) を実行し、生成されたファイルを通常のPRに含めてレビューします。

コード管理を開始した後は、設定の変更はコードで実施することを推奨します。

⚠️

Web上での変更時には、コード管理されている設定であることを示す警告が表示されます。

## CI/CDの設定例 [](#cicdの設定例)

| トリガー | 対象ブランチ | 実行内容 | 説明 |
| --- | --- | --- | --- |
| PR作成時 | `main` | `bm sync --dry` | 開発環境への適用差分をPRにコメント |
| PRマージ時 | `main` | `bm sync` | 設定の差分を開発環境に反映 |
| PR作成時 | `prd` | `bm sync --dry <prd環境ID>` | 本番への同期差分をPRにコメント |
| PRマージ時 | `prd` | `bm sync <prd環境ID>` | 開発環境のバージョンを本番に同期 |

### GitHub Actionsの設定ファイル例 [](#github-actionsの設定ファイル例)

以下は `.github/workflows/` に配置するワークフローファイルの例です。公式Composite Action [`basemachina/bm-action` (opens in a new tab)](https://github.com/basemachina/bm-action) を使い、OIDC認証・ `bm sync` 実行・PRコメント投稿を一括で扱います。認証の詳細は [GitHub Actions](/code_management/ci_cd/github_actions/) をご参照ください。

#### 開発環境への反映（ `.github/workflows/sync-dev.yml` ） [](#開発環境への反映githubworkflowssync-devyml)

```
name: Sync to dev
on:
  pull_request:
    branches: [main]
  push:
    branches: [main]
 
permissions:
  contents: read
  id-token: write
  pull-requests: write
  packages: read
 
jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: "22"
      - run: npm ci
      - run: npx tsc --noEmit
      - uses: basemachina/bm-action@v1
        with:
          audience: "https://basemachina.com"
          with-disable: "true"
```

`dry` はデフォルトで `"auto"` です。 `pull_request` では自動的に `bm sync --dry` が実行されてPRに差分がコメントされ、 `push` では `bm sync` が実行されて開発環境に反映されます。開発環境への反映時のPRコメントは `以下の変更が適用されます` 、push時のヘッダーは `## bm sync が完了しました` です。

#### 本番環境への同期（ `.github/workflows/sync-prd.yml` ） [](#本番環境への同期githubworkflowssync-prdyml)

```
name: Sync to prd
on:
  pull_request:
    branches: [prd]
  push:
    branches: [prd]
 
permissions:
  contents: read
  id-token: write
  pull-requests: write
  packages: read
 
jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: "22"
      - run: npm ci
      - run: npx tsc --noEmit
      - uses: basemachina/bm-action@v1
        with:
          audience: "https://basemachina.com"
          environment-id: "${{ vars.BM_PRD_ENV_ID }}"
```

環境IDは [GitHub Actionsの変数 (opens in a new tab)](https://docs.github.com/ja/actions/learn-github-actions/variables) などで管理することを推奨します。

本番環境への同期時も `dry` はデフォルトで `"auto"` です。 `pull_request` では `以下の変更が同期されます` 、 `push` では `## bm sync が完了しました` というヘッダーで結果が出力されます。

[GitLab CI](/code_management/ci_cd/gitlab_ci/) [実践的な開発フロー](/code_management/examples/three_branch/)
---
コード管理

運用例

コード取得設定との連携

# コード取得設定との連携

ビューの設定自体は [`defineView`](/code_management/sdk/define_view/) でコード管理できます。このページで扱うのは、それとは別の仕組みで、コードエディターのビューのコードをストレージ（GCSやS3など）経由で配信する運用です。コード管理のリポジトリでビュー（コードエディター）のコードを管理し、 [コード取得設定](/view/code_editor/git_management/) と組み合わせて配信します。

アクションとビューのコードの変更を同じPRでレビューできるため、関連する変更をまとめて管理できます。

## リポジトリ構造の例 [](#リポジトリ構造の例)

```
my-project/
├── basemachina.config.ts
├── actions/
│   ├── get-users.ts
│   └── fetch-view-code.ts       # ビューのコードを取得するアクション
└── views/
    └── user-list/
        └── index.tsx             # ビューのコード
```

## TypeScriptの設定 [](#typescriptの設定)

ビューのコード（ `.tsx` ）をTypeScriptの型チェック対象に含める場合は、コード管理のリポジトリにダウンロードされる `tsconfig.json` へ次の設定を追加してください。

```
{
  "extends": "@basemachina/sdk/tsconfig.code.json",
  "compilerOptions": {
    "jsx": "react-jsx"
  },
  "include": [
    "basemachina.config.ts",
    "type.d.ts",
    "src/**/*.ts",
    "views/**/*.tsx"
  ]
}
```

`@basemachina/sdk` が提供する `tsconfig.code.json` には `jsx` の設定が含まれていないため、ビューのTSXファイルを `tsc` に通すには `"jsx": "react-jsx"` を個別に指定する必要があります。

また、ビューの型定義（ `@basemachina/view` ）はReactの型を参照しているため、 `react` と `@types/react` を別途インストールしてください。

```
npm install --save-dev react @types/react
```

`@basemachina/sdk` の `peerDependencies` には `react` / `@types/react` は含まれていないため、ビューのコードを同じリポジトリに同居させる場合は個別の追加が必要です。

CIで型チェックを実行する場合、 `views/**/*.tsx` を `tsconfig.json` の `include` に追加しておく必要があります。含めていないビューコードは型チェックの対象になりません。

## 仕組み [](#仕組み)

ビューのコード管理は、以下の流れで動作します。

1. リポジトリ内の `views/` ディレクトリにビューのコードを配置する
1. CI/CDで、ビューのコードをビルドしてストレージ（GCSやS3など）にアップロードする
1. ベースマキナのビューで [コード取得設定](/view/code_editor/git_management/) を有効化し、ストレージからコードを取得するアクションを指定する
1. ビューを表示するたびに、ストレージから最新のコードが読み込まれる

## GitHub Actionsの設定ファイル例 [](#github-actionsの設定ファイル例)

以下は、ビューのコードをビルドしてGCSにアップロードするワークフローの例です。アクションの反映には公式Composite Action [`basemachina/bm-action` (opens in a new tab)](https://github.com/basemachina/bm-action) を使用します。

#### 開発環境への反映（ `.github/workflows/sync-dev.yml` ） [](#開発環境への反映githubworkflowssync-devyml)

```
name: Sync to dev
on:
  pull_request:
    branches: [main]
  push:
    branches: [main]
 
permissions:
  contents: read
  id-token: write
  pull-requests: write
  packages: read
 
jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: "22"
      - run: npm ci
      - run: npx tsc --noEmit
 
      # アクションの差分検出・反映
      - uses: basemachina/bm-action@v1
        with:
          audience: "https://basemachina.com"
          with-disable: "true"
 
      # ビューのビルド・アップロード
      - name: Build views
        if: github.event_name == 'push'
        run: npm run build:views
      - name: Upload to GCS (dev)
        if: github.event_name == 'push'
        uses: google-github-actions/upload-cloud-storage@v2
        with:
          path: dist/views
          destination: my-bucket/dev
```

ストレージへのアップロード方法は使用するサービス（GCS、S3など）に合わせて変更してください。

## 環境ごとのコードの切り替え [](#環境ごとのコードの切り替え)

[変数](/action/parameter/vars_secrets/) と組み合わせることで、環境ごとに異なるビューのコードを読み込めます。

例えば、ストレージのパスに環境ごとの変数をプレフィックスとして設定することで、開発環境と本番環境で異なるコードを使用できます。

詳しくは [Git管理](/view/code_editor/git_management/) の「branchの切り替え」をご参照ください。

[実践的な開発フロー](/code_management/examples/three_branch/) [トラブルシューティング](/code_management/troubleshooting/)
---
コード管理

始め方

# 始め方

コード管理を始めるための手順を説明します。

## 前提条件 [](#前提条件)

- [開発環境](/admin/environment/development_environment/) が設定済みであること
- 企業アカウントの管理者の権限を持っていること

## 1. サービスアカウントとOIDC信頼ポリシーの用意 [](#1-サービスアカウントとoidc信頼ポリシーの用意)

コード管理では、CLIやCI/CDからの操作を [サービスアカウント](/service_account/) として実行します。コード管理を始める前に、 [サービスアカウント](/service_account/) を用意し、アクション管理権限を持つグループへ所属させてください。

CI/CDからコード管理を利用する場合は、 [OIDC信頼ポリシー](/service_account/#oidc%E4%BF%A1%E9%A0%BC%E3%83%9D%E3%83%AA%E3%82%B7%E3%83%BC) の設定も必要です。ローカルから `bm sync` を実行するだけであれば、OIDC信頼ポリシーの設定は不要です。

## 2. プロジェクトのダウンロード [](#2-プロジェクトのダウンロード)

「設定」→「開発設定」を開くと、「コード管理」セクションにセットアップガイドが表示されます。ガイドの「設定をダウンロードする」ステップにある「設定ファイル一式のダウンロード」ボタンをクリックすると、プロジェクトの設定ファイル一式（ `oac-project.zip` ）をダウンロードできます。アクションだけでなくビューも、コード管理対応のものはあわせてダウンロードされます。

ダウンロードされるファイルの構成は、 [設定ファイル](/code_management/configuration/) をご参照ください。

ダウンロードの対象は、コード管理対応のアクション・ビューのうち識別子が設定されているものです。識別子が未設定のアクションはダウンロードされないため、同じ画面にある「識別子の一括設定」から事前に識別子を設定してください。ビューについても識別子が未設定のものはダウンロードされないため、各ビューの編集画面から事前に識別子を設定してください。

## 3. リポジトリの作成とセットアップ [](#3-リポジトリの作成とセットアップ)

ダウンロードしたファイルをGitリポジトリとして管理します。

```
# リポジトリを作成
git init
git remote add origin <リモートリポジトリのURL>
 
# 依存関係をインストール
npm install
 
# 初回コミットとプッシュ
git add .
git commit -m "Initial commit"
git push -u origin main
```

ダウンロードした `package.json` には、npmで公開されている [`@basemachina/sdk` (opens in a new tab)](https://www.npmjs.com/package/@basemachina/sdk) と [`@basemachina/cli` (opens in a new tab)](https://www.npmjs.com/package/@basemachina/cli) の依存関係が含まれています。通常は `npm install` でそのままインストールできます。

セットアップ後にWeb
UIで作成したアクションをコード管理へ取り込みたい場合は、 [`bm   pull`](/code_management/cli/pull/) を使用します。 `bm   pull` は標準の `src/actions/` 、 `src/bm-refs.ts` 、 `type.d.ts` を更新対象にするため、取り込み運用を使う場合はこれらのパスを維持することを推奨します。

## 4. CI/CDからの認証の準備 [](#4-cicdからの認証の準備)

GitHub Actionsから `bm sync` を実行する場合は、公式のComposite Action [`basemachina/bm-action` (opens in a new tab)](https://github.com/basemachina/bm-action) を使うのが簡単です。 `bm-action` がOIDC ID Tokenの取得・ `bm sync` の実行・PRへのコメント投稿を一括で担います。

ワークフローには `id-token: write` のパーミッションを付与します。具体的なワークフローの書き方は、 [CI/CDの設定](/code_management/ci_cd/) と [運用例](/code_management/examples/two_branch/) をご参照ください。

`bm-action` を使わずに自前でCI/CDを構成する場合は、CI/CDが発行したOIDC ID Tokenを環境変数 `BM_OIDC_TOKEN` に設定して `bm sync` を実行します。

ローカルからCLIを実行する場合は、 [`bm   login`](/code_management/cli/login/) でブラウザログインするとトークンが `~/.basemachina/credentials.json` に保存されます。以降はそのトークンが自動で利用されるため、 `BM_OIDC_TOKEN` の設定は不要です。

## 5. 初回の反映 [](#5-初回の反映)

セットアップが完了したら、PRを作成してコード管理を開始します。

1. PRを作成すると、CIで `bm sync --dry` が実行され、設定の差分がPRにコメントされます。
1. 初回は各アクション・ビューの管理方法が「Web管理」から「コード管理」に移行する差分が表示されます。
1. PRをマージすると、 `bm sync` が実行されて管理方法が更新されます。

初回の反映では、管理方法の変更のみが反映されます。アクション・ビューの設定内容自体は変更されません。ダウンロード後に画面上で設定を変更した場合は、差分として検出されます。

## 6. 必要に応じてWeb管理のアクション・ビューを取り込む [](#6-必要に応じてweb管理のアクションビューを取り込む)

コード管理の開始後も、Web UIでアクションやビューを新規作成することがあります。設定ファイルにまだ存在しないWeb管理のアクション・ビューは、ローカルで `bm pull` を実行するとコード管理用のファイルとして取り込めます。

```
bm pull
```

`bm pull` は取り込み予定を表示し、確認後に `src/actions/` ・ `src/views/` 配下の新規ファイル、 `src/bm-refs.ts` 、 `type.d.ts` 、設定ファイルへの追記を適用します。詳しくは [`bm pull`](/code_management/cli/pull/) をご参照ください。

これで、以降はコード管理の運用に沿って開発を進められます。詳しくは [運用例](/code_management/examples/two_branch/) をご参照ください。

[コード管理とは](/code_management/) [設定ファイル](/code_management/configuration/)
---
コード管理

SDK

defineAction

# defineAction

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

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

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

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

## 共通フィールド [](#共通フィールド)

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

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

### previousId [](#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` は実行を許可する対象の配列です。未指定の場合はプロジェクト内の全ユーザーに実行が許可されます。

```
permissions: [
  { type: "user", id: "<ユーザーID>" },
  { type: "userGroup", id: "<ユーザーグループID>" },
  { type: "javascriptAction", id: "<JavaScriptアクションの識別子>" },
];
```

| `type` | 説明 |
| --- | --- |
| `"user"` | 特定のユーザーに実行を許可 |
| `"userGroup"` | 特定のユーザーグループに属するユーザーに実行を許可 |
| `"javascriptAction"` | JavaScriptアクションの判定結果に従って実行を許可 |

### notificationSettings [](#notificationsettings)

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

```
notificationSettings: {
  onSuccess: {
    notificationMethodId: "<通知方法の識別子>",
    mentionTargetUserIds: ["<ユーザーID>"],
    message: { type: "text", value: "ユーザー作成が成功しました" },
  },
  onError: {
    notificationMethodId: "<通知方法の識別子>",
    message: { type: "text", value: "ユーザー作成に失敗しました" },
  },
};
```

| フィールド | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `onSuccess.notificationMethodId` | `string` | はい | 通知方法の識別子 |
| `onSuccess.mentionTargetUserIds` | `string[]` | いいえ | メンション対象ユーザー |
| `onSuccess.message` | `{ type: "text"; value: string }` | いいえ | 通知メッセージ |
| `onError.notificationMethodId` | `string` | はい | 通知方法の識別子 |
| `onError.mentionTargetUserIds` | `string[]` | いいえ | メンション対象ユーザー |
| `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アクションを指定 |
| `dataSource` | `string` | はい | Amazon Athenaデータソースの識別子 |
| `statements` | `SqlReadStatement[]` | はい | 実行するSQL文（1件以上）。SELECT系クエリのみサポート |
| `parseColumnTypeJSONEnabled` | `boolean` | いいえ | JSON型の列の値をJavaScriptの配列やオブジェクトに変換するかどうか。未指定時は変換する（ `true` ） |
| `parameters` | `ParameterConfig[]` | いいえ | パラメーター定義（下記参照） |

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

| フィールド | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `sql` | `string` | はい | 実行するSQL文。 `{{ paramName }}` でパラメーターを埋め込める |
| `title` | `string` | いいえ | 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アクションを指定 |
| `dataSource` | `string` | はい | Amazon S3データソースの識別子 |
| `bucket` | `string` | はい | 操作対象のバケット名。 `{{ paramName }}` でパラメーターを埋め込める |
| `operation` | discriminated union | はい | バケットへの操作種別と関連フィールド（下記参照） |
| `parameters` | `ParameterConfig[]` | いいえ | パラメーター定義（下記参照） |

### `operation` の指定方法 [](#operationの指定方法)

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

```
// オブジェクトをアップロード
operation: "UPLOAD",
objectKey: "invoices/{{ invoiceId }}.pdf",
fileParameter: "file",
 
// オブジェクトをダウンロード
operation: "DOWNLOAD",
objectKey: "invoices/{{ invoiceId }}.pdf",
 
// バケット内のオブジェクト一覧を取得（objectKey は任意。指定すると接頭辞で絞り込む）
operation: "LIST",
objectKey: "invoices/",
 
// 署名付きURLを発行
operation: "ISSUE_SIGNED_URL",
objectKey: "invoices/{{ invoiceId }}.pdf",
signedUrlMethod: "GET",
```

| `operation` | 必須フィールド | 説明 |
| --- | --- | --- |
| `"UPLOAD"` | `objectKey` 、 `fileParameter` | 指定したファイルパラメーターの内容をバケットの `objectKey` にアップロードする。 `fileParameter` は `parameters` に定義したFILEパラメーターの `name` と一致する必要がある |
| `"DOWNLOAD"` | `objectKey` | バケットの `objectKey` からオブジェクトをダウンロードする |
| `"LIST"` | なし | バケット内のオブジェクト一覧を取得する。任意で `objectKey` を指定すると、そのキーを接頭辞（prefix）として一覧を絞り込む |
| `"ISSUE_SIGNED_URL"` | `objectKey` 、 `signedUrlMethod` | `objectKey` に対する署名付きURLを発行する。 `signedUrlMethod` は `"GET"` または `"PUT"` |

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

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

## BigQueryアクション [](#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アクションを指定 |
| `dataSource` | `string` | はい | BigQueryデータソースの識別子 |
| `statements` | `SqlReadStatement[]` | はい | 実行するSQL文（1件以上）。SELECT系クエリのみサポート |
| `parseColumnTypeJSONEnabled` | `boolean` | いいえ | JSON型の列の値をJavaScriptの配列やオブジェクトに変換するかどうか。未指定時は変換する（ `true` ） |
| `parameters` | `ParameterConfig[]` | いいえ | パラメーター定義（下記参照） |

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

## Firestoreアクション [](#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アクションを指定 |
| `dataSource` | `string` | はい | Firestoreデータソースの識別子 |
| `code` | `string` | はい | 実行するスクリプト。 `firebase-admin` SDKの `firestore` インスタンスを利用できる。 `readFile()` の戻り値も指定可能（JavaScriptアクションと同様） |
| `parameters` | `ParameterConfig[]` | いいえ | パラメーター定義（下記参照） |

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

## Google Cloud Storageアクション [](#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アクションを指定 |
| `dataSource` | `string` | はい | Google Cloud Storageデータソースの識別子 |
| `bucket` | `string` | はい | 操作対象のバケット名。 `{{ paramName }}` でパラメーターを埋め込める |
| `operation` | discriminated union | はい | バケットへの操作種別と関連フィールド |
| `parameters` | `ParameterConfig[]` | いいえ | パラメーター定義（下記参照） |

`operation` の指定方法と取りうる値、パラメーターで利用できない種別はAmazon S3アクションと同じです。詳しくは [Amazon S3アクションの `operation`](/code_management/sdk/define_action/#operation%E3%81%AE%E6%8C%87%E5%AE%9A%E6%96%B9%E6%B3%95) をご参照ください。

## Google Sheetsアクション [](#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アクションを指定 |
| `dataSource` | `string` | はい | Google Sheetsデータソースの識別子 |
| `spreadsheetId` | `string` | はい | 対象スプレッドシートのID |
| `sheetId` | `number` | いいえ | 対象シートのID。省略時は先頭シート |
| `operation` | discriminated union | はい | シートへの操作種別と関連フィールド（下記参照） |
| `parameters` | `ParameterConfig[]` | いいえ | パラメーター定義（下記参照） |

### `operation` の指定方法 [](#operationの指定方法-1)

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

| `operation` | 必須フィールド | 説明 |
| --- | --- | --- |
| `"READ"` | なし | シートからデータを読み取る。 `a1Notation` でフィルター範囲を指定可（例: `"Sheet1!A1:B10"` ）。 `{{ paramName }}` でパラメーターを埋め込める。 `valueRenderOption` で値の解釈方法を指定可 |
| `"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アクション [](#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アクションを指定 |
| `dataSource` | `string` | はい | gRPCデータソースの識別子 |
| `fullMethodName` | `string` | はい | gRPCメソッドの完全修飾名。形式は `{package}.{Service}/{Method}` |
| `headers` | `{ name: string; value: string }[]` | いいえ | リクエストヘッダー |
| `body` | `{ payload: string }` | いいえ | リクエストボディ。 `payload` はJSON文字列で指定し、内部で `{{ paramName }}` の形式でパラメーターを埋め込める |
| `parameters` | `ParameterConfig[]` | いいえ | パラメーター定義（下記参照） |

## HTTP APIアクション [](#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アクションを指定 |
| `dataSource` | `string` | はい | HTTP APIデータソースの識別子 |
| `url` | `string` | はい | リクエスト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` では指定不可 |
| `validateStatus` | `boolean` | いいえ | 200系以外のレスポンスステータスコードをエラーとして扱うか。未指定時は `true` |
| `parameters` | `ParameterConfig[]` | いいえ | パラメーター定義（下記参照） |

### bodyフィールド [](#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"` | `content` | JSON文字列 |
| `"multipart/form-data"` | `entries` （1件以上） | `name` と `value` または `fileParameter` で指定。 `fileParameter` はFILEパラメーターの `name` と一致する必要がある |
| `"application/x-www-form-urlencoded"` | `entries` | `name` と `value` のペア |
| `"graphql"` | `query` | GraphQLクエリ。 `variables` はJSON文字列で指定 |
| 未指定 | `content` | Content-TypeをSDK側でつけない。MIMEを指定したい場合は `headers` で `Content-Type` を別途指定 |

## JavaScriptアクション [](#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アクションを指定 |
| `code` | `string` | はい | JavaScriptコードまたは `readFile()` の戻り値 |
| `parameters` | `ParameterConfig[]` | いいえ | パラメーター定義（下記参照） |

### コード本体の書き方 [](#コード本体の書き方)

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

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

#### TypeScriptで書く場合（推奨） [](#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`](/code_management/sdk/read_file/) をご参照ください。

#### JavaScriptで書く場合 [](#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アクション [](#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アクションを指定 |
| `dataSource` | `string` | はい | MySQLデータソースの識別子 |
| `statements` | `SqlStatement[]` | はい | 実行するSQL文（1件以上） |
| `convertNullToString` | `boolean` | いいえ | 結果の `NULL` を文字列の `"NULL"` として扱うか。未指定時は `null` として扱う |
| `parameters` | `ParameterConfig[]` | いいえ | パラメーター定義（下記参照） |

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

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

## PostgreSQLアクション [](#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アクションを指定 |
| `dataSource` | `string` | はい | PostgreSQLデータソースの識別子 |
| `statements` | `SqlStatement[]` | はい | 実行するSQL文（1件以上） |
| `convertNullToString` | `boolean` | いいえ | 結果の `NULL` を文字列の `"NULL"` として扱うか。未指定時は `null` として扱う |
| `parameters` | `ParameterConfig[]` | いいえ | パラメーター定義（下記参照） |

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

## Snowflakeアクション [](#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アクションを指定 |
| `dataSource` | `string` | はい | Snowflakeデータソースの識別子 |
| `statements` | `SqlReadStatement[]` | はい | 実行するSQL文（1件以上）。SELECT系クエリのみサポート |
| `parameters` | `ParameterConfig[]` | いいえ | パラメーター定義（下記参照） |

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

## パラメーター定義 [](#パラメーター定義)

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

| パラメーター種別 | 使用可能なアクション種別 |
| --- | --- |
| `TEXT` | すべて |
| `NUMBER` | すべて |
| `DATE` | すべて |
| `BOOL` | すべて |
| `ARRAY` | すべて |
| `TUPLE` | すべて |
| `SYSTEM_VALUE` | Amazon S3 / Firestore / Google Cloud Storage / Google Sheets / gRPC / HTTP API / JavaScript / MySQL / PostgreSQL |
| `JSON` | gRPC / HTTP API / MySQL / PostgreSQL |
| `FILE` | Amazon S3 / Google Cloud Storage / HTTP API / JavaScript |
| `SQL` | Amazon 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パラメーター [](#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"` | はい | テキストパラメーターを指定 |
| `name` | `string` | はい | パラメーター名 |
| `description` | `string` | いいえ | 説明 |
| `required` | `boolean` | いいえ | 必須かどうか |
| `defaultValue` | `string` | いいえ | 初期値 |
| `minLength` | `number` | いいえ | 最小文字数 |
| `maxLength` | `number` | いいえ | 最大文字数 |
| `multiline` | `boolean` | いいえ | 複数行入力を許可するか |
| `newlineCharacters` | `string` | いいえ | `multiline: true` の場合の改行コード |
| `regexValidation` | `{ type?: "custom"; pattern: string; errorMessage?: string }` | いいえ | 入力値のバリデーション正規表現（ `multiline: false` のみ） |
| `selectOptions` | `{ label?: string; value: string }[]` | いいえ | 選択肢（ `multiline: false` のみ。1件以上必須）。 `label` 省略時は `value` を表示 |
| `masterDataFetchSettingId` | `string` | いいえ | マスターデータ取得設定の識別子（ `multiline: false` のみ） |

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

### NUMBERパラメーター [](#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 }[]` | いいえ | 選択肢（1件以上必須）。 `label` 省略時は `value` を表示 |
| `masterDataFetchSettingId` | `string` | いいえ | マスターデータ取得設定の識別子 |

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

### DATEパラメーター [](#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"` | はい | 日付パラメーターを指定 |
| `name` | `string` | はい | パラメーター名 |
| `description` | `string` | いいえ | 説明 |
| `required` | `boolean` | いいえ | 必須かどうか |
| `includeTime` | `boolean` | いいえ | 時刻を含めるか |
| `useUnixTimestamp` | `boolean` | いいえ | Unixタイムスタンプで扱うか。 `true` の場合 `format` は指定不可 |
| `format` | `string` | いいえ | 日付フォーマット（ `useUnixTimestamp: false` の場合のみ） |
| `defaultValue` | `string` | いいえ | 初期値。日付として有効な文字列であれば `format` に従わない値も受け付ける（例: `"2024-01-31"`, `"2024-01-31T14:30:00Z"` ） |

### BOOLパラメーター [](#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"` | はい | 真偽値パラメーターを指定 |
| `name` | `string` | はい | パラメーター名 |
| `description` | `string` | いいえ | 説明 |
| `defaultValue` | `boolean` | いいえ | 初期値 |
| `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"` 扱い |
| `trueValue` | `string` | はい | `true` のときに送信する文字列 |
| `falseValue` | `string` | はい | `false` のときに送信する文字列 |

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

```
{
  type: "FILE",
  name: "uploadFile",
  required: true,
  maxBytes: 10485760,
}
```

| フィールド | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `type` | `"FILE"` | はい | ファイルパラメーターを指定 |
| `name` | `string` | はい | パラメーター名 |
| `description` | `string` | いいえ | 説明 |
| `required` | `boolean` | いいえ | 必須かどうか |
| `maxBytes` | `number` | いいえ | 最大バイト数 |

### JSONパラメーター（gRPC / HTTP API / MySQL / PostgreSQLアクションのみ） [](#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パラメーターを指定 |
| `name` | `string` | はい | パラメーター名 |
| `description` | `string` | いいえ | 説明 |
| `valueType` | `"TEXT" | "NUMBER" | "DATE"` | はい | JSONとして送信する値の型 |

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

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

### SYSTEM\_VALUEパラメーター [](#system_valueパラメーター)

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

```
{
  type: "SYSTEM_VALUE",
  name: "currentUserId",
  required: true,
}
```

| フィールド | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `type` | `"SYSTEM_VALUE"` | はい | システム値パラメーターを指定 |
| `name` | `string` | はい | パラメーター名 |
| `description` | `string` | いいえ | 説明 |
| `required` | `boolean` | いいえ | 必須かどうか |

### 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パラメーターを指定 |
| `name` | `string` | はい | パラメーター名 |
| `description` | `string` | いいえ | 説明 |
| `required` | `boolean` | いいえ | 必須かどうか |
| `defaultValue` | `string` | いいえ | 初期値 |
| `selectOptions` | `{ label?: string; value: string }[]` | いいえ | 選択肢（1件以上必須）。 `label` 省略時は `value` を表示 |

### ARRAYパラメーター [](#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"` | はい | 配列パラメーターを指定 |
| `name` | `string` | はい | パラメーター名 |
| `description` | `string` | いいえ | 説明 |
| `format` | オブジェクト | いいえ | 送信時の形式。省略時は配列のまま渡す |
| `childElement` | `ElementConfig` | はい | 要素の型（ `TEXT` / `NUMBER` / `DATE` / `ARRAY` / `TUPLE` ） |
| `defaultValue` | 配列 | いいえ | 初期値。要素には `null` や `undefined` を指定不可 |
| `minItems` | `number` | いいえ | 最小要素数 |
| `maxItems` | `number` | いいえ | 最大要素数 |

`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パラメーター [](#tupleパラメーター)

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

```
{
  type: "TUPLE",
  name: "filter",
  format: { type: "JSON" },
  tupleElements: [
    { label: "開始日", childElement: { type: "DATE" } },
    { label: "終了日", childElement: { type: "DATE" } },
  ],
}
```

| フィールド | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `type` | `"TUPLE"` | はい | タプルパラメーターを指定 |
| `name` | `string` | はい | パラメーター名 |
| `description` | `string` | いいえ | 説明 |
| `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` を省略すると真偽値のまま扱われます。

[defineConfig](/code_management/sdk/define_config/) [defineView](/code_management/sdk/define_view/)
---
コード管理

SDK

defineConfig

# defineConfig

プロジェクト全体の設定を定義する関数です。

CLIはこの関数の戻り値からプロジェクト全体の設定内容を読み込みます。 `basemachina.config.ts` で使用し、 `default export` します。

## 使用例 [](#使用例)

```
import { defineConfig } from "@basemachina/sdk/oac";
import { getUsers } from "./src/actions/get-users";
import { listUsers } from "./src/actions/list-users";
import { userListView } from "./src/views/user-list";
 
export default defineConfig({
  project: {
    id: "your-project-id",
  },
  actions: [getUsers, listUsers],
  views: [userListView],
});
```

開発環境にのみ反映したいアクションやビューは、それぞれ `developmentActions` / `developmentViews` に指定します。

```
import { defineConfig } from "@basemachina/sdk/oac";
import { getUsers } from "./src/actions/get-users";
import { listUsers } from "./src/actions/list-users";
import { experimentalAction } from "./src/actions/experimental-action";
import { userListView } from "./src/views/user-list";
import { draftView } from "./src/views/draft";
 
export default defineConfig({
  project: {
    id: "your-project-id",
  },
  actions: [getUsers, listUsers],
  developmentActions: [experimentalAction],
  views: [userListView],
  developmentViews: [draftView],
});
```

## プロパティ [](#プロパティ)

| プロパティ | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `project.id` | `string` | はい | プロジェクトのID |
| `actions` | `ActionConfig[]` | はい | アクション定義（ `defineAction` の戻り値）の配列 |
| `developmentActions` | `ActionConfig[]` | いいえ | 開発環境にのみ反映するアクション定義の配列。 `bm sync` での開発環境への反映時には `actions` と同様に反映されますが、 `bm sync <環境ID>` での他環境への同期では対象外になります |
| `views` | `ViewConfig[]` | いいえ | ビュー定義（ `defineView` の戻り値）の配列 |
| `developmentViews` | `ViewConfig[]` | いいえ | 開発環境にのみ反映するビュー定義の配列。 `bm sync` での開発環境への反映時には `views` と同様に反映されますが、 `bm sync <環境ID>` での他環境への同期では対象外になります |

`actions` と `developmentActions` に同じ識別子（ `id` ）を持つアクションを指定するとバリデーションエラーになります。同じアクションを両方に書くことはできません。 `views` と `developmentViews` についても同様です。

[設定ファイル](/code_management/configuration/) [defineAction](/code_management/sdk/define_action/)
---
コード管理

SDK

defineView

# defineView

ビューを定義する関数です。 `type` フィールドで種別（コードエディター/ビジュアルエディター）を指定し、種別に応じたフィールドを設定します。

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

## 使用例 [](#使用例)

コードエディターのビューは、 `code` にビューのコードを指定します。

```
import { defineView, readFile } from "@basemachina/sdk/oac";
 
export const userListView = defineView({
  type: "codeEditor",
  id: "user-list",
  name: "ユーザー一覧",
  code: readFile("./view-codes/user-list.tsx"),
});
```

ビジュアルエディターのビューは、 `config` に画面構成を指定します。

```
import { defineView } from "@basemachina/sdk/oac";
 
export const orderListView = defineView({
  type: "visualEditor",
  id: "order-list",
  name: "注文一覧",
  config: {
    pageSetting: { title: "注文一覧" },
    components: [
      {
        type: "actionTable",
        id: "order-table",
        actionSetting: {
          type: "onComponentRender",
          actionId: "list-orders",
          args: {},
        },
        columnCustomizationSetting: [],
        resultTransformationSetting: { enabled: false },
      },
    ],
  },
  queryParameters: [
    { name: "status", required: false, valueForEditing: "shipped" },
  ],
});
```

## 共通フィールド [](#共通フィールド)

すべてのビュー種別で使用できるフィールドです。

| フィールド | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `type` | `"codeEditor" | "visualEditor"` | はい | ビュー種別 |
| `id` | `string` | はい | ビューの識別子。最大128文字で、使用できる文字は英数字・アンダースコア・ハイフン（ `^[a-zA-Z0-9_-]+$` ） |
| `previousId` | `string` | いいえ | 変更前の id。既存ビューの id を `bm sync` で変更するために宣言する（下記参照） |
| `name` | `string` | はい | ビュー名。1〜128文字 |

### previousId [](#previousid)

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

```
// before（typo を含む id）
export const userListView = defineView({
  type: "codeEditor",
  id: "user-lsit",
  name: "ユーザー一覧",
  code: readFile("./view-codes/user-list.tsx"),
});
 
// after（id を変更）
export const userListView = defineView({
  type: "codeEditor",
  id: "user-list",
  previousId: "user-lsit",
  name: "ユーザー一覧",
  code: readFile("./view-codes/user-list.tsx"),
});
```

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

`previousId` にはidと同じ値を指定できません。

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

## codeEditorのフィールド [](#codeeditorのフィールド)

| フィールド | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `code` | `string` | はい | ビューのコード。空文字は指定不可。 `readFile()` の戻り値も指定可能 |

コードの書き方は [`readFile`](/code_management/sdk/read_file/) をご参照ください。

## visualEditorのフィールド [](#visualeditorのフィールド)

| フィールド | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `config` | `VisualEditorConfig` | はい | ビジュアルエディターの画面構成（下記参照） |
| `queryParameters` | `ViewQueryParameterConfig[]` | いいえ | クエリパラメーターの定義（下記参照）。省略時は空配列 |

### config [](#config)

`config` はビジュアルエディターの画面構成を表すオブジェクトです。型定義が500行を超えるため、ここではトップレベルのフィールドと、配置できるコンポーネントの種類だけを紹介します。

| フィールド | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `pageSetting` | `{ title: string }` | いいえ | ページ設定。省略時はタイトルなし |
| `components` | コンポーネントの配列 | はい | ビューに配置するコンポーネントの一覧 |

`components` に配置できるコンポーネントは以下の4種類です。

- **actionDetailTable** ：アクション詳細テーブル
- **actionTable** ：アクションテーブル
- **actionForm** ：アクションフォーム
- **tab** ：他のコンポーネントをまとめるタブ

各コンポーネントの `id` はビュー内で一意にする必要があります。 `actionForm` の `onActionFormSubmit` など、コンポーネント間の参照先を指定する際のキーになります。

`config` を手書きするのは煩雑なため、通常はベースマキナの画面上でビジュアルエディターを使ってビューを作成し、 [`bm   pull`](/code_management/cli/pull/) で取り込んでコード管理に移行する運用を推奨します。

### queryParameters [](#queryparameters)

ビューのURLで受け取るクエリパラメーターの定義です。

```
queryParameters: [
  { name: "status", required: false, valueForEditing: "shipped" },
];
```

| フィールド | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `name` | `string` | はい | クエリパラメーター名。英数字とハイフン、アンダースコアのみ使用可能で1〜128文字。ビュー内で重複不可 |
| `required` | `boolean` | はい | 入力を必須にするかどうか |
| `valueForEditing` | `string` | はい | エディター上で編集する際に使用する値。1〜128文字の非空文字列 |

## 設定ファイルへの組み込み [](#設定ファイルへの組み込み)

定義したビューは、 `defineConfig` の `views` （または `developmentViews` ）に指定します。詳しくは [`defineConfig`](/code_management/sdk/define_config/) をご参照ください。

```
import { defineConfig } from "@basemachina/sdk/oac";
import { userListView } from "./src/views/user-list";
 
export default defineConfig({
  project: { id: "your-project-id" },
  actions: [],
  views: [userListView],
});
```

[defineAction](/code_management/sdk/define_action/) [readFile](/code_management/sdk/read_file/)
---
コード管理

SDK

readFile

# readFile

外部ファイルの内容を読み込む関数です。JavaScriptアクションやコードエディターのビューのコードを別ファイルで管理できます。

## 使用例 [](#使用例)

```
import { defineAction, readFile } from "@basemachina/sdk/oac";
 
// JavaScriptアクションのコードを読み込む
export const createUser = defineAction({
  id: "create-user",
  name: "ユーザー作成",
  type: "javascript",
  code: readFile("./js-action-codes/create-user.ts"),
});
```

```
import { defineView, readFile } from "@basemachina/sdk/oac";
 
// コードエディターのビューのコードを読み込む
export const userListView = defineView({
  type: "codeEditor",
  id: "user-list",
  name: "ユーザー一覧",
  code: readFile("./view-codes/user-list.tsx"),
});
```

## 引数 [](#引数)

| 引数 | 型 | 説明 |
| --- | --- | --- |
| `relativePath` | `string` | 呼び出し元ファイルからの相対パス |

## TypeScriptファイルの変換 [](#typescriptファイルの変換)

拡張子が `.ts` / `.tsx` / `.mts` / `.cts` のファイルを指定した場合は、型注釈を取り除いたJavaScriptに変換してから `code` に渡します。

これにより、JavaScriptアクションのコードをTypeScriptで記述できます。

JSXはそのまま残ります。 `.tsx` で書いたビューのコードも、変換後はJSXを含むJavaScriptとして保存されます。

変換後のコードは、元のファイルとインデントや空行の位置が一致するとは限りません。コードエディターで開いたときの見た目が元のファイルと異なる場合がありますが、動作に影響はありません。

拡張子が `.js` / `.jsx` のファイルは変換せず、内容をそのまま読み込みます。

[defineView](/code_management/sdk/define_view/) [bm login](/code_management/cli/login/)
---
コード管理

トラブルシューティング

# トラブルシューティング

コード管理の運用中によく発生する困りごとと、その対処方法をまとめます。

本ページでは「現状の対応方法」と並べて、 [今後追加予定の機能](/code_management/upcoming_features/) （ `bm   rollback` 、 `bm   hotfix` ）を使った将来の対応方法も紹介します。将来の対応方法は構想段階のため、仕様は変更される可能性があります。各ケースごとに、該当する「現状の対応方法」「将来の対応方法」またはその両方を記載します。

## バージョンを戻したい [](#バージョンを戻したい)

### 1つのアクションを以前のバージョンに戻したい [](#1つのアクションを以前のバージョンに戻したい)

**状況**: 本番環境に同期した特定のアクションに不具合があり、そのアクションだけを以前のバージョンに戻したい。

#### 対応方法 [](#対応方法)

アクション単位のバージョン巻き戻しはWeb UIからのみ実行できます（CLIには該当コマンドがありません）。

1. 本番環境のアクション一覧から、対象のアクションのバージョン/有効化設定画面を開く
1. 戻したい特定のバージョンを選択して保存する

[今後追加予定の `bm   rollback`](/code_management/upcoming_features/) は同期単位の巻き戻しのみを扱います。アクション単位の巻き戻しは、将来も引き続きWeb
UIでの操作を想定しています。

#### 注意事項 [](#注意事項)

- バージョンを戻しても、設定ファイル（ `basemachina.config.ts` ）の内容は変わりません。次回の `bm sync <環境ID>` で設定ファイルの内容が再度反映されるため、根本対応として設定ファイルも修正する必要があります

### 直前の同期全体を取り消したい [](#直前の同期全体を取り消したい)

**状況**: 本番環境への `bm sync <環境ID>` で複数のアクションをまとめて同期したが、同期全体を取り消したい。

#### 現状の対応方法 [](#現状の対応方法)

現状は、Web UIから **1アクションずつ手作業でバージョンを戻す** 方法しかありません。

1. 本番環境のアクション一覧から、同期で更新された各アクションのバージョン/有効化設定画面を開く
1. 戻したい特定のバージョンを選択して保存する

⚠️

`bm sync <環境ID>` は **同期元環境（開発環境または検証環境）の現在の状態** を本番環境に反映するコマンドです。そのため、本番ブランチで `git   revert` してCIを再実行しても、同期元環境のバージョンがすでに進んでいれば本番環境は戻りません。同期後に開発環境での変更が続いている通常の運用では、 `git   revert` による復旧はできません。

#### 将来の対応方法 [](#将来の対応方法)

[ロールバック（ `bm rollback` ）](/code_management/upcoming_features/) で、同期単位の一括ロールバックを実行します。

### 環境ごとに異なるバージョンで動かしたい [](#環境ごとに異なるバージョンで動かしたい)

**状況**: 開発環境では新しいバージョンで開発を続けつつ、本番環境だけは以前のバージョンに戻して動かしたい。

#### 現状の対応方法 [](#現状の対応方法-1)

本番環境のWeb UIで対象のアクションを以前のバージョンに切り替えます。ただし、次回の `bm sync <環境ID>` で開発環境のバージョンが再度反映されてしまうため、本番環境への同期のタイミングを制御する必要があります。

#### 将来の対応方法 [](#将来の対応方法-1)

[`bm rollback`](/code_management/upcoming_features/) で本番環境のみを以前の同期時点に戻すか、 [`bm hotfix`](/code_management/upcoming_features/) で本番環境専用のバージョンを作成します。

### 環境間でバージョンを揃え直したい [](#環境間でバージョンを揃え直したい)

**状況**: 何らかの理由で検証環境と本番環境のバージョンがずれてしまったため、揃え直したい。

#### 対応方法 [](#対応方法-1)

`bm sync` で同期元の環境を明示的に指定して再同期します。

```
# 検証環境のバージョンを本番環境に揃える
bm sync <本番環境のID> --from <検証環境のID>
```

詳細は [`bm sync` の他の環境への同期](/code_management/cli/sync/) をご参照ください。

## 特定の環境だけ修正したい [](#特定の環境だけ修正したい)

### 本番環境でのみ緊急修正を入れたい [](#本番環境でのみ緊急修正を入れたい)

**状況**: 本番環境でのみ発生するバグが見つかり、開発環境を経由せずに本番環境だけを直接修正したい。

#### 現状の対応方法 [](#現状の対応方法-2)

現状の `bm sync` では、開発環境を経由しないと本番環境のアクションを修正できません。やむを得ずWeb UIでアクションを直接修正する場合は、新しいバージョンを作成したうえで、本番環境のバージョン/有効化設定画面から作成したバージョンを紐づけます。その後、変更内容を設定ファイルにも反映する必要があります。

#### 将来の対応方法 [](#将来の対応方法-2)

`bm hotfix` コマンドで、本番環境のアクションを直接修正します。想定する運用フローは [hotfix（ `bm hotfix` ）](/code_management/upcoming_features/) をご参照ください。

## 設定ファイルとWeb UIの整合性 [](#設定ファイルとweb-uiの整合性)

### Web UIで変更した内容をコード管理に戻したい [](#web-uiで変更した内容をコード管理に戻したい)

**状況**: Web UIから誤って変更してしまったアクションを、設定ファイルの内容に戻したい。

#### 対応方法 [](#対応方法-2)

設定ファイルを変更せずに `bm sync` を実行します。Web UIで変更されたアクションは、次回の `bm sync` で「コード管理に移行（変更あり）」として設定ファイルの内容に上書きされます。

詳細は [`bm sync` の管理方法による挙動の違い](/code_management/cli/sync/) をご参照ください。

### Web UIで作成したアクションを設定ファイルに取り込みたい [](#web-uiで作成したアクションを設定ファイルに取り込みたい)

**状況**: Web UIで新しく作成したアクションを、設定ファイルにも反映してコード管理に戻したい。

#### 対応方法 [](#対応方法-3)

ローカルで [`bm pull`](/code_management/cli/pull/) を実行します。

```
bm pull
```

`bm pull` は、設定ファイルにまだ存在しないWeb管理アクションを `src/actions/` 配下に生成し、設定ファイルの `actions` 配列へ追記します。識別子が未設定のアクションは取り込めないため、Web UIの「識別子の一括設定」で識別子を設定してから再実行してください。

更新後、 `bm sync --dry` で差分が出ないことを確認してから運用に戻します。

### 既存のコード管理アクションをWeb UIで変更した内容を取り込みたい [](#既存のコード管理アクションをweb-uiで変更した内容を取り込みたい)

**状況**: すでに設定ファイルに含まれているアクションをWeb UIで変更し、その変更内容を設定ファイルへ反映したい。

#### 対応方法 [](#対応方法-4)

既存の設定ファイルに同じ識別子のアクションがある場合、そのアクションは `bm pull` の取り込み対象にはなりません。以下のいずれかの方法で設定ファイルを更新してください。

- Web UIで変更内容を確認し、対応する設定ファイルを手動で更新する
- [始め方](/code_management/getting_started/) の「プロジェクトのダウンロード」と同じ手順で「設定ファイル一式のダウンロード」から再ダウンロードし、変更されたアクションのファイルだけ差し替える

設定ファイルの内容でWeb UIの変更を戻したい場合は、設定ファイルを変更せずに `bm sync` を実行します。

### 設定ファイルから誤ってアクションを削除した [](#設定ファイルから誤ってアクションを削除した)

**状況**: 設定ファイルから誤ってアクションの定義を削除してしまいました。 `bm sync` はまだ実行していない、または `--with-disable` を指定していません。

#### 対応方法 [](#対応方法-5)

設定ファイルからアクションを削除しただけでは、 `--with-disable` を指定しない限り環境上のアクションは変更されません。 `git revert` または手動で設定ファイルを元に戻し、再度 `bm sync` を実行してください。

`--with-disable` を指定して開発環境で無効化してしまった場合も、設定ファイルにアクションを戻して `bm sync` を実行すれば、開発環境で **自動的に再有効化** されます。

詳細は [開発環境での無効化と再有効化](/code_management/cli/sync/) をご参照ください。

### 設定ファイルから削除したアクションを環境からも削除したい [](#設定ファイルから削除したアクションを環境からも削除したい)

**状況**: 不要になったアクションを設定ファイルから削除したので、環境上でも無効化したい。

#### 対応方法 [](#対応方法-6)

`--with-disable` オプションを指定して `bm sync` を実行することで、開発環境上のアクションを無効化できます。

```
bm sync --with-disable
```

検証環境・本番環境への伝播は、その後の `bm sync <環境ID>` で実行します。

`--with-disable` はアクションを削除するのではなく、有効化設定を「無効」に変更する操作です。アクションのデータと識別子は保持されるため、設定ファイルに戻して `bm   sync` を実行すれば再有効化できます。

## 誤った同期への対処 [](#誤った同期への対処)

### 反映したくない変更が本番ブランチにマージされた [](#反映したくない変更が本番ブランチにマージされた)

**状況**: レビューが不十分なPRや、まだ本番環境に反映したくない変更が、誤って本番環境用のブランチにマージされてしまいました。

#### 対応方法 [](#対応方法-7)

現状は、本番環境のWeb UIから、マージ内容に含まれる各アクションを手作業で以前のバージョンに戻します。前述の「 [直前の同期全体を取り消したい](/code_management/troubleshooting/#%E7%9B%B4%E5%89%8D%E3%81%AE%E5%90%8C%E6%9C%9F%E5%85%A8%E4%BD%93%E3%82%92%E5%8F%96%E3%82%8A%E6%B6%88%E3%81%97%E3%81%9F%E3%81%84) 」と同じ手順です。

`git revert` でブランチの履歴を戻しても、同期元環境のバージョンがすでに進んでいれば本番環境は戻らないため、Web UIでの手作業が必要になります。

将来的には、 [`bm rollback`](/code_management/upcoming_features/) による同期単位のロールバックでも対応できる予定です。

### 本番に反映したくないアクションを分離したい [](#本番に反映したくないアクションを分離したい)

**状況**: 開発中・実験中のアクションが `bm sync <環境ID>` で他の環境にも反映されてしまうのを防ぎたい。

#### 対応方法 [](#対応方法-8)

設定ファイルで、対象アクションを `actions` ではなく `developmentActions` フィールドに指定します。 `developmentActions` に入れたアクションは `bm sync` で開発環境にのみ反映され、 `bm sync <環境ID>` の対象外となります。

詳細は [`defineConfig` の `developmentActions`](/code_management/sdk/define_config/) をご参照ください。運用フローに組み込んだ例は [実践的な開発フロー](/code_management/examples/three_branch/) をご参照ください。

## ビュー（コード取得設定）との組み合わせ [](#ビューコード取得設定との組み合わせ)

[コード取得設定](/view/code_editor/git_management/) を使ってビューのコードも同じリポジトリで管理している場合の対処方法です。

### アクションのロールバックに合わせてビューのコードも戻したい [](#アクションのロールバックに合わせてビューのコードも戻したい)

**状況**: アクションを以前のバージョンに戻したが、ビューのコード（コード取得設定で読み込んでいるファイル）が新しいままで動作しない。

#### 対応方法 [](#対応方法-9)

ビューのコード（コード取得設定で読み込んでいるファイル）は、アクションのバージョン履歴とは独立して、ストレージ上のファイルとして管理されています。アクションのロールバックと合わせてビューのコードも戻すには、本番環境用のブランチ（ `prd` ブランチなど）でビューのコードを修正してマージしてください。

⚠️

通常のCI構成（ [2ブランチ運用](/code_management/examples/two_branch/) や [実践的な開発フロー](/code_management/examples/three_branch/) の例）では、本番ブランチへのマージをトリガーに `bm   sync   <環境ID>` が自動実行されます。その結果、同期元環境の現在のバージョンが再度反映され、 **Web
UIで戻したアクションが最新バージョンに戻ってしまいます** 。

これを防ぐには、CIの設定に以下のような調整を加える必要があります。

- アクションの `bm sync <環境ID>` は、検証環境ブランチからのマージ経由でのみ実行するようにし、本番ブランチ直接のpushでは走らせない
- ビューのビルド・アップロードは、ビューのコードに変更があるときにだけ実行するようにする

これにより、本番ブランチでビューのコードだけを修正してマージしても、アクションの再同期は走らずビューのコードだけが差し戻されます。

[コード取得設定との連携](/code_management/examples/view_code_fetch/) [今後追加予定の機能](/code_management/upcoming_features/)
---
コード管理

今後追加予定の機能

# 今後追加予定の機能

⚠️

このページで紹介する機能はまだ開発に着手していない構想段階のものであり、仕様は大きく変更される可能性があります。実装時期は未定です。

コード管理で検討している今後の拡張機能を紹介します。

## 本番環境への反映後の修正 [](#本番環境への反映後の修正)

本番環境に同期したあとで問題が発覚した際に、素早くロールバックや修正ができる仕組みを追加する予定です。

### 現状の課題 [](#現状の課題)

現状の `bm sync` では、本番環境への反映後に問題が起きた場合、以下の点で対応が難しい状況です。

- 特定のアクションのバージョンを戻したい場合、Web UIで1つずつ手作業で戻す必要がある
- 本番環境のバージョンから特定のアクションだけを修正して同期する手段がない

これらを解消するため、 **ロールバック** と **hotfix** の2つの仕組みを追加する予定です。

### ロールバック（ `bm rollback` ） [](#ロールバックbm-rollback)

過去の同期で適用された [バージョンと有効化設定](/action/enablement_settings/) に、指定した環境を巻き戻すコマンドを追加する予定です。 `bm sync <環境ID>` で実施した同期を履歴として保持し、その履歴を参照して同期単位でロールバックします。 `bm sync <環境ID>` で同時に更新されたアクションを、まとめて1つ前の状態に戻せます。

`bm   rollback` が扱うのは **同期単位** の巻き戻しのみです。特定の1アクションだけを以前のバージョンに戻したい場合は、現状と同様にWeb
UIの「バージョン/有効化設定画面」から個別に切り替えてください。

#### ビューのコードも一緒に戻したい場合 [](#ビューのコードも一緒に戻したい場合)

ビューのコード（ [コード取得設定](/view/code_editor/git_management/) で管理しているコード）も併せて戻したい場合は、本番環境用のブランチ（ `prd` ブランチなど）からビューのコードを修正してマージする運用を想定しています。

このとき、アクションのロールバックとビューのコードの差し戻しを独立して扱えるよう、CI/CD側で以下のような調整が必要になる想定です。

- ビューのコードに変更がある場合のみ、ビューのビルド・アップロードが実行されるようにする
- `bm sync <環境ID>` は、検証環境ブランチからのマージ経由でのみ実行されるようにする

### hotfix（ `bm hotfix` ） [](#hotfixbm-hotfix)

本番環境など特定の環境のアクションを、その環境だけで直接修正するコマンドを追加する予定です。通常の `bm sync` のように開発環境を経由せずに、指定した環境に直接新しい [バージョンと有効化設定](/action/enablement_settings/) を作成して紐づけます。

#### `bm sync` との違い [](#bm-syncとの違い)

| コマンド | 比較対象 | 反映先 |
| --- | --- | --- |
| `bm sync` | 設定ファイル ↔ 開発環境 | 開発環境 |
| `bm hotfix` | 設定ファイル ↔ 指定環境 | 指定した環境のみ |

`bm sync` は常に開発環境との差分を起点にしますが、 `bm hotfix` は指定した環境の現在の設定内容と、設定ファイルの差分を比較します。

#### 想定する挙動 [](#想定する挙動)

設定ファイルと、指定した環境の状態の組み合わせに応じて、以下のように動作する予定です。

| 設定ファイル | 指定環境の状態 | 動作 |
| --- | --- | --- |
| 存在する | 有効 | 新しいバージョンを作成し、その環境のhotfixバージョンとして紐づける |
| 存在する | 無効 | その環境で **再有効化** する（差分があれば新しいバージョンも作成して紐づける） |
| 存在する | アクション自体が存在しない | **エラー** （hotfixでの新規作成は禁止） |
| 存在しない | 存在する | その環境でアクションを無効化する |

アクションをその環境にしか存在しない状態で新規作成することは、他環境との乖離が大きくなるため禁止します。新規アクションの作成は、通常の `bm   sync` フローで全環境に展開する必要があります。また、開発環境は通常の `bm   sync` で管理される起点のため、 `bm   hotfix` の対象環境には指定できない想定です。開発環境への反映は引き続き `bm   sync` を使用します。

#### 想定する運用フロー [](#想定する運用フロー)

本番環境で発生した問題を `bm hotfix` で修正する場合は、以下のような運用を想定しています。

1. 本番環境用のブランチ（ `prd` ブランチなど）から、hotfix用のブランチを作成する
1. hotfixブランチで設定ファイルを修正する
1. PRを作成すると、CIで `bm hotfix <本番環境のID> --dry` が実行され、差分がPRにコメントされる
1. PRをマージすると、CIで `bm hotfix <本番環境のID>` が実行され、本番環境に直接反映される
1. hotfixブランチの内容を `main` などの開発ブランチにも取り込み、次回の通常同期と整合を取る

ビューのコードも一緒に修正したい場合は、hotfixブランチで修正してマージします。

[トラブルシューティング](/code_management/troubleshooting/) [サービスアカウント](/service_account/)
---
非推奨の機能

環境別のアクション表示・非表示設定

# 環境別アクションの表示・非表示設定

⚠️

この機能は廃止いたしました（ただし、一部のお客さまには継続してご提供しております）。
代わりに [アクションの有効化設定](/action/enablement_settings/) をご利用ください。

アクション一覧画面で環境ごとに特定のアクションを非表示にする設定です。

例えば、開発環境でのデバッグ用のアクションを本番環境では非表示にするといった設定が可能です。

## 環境別のアクション表示・非表示設定の方法 [](#環境別のアクション表示非表示設定の方法)

アクション一覧画面の「環境別のアクションの表示・非表示設定」メニューから設定できます。

1. メニューから「アクション」を選択します。
1. アクション一覧画面の右上のメニューボタンをクリックします。
1. 「環境別のアクションの表示・非表示設定」画面に移動します。

![環境別のアクション表示・非表示設定の導線](/images/environment/action_visibility/link.png)

設定画面では、現在の環境での各アクションの表示・非表示を設定できます。

![環境別のアクション表示・非表示設定画面](/images/environment/action_visibility/setting.png)

メニューバーから環境を切り替えると他の環境の設定ができます。

![環境を切り替える](/images/environment/switch_environment.png)

非表示にされたアクションは、アクション一覧画面の「非表示のアクションを表示する」を有効にすると現在の画面に表示できます。
この設定は管理者でないユーザーでも有効にできます。

[UIビルダーとは](/deprecated/uibuilder/what_is_uibuilder/)
---
非推奨の機能

チェックボックスを使ったアクションへの移動

# チェックボックスを使ったアクションへの移動

アクションの実行結果をチェックボックスで選択できるフォームを表示して、別のアクションに選択結果を渡すことができます。

## チェックボックスの利用に使う関数 [](#チェックボックスの利用に使う関数)

チェックボックスを結果加工のカスタマイズで利用する際には、以下の3つの関数を使用します。

```
/**
 * checkboxInput は指定された名前と値、デフォルトのチェック状態をもとに、チェックボックスを作成します。
 */
function checkboxInput(
  name: string,
  value: string | number,
  checked: boolean,
): Checkbox;
```

```
/**
 * submitToActionForm は指定されたフォームの値を使って、アクションに遷移するためのフォームタグを作成します。
 * @param formId フォームの ID です。
 * @param actionId 遷移先のアクションのID、または識別子です。
 * @param params 必須ではありません。指定すると URL パラメータになります。
 * @param data フォームで括りたい、後続のコンポーネントの表示に必要なデータを指定します。
 */
function submitToActionForm(
  formId: string,
  actionId: string,
  params?: Record<string, string>,
  data: any,
): SubmitToActionForm;
```

```
/**
 * submitToAction は指定されたフォームID（アクションへの遷移用）の送信ボタンを作成する。
 */
function submitToActionButton(
  formId: string,
  label: string,
): SubmitToActionButton;
```

チェックボックスの表示に必要な関数が `checkboxInput` です。

別のアクションに移動したり、選択肢を渡すために必要な関数が `SubmitToActionForm`, `submitToActionButton` です。

## チェックボックスを表示する [](#チェックボックスを表示する)

実際にチェックボックスを使ってアクションへの移動を作っていきます。

ID付きのオブジェクトの配列にチェックボックスをつけて、複数のIDを選択して別のアクションに渡しながら移動するような例を取り上げます。

まず、チェックボックスは `checkboxInput` を使って表示できます。

オブジェクトのIDを複数選択して、 `ids` というパラメーター名で別のアクションに渡すような想定をして、以下のような関数を呼び出します。

![チェックボックスの表示スクリプト](/images/checkbox_input/checkbox_input_script.png)

関数が呼び出されるとUI上にはチェックボックスが表示されます。この時点では表示されるだけで選択候補を使って他の画面に移動できません。

![チェックボックスが表示されたUI](/images/checkbox_input/checkbox_input_view.png)

## チェックした候補を使って別のアクションに移動する [](#チェックした候補を使って別のアクションに移動する)

次に、別のアクションへの移動を設定します。

チェックボックスの値が別のアクションへの移動に使われるものだと宣言するために `submitToActionForm` を呼び出します。

![チェックボックスを使ったフォーム](/images/checkbox_input/checkbox_input_form.png)

次に、このフォームの入力値を使ってアクションへの移動イベントを発火されるために、 `submitToActionButton` を呼び出します。

呼び出す際に、どのフォームの値を移動に使うのか識別するため `sample_form` というフォームのIDを `submitToActionForm` と `submitToActionButton` で設定しています。

![アクションボタン](/images/checkbox_input/checkbox_input_button.png)

設定すると以下のような画面が表示されます。

![アクションボタンを使った画面](/images/checkbox_input/checkbox_input_button_view.png)

チェックボックスをクリックして選択候補を選び、ボタンを押すと別のアクションで `ids` というパラメーター名で値が受け渡されていることがわかります。

この時、複数の選択肢の値はカンマつなぎの文字列として移動先のアクションに渡されます。

![遷移先に渡される値](/images/checkbox_input/checkbox_input_arguments.png)

このようにして事前に複数の選択肢をチェックボックスで選び、値を別のアクションへ渡せるようになりました。

[(旧)JavaScriptアクション](/deprecated/javascript_action/) [システム値](/deprecated/system_parameter/)
---
非推奨の機能

(旧)JavaScriptアクション

# (旧)JavaScriptアクション

## (旧)JavaScriptアクションとは [](#旧javascriptアクションとは)

（旧）JavaScriptアクションは、任意のJavaScriptのコードをブラウザ上で実行するアクションです。

（旧）JavaScriptアクションの登録にはデータソースの設定が必要ないため、アクションの追加画面から直接登録できます。

## (旧)JavaScriptアクションの記述方法 [](#旧javascriptアクションの記述方法)

（旧）JavaScriptアクションの内容は、関数の中身として実行されます。

`return` 文を使って返した配列またはObjectがアクションの結果となります。

`{{ パラメータ名 }}` で、アクションに渡されたパラメータを変数として扱うことができます。

（旧）JavaScriptアクションは、Firestoreアクションと異なりAsyncFunctionとして実行されないため、トップレベルで `await` を使うことができません。

### 記述例 [](#記述例)

```
return {
  data: [{ id: 1 }, { id: 2 }, { id: 3 }],
};
```

#### 実行結果 [](#実行結果)

![(旧)JavaScriptアクションの実行結果](/images/deprecated_javascript_action/result.png)

[マスターデータの多言語翻訳](/usecase/ai_integration/master_data_translator/) [チェックボックスを使ったアクションへの移動](/deprecated/checkbox_input/)
---
非推奨の機能

システム値

# システム値

システム値はベースマキナ上の処理の結果（例：ページネーション設定時の情報）を値と紐づける際に設定するパラメーターの種類です。

ユーザー自身がシステム値を任意入力で変更することは想定されていません。

特に紐づけがされていない場合は空文字列として送信されます。

システム値を実際に利用する例として [ページネーション](/action/transformer_script/pagination/) の設定があります。

ぜひそちらのドキュメントもご確認ください。

![システム](/images/action_parameter/system.png)

[チェックボックスを使ったアクションへの移動](/deprecated/checkbox_input/) [UIビルダーとは](/deprecated/uibuilder/what_is_uibuilder/)
---
非推奨の機能

UIビルダー

UIビルダーとは

⚠️

UIビルダーは実験的な機能として一部のお客さまに限定して提供されていましたが、「 [ビジュアルエディター](/view/visual_editor/) 」のリリースに伴い非推奨となります。
UIビルダーでの新規のビューの作成はできませんのでご注意ください。

# UIビルダーとは

![UIビルダーの画面](/images/uibuilder/what_is_uibuilder/uibuilder_setting.png)

UIビルダーは、 [ビュー](/view/) をノーコードに近い形式で作成できる機能です。

ソフトウェアエンジニアか否かを問わず広いお客さまが、型が決まった範囲で情報やフォームを集約した自然なUIで管理画面を作ることを目的としています。

UIビルダーは、現在α版の機能となっております。また大幅な機能変更が入ることによるお客さまへの業務影響を考慮し、主に新規のお客さまを中心に限定的に公開しています。

## UIビルダーの利用目的 [](#uiビルダーの利用目的)

ベースマキナには **アクション** と **ビュー** の2種類の画面作成方法があります。

アクションではパラメーターの型に応じたフォームと、レスポンス内容に対応した画面が自動で作成されます。

一方でビューでは、プレビューツールや [Git管理](/view/code_editor/git_management/) などの機能を使いつつ、JavaScriptを使って自由なUIを作成できる機能です。

UIビルダーは、その中間の位置づけの画面作成機能です。

決められた範囲でコンポーネントやイベントトリガーを設定するだけで、業務をストレスなく進められる管理画面を作成できます。

### 利用想定 [](#利用想定)

具体的には以下のような画面を作ることを想定しています。

- 複数のアクションを呼び出して、ユーザーの関連情報を集約する詳細画面
- レコードの新規追加画面へのボタンや、行ごとの操作メニューがついたテーブルを表示できる検索画面
- グリッドやタブなどを用いたレイアウトで、複数の業務の起点に使える画面

## UIビルダーへの導線 [](#uiビルダーへの導線)

UIビルダーへの導線は、ビューの一覧画面の上部にあります。

クリックするとUIビルダーでのビュー作成画面が開きます。

![UIビルダーへの導線](/images/uibuilder/what_is_uibuilder/uibuilder_button.png)

## 画面構成 [](#画面構成)

![UIビルダーの画面構成](/images/uibuilder/what_is_uibuilder/uibuilder_page_elements.png)

UIビルダーの設定画面は大きく4つの領域で構成されています。

- コンポーネント追加、配置換えをする左側のサイドバー
- コンポーネントごとの設定をする右側のサイドバー
- 設定内容をプレビューする中央の表示領域
- 画面名やアクセス制御など、ページ全体にかかる設定をする上部のメニュー

です。それぞれの領域で設定を登録した後、画面上部のメニューの「保存」ボタンを押すと、設定内容が保存されます。

## コンポーネント [](#コンポーネント)

### コンポーネントの配置方法 [](#コンポーネントの配置方法)

左側のサイドバーの「新規追加」タブからコンポーネントを選択すると、中央の表示領域の一番下にコンポーネントが追加されます。

追加されたコンポーネントは同じく左側のサイドバーの「レイアウト」タブで削除や並べ替え、入れ子にする設定ができます。

### コンポーネントの種類別の設定 [](#コンポーネントの種類別の設定)

「レイアウト」タブでコンポーネントを選択すると、各コンポーネントの詳細を設定できます。

#### テキスト [](#テキスト)

テキストを表示するためのコンポーネントです。

見出しやページタイトルにご利用ください。

#### アクションフォーム [](#アクションフォーム)

アクションを実行するためのフォームです。

実行するアクションの設定や、実行時に表示するメッセージなどを設定できます。

実行後の処理の設定で、画面移動や再読み込みなどの処理も設定できます。

#### アクションテーブル [](#アクションテーブル)

アクションの実行結果を表示するためのコンポーネントです。

ページ表示時にアクションを実行するか、別のコンポーネント（アクションフォーム）で実行したアクションの実行結果を表示するかを設定できます。

また、高度なオプションでアクションの結果を調整できます。

**ページネーション設定**

ページネーション方式を選んで、クライアントサイドとサーバーサイドのどちらでページネーションするかを設定できます。

サーバーサイドの場合はオフセット形式かカーソル形式かを選択できます。

それぞれの形式に対応して、ページネーションに設定するアクションのパラメーターなどを設定してください。

**操作設定**

- テーブル全体のメニュー
- 行クリック時のイベント
- 行操作メニュー

という設定項目を通じて、アクションテーブルを起点にした操作を充実させられます。

テーブル全体にかかる操作導線の表示（新規追加など）はテーブル全体のメニューで設定してください。

行をクリックしたときの画面移動などは行クリック時のイベントで設定してください。

行の値を使ったアクションの実行、行クリック時に移動する画面以外へと移動したいときの導線などは行操作メニューで設定できます。

#### ボックス [](#ボックス)

画面のレイアウトを調整するためのコンポーネントです。

- グリッド
- フレックスボックス
- タブ

の3種類から選択できます。

ボックスを追加した後、そのボックスの中に入れるコンポーネントは画面左側の「レイアウト」から選択できます。

ボックス以外のコンポーネントを選択すると、どのボックスに追加するかを選ぶセレクトボックスが表示されるので、お選びください。

## 変数 [](#変数)

変数は、アクションフォームの初期値、アクションテーブルの行クリックや行操作メニューのアクション実行のパラメーター、画面移動の際のクエリパラメーターなどで、使用できる値です。

### 変数の使用方法 [](#変数の使用方法)

値の入力欄で `{{ 変数 }}` という形式で設定すると、設定に対応する操作をした際に変数が展開されます。

### 使用できる変数 [](#使用できる変数)

以下が使用できる変数の一覧です。

#### actions [](#actions)

アクションの実行結果が格納された変数です。

`actions['fetch-user-list'].results[0].success` のように、IDまたは識別子を指定してアクションの実行結果を参照できます。

#### urlQueries [](#urlqueries)

クエリパラメーターが格納された変数です。

`urlQueries.id` のように、パラメーター名を指定してクエリパラメーターの値を参照できます。

#### row [](#row)

アクションテーブルの行の値が格納された変数です。

`row.id` のように、列名を指定して値を取得できます。

### 変数の値の確認方法 [](#変数の値の確認方法)

`actions` や `urlQueries` は画面右下の **ページ内で使用できる変数** から確認できます。

アクションを実行した後や画面移動直後に、変数の値がどう保持されているかを確認しながら設定できます。

![ページ内で使用できる変数](/images/uibuilder/what_is_uibuilder/uibuilder_inspector.png)

[システム値](/deprecated/system_parameter/) [環境別のアクション表示・非表示設定](/deprecated/action_visibility/)
---
よくある疑問点

アクションに関する質問

# アクションに関する質問

## HTTP API/gRPCアクションでオブジェクトの配列を送信したい [](#http-apigrpcアクションでオブジェクトの配列を送信したい)

HTTP APIアクションやgRPCアクションのリクエストボディでオブジェクトの配列（gRPCにおけるrepeatedのmessage）を送信したい場合、現状ではJavaScriptアクションと組み合わせて実現する必要があります。

### 送信したいオブジェクトの配列の例 [](#送信したいオブジェクトの配列の例)

以下のように、オブジェクトの配列を送信したい場合を考えます。

```
{
  "id": "example123",
  "items": [
    { "name": "item1", "value": 100 },
    { "name": "item2", "value": 200 },
    { "name": "item3", "value": 300 }
  ]
}
```

### 設定方法 [](#設定方法)

#### 1. HTTP API/gRPCアクションの設定例 [](#1-http-apigrpcアクションの設定例)

オブジェクトの配列のJSON文字列を受け取るパラメーターを **テキストパラメーター** として設定します。

- パラメーター名： `items` （配列のJSON文字列を受け取るパラメーター）
- 種類：テキスト

リクエストボディでは、以下のように `items` パラメーターを使用します。

```
{
  "id": "{{ id }}",
  "items": {{ items }}
}
```

`{{ items }}` は、後述の通りJavaScriptアクションから送信したJSON文字列によって置換されるため、ダブルクォートをつけないように注意してください。

gRPCアクションでも同様の設定方法で、repeatedのmessageを送信できます。

#### 2. JavaScriptアクションの設定例 [](#2-javascriptアクションの設定例)

JavaScriptアクションでオブジェクトの配列を作成し、 `JSON.stringify()` でJSON文字列に変換してからHTTP API/gRPCアクションのパラメーターの値に入力します。

**パラメーター設定例**

- `id` ：テキストパラメーター
- `items` ：配列パラメーター（要素の種類がタプル）
  - タプルにはオブジェクトのプロパティに対応する要素を設定

**コード例**

```
import { executeAction } from "@basemachina/action";
 
/** @type { import("@basemachina/action").Handler } */
export default async (args) => {
  // タプルの配列からオブジェクトの配列を作成
  const items = args.items.map((item) => {
    return {
      name: item[0], // タプルの1番目の要素
      value: item[1], // タプルの2番目の要素
    };
  });
 
  // HTTP API/gRPCアクションを実行
  return await executeAction("action-id", {
    id: args.id,
    items: JSON.stringify(items), // JSON文字列に変換
  });
};
```

### 今後の改善予定 [](#今後の改善予定)

多くのお客さまからご要望をいただいておりますので、よりシンプルに設定できる機能を検討中です。恐れ入りますが、それまではこちらの方法での実装をお願いいたします。

[トラブルシューティング](/faq/troubleshooting/) [ユーザーの権限](/faq/authorities/)
---
よくある疑問点

ユーザーの権限

# ユーザーの権限

ベースマキナでは、各ユーザーの機能や情報へのアクセスを適切に制御するための各種権限が設定できます。

以下で、企業アカウントとプロジェクトのそれぞれの権限について詳しく説明します。

## 企業アカウントの権限 [](#企業アカウントの権限)

企業アカウントの権限は、以下の2種類で管理できます。

- 管理者
- 通常ユーザー

### 企業アカウントの管理者 [](#企業アカウントの管理者)

企業アカウントの管理者は、以下の操作ができます。

- 企業アカウント設定画面内の操作
  - 企業アカウントのユーザー管理： ユーザーの追加、削除、編集が可能です。
  - 企業アカウントのセキュリティ設定： SSO（シングルサインオン）やIPアドレス制限などの設定ができます。
  - 決済設定の確認： 決済設定の内容が確認できます。
  - 監査ログの設定・出力：企業アカウント内の操作履歴やログを確認できます。
- プロジェクトの作成

### 企業アカウントの通常ユーザー [](#企業アカウントの通常ユーザー)

企業アカウントの通常ユーザーは企業アカウント設定画面を閲覧できず、プロジェクトの権限に応じたプロジェクト内の操作のみができます。

## プロジェクトの権限 [](#プロジェクトの権限)

各プロジェクトの情報の閲覧やアクションの実行などの操作は、プロジェクトに追加されたユーザーのみできます。

たとえ企業アカウントの管理者であっても、プロジェクトに所属していなければプロジェクト内の情報は閲覧できません。

### プロジェクトの各設定の管理権限 [](#プロジェクトの各設定の管理権限)

プロジェクトの各種設定ができる管理権限は、プロジェクトユーザーの [グループ](/admin/user_management/project_group/) に「プロジェクトユーザー管理者」「開発者」などのロールを設定して管理できます。

ロールの設定されたグループに所属するプロジェクトユーザーは、ロールに応じたプロジェクト内の管理権限を持ち「アクション管理」「環境設定」などの設定ができるようになります。

以下がロールと各ロールが持つ管理権限の一覧です。

| 管理権限 | プロジェクト管理者 | プロジェクトユーザー管理者 | インフラ管理者 | 開発責任者 | 開発者 | アクション運用責任者 |
| --- | --- | --- | --- | --- | --- | --- |
| プロジェクトユーザー管理 | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
| グループ管理 | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
| プロジェクトの削除 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| プロジェクト名の変更 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| 環境設定 | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
| ナビゲーション設定 | ✅ | ✅ | ❌ | ✅ | ✅ | ❌ |
| アクション管理 | ✅ | ❌ | ❌ | ✅ | ✅ | ❌ |
| データソース管理 | ✅ | ❌ | ✅ | ✅ | ❌ | ❌ |
| ネットワーク設定 | ✅ | ❌ | ✅ | ✅ | ❌ | ❌ |
| 変数設定 | ✅ | ❌ | ❌ | ✅ | ✅ | ❌ |
| シークレット設定 | ✅ | ❌ | ✅ | ✅ | ❌ | ❌ |
| マスターデータ取得設定の設定 | ✅ | ❌ | ❌ | ✅ | ✅ | ❌ |
| ビュー管理 | ✅ | ❌ | ❌ | ✅ | ✅ | ❌ |
| 実行権限設定 | ✅ | ❌ | ❌ | ✅ | ❌ | ✅ |
| レビュー設定の設定 | ✅ | ❌ | ❌ | ✅ | ❌ | ✅ |
| アクションのバージョン・有効化の設定 | ✅ | ❌ | ❌ | ✅ | ❌ | ✅ |
| ビューのバージョン・有効化の設定 | ✅ | ❌ | ❌ | ✅ | ❌ | ✅ |
| 通知設定 | ✅ | ❌ | ❌ | ✅ | ❌ | ✅ |
| 定期実行の管理 | ✅ | ❌ | ❌ | ✅ | ✅ | ✅ |
| ジョブ結果の閲覧制限設定 | ✅ | ❌ | ❌ | ✅ | ❌ | ✅ |

管理権限のないプロジェクトユーザーは、アクションの実行やレビューの依頼・承認などの操作のみができます。

[アクションに関する質問](/faq/action_questions/) [bridgeとは](/faq/what_is_bridge/)
---
よくある疑問点

初回セットアップの流れ

# 初回セットアップの流れ

ベースマキナを実際にご利用の際には、以下のような手順をたどるとよりスムーズにご利用いただけます。

## 1. bridgeの設定 [](#1-bridgeの設定)

もしbridgeを利用して、より安全に社内のデータソースへのアクセスを試みる場合は、
自社のVPC内にbridgeを設置してください。bridgeはコンテナイメージを配布しておりますので、自由に配置できます。

詳しい設定方法（必要な環境変数など）はbridgeの設定画面で確認できます。

ベースマキナのサーバーがbridgeを通じてデータソースアクセスできるように固定IPからのアクセスを許可してください。

設定が保存できない場合は、トラブルシューティングを参考にしてください。
もし解決しない場合は、お気軽にサポートにお問い合わせください。

## 2. データソースの設定 [](#2-データソースの設定)

bridgeを通じてアクセスするデータソースを設定してください。

## 3. アクションの設定 [](#3-アクションの設定)

データソースを呼び出すアクションを設定してください。

もしアクションの実行に失敗する場合は、トラブルシューティングを参考にしてください。もし解決しない場合は、お気軽にサポートにお問い合わせください。

## 4. 他のユーザーの追加 [](#4-他のユーザーの追加)

企業アカウント設定画面から必要なユーザーを招待して、その後プロジェクトに追加してください。

### 4.1. サポートアカウントの設定 [](#41-サポートアカウントの設定)

ベースマキナからのサポートが必要な場合、企業アカウント設定画面のユーザー管理からサポートアカウントを追加できます。原因調査時にベースマキナ側からお手伝いできます。

## 5. 組織にあった権限設定（グループの作成） [](#5-組織にあった権限設定グループの作成)

プロジェクトの設定から、承認条件設定やアクション実行権限の設定に使う権限グループを設定できます。組織内の事情にあった形で、職種や担当業務などに応じた権限設定をしてください。

[HTTP API/gRPCのデータソースを登録する](/start_guide/datasource/http_or_grpc_datasource/) [トラブルシューティング](/faq/troubleshooting/)
---
よくある疑問点

画面作成機能の使い分け

# 画面作成機能の使い分け

ベースマキナには「アクションを実行する」、「アクションの実行結果を表示する」ための画面を作成する機能が用途別に複数あります。
このページでは、それぞれの機能の特徴と使い分けについて説明します。

生成AIを使用した「作りたい画面がどの機能で作れるか」の確認も可能です。
詳細は以下のドキュメントをご参照ください。

- [GeminiのGemでベースマキナのドキュメントを活用する](/tips/gemini_gem_integration/)
- [NotebookLMでベースマキナのドキュメントを活用する](/tips/notebooklm_integration/)
- [Claudeでベースマキナのドキュメントを活用する](/tips/claude_project_integration/)

※生成AIの回答内容の正確性は保証いたしかねます。あらかじめご了承ください。

## 画面を作成する3つの方法 [](#画面を作成する3つの方法)

ベースマキナで画面を作成する方法は、主に以下の3つがあります。

- [ビューのビジュアルエディター](/view/visual_editor/)
- [ビューのコードエディター](/view/)
- [アクション実行画面の結果の加工](/action/transformer_script/action_transform/)

### ビューのビジュアルエディター [](#ビューのビジュアルエディター)

直感的な操作で画面（ビュー）を作成できる機能です。
基本的にはノーコードで設定でき、さらにJavaScriptを使用した高度な設定も可能です。

### ビューのコードエディター [](#ビューのコードエディター)

ReactとJavaScriptを使って完全にカスタマイズされた画面を作成できる機能です。
コードを書く必要はありますが、組み込みの関数やコンポーネントが用意されているためフルスクラッチの開発よりも簡単に画面を作成できます。

### アクション実行画面の結果の加工 [](#アクション実行画面の結果の加工)

アクション実行画面で実行結果を加工して画面を作成できる機能です。
JavaScriptを使用して、実行結果を加工、別の画面へのリンクを表示などが可能です。
またアクションのパラメーターを使用したサーバーサイドのページネーションも設定できます。

## 使い分け [](#使い分け)

基本的に最も作成が簡単なビューのビジュアルエディターを推奨しています。

その上で、ビジュアルエディターでは対応できない画面の場合は「アクション実行画面の結果の加工」、
それら2つの機能でも対応できない場合にビューのコードエディターを使用するのがおすすめです。

以下では典型的な管理画面ごとに3つの方法の使い分けについて説明します。

### 一覧画面、検索画面 [](#一覧画面検索画面)

まずは以下のような一覧データをテーブルで表示する一覧画面・検索画面についてです。

![ユーザー名の入力フォームと検索機能を持つデータテーブルの例。ID、名前、メールアドレス、住所、作成日の列があり、10件のユーザーデータが表示されている。各行には編集するボタンがあり、ページネーション機能も含まれている](/images/faq/screen_creation_features_comparison/table.png)

以下の機能を持つ画面は、ビジュアルエディターで最も簡単に作成できます。

- 列名をカスタマイズする
- 列を並べ替える
- 列にアクション実行画面やビューへのリンクを表示する
- 列にリンクや画像、動画を表示する
- 実行結果をJavaScriptを使用して加工する
- クライアントサイドでのページネーション

以下の機能が必要な画面はビジュアルエディターでは作成できないため「アクション実行画面の結果の加工」を使用してください。
※ビューのコードエディターでも作成できますがコードを書いて設定する必要があるため、「アクション実行画面の結果の加工」の使用を推奨しています。

- サーバーサイドのページネーション
- 画像の表示サイズの変更（結果の加工の [image関数](/action/transformer_script/builtin_functions/image/) に対応する機能）

上記以外の機能を持つ画面は、ビューのコードエディターでのみ作成できます。

- 各行にサブメニューを表示する
- 列にバッジ、ボタンなどを表示する
- テーブルの上にボタンやメニューを表示する
- 文字や背景の色を変える

など。

### 詳細画面 [](#詳細画面)

次に以下のような詳細データを1件表示する詳細画面についてです。

![詳細ページのレコード情報表示例。ID、名前、メールアドレス、ロール、グループ、更新日時などのフィールドが縦に並んだレイアウトで表示されている](/images/faq/screen_creation_features_comparison/detail_table.png)

以下の機能を持つ画面は、ビジュアルエディターで最も簡単に作成できます。

- リンクや画像、動画を表示する
- 実行結果をJavaScriptを使用して加工する

以下の機能が必要な画面はビジュアルエディターでは作成できないため「アクション実行画面の結果の加工」を使用してください。
※ビューのコードエディターでも作成できますがコードを書いて設定する必要があるため、「アクション実行画面の結果の加工」の使用を推奨しています。

- アクション実行画面やビューへのリンクを表示する（結果の加工の [linkToAction関数](/action/transformer_script/builtin_functions/link_to_action/) 、 [linkToView関数](/action/transformer_script/builtin_functions/link_to_view/) に対応する機能）
- 画像の表示サイズの変更（結果の加工の [image関数](/action/transformer_script/builtin_functions/image/) に対応する機能）

上記以外の機能を持つ画面は、ビューのコードエディターでのみ作成できます。

- バッジ、ボタンなどを表示する
- 詳細データの上にボタンやメニューを表示する
- 文字や背景の色を変える

など。

### 作成画面、更新画面 [](#作成画面更新画面)

最後に以下のようなデータを入力するフォームを表示する作成画面・更新画面についてです。

![フォームページの入力フォーム例。ID、名前、メールアドレス、ロール、グループなどの入力フィールドと実行ボタンが表示されている](/images/faq/screen_creation_features_comparison/form.png)

以下の機能を持つ画面は、ビジュアルエディターで最も簡単に作成できます。

- フォームの初期値で固定の値を使用する
- フォームの初期値でクエリパラメーターの値を使用する
- フォームの初期値でアクションの実行結果の値を使用する

上記以外の機能を持つ画面は、ビューのコードエディターでのみ作成できます。

- 特定の入力項目を編集不可または非表示にする
- 入力項目のレイアウトを変更する（横並びにするなど）
- フォームの送信ボタンのラベルを変更する
- フォームの送信時にトーストを表示する
- 文字や背景の色を変える

など。

[用語集](/faq/terminology/) [アクション](/action/)
---
よくある疑問点

用語集

# 用語集

こちらは、ベースマキナ上で登場する用語について解説するページです。

### ベースマキナの設定に必要なもの [](#ベースマキナの設定に必要なもの)

| 用語 | 意味・用途 |
| --- | --- |
| 企業アカウント | お客さまの契約アカウントの単位。基本的に１事業者様ごとに１企業アカウントとして扱われます。 |
| プロジェクト | 企業アカウント内で作ることができるワークスペースの単位。別プロジェクトの設定は許可されたユーザーしか閲覧・編集することができません。 |
| 環境 | プロジェクト内で作ることができる運用環境の単位。環境ごとに、データソース・レビュー設定などの設定が切り替わります。「本番環境」「開発環境」などの環境を使い分けることができます。 |
| グループ | プロジェクトユーザーのグループ。グループ単位でのアクションの実行権限やレビューの承認条件の設定も可能です。 |
| プロジェクトユーザー | プロジェクトに追加されたユーザー。 |

### アクション [](#アクション)

| 用語 | 意味・用途 |
| --- | --- |
| アクション | ベースマキナ上に登録されたビジネスロジック。SQLやAPIコールごとに１アクションとして扱います。 |
| アクショングループ | 複数のアクションを束ねて１つの画面で呼び出しができるようにしたもの。 |
| ジョブ | 実行が終了するまで待ち続ける必要がない、非同期で実行されるアクションのこと。 |

[bridgeとは](/faq/what_is_bridge/) [画面作成機能の使い分け](/faq/screen_creation_features_comparison/)
---
よくある疑問点

トラブルシューティング

# トラブルシューティング

## bridgeの接続設定が保存できない [](#bridgeの接続設定が保存できない)

bridgeの接続設定が保存できない場合、疎通確認に失敗している可能性が高いです。原因として以下の項目を確認してください。

- ベースマキナの固定IPからのアクセスが許可されていない
- bridgeのURLが間違っている
- SSL設定が有効になっていない
- 設定されている環境変数に誤りがある
- 前段に立っているロードバランサーとbridgeの間でアクセスが途切れている
  - インスタンスのヘルスチェックができておらず、疎通できていない

#### ※bridgeをコンテナ内から調査したい場合 [](#bridgeをコンテナ内から調査したい場合)

コンテナイメージは調査のしやすさを考慮して [alpine (opens in a new tab)](https://hub.docker.com/_/alpine) イメージをベースに作成しています。

```
$ docker pull gcr.io/basemachina/bridge:latest
$ docker run -it --entrypoint=/bin/sh gcr.io/basemachina/bridge:latest
/ $
```

コンテナ内からの調査の1つとして、正しくDNSの名前解決ができるか確認する場合は `nc` コマンドが役に立ちます。

```
/ $ nc -vz example.com 80
example.com (93.184.216.34:80) open
/ $ nc -vz example.com 443
example.com (93.184.216.34:443) open
```

利用可能なコマンド一覧を取得するにはシェル上でタブキーを2回入力します。

```
/ $ # タブキーを二回タイプする
.                       fdflush                 microcom                sh
:                       fdisk                   mkdir                   sha1sum
[                       fg                      mkdosfs                 sha256sum
# ...
```

## アクションの実行に失敗する [](#アクションの実行に失敗する)

アクションの実行に失敗する場合、以下の要素で失敗しているか調べる必要があります。

- ベースマキナのサーバー
- ロードバランサー
- bridge
- データソース

以下の例を参考に、問題の原因を特定してください。

- データソースの接続情報の設定ミス
- bridgeの接続設定に失敗している
- bridgeの接続設定が存在しない環境で、社内のデータソースを呼び出そうとしている
- bridgeからデータソースへのトラフィックが許可されていない
- タイムアウトしている
  - タイムアウトの原因になりやすい箇所は次の通りです
        - bridgeの設定画面で設定されたタイムアウト期限
        - ロードバランサーからbridgeへのタイムアウト期限
        - bridgeからデータソースのタイムアウト期限
        - データソースの設定画面で設定されたタイムアウト期限
- リクエスト内容が不正
  - パラメーターの利用方法に誤りがあり、リクエストの情報がプログラムによって解釈不可能な値になっている

[初回セットアップの流れ](/faq/howto_setup/) [アクションに関する質問](/faq/action_questions/)
---
よくある疑問点

bridgeとは

# bridgeとは

![bridgeの概念図](/images/agent.png)

bridgeは、ベースマキナからお客さまが持つデータベースやAPIへアクセスする際に中継する、認証機能付きのゲートウェイのことを指します。

![bridgeの設定ページ](/images/agent_setting_page.png)

## bridgeの役割 [](#bridgeの役割)

bridgeはセキュリティの観点で非常に重要な役割を担っています。

- 認証
- ネットワークセキュリティの担保

### 認証 [](#認証)

bridgeを起動する際には、いくつかの環境変数を設定する必要があります。

bridgeはそのなかで指定される変数と、ベースマキナ上から送信されたリクエストのヘッダーに含まれる認証情報を照合し、正規のリクエストかどうかを検証します。

### ネットワークセキュリティの担保 [](#ネットワークセキュリティの担保)

当bridgeは、ベースマキナ社がホスティングするbridgeのサーバーをご利用いただくか、お客さま自身のクラウドまたはオンプレミス環境にbridgeを設置していただくかの2種類の形での設置方法をお選びいただけます。

ベースマキナのAPIからのアクション実行リクエストは、固定IPを介して送信されます。そのため、固定IPからのアクセスだけを通すためにファイアーウォールの設定をしていただくと最低限のアクセス制限ができます。

さらにお客さま自身でbridgeを設置した場合には、セキュリティグループなどの設定をbridgeに対して適用することで、ベースマキナのAPIが非公開のデータベースやAPIに直接アクセスしないように多重にセキュリティを強化できます。

## bridgeが使われるデータソース [](#bridgeが使われるデータソース)

bridgeが使われるデータソースは以下の通りです。

- [MySQLデータソース](/action/datasources/mysql_integration/)
- [PostgreSQLデータソース](/action/datasources/postgresql_integration/)
- [HTTP APIデータソース](/action/datasources/httpapi_integration/)
- [gRPCデータソース](/action/datasources/grpc_integration/)

## bridgeのセットアップ [](#bridgeのセットアップ)

### ネットワーク要件 [](#ネットワーク要件)

bridgeの動作に必要な通信は次の通りです。

#### インバウンド（ベースマキナ -> bridge） [](#インバウンドベースマキナ---bridge)

ベースマキナの固定IP `34.85.43.93` から、bridgeへのアクセスを許可してください。

#### アウトバウンド（bridge -> 外部） [](#アウトバウンドbridge---外部)

bridgeから `https://api.basemachina.com/` へのHTTPSアクセスを許可してください。リクエストの検証に必要な公開鍵を定期的に取得します。

### 接続設定 [](#接続設定)

bridgeへの接続はベースマキナからHTTP(HTTPS)を用いて確立されます。

bridgeの接続設定は環境ごとに保存されます。
選択中の環境以外で接続情報を保存したい場合は、環境を切り替えてから設定を保存してください。

### bridgeの設定 [](#bridgeの設定)

コンテナイメージを以下で配布しております。対応アーキテクチャはlinux/amd64および、linux/arm64です。

- [ghcr.io/basemachina/bridge (opens in a new tab)](https://ghcr.io/basemachina/bridge)
- [gcr.io/basemachina/bridge (opens in a new tab)](https://gcr.io/basemachina/bridge)
- [public.ecr.aws/basemachina/bridge (opens in a new tab)](https://gallery.ecr.aws/basemachina/bridge)

任意で次の環境変数をご利用いただけます。

```
# 認可処理に利用する公開鍵を更新する間隔です。
# 時間として指定します。有効な単位は "ns", "us" (or "µs"), "ms", "s", "m", "h" です。
export FETCH_INTERVAL=1h
# 認可処理に利用する公開鍵を更新するタイムアウトです。
# 時間として指定します。有効な単位は "ns", "us" (or "µs"), "ms", "s", "m", "h" です。
export FETCH_TIMEOUT=10s
# bridge を HTTP としてサーブするために利用します。4321 以外を指定してください。
# 文字列として指定します。
export PORT=8080
# 認可処理に利用します。設定されると指定されたテナント ID 以外からのリクエストを拒否します。
# 文字列として指定します。
# TENANT_IDは設定ページよりご確認ください。
export TENANT_ID=XXXXXX
```

### 推奨される動作環境 [](#推奨される動作環境)

前述の通り、bridgeはコンテナイメージを提供しています。それらを用いてbridgeを起動する場合、以下の環境でのセットアップを推奨します。

- AWSの場合： ECS Fargate
- Google Cloudの場合： Cloud Run

他にも起動方法はございますが、多くのお客さまが上記の環境でbridgeを利用されています。

### Terraformモジュール [](#terraformモジュール)

Terraformを使ってbridgeをデプロイしたい場合は、以下のモジュールをご利用いただけます。AWS ECS FargateおよびGoogle CloudのCloud Runに対応しています。

- [terraform-basemachina-bridge (opens in a new tab)](https://github.com/basemachina/terraform-basemachina-bridge)

### ヘルスチェック [](#ヘルスチェック)

bridgeを起動するインスタンスのヘルスチェックをしたいケースを想定して、 `/ok` というGETメソッドのエンドポイントを用意しております。

こちらのパスにリクエストを投げていただくことで、bridgeが正常に動作しているかを確認できます。

### 接続チェック [](#接続チェック)

「bridgeへの接続設定」と同じネットワーク設定画面上で、接続チェックができます。
お使いのデータベースやAPIへ、bridgeを経由してTCPで接続できるか確認したい場合にご利用ください。
プライベートなDNSによる名前解決が意図通りにできているかの確認などにご活用いただけます。

接続チェックは、 [ネットワーク設定の権限を持つユーザー](/faq/authorities/#%E3%83%97%E3%83%AD%E3%82%B8%E3%82%A7%E3%82%AF%E3%83%88%E3%81%AE%E5%90%84%E8%A8%AD%E5%AE%9A%E3%81%AE%E7%AE%A1%E7%90%86%E6%A8%A9%E9%99%90) のみが実行できます。

![bridgeからの接続チェックフォーム](/images/faq/what_is_bridge/bridge_ping.png)

[ユーザーの権限](/faq/authorities/) [用語集](/faq/terminology/)
---
ナビゲーション

# ナビゲーション

ナビゲーションはよく使うページをサイドバーに設定し簡単にアクセスできる機能です。

ナビゲーションはプロジェクトごとに設定でき、プロジェクト内で複数のナビゲーションを用意して用途ごとに使い分けられます。

![ナビゲーションのサイドバー](/images/navigation/sidebar.png)

## ナビゲーションの設定方法 [](#ナビゲーションの設定方法)

ナビゲーション一覧画面からナビゲーションの追加、更新、削除ができます。

1. 右上のメニューから「設定」を選択します。
1. 左のサイドバーから「ナビゲーション」を選択してナビゲーション一覧画面に移動します。

![ナビゲーション一覧画面](/images/navigation/setting_sidebar.png)

### ナビゲーションを追加する [](#ナビゲーションを追加する)

右上の「追加」ボタンをクリックして作成画面に移動します。

ナビゲーションでは以下の項目を設定します。

- ナビゲーションの名前
- ナビゲーションのグループ
- ナビゲーションの要素
- ログイン時に表示する初期画面
- ナビゲーションを利用できるグループ

![ナビゲーション作成画面](/images/navigation/create.png)

#### ナビゲーションの名前 [](#ナビゲーションの名前)

サイドバーに表示されるナビゲーションの名前を設定します。

#### ナビゲーションのグループ [](#ナビゲーションのグループ)

ナビゲーションの要素は任意のグループを設定でき、グループごとに階層が分かれてサイドバーに表示されます。

![ナビゲーションのサイドバーの階層の説明](/images/navigation/sidebar_hierarcy.png)

#### ナビゲーションの要素 [](#ナビゲーションの要素)

ナビゲーションの要素には以下の項目を設定できます。

- 要素の名前
- 遷移先の種類
- 要素のグループ

##### 要素の名前 [](#要素の名前)

サイドバーに表示される要素の名前を設定します。

##### 遷移先の種類 [](#遷移先の種類)

以下から要素の種類を選択します。

- アクション
- ビュー
- 開発者メニュー

##### 要素のグループ [](#要素のグループ)

要素のグループを設定します。

---

さらに遷移先の種類によって以下の項目を設定できます。

- 遷移先の種類が「アクション」の場合
  - 使用するアクション
  - パラメータのデフォルト値
  - 遷移時に自動でアクションを実行する
- 遷移先の種類が「ビュー」の場合
  - 使用するビュー
  - パラメータのデフォルト値
- 遷移先の種類が「開発者メニュー」の場合
  - 遷移先

##### 使用するアクション/ビュー [](#使用するアクションビュー)

遷移先のアクション/ビューを選択します。

##### パラメータのデフォルト値 [](#パラメータのデフォルト値)

遷移時のアクション、ビューのパラメータにデフォルト値を設定できます。

##### 遷移時に自動でアクションを実行する [](#遷移時に自動でアクションを実行する)

遷移時にアクションを自動で実行するか設定できます。

##### 遷移先 [](#遷移先)

以下から開発者メニューの遷移先を選択します。

- アクション一覧画面
- ビュー一覧画面
- レビュー依頼一覧画面
- アクショングループ一覧画面

![ナビゲーションの要素の作成画面](/images/navigation/create_item.png)

**パラメータのデフォルト値** を設定すると、遷移先への移動時にデフォルト値が入力された状態でフォームが表示されます。

**遷移時に自動でアクションを実行する** を設定すると移動時にアクションが実行され、実行結果のページが表示されます。

なお **パラメータのデフォルト値** が設定されている場合は、その値を使ってアクションが実行されます。

#### ログイン時に最初に表示する画面 [](#ログイン時に最初に表示する画面)

このナビゲーションを使用しているユーザーのログイン時に表示する画面を設定できます。

#### ナビゲーションを利用できるグループ [](#ナビゲーションを利用できるグループ)

ナビゲーションを利用できるグループを制限できます。
選択していないグループのユーザーのサイドバーにはこのナビゲーションは表示されません。

---

すべての設定項目の入力が終わったら「保存」をクリックします。

### ナビゲーションを更新する [](#ナビゲーションを更新する)

ナビゲーション一覧から更新したいナビゲーションをクリックすると、更新画面に移動できます。

ナビゲーションの追加時と同様に設定項目を編集して「保存」をクリックします。

### ナビゲーションを削除する [](#ナビゲーションを削除する)

ナビゲーション一覧から削除したいナビゲーションにカーソルをホバーし、右端に表示されるボタンをクリックして「削除する」をクリックします。

![ナビゲーションの削除画面](/images/navigation/delete.png)

### ナビゲーションを並べ替える [](#ナビゲーションを並べ替える)

ナビゲーション一覧から「並べ替え」をクリックすると、ナビゲーションの並べ替えができます。

[バージョン/有効化設定](/view/versions/) [AI活用とは](/ai_integration/)
---
開発中の機能

Remote MCP

Remote MCPとは

# Remote MCPとは

⚠️

この機能は現在開発中であり、まだ公開されていません。記載内容は今後変更される可能性があります。

Remote MCPは、Claudeなどの [MCP（Model Context Protocol） (opens in a new tab)](https://modelcontextprotocol.io/) クライアントから、OAuthでベースマキナに接続し、登録済みの [アクション](/action/) をMCPの「ツール」として扱えるようにする機能です。

MCPは、AIエージェントが外部のツールやデータにアクセスするための標準プロトコルです。ベースマキナのMCPサーバーに接続すると、クライアントは接続したユーザーがアクセスできる環境のアクションを、ツールの一覧として取得できます。

この機能は現在、限定提供中です。利用を希望する場合はお問い合わせください。許可されていない企業アカウントでは接続できません。

## できること [](#できること)

- **アクションをツールとして公開する**: 接続を許可した環境で利用可能なアクションが、MCPのツールとして一覧に並びます。各ツールには、アクションの説明と入力パラメーターの定義（JSON Schema）が含まれます。無効化されたアクションや、環境で無効・非表示に設定されたアクション、使用するデータソースが接続されていないアクションは一覧に表示されません。
- **ツールとしてアクションを実行する**: 実行可能なツールを実行すると、対応するアクションが実行され、結果が返ります。実行は接続したユーザー自身の権限に従います。
- **公開する環境をユーザーが選ぶ**: 接続を許可する際に、どの環境のアクションを公開するかをユーザー自身が選択します。公開されるのは、選択した環境のアクションに限られます。

実行権限のないアクションなど、一覧には表示されても実行できないアクションもあります。この場合、実行できない理由がツールの説明に記載され、 `inputSchema` は空になり、実行するとエラーになります。一覧に表示されないアクションと、表示されても実行できないアクションの詳細については、 [アクションを実行する](/preview/remote_mcp/execute_actions/) を参照してください。

## 仕組み [](#仕組み)

接続から利用までの流れは次のとおりです。

1. MCPクライアントにベースマキナのMCPサーバーのURLを登録します。
1. クライアントがOAuthの認可フローを開始し、ブラウザでベースマキナのログインと同意画面が開きます。
1. 同意画面で、公開を許可する環境を選択します。
1. 許可した各環境のアクションが、MCPのツールとしてクライアントから取得できるようになります。

OAuthの認可やトークンのやり取りはMCPクライアントが自動で処理するため、ユーザーが手動でトークンを発行・管理する必要はありません。

## 利用できるユーザー [](#利用できるユーザー)

- この機能は、ベースマキナ側で許可された企業アカウントでのみ利用できます。許可されていない企業アカウントでは利用できません。
- 接続を許可する際に選択できるのは、操作しているユーザー自身がアクセスできる環境のみです。アクセス権のない環境は同意画面に表示されません。

## 次のステップ [](#次のステップ)

- [クライアントを接続する](/preview/remote_mcp/connect/) で、MCPクライアントからの接続手順とツールの仕様を確認してください。
- [アクションを実行する](/preview/remote_mcp/execute_actions/) で、ツールからアクションを実行する方法を確認してください。

## 関連ページ [](#関連ページ)

- [AI活用とは](/ai_integration/)
- [アクション](/action/)
- [公開API](/public_api/)

[APIリファレンス](/public_api/reference/) [クライアントを接続する](/preview/remote_mcp/connect/)
---
開発中の機能

Remote MCP

クライアントを接続する

# クライアントを接続する

⚠️

この機能は現在開発中であり、まだ公開されていません。記載内容は今後変更される可能性があります。

Claudeなどの [MCP（Model Context Protocol） (opens in a new tab)](https://modelcontextprotocol.io/) クライアントから、ベースマキナのMCPサーバーに接続する手順を説明します。機能の概要は [Remote MCPとは](/preview/remote_mcp/) を参照してください。

## 接続先URL [](#接続先url)

MCPクライアントには、次のURLをベースマキナのMCPサーバーとして登録します。

```
https://platform.basemachina.com/mcp
```

このエンドポイントは、JSON-RPCをStreamable HTTPで扱うMCPサーバーです。プロジェクトや環境はURLには含めず、後述の同意画面で許可した環境から決まります。

## 接続の手順 [](#接続の手順)

1. MCPクライアントに、接続先URL `https://platform.basemachina.com/mcp` を登録します。
1. クライアントがOAuthの認可フローを開始すると、ブラウザでベースマキナの画面が開きます。ログインしていない場合はログインを求められます。
1. 「アクセスを許可」の画面で、接続を許可するクライアントの情報（Client ID・Redirect URI）と「許可する環境」が表示されます。
1. 公開を許可する環境を選択し、「許可する」を選択します。
1. クライアントに戻り、許可した環境のアクションがツールとして取得できるようになります。

OAuthの認可コードの取得やアクセストークンの交換は、MCPクライアントが自動で処理します。ユーザーがトークンを手動で扱う必要はありません。

「許可する環境」には、操作しているユーザー自身がアクセスできる有効な環境のみが表示されます。利用できる環境がない場合は、プロジェクトへのアクセス権を確認してください。

## 接続できるMCPクライアント [](#接続できるmcpクライアント)

ベースマキナのMCPサーバーは、OAuthのクライアント登録にClient ID Metadata Document（CIMD）方式のみを採用しています。CIMDは、クライアントが自身の情報を公開しているHTTPS URLを、そのままクライアントIDとして扱う方式です。

動的クライアント登録（Dynamic Client Registration）には対応していません。そのため、接続にはCIMDに対応したMCPクライアントが必要です。Claudeなど、対応済みのクライアントから接続してください。

## アクセストークンの有効期限 [](#アクセストークンの有効期限)

接続を許可すると、MCPクライアントにはアクセストークンとリフレッシュトークンが発行されます。アクセストークンの有効期限は900秒（15分）です。

有効期限が切れると、MCPクライアントがリフレッシュトークンを使ってアクセストークンを自動的に取得し直します。ユーザーが接続を再度許可する必要はありません。リフレッシュトークンの有効期限は30日で、アクセストークンを取得し直すたびに更新されます。30日以上クライアントを利用しなかった場合は、再度接続を許可してください。

## アクションがツールになる仕組み [](#アクションがツールになる仕組み)

許可した各環境のアクションが、1つずつMCPのツールに変換されます。ただし、無効化されたアクションや、環境で無効・非表示に設定されたアクション、使用するデータソースが接続されていないアクションはツールになりません。詳細は [アクションを実行する](/preview/remote_mcp/execute_actions/) を参照してください。

各ツールの内容は次のように決まります。

| ツールの項目 | 内容 |
| --- | --- |
| `name` | `{環境名}__{識別子}` の形式（例: `production__send_email` ）。環境名は小文字化され、半角英数字・ `_` ・ `-` 以外の文字は `_` に置き換えられます。 |
| `description` | アクション名・識別子・環境名・説明文をラベル付きで列挙します（例: `アクション名: メール送信` / `識別子: send_email` / `環境: 本番` / `説明: ユーザーにメールを送信する` ）。アクション名・説明文が空の場合は、その行を省略します。実行できないツールは、先頭行に実行できない理由を含めます。 |
| `inputSchema` | アクションの入力パラメーターの定義（JSON Schema）。実行できないツールは空のスキーマになります。 |

複数の環境を許可した場合、同じアクションでも環境ごとに別々のツールになります。ツール名の先頭に環境名が付くため、どの環境のアクションかを区別できます。

環境名が日本語のみで構成される場合、ツール名に使える文字が残らないため、環境名の代わりに環境IDを使います。 `cl5hr5q23akg00ca2bug__send_email`
のような形式です。環境名を日本語で設定している場合は、こちらの形式になります。正規化した環境名が他の環境と重複する場合は、環境名のうしろに環境IDをつけて一意にします。

### ツール名が長い場合 [](#ツール名が長い場合)

MCPクライアント側の制約により、ツール名は64文字以内である必要があります。この長さに収まるよう、ベースマキナ側で次のように調整します。

- 環境名の部分が長い場合は、42文字までに切り詰めます
- 識別子が残りの長さに収まらない場合や、識別子に半角英数字・ `_` ・ `-` 以外の文字が含まれる場合は、識別子の代わりにアクションの内部IDを使います

内部IDを使ったツールは、ツールの説明にその旨を記載します。ベースマキナの画面でアクションを探すときは、ツールの説明に記載されている識別子を利用してください。

接続したクライアントからツールを実行する方法は、 [アクションを実行する](/preview/remote_mcp/execute_actions/) を参照してください。

## 関連ページ [](#関連ページ)

- [Remote MCPとは](/preview/remote_mcp/)
- [アクションを実行する](/preview/remote_mcp/execute_actions/)
- [アクション](/action/)

[Remote MCPとは](/preview/remote_mcp/) [アクションを実行する](/preview/remote_mcp/execute_actions/)
---
開発中の機能

Remote MCP

アクションを実行する

# アクションを実行する

⚠️

この機能は現在開発中であり、まだ公開されていません。記載内容は今後変更される可能性があります。

MCPクライアントからツールを実行して、対応する [アクション](/action/) を実行する方法を説明します。機能の概要は [Remote MCPとは](/preview/remote_mcp/) 、接続手順は [クライアントを接続する](/preview/remote_mcp/connect/) を参照してください。

## 実行の流れ [](#実行の流れ)

MCPクライアントがツールを実行すると、対応するアクションがベースマキナ上で実行されます。アクションを実行できるかどうかは、接続したユーザー自身の権限に従います。

## 実行結果 [](#実行結果)

実行に成功すると、アクションの実行結果がJSONで返ります。MCPクライアントはこの結果を使って、続きの処理を進められます。

## 実行に失敗したとき [](#実行に失敗したとき)

入力値の不備、データソースのエラー、JavaScriptアクションのエラーなど、入力やアクションの設定を見直せば対処できる失敗は、その内容がツールのエラーとして返ります。MCPクライアントはエラーの内容を踏まえて入力を直し、再実行できます。

ベースマキナ側の想定外のエラーで失敗した場合は、ツールの実行自体がエラーになります。時間をおいて再試行しても解決しない場合は、お問い合わせください。

## 実行できないアクション [](#実行できないアクション)

無効化されたアクション、現在の環境で無効になっているアクション、非表示に設定されたアクション、使用するデータソースが現在の環境に接続されていないアクションは、ツール一覧に表示されません。

次のアクションはツール一覧に表示されますが、MCPからは実行できません。実行できない理由がツールの説明に記載されるほか、実行した場合もエラーとして返ります。

| 実行できないアクション | 代わりの実行方法 |
| --- | --- |
| 実行権限のないアクション | 企業アカウントの管理者に権限の付与を依頼してください。 |
| 実行前にレビュー承認が必要なアクション | アクション実行画面からレビューを依頼し、承認後に実行してください。 |
| レビュー設定が削除されたアクション | アクション設定画面でレビュー設定をやり直してください。 |
| ジョブキューが設定されたアクション | アクション実行画面から「ジョブとして実行する」を選んで実行してください。 |
| ファイルを入力として受け取るアクション | アクション実行画面から実行してください。 |
| ストレージのダウンロード操作のアクション | 署名付きURL発行（ISSUE\_SIGNED\_URL）操作のアクションを使用してください。 |
| （旧）JavaScriptアクション | アクション設定画面で現行のJavaScriptアクションに移行してください。 |
| 対応していないバージョンのMySQLアクション | アクション実行画面から実行してください。 |

MCPのツールの実行結果はJSONで返るため、ファイル（バイナリデータ）を返すアクションは実行できません。ストレージのダウンロード操作のアクションは、上の表のとおりツールの説明で事前にわかります。一方、HTTP APIアクションが画像やPDFを返した場合や、JavaScriptアクションがファイルを返した場合は、実行してはじめてエラーになります。

## 関連ページ [](#関連ページ)

- [Remote MCPとは](/preview/remote_mcp/)
- [クライアントを接続する](/preview/remote_mcp/connect/)
- [アクション](/action/)

[クライアントを接続する](/preview/remote_mcp/connect/) [企業アカウントのユーザー管理](/admin/user_management/tenant_add_new_user/)
---
公開API

公開APIとは

# 公開APIとは

公開APIは、ベースマキナのリソースを外部システムから操作するためのREST APIです。環境の一覧取得や、アクションの一覧取得・詳細取得・実行を、HTTPリクエストで実行できます。

主なユースケースは以下の通りです。

- 外部システムからベースマキナのアクションを実行する
- CI/CDのジョブからアクションを呼び出して定型作業を自動化する
- 自社のスクリプトやツールに、ベースマキナのアクションを組み込む
- AIエージェント（Claude Codeなど）からアクションをツールとして実行する

## 対応する操作 [](#対応する操作)

現状、公開APIで提供しているのは **環境の一覧取得** と、アクションの **一覧取得・詳細取得・実行** です。加えて、レビューが必須のアクションに対しては **レビュー依頼の作成・状態取得・承認後の実行** も提供しています。環境一覧では有効化されている環境のみを返します。アクションやデータソースなどの設定変更（作成・編集・削除）は提供していません。設定の作成・編集・削除にはベースマキナの管理画面、またはコード管理を使用してください。

ベースURL・各エンドポイントの詳細（リクエスト・レスポンス・パラメーター・エラーコードなど）は [APIリファレンス](/public_api/reference/) を参照してください。

## アクションの識別子 [](#アクションの識別子)

公開APIではアクションを **アクションID、または識別子** で参照します。管理画面やコード管理で識別子を設定している場合は識別子を、未設定の場合は自動生成されたアクションIDを使います。アクション一覧・詳細のレスポンスに含まれる `id` を、そのまま実行時の `action_id` に指定してください。

## アクションの実行権限 [](#アクションの実行権限)

公開APIでのアクション実行は、認証に使ったトークンの主体が持つ権限で実行されます。主体は認証方式によって決まります。

- [`bm login`](/code_management/cli/login/) で取得したJWT: ログインしたユーザー
- 外部OIDC ID Token: [サービスアカウント](/service_account/)

アクションに [実行権限](/action/action_permission/) が設定されている場合、実行権限を持たない主体は `403 forbidden` になります。サービスアカウントで実行する場合は、所属グループに対象アクションの実行権限を付与してください。実行権限は所属グループ単位で決まります。サービスアカウントごとに個別の権限は付与できません。

[レビュー設定](/action/review/) でレビューが必須のアクションは、公開APIから直接実行できず `403 forbidden` を返します。この場合はレビュー依頼を作成し、承認後に実行してください。

なお、レビュー依頼は [`bm login`](/code_management/cli/login/) で取得したJWT（ログインしたユーザー）でのみ作成できます。サービスアカウントはレビュー依頼を作成できず `403 forbidden` を返します。

## 公開APIから実行できないアクション [](#公開apiから実行できないアクション)

次のアクションはアクション実行画面からは実行できますが、公開APIからは実行できず `422 argument_invalid` を返します。

| 種別 |
| --- |
| ファイルパラメーターを持つアクション |
| (旧)JavaScriptアクション |
| ストレージ（Amazon S3 / Google Cloud Storage）のダウンロード操作のアクション |
| 実行結果にファイル（バイナリデータ）が含まれるアクション |

公開APIはJSON形式で表現できる結果のみを返せます。HTTP APIアクションが画像やPDFなどのバイナリを返した場合や、JavaScriptアクションがファイルを返した場合は実行できません。公開APIでストレージのファイルを取得したい場合は、署名付きURL発行操作のアクションを使用してください。

また、次の状態のアクションは公開APIに限らず実行できず `404 not_found` を返します。状態を解消してから実行してください。

| 状態 | 対処 |
| --- | --- |
| アクションが無効化されている | アクションを有効化する |
| データソースが現在の環境に接続されていない | データソースの接続先設定で現在の環境を有効にする |

## 認証 [](#認証)

公開APIのエンドポイント（トークン交換エンドポイント `/token` を除く）はBearerトークン認証（ `Authorization: Bearer <token>` ）で保護されています。ローカル端末からは [`bm login`](/code_management/cli/login/) で取得したJWTを、CI/CDやクラウドからは外部OIDC IdPが発行したID Tokenをトークン交換エンドポイントでアクセストークンに交換して利用します。シナリオ別の取得手順と呼び出し例は [認証して呼び出す](/public_api/authentication/) を参照してください。

## 利用までの流れ [](#利用までの流れ)

1. ベースマキナの管理画面で [サービスアカウント](/service_account/) を用意し、CI/CDやクラウドから呼び出す場合は [OIDC信頼ポリシー](/service_account/#oidc%E4%BF%A1%E9%A0%BC%E3%83%9D%E3%83%AA%E3%82%B7%E3%83%BC) を設定する
1. [認証して呼び出す](/public_api/authentication/) を参考に、ローカルからは [`bm login`](/code_management/cli/login/) で、CI/CDやクラウドからは外部OIDC ID Tokenをアクセストークンに交換して、呼び出し用のトークンを用意する
1. プロジェクトIDと環境IDを確認し、URLパスの `project_id` ・ `environment_id` に指定する
1. [APIリファレンス](/public_api/reference/) のエンドポイント定義に従って環境一覧・アクション一覧・詳細・実行を呼び出す

## OpenAPI仕様 [](#openapi仕様)

公開APIのインターフェースはOpenAPI仕様（YAML形式）として公開しています。仕様ファイルは次のURLから取得できます。

[https://docs.basemachina.com/openapi/public\_api.yaml (opens in a new tab)](https://docs.basemachina.com/openapi/public_api.yaml)

OpenAPI対応のツールへ仕様ファイルを取り込めば、APIクライアントの生成やリクエストの動作確認に活用できます。

## エラーコード [](#エラーコード)

エラーレスポンスは [RFC 9457 Problem Details (opens in a new tab)](https://www.rfc-editor.org/rfc/rfc9457) 形式（ `Content-Type: application/problem+json` ）で返ります。 `code` フィールドで分類されます。各コードの発生条件・レスポンス例は [APIリファレンス](/public_api/reference/) の各エンドポイントのレスポンス定義を参照してください。

トークン交換エンドポイント `/token` のエラーレスポンスのみ、 [RFC 8693 (opens in a new tab)](https://www.rfc-editor.org/rfc/rfc8693) /
[RFC 6749 §5.2 (opens in a new tab)](https://www.rfc-editor.org/rfc/rfc6749#section-5.2) 準拠の `{ error, error_description }` 形式（ `Content-Type: application/json` ）で返ります。詳細は [認証して呼び出す](/public_api/authentication/#%E3%83%88%E3%83%BC%E3%82%AF%E3%83%B3%E4%BA%A4%E6%8F%9B%E3%82%A8%E3%83%B3%E3%83%89%E3%83%9D%E3%82%A4%E3%83%B3%E3%83%88%E3%81%AE%E3%82%A8%E3%83%A9%E3%83%BC%E3%83%AC%E3%82%B9%E3%83%9D%E3%83%B3%E3%82%B9) を参照してください。

### unauthorized [](#unauthorized)

`401` 。Bearerトークンが欠落・期限切れ・検証失敗。

### bad\_request [](#bad_request)

`400` 。URLパスやリクエストの文法レベルの不正。

### forbidden [](#forbidden)

`403` 。対象プロジェクト・アクションへの権限不足、またはサービスアカウントから実行できない操作の呼び出し。

### not\_found [](#not_found)

`404` 。アクション・環境などのリソースが存在しない、または無効化されている。

### method\_not\_allowed [](#method_not_allowed)

`405` 。許可されていないHTTPメソッドの利用。

### state\_conflict [](#state_conflict)

`409` 。アクションの状態不整合。

### payload\_too\_large [](#payload_too_large)

`413` 。リクエストボディのサイズ超過。

### unsupported\_media\_type [](#unsupported_media_type)

`415` 。 `Content-Type` が `application/json` 以外。

### argument\_invalid [](#argument_invalid)

`422` 。引数・クエリパラメーターのバリデーション違反、または [公開APIから実行できないアクション](/public_api/#%E5%85%AC%E9%96%8Bapi%E3%81%8B%E3%82%89%E5%AE%9F%E8%A1%8C%E3%81%A7%E3%81%8D%E3%81%AA%E3%81%84%E3%82%A2%E3%82%AF%E3%82%B7%E3%83%A7%E3%83%B3) の呼び出し。

### javascript\_action\_error [](#javascript_action_error)

`422` 。JavaScriptアクションのコードが投げた業務エラー。

### data\_source\_error [](#data_source_error)

`422` 。データソースなど接続先のエラー。接続先のHTTPステータスを取得できた場合は `data_source.status` に格納される。

### internal\_error [](#internal_error)

`500` 。ベースマキナ側で予期しないエラーが発生した。

### service\_unavailable [](#service_unavailable)

`503` 。ベースマキナ側の一時障害。 `Retry-After` ヘッダーに従ってリトライ可能。

[サービスアカウント](/service_account/) [認証して呼び出す](/public_api/authentication/)
---
公開API

認証して呼び出す

# 公開APIを認証して呼び出す

公開APIはBearerトークン認証で保護されています。ローカル端末からの検証では `bm login` で取得したJWTを、自社バックエンドやCI/CDからの呼び出しでは外部OIDC IdPが発行したID Tokenをアクセストークンに交換して、それぞれ利用できます。本ページでは、シナリオ別に必要なトークンの取得方法と呼び出し例を示します。

## 認証フローの概要 [](#認証フローの概要)

公開APIのエンドポイント（後述のトークン交換エンドポイント `/token` を除く）へのリクエストには `Authorization: Bearer <token>` ヘッダーを付与します。利用できるトークンは以下の2系統です。

- **`bm login` で取得したJWT**: 公開APIがそのまま受け付けます。ブラウザでログインしたユーザーの権限で実行されます。
- **外部OIDC IdPが発行したID Tokenを交換したアクセストークン**: ID Tokenをそのまま指定しても受け付けられません。トークン交換エンドポイント `POST /public/v1/token` でアクセストークンに交換してから利用します。サービスアカウントの権限で実行されます。

外部OIDC ID Tokenを利用する場合、呼び出し元のシステムは特定のサービスに限定されません。OIDC IdPが `/.well-known/openid-configuration` を公開しており、ID Tokenが信頼ポリシーの `Issuer` / `Audience` / `Bound Claims` を満たせば交換は成功します。

トークン交換エンドポイントは認証不要です。交換で得たアクセストークンには有効期限があるため、期限が切れるまでは使い回し、期限が切れたら再度交換します。

## シナリオの選び方 [](#シナリオの選び方)

| シナリオ | 推奨トークン | 取得手段 |
| --- | --- | --- |
| ローカル端末からの検証・開発 | `bm login` で取得したJWT | [`bm login`](/code_management/cli/login/) |
| GitHub ActionsなどのCI/CD | 外部OIDC ID Token | GitHub OIDC、GitLab OIDC など、各CIサービスのID Token発行機能 |
| Google Cloud / AWS などのクラウドサービス上での実行 | 外部OIDC ID Token | メタデータサーバー、IAM Outbound Identity Federation など |
| 自社IdP配下のサービス | 外部OIDC ID Token | Auth0 / Okta / Keycloak / Kubernetes など、自社で運用するOIDC IdP |

## ローカル端末から呼び出す（ `bm login` ） [](#ローカル端末から呼び出すbm-login)

ローカル端末から公開APIを呼び出して挙動を検証したい場合は、 `bm login` で取得したJWTをそのまま `Authorization: Bearer` に指定するのが最も簡単な方法です。トークン交換は不要です。

### 事前準備 [](#事前準備)

1. ローカル端末で [`bm login`](/code_management/cli/login/) を実行し、ブラウザでベースマキナにログインする
1. ログイン成功後、認証情報が `~/.basemachina/credentials.json` に自動で保存される

`credentials.json` には以下の形式でJWTとメタ情報が保存されます。

```
{
  "token": "<JWT>",
  "email": "you@example.com",
  "expiresAt": 1735689600
}
```

### 呼び出し例 [](#呼び出し例)

[`bm print-access-token`](/code_management/cli/print_access_token/) で保存済みのJWTを取り出し、環境変数に格納してから `curl` で呼び出します。

```
export BM_TOKEN=$(bm print-access-token)
 
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..."
    }
  }'
```

`bm print-access-token` はWindows環境でも利用できますが、環境変数の設定方法はシェルごとに異なります。PowerShellでは以下のように設定します。

```
$env:BM_TOKEN = bm print-access-token
```

### トークンの期限切れ [](#トークンの期限切れ)

`credentials.json` に保存されたJWTには有効期限があります。期限を過ぎたトークンを使うと公開APIは `401 unauthorized` を返します。再度 `bm login` を実行すると、新しいJWTが `credentials.json` に上書き保存されます。

## OIDC利用時の前提条件 [](#oidc利用時の前提条件)

外部OIDC ID Tokenを交換して公開APIを呼び出す場合、以下が完了している必要があります。

- プロジェクトにサービスアカウントが作成・割り当て済みである
- 呼び出し元のOIDC IdPに合わせて、サービスアカウントのOIDC信頼ポリシーが登録済みである

サービスアカウントの作成・グループへの所属・OIDC信頼ポリシーの設定手順は [サービスアカウント](/service_account/) をご参照ください。OIDC信頼ポリシーで設定する `Issuer` / `Audience` / `Bound Claims` の呼び出し元別の具体値は、後述の [呼び出し元別のID Token取得方法](/public_api/authentication/#%E5%91%BC%E3%81%B3%E5%87%BA%E3%81%97%E5%85%83%E5%88%A5%E3%81%AEid-token%E5%8F%96%E5%BE%97%E6%96%B9%E6%B3%95) で説明します。

## 呼び出し元別のID Token取得方法 [](#呼び出し元別のid-token取得方法)

外部OIDC IdPを利用する場合、まず呼び出し元の環境でID Tokenを取得します。取得したID Tokenは次節「 [ID Tokenをアクセストークンに交換する](/public_api/authentication/#id-token%E3%82%92%E3%82%A2%E3%82%AF%E3%82%BB%E3%82%B9%E3%83%88%E3%83%BC%E3%82%AF%E3%83%B3%E3%81%AB%E4%BA%A4%E6%8F%9B%E3%81%99%E3%82%8B) 」でアクセストークンに交換します。

### Google Cloud（Cloud Run / GKE / GCE / Cloud Functions） [](#google-cloudcloud-run--gke--gce--cloud-functions)

Google Cloud上のワークロードでは、 `google-auth-library` を使い、ワークロードに紐づくサービスアカウントのID Tokenを取得します。メタデータサーバー経由で取得されるため、サービスアカウント鍵をアプリケーションに置く必要はありません。

```
import { GoogleAuth } from "google-auth-library";
 
const auth = new GoogleAuth();
const audience = "https://your-tenant.example.com";
const client = await auth.getIdTokenClient(audience);
const idToken = await client.idTokenProvider.fetchIdToken(audience);
```

OIDC信頼ポリシーは以下の項目で設定します。

| 項目 | 設定値 |
| --- | --- |
| `Issuer` | `https://accounts.google.com` |
| `Audience` | クライアントが指定した値（例: `https://your-tenant.example.com` ） |
| `Bound Claims` | 呼び出し元サービスアカウントを特定するclaim（例: `key: email`, `pattern: my-app@my-project.iam.gserviceaccount.com` ） |

### AWS（EC2 / Lambda / ECS） [](#awsec2--lambda--ecs)

AWS上のワークロードでは、2025年11月に公開された [AWS IAM Outbound Identity Federation (opens in a new tab)](https://aws.amazon.com/blogs/aws/simplify-access-to-external-services-using-aws-iam-outbound-identity-federation/) を使い、 `sts:GetWebIdentityToken` APIでID Tokenを取得します。AWSアカウントごとに固有のOIDC Issuer URLが自動生成され、 `/.well-known/openid-configuration` と `/.well-known/jwks.json` が公開されます。

```
import { STSClient, GetWebIdentityTokenCommand } from "@aws-sdk/client-sts";
 
const sts = new STSClient({});
const audience = "https://your-tenant.example.com";
 
const { WebIdentityToken: idToken } = await sts.send(
  new GetWebIdentityTokenCommand({
    Audience: [audience],
    SigningAlgorithm: "ES384",
    DurationSeconds: 900,
  }),
);
```

EC2やLambdaに付与されているIAMロールには、 `sts:GetWebIdentityToken` の許可が必要です。

OIDC信頼ポリシーは以下の項目で設定します。

| 項目 | 設定値 |
| --- | --- |
| `Issuer` | AWSアカウント固有のIssuer URL（例: `https://<account-uuid>.tokens.sts.global.api.aws` ）。マネジメントコンソールから確認可能 |
| `Audience` | クライアントが指定した値（例: `https://your-tenant.example.com` ） |
| `Bound Claims` | 呼び出し元IAMロールを特定するclaim（例: `key: aws:PrincipalArn`, `pattern: arn:aws:iam::123456789012:role/my-app-role` ） |

AWS IAM Outbound Identity
Federationは2025年11月19日以降、全AWS商用リージョン・GovCloud・China
Regionsで追加コストなしで提供されています。

### GitHub Actions [](#github-actions)

`actions/github-script` から `@actions/core` の `getIDToken(audience)` を呼んでID Tokenを取得します。コード管理の `bm sync` と異なり、公式の `bm-action` は使いません。

```
- uses: actions/github-script@v7
  id: get-token
  with:
    script: |
      const idToken = await core.getIDToken("https://your-tenant.example.com");
      core.setSecret(idToken);
      core.setOutput("idToken", idToken);
```

`core.getIDToken()` を呼ぶには、このステップを含むジョブに `permissions: id-token: write` の指定が必要です。取得したID Tokenは後続ステップから `steps.get-token.outputs.idToken` として参照できます。

OIDC信頼ポリシーは以下の項目で設定します。

| 項目 | 設定値 |
| --- | --- |
| `Issuer` | `https://token.actions.githubusercontent.com` |
| `Audience` | `core.getIDToken()` に渡した値（例: `https://your-tenant.example.com` ） |
| `Bound Claims` | 呼び出し元リポジトリ・ブランチを特定するclaim（例: `key: sub`, `pattern: repo:my-org/my-repo:ref:refs/heads/main` ） |

### その他のOIDC IdP（Auth0 / Okta / Kubernetes / 自社IdP など） [](#その他のoidc-idpauth0--okta--kubernetes--自社idp-など)

上記以外のOIDC IdPも、以下を満たせば利用できます。

- `/.well-known/openid-configuration` でOIDC Discovery情報が公開されている
- JWKSがHTTPSで公開されている
- ID Tokenに `iss` 、 `aud` 、信頼ポリシーで使うclaimが含まれている

ID Tokenの取得方法は各IdPのドキュメントに従ってください。KubernetesではaudienceパラメータをつけたProjected ServiceAccount Token（OIDC互換JWT）が利用できます。Auth0やOkta、Keycloakなど一般的なOIDC IdPでは、Authorization Code Flowや、各IdPの拡張機能でマシン間通信向けに発行した `id_token` が利用できます。

## ID Tokenをアクセストークンに交換する [](#id-tokenをアクセストークンに交換する)

取得したID Tokenは、トークン交換エンドポイントでベースマキナのアクセストークンに交換します。

```
POST https://platform.basemachina.com/public/v1/token
```

リクエストボディは `Content-Type: application/json` で以下を送信します。 `subject_token` に取得したID Tokenを指定します。

```
curl -X POST \
  "https://platform.basemachina.com/public/v1/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
    "subject_token": "'"$ID_TOKEN"'",
    "subject_token_type": "urn:ietf:params:oauth:token-type:jwt"
  }'
```

リクエストボディの各パラメーターは以下の通りです。

| パラメーター | 必須 | 説明 |
| --- | --- | --- |
| `grant_type` | 必須 | トークン交換を表す固定値 `urn:ietf:params:oauth:grant-type:token-exchange` を指定する |
| `subject_token` | 必須 | 交換元のID Token。取得したID Tokenをそのまま指定する |
| `subject_token_type` | 必須 | `subject_token` の種別。JWTを表す固定値 `urn:ietf:params:oauth:token-type:jwt` を指定する |
| `service_account_email` | 任意 | 交換先のサービスアカウントのメールアドレス。 `subject_token` が複数のサービスアカウントの信頼ポリシーに合致しうる場合に、認証対象をこのサービスアカウントに絞り込む。省略時は合致した信頼ポリシーのうち最初の1件が選ばれるため、複数のポリシーに合致しうる場合は意図しないサービスアカウントとして認証される可能性がある。指定して曖昧さをなくすことを推奨する。なお、これはベースマキナ独自の拡張パラメーターで、RFC 8693 標準には含まれない |

交換に成功すると、アクセストークンと有効期間（秒）が返ります。

```
{
  "access_token": "<アクセストークン>",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "token_type": "Bearer",
  "expires_in": 300
}
```

`access_token` は `Authorization: Bearer` にそのまま渡してください。トークンの内部形式は予告なく変更される場合がありますので、デコードして中身を使うことは推奨されません。

### トークン交換エンドポイントのエラーレスポンス [](#トークン交換エンドポイントのエラーレスポンス)

トークン交換エンドポイント `/token` のエラーレスポンスは、他の公開APIエンドポイントとは異なる形式で返ります。

形式は [RFC 8693 OAuth 2.0 Token Exchange (opens in a new tab)](https://www.rfc-editor.org/rfc/rfc8693) / [RFC 6749 §5.2 (opens in a new tab)](https://www.rfc-editor.org/rfc/rfc6749#section-5.2) 準拠です。 `Content-Type` は `application/json` です。

レスポンスボディは `error` と `error_description` の2フィールドのみです。Problem Details形式の `type` / `code` / `status` / `title` / `instance` は含まれません。

```
{
  "error": "invalid_grant",
  "error_description": "The subject_token is invalid, expired, or rejected by the trust policy."
}
```

`error_description` はRFC 6749 §5.2の文字種制限（ASCII printable、 `"` と `\` を除く）に従うため、英語の固定文言で返ります。ローカライズされたメッセージは返らない点にご注意ください。

HTTPステータスと `error` 値の対応は以下の通りです。

| HTTPステータス | `error` | 発生条件 |
| --- | --- | --- |
| `400` | `invalid_request` | リクエストボディがJSONとして解釈できない |
| `400` | `invalid_grant` | `subject_token` が無効、期限切れ、または信頼ポリシーに合致しない |
| `415` | `invalid_request` | `Content-Type` が `application/json` 以外 |
| `422` | `invalid_request` | `grant_type` / `subject_token_type` の不一致や不足など |
| `500` | `server_error` | ベースマキナ側で予期しないエラーが発生した |
| `503` | `temporarily_unavailable` | ベースマキナ側の一時障害 |

`503` 時は `Retry-After` ヘッダーで再試行までの待機秒数を返します。クライアントはこのヘッダーに従って再試行してください。

その他公開APIエンドポイントのエラーレスポンスは引き続き [RFC 9457 Problem Details (opens in a new tab)](https://www.rfc-editor.org/rfc/rfc9457) 形式（ `Content-Type: application/problem+json` ）です。詳細は [APIリファレンス](/public_api/reference/) を参照してください。

## 呼び出し例（共通） [](#呼び出し例共通)

ID Tokenをアクセストークンに交換したあとは、認証方式に関わらず同じ形式で公開APIのエンドポイントを呼び出します。 `access_token` を `Authorization: Bearer` に指定します。POST時は `Content-Type` を必ず指定してください。

```
# 1. ID Token をアクセストークンに交換する
ACCESS_TOKEN=$(curl -s -X POST \
  "https://platform.basemachina.com/public/v1/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
    "subject_token": "'"$ID_TOKEN"'",
    "subject_token_type": "urn:ietf:params:oauth:token-type:jwt"
  }' | jq -r .access_token)
 
# 2. アクセストークンで公開APIを呼び出す
curl -X POST \
  "https://platform.basemachina.com/public/v1/projects/csi2hcc0iaejrqgivkfg/environments/9m4e2mr0ui3e8a215n4g/actions/send_email/executions" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "arguments": {
      "user_id": "usr_01H..."
    }
  }'
```

エンドポイントとリクエスト・レスポンス形式の詳細は [APIリファレンス](/public_api/reference/) をご参照ください。

## トークンの寿命 [](#トークンの寿命)

外部OIDC ID Tokenの有効期限は発行元のOIDC IdPに依存します。代表的な値は以下の通りです。

| 発行元 | デフォルト有効期限 |
| --- | --- |
| GitHub Actions | 5分 |
| Google Cloud | 1時間 |
| AWS IAM Outbound Identity Federation | デフォルト1時間、最大3時間（ `DurationSeconds` で指定） |

ID Tokenはトークン交換の `subject_token` としてのみ使うため、交換が完了するまで有効であれば十分です。交換で得たアクセストークンには `expires_in` で示される有効期限があります。アクセストークンは期限が切れるまで複数のリクエストで使い回し、期限が切れたら再度トークン交換してください。期限切れのアクセストークンを使うと公開APIは `401 unauthorized` を返します。

`bm login` で取得したJWTの有効期限切れ時の挙動は、「 [トークンの期限切れ](/public_api/authentication/#%E3%83%88%E3%83%BC%E3%82%AF%E3%83%B3%E3%81%AE%E6%9C%9F%E9%99%90%E5%88%87%E3%82%8C) 」を参照してください。

## 関連情報 [](#関連情報)

- [公開APIとは](/public_api/) — 公開APIの概要・対応する操作・アクションの識別子の扱い
- [APIリファレンス](/public_api/reference/) — エンドポイント・パラメーター・レスポンス・エラーコードの詳細
- [サービスアカウント](/service_account/) — サービスアカウントの作成とOIDC信頼ポリシー設定の詳細手順
- [`bm login`](/code_management/cli/login/) — ローカル端末でJWTを取得するコマンドの説明
- [`bm print-access-token`](/code_management/cli/print_access_token/) — 保存済みのJWTを標準出力に取り出すコマンドの説明

[公開APIとは](/public_api/) [APIリファレンス](/public_api/reference/)
---

---
サービスアカウント

# サービスアカウント

サービスアカウントは、CI/CDなど機械からの操作専用のアカウントです。人のユーザーアカウントとは独立して、権限と監査対象を管理できます。

サービスアカウントには以下の特徴があります。

- ベースマキナの画面上のユーザー一覧には表示されない
- 課金の対象にならない
- 人のユーザーアカウントとは独立して、グループ所属による権限を管理できる

## サービスアカウントを利用する機能 [](#サービスアカウントを利用する機能)

サービスアカウントは、外部システムや機械からベースマキナを操作する複数の機能で共通して利用します。

- [コード管理](/code_management/) — CLIやCI/CDから設定の差分を検出・反映する
- [公開API](/public_api/) — 外部システムからアクションを実行する
- [定期実行](/action/cron_jobs/#%E5%AE%9F%E8%A1%8C%E8%80%85) — 定期実行の実行者に指定する

いずれの機能でも、CLI・CI/CD・クラウドからの操作はサービスアカウントの権限で実行されます。

## 必要なロール [](#必要なロール)

サービスアカウントの作成、プロジェクトへの追加、グループへの所属設定、OIDC信頼ポリシーの設定には、企業アカウントの管理者の権限が必要です。

## サービスアカウントの作成とプロジェクトへの追加 [](#サービスアカウントの作成とプロジェクトへの追加)

1. 右上のメニューから「設定」を選択します。
1. サイドバーのメニューから「サービスアカウント管理」を選択します。
1. サービスアカウントを新規作成するか、既存のサービスアカウントをプロジェクトに追加します。

複数のサービスアカウントを使い分けることもできます（例：開発用とCI/CD用を分ける、リポジトリごとに分ける）。

## グループへの所属（権限付与） [](#グループへの所属権限付与)

サービスアカウントの権限は、所属するグループのロールによって決まります。「設定」→「グループ管理」から、用意したサービスアカウントを目的別のグループへ追加してください。必要な権限は用途によって異なります。

### コード管理で使う場合 [](#コード管理で使う場合)

アクションの作成・更新などの操作をするには、アクション管理権限を持つロール（プロジェクト管理者・開発責任者・開発者のいずれか）を含むグループへの所属が必要です。

### 公開APIでアクションを実行する場合 [](#公開apiでアクションを実行する場合)

公開APIでのアクション実行は、サービスアカウントが所属するグループの権限で実行されます。アクションに [実行権限](/action/action_permission/) が設定されている場合は、対象アクションの実行権限をサービスアカウントの所属グループへ付与してください。実行権限を制限していないアクションは、グループへの所属だけで実行できます。

サービスアカウントへ付与する権限は、必要最小限にとどめることを推奨します。

## OIDC信頼ポリシー [](#oidc信頼ポリシー)

CI/CDやクラウドからサービスアカウントとして操作する場合は、OIDC信頼ポリシーを設定します。OIDC信頼ポリシーは、GitHub Actionsなどの外部サービスが発行したOIDC ID Tokenを、ベースマキナのサービスアカウントと紐づけるためのポリシーです。

複数のポリシーを設定した場合、どれか1つのポリシーを満たすと認証できます。

「サービスアカウント管理」画面で対象のサービスアカウントを開き、詳細画面の「OIDC信頼ポリシー」から、「ポリシーを追加」→「GitHub Actions」または「カスタム」を選択して、ポリシーを追加します。

ローカル端末から `bm   login` で認証して操作する場合は、OIDC信頼ポリシーの設定は不要です。CI/CDやクラウドと連携する段階で設定してください。

### 設定項目 [](#設定項目)

| 項目 | 説明 |
| --- | --- |
| `Issuer` | OIDC ID Tokenを発行するサービスのURL（例: `https://token.actions.githubusercontent.com` ） |
| `Audience` | ID Tokenの `aud` クレームに含めるAudience（例: `https://basemachina.com` ）。企業アカウントごとに固有の値を設定するとトークン悪用を防げる |
| `Bound Claims` | 受け入れるID Tokenの条件を `key` と `pattern` のペアで指定する（1件以上必須） |

### GitHub Actionsの場合 [](#github-actionsの場合)

「ポリシーを追加」ドロップダウンリストで「GitHub Actions」を選択すると、 `Issuer` などがあらかじめ入力された状態でポリシーを追加できます。 `Bound Claims` には、例えば `key: sub` 、 `pattern: repo:<org>/<repo>:ref:refs/heads/main` のように、受け付けるブランチ・リポジトリの条件を指定します。

### カスタムの場合 [](#カスタムの場合)

GitHub Actions以外のOIDC IdP（Google Cloud / AWS / Auth0 / Okta / Kubernetesなど）を利用する場合は、「カスタム」を選択します。「ポリシーを追加」ドロップダウンリストから「カスタム」を選び、各項目を手動で設定してください。呼び出し元別の具体的な設定値は [公開APIを認証して呼び出す](/public_api/authentication/) を参照してください。

ここで設定した `Audience` は、CI/CD側のワークフロー（ `bm-action` の `audience` 入力や `bm   sync` の認証、公開APIの呼び出し）でも同じ値を指定する必要があります。

## 関連情報 [](#関連情報)

- [コード管理の始め方](/code_management/getting_started/) — サービスアカウントを使ったコード管理のセットアップ手順
- [公開APIを認証して呼び出す](/public_api/authentication/) — サービスアカウントのOIDC信頼ポリシーを使った公開APIの認証
- [定期実行](/action/cron_jobs/#%E5%AE%9F%E8%A1%8C%E8%80%85) — 定期実行の実行者にサービスアカウントを指定する

[今後追加予定の機能](/code_management/upcoming_features/) [公開APIとは](/public_api/)
---
スタートガイド

# スタートガイドとは

スタートガイドは、ベースマキナにはじめて触れるお客さまへ主要な機能を体系的に説明するコンテンツです。

順番に従ってお読みいただくことで機能をまんべんなく知っていただき、セットアップの助けになることを目的としています。

## スタートガイドの目次 [](#スタートガイドの目次)

- [サンプルのアクションを実行する](/start_guide/sample_action/)
- [データソースへの接続設定をする](/start_guide/datasource/environment/)
- （作成中）アクションを使って画面を作る
- （作成中）画面移動を設定する
- （作成中）必要なメンバーを招待する
- （作成中）安全に実行できるようにする
- （作成中）時間がかかる処理を実行する
- （作成中）複雑な画面をビューで作成する

[ベースマキナとは](/) [サンプルのアクションを実行する](/start_guide/sample_action/)
---
[スタートガイド](/start_guide/)

データソースへの接続設定をする

開発環境と本番環境を登録する

# 開発環境と本番環境を登録する

ベースマキナには [環境を作成する機能](/admin/environment/what_is_environment/) が用意されています。

機能の詳細は上記のドキュメントをご覧ください。

任意の数の環境を作成してデータソースの接続情報をはじめとした設定を切り替えられます。

ここでは開発環境と本番環境を作成しましょう。

## 環境を登録する [](#環境を登録する)

このとき、使用中の環境がどれかを目視確認しやすいように、テーマカラーを設定できます。

登録後、画面左上のメニューで環境が切り替えられることを確認しましょう。

これで各環境に対応した設定を登録できるようになりました。

## 環境に利用制限をつける [](#環境に利用制限をつける)

環境を作成・更新する際に [利用制限](/admin/environment/access_control/) を設定できます。

例えば開発環境はエンジニアのグループだけがアクセスできるようにして、本番環境は全員がアクセスできるといった設定が可能です。

他にも「開発環境は全員アクセス可能だが、本番環境は運用者のCSやエンジニアだけがアクセス可能」といった設定でも良いでしょう。

[サンプルのアクションを実行する](/start_guide/sample_action/) [ファイアウォールを設定する](/start_guide/datasource/firewall_setting/)
---
[スタートガイド](/start_guide/)

データソースへの接続設定をする

ファイアウォールを設定する

# ファイアウォールを設定する

ベースマキナは、固定のIPアドレスを通じてお客さまが設定されたデータソースへアクセスします。

検証段階で厳格さが求められない場合、ファイアウォールの設定は不要です。

一方、本番運用で社内のデータソースへアクセスする際にはアクセス元の制限を推奨しています。

[IPホワイトリスト](/admin/action/ip_whitelist/) を参考に、ファイアウォールを設定してください。

[開発環境と本番環境を登録する](/start_guide/datasource/environment/) [HTTP API/gRPCのデータソースを登録する](/start_guide/datasource/http_or_grpc_datasource/)
---
[スタートガイド](/start_guide/)

データソースへの接続設定をする

HTTP API/gRPCのデータソースを登録する

# HTTP API/gRPCのデータソースを登録する

環境を作成したら、データソースを登録しましょう。

すでにお持ちのAPIが外部に公開されていたり、SaaSのAPIと連携してデータを更新・取得できるケースであれば、後述する [bridge](/faq/what_is_bridge/) をセットアップする手間が不要なケースもあるため、手軽に始められます。

そうした前提を踏まえて、まずはHTTP API/gRPCのデータソースを登録してみましょう。

## 接続情報の登録 [](#接続情報の登録)

データソースの種類の中からHTTP APIまたはgRPCを選択します。

接続先のURLや共通のヘッダー情報を入力する欄が表示されるので、入力しましょう。

詳細な接続情報は [HTTP API](/action/datasources/httpapi_integration/) や、 [gRPC](/action/datasources/grpc_integration/) のページをご覧ください。

認証が必要なAPIでは [環境ごとの変数・シークレット](/action/parameter/vars_secrets/) に設定したAPIキーをヘッダーに含めたり、 [認証用アクション](/action/datasources/httpapi_integration/#%E8%AA%8D%E8%A8%BC%E7%94%A8%E3%82%A2%E3%82%AF%E3%82%B7%E3%83%A7%E3%83%B3%E3%81%AE%E8%A8%AD%E5%AE%9A) を使った動的なトークン取得なども可能です。

[ファイアウォールを設定する](/start_guide/datasource/firewall_setting/) [初回セットアップの流れ](/faq/howto_setup/)
---
[スタートガイド](/start_guide/)

サンプルのアクションを実行する

# このページで説明していること

ベースマキナがサンプルとして用意したアクションを使って、ベースマキナの基本的な動作を説明します。

## アクションについて [](#アクションについて)

ベースマキナではアクションのパラメーター（入力値）の設定を使ってフォームが生成されます。

結果の型に応じて自動で画面が用意されるため、アクションの実行画面をそのまま管理画面としてお使いいただけます。

## サンプルのアクションを開く [](#サンプルのアクションを開く)

プロジェクトにはサンプルのデータソースとアクションが用意されています。

ここでは、ベースマキナがサンプルとして用意しているアクションを開いて実行してみましょう。

画面上部のメニューバーからアクションのアイコンをクリックし、「【サンプル】ユーザーの一覧取得」を実行してみましょう。

アクションの画面を開くと実行ボタンが表示されます。

## サンプルのアクションを実行する [](#サンプルのアクションを実行する)

実行ボタンを押すとサンプル用のHTTP APIのデータソースにGETのリクエストが送信されます。

そしてリクエストが成功すると画面上にレスポンス内容が表示されますが、このとき配列のデータは自動でテーブルの形に整形されて表示されます。

この画面では実行画面にボタンしか表示されていませんが、パラメーターを設定すればそれぞれの値の型に対応したフィールドを含んだフォームが用意されます。

# まとめ

このページでは、ベースマキナがサンプルとして用意しているアクションを開いて実行することで、ベースマキナの基本的な動作を説明しました。

データの変更・読み込みの両面で、まずはアクションを使用して簡素に管理画面化することをおすすめいたします。

# 関連するドキュメント

- [HTTP API](/httpapi_integration/)
- [パラメーターとは](/action/parameter/action_parameter/)

[スタートガイド](/start_guide/) [開発環境と本番環境を登録する](/start_guide/datasource/environment/)
---
便利な使い方

Claudeのプロジェクトでベースマキナのドキュメントを活用する

# Claudeのプロジェクトでベースマキナのドキュメントを活用する

[Claude (opens in a new tab)](https://claude.ai/) の [プロジェクト機能 (opens in a new tab)](https://support.anthropic.com/ja/articles/9517075-%E3%83%97%E3%83%AD%E3%82%B8%E3%82%A7%E3%82%AF%E3%83%88%E3%81%A8%E3%81%AF%E4%BD%95%E3%81%A7%E3%81%99%E3%81%8B) を使用して、ベースマキナのドキュメントを効率的に活用する方法を説明します。

## Claudeのプロジェクトとは [](#claudeのプロジェクトとは)

Claudeのプロジェクトは、有料プランのユーザーが利用できる専用のワークスペース機能です。プロジェクトごとに独立したチャット履歴と知識ベースを持ち、アップロードした文書やテキストをもとに、より文脈に即したAI支援を受けることができます。

## プロジェクト作成方法 [](#プロジェクト作成方法)

### 1. プロジェクトの新規作成 [](#1-プロジェクトの新規作成)

1. [Claude (opens in a new tab)](https://claude.ai/) の「プロジェクト」を開く

![プロジェクトへのメニュー](/images/claude_project_integration/claude_menu.png) 1. 「+新規プロジェクト」をクリック
1. プロジェクト名、 プロジェクトの説明を入力し、「プロジェクトを作成」をクリック

![プロジェクトの作成](/images/claude_project_integration/create_project.png) 1. 以下のURLから、 `llms-full.txt` をダウンロードする

[https://docs.basemachina.com/llms-full.txt (opens in a new tab)](https://docs.basemachina.com/llms-full.txt)

1. プロジェクトナレッジに、先ほどダウンロードした `llms-full.txt` をアップロードする

![ファイルのアップロード](/images/claude_project_integration/add_project_knowledge.png) 1. （必要に応じて）プロジェクトの指示を追加する

設定しなくてもよいですが、設定することで、より目的に沿った回答が得られるようになります。

プロンプトの設定例 ```
あなたはベースマキナの専門知識を持つアシスタントです。
ベースマキナは自社データを使った社内向けシステムを簡単に作成できるローコードのプラットフォームです。

## 回答形式
- 技術的な質問には具体例を含めて回答
  - JavaScriptアクションおよび、ビューのコード例では必ずimport元を明示
- 詳細に調査し、複数の実現手段を検討して提案する
- 正確性に注意し、ドキュメントに記載されている情報で回答する
  - JavaScriptアクションおよび、ビューのコードの質問には、関数、コンポーネントの使い方を詳しく調べて回答する
- 設定手順は段階的に説明
- トラブルシューティングでは原因と解決策を明示

## 知識の範囲
- ベースマキナの全機能について詳細な知識を保持
- 実装パターンとベストプラクティス
- よくある問題と解決方法
- セキュリティ要件と対応方法
```

以上の作業が完了すると、チャット形式でベースマキナの使い方についてClaudeへ質問できるようになります。

Claude はチャットの回答に生成AIを使用するため、内容の正確性を保証いたしかねます。あらかじめご了承ください。

## 活用方法 [](#活用方法)

### 基本的な質問例 [](#基本的な質問例)

```
Q: 環境ごとにどんな情報を切り替えられますか？
Q: アクションの実行制限はどのように有効化できますか？
Q: あるアクションの実行結果を使って別のアクションを呼ぶ方法は？
Q: ビューでアクションを実行するフォームを作る方法は？
```

#### チャットの例 [](#チャットの例)

![チャットの例](/_next/static/media/chat_example.84bc4152.png)

### チーム機能の活用 [](#チーム機能の活用)

Claude for Workプランでは、 [プロジェクトをチームメンバーと共有できます (opens in a new tab)](https://support.anthropic.com/ja/articles/9519189-%E3%83%97%E3%83%AD%E3%82%B8%E3%82%A7%E3%82%AF%E3%83%88%E3%81%AE%E5%8F%AF%E8%A6%96%E6%80%A7%E3%81%A8%E5%85%B1%E6%9C%89) 。
各メンバーが個別にプロジェクトを設定することなく、簡単にご活用いただけます。

[NotebookLMでベースマキナのドキュメントを活用する](/tips/notebooklm_integration/) [AIプラットフォームへの接続](/usecase/ai_integration/ai_platform_connection/)
---
便利な使い方

GeminiのGemでベースマキナのドキュメントを活用する

# GeminiのGemでベースマキナのドキュメントを活用する

[Gemini (opens in a new tab)](https://gemini.google.com/) の [Gem機能 (opens in a new tab)](https://support.google.com/gemini/answer/15236405?hl=ja) を使用して、ベースマキナのドキュメントを効率的に活用する方法を説明します。

## GeminiのGemとは [](#geminiのgemとは)

GeminiのGemは、特定の目的や分野に特化したカスタマイズ機能です。Gemごとに独立した指示設定とファイルベースを持ち、アップロードした文書やテキストをもとに、より文脈に即したAI支援を受けることができます。

## Gemの作成方法 [](#gemの作成方法)

1. [Gemini (opens in a new tab)](https://gemini.google.com/) にGoogleアカウントでログイン
1. 左側にある「Gemを表示」をクリック

![Gemを表示](/images/gemini_gem_integration/show_gems.png) 1. 「+ Gemを作成」をクリック
1. Gemの名前を入力（例：ベースマキナ ドキュメント）

### カスタム指示の設定 [](#カスタム指示の設定)

設定しなくてもよいですが、設定することで、より目的に沿った回答が得られるようになります。

プロンプトの設定例 ```
あなたはベースマキナの専門知識を持つアシスタントです。
ベースマキナは自社データを使った社内向けシステムを簡単に作成できるローコードのプラットフォームです。

## 回答形式
- 技術的な質問には具体例を含めて回答
  - JavaScriptアクションおよび、ビューのコード例では必ずimport元を明示
- 詳細に調査し、複数の実現手段を検討して提案する
- 正確性に注意し、ドキュメントに記載されている情報で回答する
  - JavaScriptアクションおよび、ビューのコードの質問には、関数、コンポーネントの使い方を詳しく調べて回答する
- 設定手順は段階的に説明
- トラブルシューティングでは原因と解決策を明示

## 知識の範囲
- ベースマキナの全機能について詳細な知識を保持
- 実装パターンとベストプラクティス
- よくある問題と解決方法
- セキュリティ要件と対応方法
```

### llms-full.txtの設定 [](#llms-fulltxtの設定)

以下のURLから、 `llms-full.txt` をダウンロードしてください。

[https://docs.basemachina.com/llms-full.txt (opens in a new tab)](https://docs.basemachina.com/llms-full.txt)

「知識」の「+」ボタンをクリックして保存した `llms-full.txt` を選択してください。

![Gemの知識の追加](/images/gemini_gem_integration/add_gem_knowledge.png) ここまでの作業が終わったら、「保存」をクリックします。

以上の作業が完了すると、チャット形式でベースマキナの使い方についてGemへ質問できるようになります。

Gemini はチャットの回答に生成AIを使用するため、内容の正確性を保証いたしかねます。あらかじめご了承ください。

## 活用方法 [](#活用方法)

### 基本的な質問例 [](#基本的な質問例)

```
Q: 環境ごとにどんな情報を切り替えられますか？
Q: アクションの実行制限はどのように有効化できますか？
Q: あるアクションの実行結果を使って別のアクションを呼ぶ方法は？
Q: ビューでアクションを実行するフォームを作る方法は？
```

#### チャットの例 [](#チャットの例)

![チャットの例](/_next/static/media/chat_example.c7a81c14.png)

[SQLのアクションで前のクエリの結果を使用する](/tips/sql_previous_result/) [NotebookLMでベースマキナのドキュメントを活用する](/tips/notebooklm_integration/)
---
便利な使い方

NotebookLMでベースマキナのドキュメントを活用する

# NotebookLMでベースマキナのドキュメントを活用する

Googleの [NotebookLM (opens in a new tab)](https://notebooklm.google.com/) を使用して、ベースマキナのドキュメントを効率的に活用する方法を説明します。

## NotebookLMとは [](#notebooklmとは)

NotebookLMは、Googleが開発したAI搭載の研究支援ツールです。アップロードしたドキュメントをもとに、質問応答や要約、新しいアイデアの提案ができます。

## ドキュメントの追加方法 [](#ドキュメントの追加方法)

### 1. NotebookLMにアクセス [](#1-notebooklmにアクセス)

1. [NotebookLM (opens in a new tab)](https://notebooklm.google.com/) にGoogleアカウントでログイン
1. 「+新規作成」をクリック
1. 「ソースを追加」画面から、「リンク」の「ウェブサイト」を選択

![「ソースを追加」画面](/_next/static/media/add_source_dialog.0d18acaa.png)

1. 以下のURLを入力して、「挿入」をクリック

```
https://docs.basemachina.com/llms-full.txt
```

![URLの入力](/_next/static/media/input_url.5ec96633.png)

以上の作業が完了すると、チャット形式でベースマキナの使い方についてNotebookLMへ質問できるようになります。

NotebookLM はチャットの回答に生成AIを使用するため、内容の正確性を保証いたしかねます。あらかじめご了承ください。

## 活用方法 [](#活用方法)

### 基本的な質問例 [](#基本的な質問例)

```
Q: 環境ごとにどんな情報を切り替えられますか？
Q: アクションの実行制限はどのように有効化できますか？
Q: あるアクションの実行結果を使って別のアクションを呼ぶ方法は？
Q: ビューでアクションを実行するフォームを作る方法は？
```

#### チャットの例 [](#チャットの例)

![チャットの例](/_next/static/media/chat_example.90ce6a48.png)

### 音声概要の活用 [](#音声概要の活用)

NotebookLMの「音声概要」機能を使用すると、ベースマキナの機能について説明するポッドキャスト形式の音声を生成できます。

[GeminiのGemでベースマキナのドキュメントを活用する](/tips/gemini_gem_integration/) [Claudeのプロジェクトでベースマキナのドキュメントを活用する](/tips/claude_project_integration/)
---
便利な使い方

SQLのアクションで前のクエリの結果を使用する

# SQLのアクションで前のクエリの結果を使用する

ベースマキナのSQL系のデータソース（MySQL、PostgreSQL）では、複数のクエリを登録して順番に実行できます。

この機能を使う際に、前のクエリの結果を次のクエリで使用できます。

ここでは、次のように指定のメールアドレスのユーザー情報を取得してから、取得したユーザーIDを使用してユーザーの決済情報を無効化するクエリを実行する例を紹介します。

```
-- 指定したメールアドレスのユーザーIDを取得する
SELECT id FROM users WHERE email = {{ email }} LIMIT 1;
 
-- 取得したユーザーIDを使用してユーザーの決済情報を無効化する
DELETE FROM payment_settings WHERE user_id = （取得したユーザーID）;
```

## 変数を利用する方法（MySQLのみ） [](#変数を利用する方法mysqlのみ)

変数を定義して、取得したユーザーIDを格納し、その変数を次のクエリで使用する方法です。

まず最初のクエリで変数を定義します。

```
SET @userId = '';
```

次に、指定のメールアドレスのユーザー情報を取得して、取得したユーザーIDを変数に格納します。

```
SELECT id INTO @userId FROM users WHERE email = {{ email }} LIMIT 1;
```

最後に、取得したユーザーIDを使用してユーザーの決済情報を無効化するクエリを実行します。

このクエリだけ「書き込み」の種類のクエリとして登録します。

```
DELETE FROM payment_settings WHERE user_id = @userId;
```

以上のように、 `@` を付けた変数を定義することで、前のクエリの結果を次のクエリで使用できます。

最終的な設定は次の画像のようになります。

![変数を使って前のクエリの結果を使用する](/_next/static/media/sql_previous_result_variable.08ce37c8.png)

なお、ベースマキナのSQL系のアクションは、複数のクエリを登録していても1つのセッション内で処理されます。

したがって一度変数に格納した値は、後続のクエリのいずれでも使用できます。

## 一時テーブルを使う方法（MySQL / PostgreSQL） [](#一時テーブルを使う方法mysql--postgresql)

一時テーブルを定義して、取得したユーザーIDを格納し、その一時テーブルのレコードを次のクエリで使用する方法です。

指定のメールアドレスのユーザー情報を取得して、取得したユーザーIDを一時テーブルに格納します。

```
CREATE TEMPORARY TABLE temp_user AS SELECT id FROM users WHERE email = {{ email }} LIMIT 1;
```

そして、取得したユーザーIDを使用してユーザーの決済情報を無効化するクエリを実行します。

このクエリだけ「書き込み」の種類のクエリとして登録します。

```
DELETE FROM payment_settings WHERE user_id = (SELECT id FROM temp_user);
```

以上のように、 `CREATE TEMPORARY TABLE` を使って一時テーブルを定義することで、前のクエリの結果を次のクエリで使用できます。

最終的な設定は次の画像のようになります。

![一時テーブルを使って前のクエリの結果を使用する](/_next/static/media/sql_previous_result_temporary_table.524518c4.png)

なお、ベースマキナのSQL系のアクションは、複数のクエリを登録していても1つのセッション内で処理されます。

したがって一時テーブルに格納した値は、後続のクエリのいずれでも使用できます。

一時テーブルはセッションが終了すると自動的に削除されます。

[環境別のIPアドレス制限](/admin/environment/ip_restriction/) [GeminiのGemでベースマキナのドキュメントを活用する](/tips/gemini_gem_integration/)
---
ユースケース

AI活用

AIプラットフォームへの接続

# AIプラットフォームへの接続

## 概要 [](#概要)

AIプラットフォームと連携してコンテンツの審査やサマリ生成をする際の、共通的なアクション設定方法を説明します。

ここでは [Gemini API (opens in a new tab)](https://ai.google.dev/gemini-api/docs?hl=ja#rest) を例に、データソースとHTTPアクションの設定手順を示します。

![AIプラットフォームのデータソース設定](/images/usecase/ai_integration/customer_support_summary/gemini_api.png)

## データソースの作成 [](#データソースの作成)

| 項目 | 設定内容 |
| --- | --- |
| データソース名（例） | `Gemini API` |
| データソースの種類 | `HTTP` |
| データソースのURL | `https://generativelanguage.googleapis.com/v1beta` |
| 共通ヘッダー | キー名： `x-goog-api-key`, 値： `{{ secrets.GEMINI_API_KEY }}` （シークレットとして設定） |

## HTTPアクション作成 [](#httpアクション作成)

| 項目 | 設定内容 |
| --- | --- |
| アクション名 | `Gemini AI 呼び出し` |
| エンドポイント | `/models/gemini-2.5-flash:generateContent` |
| メソッド | `POST` |
| パラメーター | `prompt` - JSON値型 (JSON値の種類: テキスト) |

**リクエストボディ**

```
{
  "contents": [
    {
      "parts": [
        {
          "text": {{ prompt }}
        }
      ]
    }
  ]
}
```

## 関連情報 [](#関連情報)

- [AI活用とは](/ai_integration/) — ベースマキナとAIを組み合わせてできることの全体像
- [コンテンツの審査自動化](/usecase/ai_integration/screening/) — 入稿コンテンツの一次審査をAIにさせる例
- [サポート対応時のユーザーサマリ生成](/usecase/ai_integration/customer_support_summary/) — 問い合わせ対応に必要な情報をAIに要約させる例
- [マスターデータの多言語翻訳](/usecase/ai_integration/master_data_translator/) — 商品マスターデータをAIで多言語に翻訳する例

[Claudeのプロジェクトでベースマキナのドキュメントを活用する](/tips/claude_project_integration/) [サポート対応時のユーザーサマリ生成](/usecase/ai_integration/customer_support_summary/)
---
ユースケース

AI活用

サポート対応時のユーザーサマリ生成

# サポート対応時のユーザーサマリ生成

![顧客詳細ページでAIサマリが表示された画像イメージ](/images/usecase/ai_integration/customer_support_summary/demoui.png)

## 想定シナリオ [](#想定シナリオ)

カスタマーサポート担当者がユーザーからサービス上での決済が失敗しているため確認して欲しいという依頼を受けた際、ユーザーの決済にまつわる情報を集約したサマリをAIで生成する例です。

お問い合わせ管理ツール上でユーザーからの質問を受け取り、その後データベースやサービスの管理者用APIを通じてユーザーの利用プランと決済履歴を収集します。

その後、各種レスポンスの内容をAIでサマリに変換して画面上に表示。問い合わせ解決に必要な情報を迅速に把握可能になります。

### 利用者例 [](#利用者例)

- カスタマーサポート
- セールス
- CRE（Customer Reliability Engineer）

### 業界例 [](#業界例)

- 法人向けSaaS全般
- EC
- 金融

## 事前準備 [](#事前準備)

AIプラットフォームとの接続設定については、 [AIプラットフォームへの接続](/usecase/ai_integration/ai_platform_connection/) を参照してください。

## 設定例 [](#設定例)

### 想定されるアクション一覧 [](#想定されるアクション一覧)

| アクション名 | 処理の概要 | データソースの種類 |
| --- | --- | --- |
| 利用プラン情報取得 | ユーザーの現在の利用プラン情報を取得 | HTTP |
| 決済履歴取得 | ユーザーの決済履歴を取得 | HTTP |
| 決済サポート用サマリ生成 | 決済関連データを統合してサマリを生成。AIにわたすプロンプトの内容をここで定義する | JavaScript |

### 想定されるプロンプトの内容 [](#想定されるプロンプトの内容)

JavaScriptアクションのコードのなかで、以下のようにプロンプトを定義します。

```
決済の不具合を調査したいという問い合わせに対して、以下の情報を基にカスタマーサポート担当者向けの簡潔なサマリを日本語で生成してください。
 
【利用プラン情報】
- プラン名: ${subscriptionInfo.plan_name}
- プラン開始日: ${subscriptionInfo.plan_start_date}
- プラン状態: ${subscriptionInfo.plan_status}
- 料金: ${subscriptionInfo.monthly_price}円/月
 
【最近の決済履歴】
${paymentHistory.payments.map(payment =>
  `- ${payment.payment_date}: ${payment.amount}円 (${payment.status}) - ${payment.payment_method}`
).join('\n')}
 
サマリは以下の構成で生成してください：
1. 現在のプラン状況（1行）
2. 決済状況の概要（1-2行）
3. 決済不具合の可能性や確認ポイント（1-2行）
```

## 関連情報 [](#関連情報)

- [AI活用とは](/ai_integration/) — ベースマキナとAIを組み合わせてできることの全体像
- [AIプラットフォームへの接続](/usecase/ai_integration/ai_platform_connection/) — LLMを呼び出すアクションの共通的な設定方法

[AIプラットフォームへの接続](/usecase/ai_integration/ai_platform_connection/) [コンテンツの審査自動化](/usecase/ai_integration/screening/)
---
ユースケース

AI活用

マスターデータの多言語翻訳

# マスターデータの多言語翻訳

![商品マスター管理画面でAI翻訳が表示された画像イメージ](/images/usecase/ai_integration/master_data_translator/demoui.png)

## 想定シナリオ [](#想定シナリオ)

ECサイトや多言語対応が必要なサービスで、商品マスターデータの多言語翻訳を効率化する例です。

商品マスターデータの管理画面で商品情報を登録する際、AIを活用して商品名や説明文を複数言語に自動翻訳します。

翻訳結果は管理画面上でプレビューでき、翻訳内容を確認・修正した後、承認操作をすることでデータベースに本登録される想定です。

### 利用者例 [](#利用者例)

- 商品企画
- マーケティング
- カスタマーサポート

### 業界例 [](#業界例)

- EC
- 小売
- 製造業
- 観光・旅行
- 法人向けSaaS

## 事前準備 [](#事前準備)

AIプラットフォームとの接続設定については、 [AIプラットフォームへの接続](/usecase/ai_integration/ai_platform_connection/) を参照してください。

## 設定例 [](#設定例)

### 想定されるアクション一覧 [](#想定されるアクション一覧)

| アクション名 | 処理の概要 | データソースの種類 |
| --- | --- | --- |
| 商品マスターデータ情報取得 | 翻訳対象の商品マスターデータ情報を取得 | HTTP |
| 多言語翻訳の生成 | 商品情報を複数言語に翻訳。翻訳品質やトーンをコントロールするプロンプトを定義 | HTTP |
| 翻訳内容の本登録 | 承認された翻訳内容を商品マスターデータテーブルに本登録 | HTTP |

### 想定されるプロンプトの内容 [](#想定されるプロンプトの内容)

JavaScriptアクションのコードのなかで、以下のようにプロンプトを定義します。

```
以下の商品情報を{{ targetLanguage }}に翻訳してください。
 
【商品情報】
商品名: {{ name }}
商品説明: {{ description }}
カテゴリ: {{ category }}
ブランド: {{ brand }}
 
【翻訳要件】
- ターゲット言語: {{ targetLanguage }} (例: 英語、中国語、韓国語)
- トーン: {{ brand_tone }} (例: カジュアル、フォーマル、専門的)
- 文字数制限: 商品名は{{ maxNameLength }}文字以内、説明文は{{ maxDescriptionLength }}文字以内
- 専門用語や固有名詞は適切に処理すること
- 現地の文化や習慣に配慮した自然な表現を使用すること
 
【出力フォーマット】
JSON形式で以下の構造で出力してください：
{
  "translated_name": "翻訳された商品名",
  "translated_description": "翻訳された商品説明",
  "translation_notes": "翻訳時の注意点や特記事項（あれば）"
}
```

## 関連情報 [](#関連情報)

- [AI活用とは](/ai_integration/) — ベースマキナとAIを組み合わせてできることの全体像
- [AIプラットフォームへの接続](/usecase/ai_integration/ai_platform_connection/) — LLMを呼び出すアクションの共通的な設定方法

[コンテンツの審査自動化](/usecase/ai_integration/screening/) [(旧)JavaScriptアクション](/deprecated/javascript_action/)
---
ユースケース

AI活用

コンテンツの審査自動化

# コンテンツの審査自動化

![顧客詳細ページでAIサマリが表示された画像イメージ](/images/usecase/ai_integration/screening/demoui.png)

## 想定シナリオ [](#想定シナリオ)

広告プラットフォームやユーザー投稿型のメディアプラットフォームなどで、投稿されたコンテンツの審査を自動化する例です。

入稿されたデータを審査担当者が確認する前に、一次審査をAIが自動で実施し、人の目で判断する労力を下げる画面を作成します。

入稿された情報は検索・一覧画面から探すことができ、コンテンツの詳細画面から審査結果を確認できます。

詳細画面でその結果を見た後、審査担当が手動で最終的な審査結果を担当者が入力、保存する想定です。

### 利用者例 [](#利用者例)

- カスタマーサポート
- 法務
- 営業企画

### 業界例 [](#業界例)

- 広告
- メディア
- SNS
- EC

## 事前準備 [](#事前準備)

AIプラットフォームとの接続設定については、 [AIプラットフォームへの接続](/usecase/ai_integration/ai_platform_connection/) を参照してください。

## 設定例 [](#設定例)

### 想定されるアクション一覧 [](#想定されるアクション一覧)

| アクション名 | 処理の概要 | データソースの種類 |
| --- | --- | --- |
| コンテンツ情報取得 | コンテンツの情報を取得 | HTTP |
| コンテンツ審査結果生成 | コンテンツの情報を統合して審査結果を生成。ガイドラインや法規制など、AIにわたすプロンプトの内容をここで定義する | JavaScript |

### 想定されるプロンプトの内容 [](#想定されるプロンプトの内容)

JavaScriptアクションのコードのなかで、以下のようにプロンプトを定義します。

※チェック項目別の過去の判断の事例等は別途LLMに渡しておく想定です。

```
/**
 * 広告やメディア記事の1次審査用プロンプト例
 * - 薬機法、景品表示法、自社ガイドラインへの適合性をAIにチェックさせる
 * - 審査結果は日本語で簡潔にまとめる
 */
const prompt = `
以下のコンテンツが薬機法、景品表示法および自社ガイドラインに適合しているか一次審査を行ってください。
 
【コンテンツ情報】
タイトル: ${contentInfo.title}
本文: ${contentInfo.body}
カテゴリ: ${contentInfo.category}
 
【審査基準】
- 薬機法（医薬品、医療機器等の品質、有効性及び安全性の確保等に関する法律）に違反する表現がないか
- 景品表示法（不当景品類及び不当表示防止法）に違反する誇大広告や虚偽表示がないか
- 自社ガイドライン（例：過度な表現、差別的・不適切な内容、事実に基づかない記載の禁止）に違反していないか
 
【出力フォーマット】
1. 違反の有無（「適合」「一部不適合」「不適合」から選択）
2. 指摘事項（違反や懸念点があれば具体的に箇条書きで記載）
3. コメント（全体的な所感や注意点を簡潔に記載）
 
審査結果を日本語で出力してください。
`;
```

## 関連情報 [](#関連情報)

- [AI活用とは](/ai_integration/) — ベースマキナとAIを組み合わせてできることの全体像
- [AIプラットフォームへの接続](/usecase/ai_integration/ai_platform_connection/) — LLMを呼び出すアクションの共通的な設定方法

[サポート対応時のユーザーサマリ生成](/usecase/ai_integration/customer_support_summary/) [マスターデータの多言語翻訳](/usecase/ai_integration/master_data_translator/)
---
ビュー

# ビューとは

ビューとは、業務に合わせたカスタマイズされた画面を作成できる機能です。

データの表示だけでなく、画面表示後にアクションを実行したり、画面間の移動もできます。
複数のアクションを組み合わせた複雑な業務フローや、複数のデータを一箇所に集約して業務効率を上げるための画面を作成できます。

## ビューを作成する2つの方法 [](#ビューを作成する2つの方法)

ベースマキナでは、ビューを作成する方法として以下の2つを提供しています。

### ビジュアルエディター [](#ビジュアルエディター)

[ビジュアルエディター](/view/visual_editor/) は、直感的な操作で画面を作成できる機能です。
基本的にはノーコードで設定でき、さらにJavaScriptを使用した高度な設定も可能です。

典型的な管理画面を素早く簡単に作成したい場合に最適です。

### コードエディター [](#コードエディター)

[コードエディター](/view/code_editor/) は、ReactとJavaScriptを使って完全にカスタマイズされた画面を作成できる機能です。
コードを書く必要はありますが、組み込みの関数やコンポーネントが用意されているためフルスクラッチの開発よりも簡単に画面を作成できます。

ビジュアルエディターでは対応できない高度なカスタマイズが必要な場合に使用します。

## どちらを使うべきか [](#どちらを使うべきか)

基本的には、最も作成が簡単な **ビジュアルエディター** を推奨しています。

ビジュアルエディターでは対応できない画面の場合に、 **コードエディター** を使用するのがおすすめです。

詳しい使い分けについては、 [画面作成機能の使い分け](/faq/screen_creation_features_comparison/) をご覧ください。

## ビューでできること [](#ビューでできること)

ビューはベースマキナの他の機能とも連携が可能です。

- アクションの実行
- 画面移動（アクション、ビュー、外部URL）
- 別の画面から移動してきた際のクエリパラメーターの受け取り
- ログインユーザーの情報の利用（⚠️コードエディターのみ）

## ビューの一覧・作成・編集 [](#ビューの一覧作成編集)

### 一覧 [](#一覧)

ビューの一覧には、画面右上の下記のアイコンをクリックすることで移動できます。

![アイコン](/images/what_is_view/menubar_icon.png)

### 新規作成 [](#新規作成)

一覧画面右上のボタンから新規作成画面へ移動できます。
その際、ビジュアルエディターかコードエディターかを選択できます。

![ビューの新規作成](/images/what_is_view/create.png)

### 編集 [](#編集)

ビューの一覧の編集ボタンをクリックすると、作成済みのビューの編集画面に移動します。

![ビューの編集](/images/what_is_view/edit.png)

## ビューの利用 [](#ビューの利用)

ビューの一覧テーブルから使いたいビューの行をクリックすると利用画面に移動します。

[設定内容のダウンロード](/action/download_action_settings/) [ビジュアルエディター](/view/visual_editor/)
---
[ビュー](/view/)

コードエディター

# コードエディターとは

コードエディターとは、ReactとJavaScriptを使って完全にカスタマイズされた画面（ビュー）を作成できる機能です。
コードを書く必要はありますが、ベースマキナが用意した組み込みの関数やコンポーネントを利用できるため、フルスクラッチの画面開発よりも圧倒的に早く管理画面を構築できます。

より簡単に画面を作成したい場合は [ビジュアルエディター](/view/visual_editor/) の利用を推奨しています。
各機能の詳しい使い分けについては [画面作成機能の使い分け](/faq/screen_creation_features_comparison/) をご覧ください。

## コードエディターで使える機能 [](#コードエディターで使える機能)

コードエディターでは、ベースマキナの他の機能を呼び出す関数やReactのhook、さまざまな用途のReactコンポーネントを利用できます。

- アクションの呼び出し
- ログイン・権限情報の利用
- 画面移動（アクション、ビュー、外部URL）
- 別の画面から移動してきた際のURLパラメーターの受け取り
- 組み込みのReactコンポーネント
- [chakra (opens in a new tab)](https://v2.chakra-ui.com/) のコンポーネント

## コードエディターでのビュー作成方法 [](#コードエディターでのビュー作成方法)

コードエディターを使ってベースマキナの画面上でビューを作成する方法を説明します。

まず、ビューの一覧・作成画面には画面右上の下記のアイコンをクリックすることで移動できます。

![アイコン](/images/what_is_view/menubar_icon.png)

「ビューの一覧」画面から、「ビジュアルエディターで作成」ボタン右側の矢印をクリックし、メニューから「コードエディターで作成」を選択して作成画面へ移動します。

![コードエディターで作成](/images/code_editor/create_with_code_editor.png)

コードエディターでは、通常のWebフロントエンド開発のように、JavaScriptを利用してビューを作成できます。

Reactコンポーネントとして宣言して、 `default export` されたものが画面に表示されます。

ビューを作成するには、次の情報を入力する必要があります。

- 名前
- 識別子
- コード（JavaScript）

識別子は画面移動時に移動先のビューを特定する際などに使います。

また、フォームでJavaScriptを入力すると画面右側にプレビューが表示されます。

![アイコン](/images/what_is_view/form.png)

コードエディターで作成するビューのコードは次のようなイメージです。

`React` のコードを呼び出して利用したり、 `@basemachina/view` というベースマキナ製のパッケージをインポートして利用できます。

また、前述の通りアクションの呼び出しなども関数経由で実行できます。

```
import { useState } from "react";
import {
  Flexbox,
  Card,
  Chart,
  Form,
  Image,
  DatePicker,
  useExecuteAction,
  useURLQueries,
  ...
} from "@basemachina/view";
 
const BMBankView = () => {
  const urlQueries = useURLQueries()
  const userId = urlQueries["userId"]
  const [deactivate, { errors }] = useExecuteAction("deactivate-action-id")
  const handleDeactivateButtonClick = () => {
    deactive([{
        name: "userId",
        value: userId
    }])
  }
 
  return (
    <Flexbox width="full" direction="col">
      <Flexbox direction="row" width="full" items="center" justify="between">
        <Heading text={`財前　五郎 (userID: ${userId})`} size="xl" />
        <Grid gap={2}>
          <Button title="無効化する" color="red" onClick={handleDeactivateButtonClick} />
        </Grid>
      </Flexbox>
      <Flexbox direction="row" width="full">
        <Box flex={1}>
          <Card>
            ...
          </Card>
        </Box>
        ...
      </Flexbox>
    </Flexbox>
  );
};
export default BMBankView;
```

[クエリパラメーター設定](/view/visual_editor/query_parameter_setting/) [Card](/view/code_editor/layout/view_card/)
---
[ビュー](/view/)

[コードエディター](/view/code_editor/)

データ表示

Chart

# Chart

`Chart` コンポーネントは、チャートを表示するためのコンポーネントです。現状では折れ線グラフのみをサポートしており、複数のデータセットを表示できます。

## 基本的な使い方 [](#基本的な使い方)

```
<Chart
  title="年度別売上と利益"
  xAxis="year"
  dataSetColors={{
    sales: "blue",
    profit: "green",
  }}
  dataSet={[
    { year: "2020", sales: 1000, profit: 200 },
    { year: "2021", sales: 1500, profit: 300 },
    { year: "2022", sales: 1300, profit: 250 },
    { year: "2023", sales: 1700, profit: 350 },
  ]}
/>
```

![使用例](/images/view/chart/usage.png)

## 詳細なインターフェース [](#詳細なインターフェース)

| 名前 | 説明 | 必須・任意 | デフォルト値 |
| --- | --- | --- | --- |
| title | チャートのタイトルを指定します。 | 任意 | なし |
| type | チャートの種類を指定します。現在は'line'のみをサポートしています。 | 任意 | 'line' |
| xAxis | データセット内でX軸に対応するキーを指定します。 | 必須 | なし |
| xAxisTitle | X軸のタイトルを指定します。 | 任意 | なし |
| yAxisTitle | Y軸のタイトルを指定します。 | 任意 | なし |
| dataSetColors | データセットのカラーを指定します。キーはデータセット内のキー、値は'ChartColor'型で指定します。 'red', 'blue', 'green', 'yellow'から選択できます。 | 任意 | なし |
| dataSet | データセットを指定します。 | 必須 | なし |

[Stat](/view/code_editor/data_display/view_stat/) [フォーム](/view/code_editor/form/)
---
[ビュー](/view/)

[コードエディター](/view/code_editor/)

データ表示

DescriptionList

# DescriptionList

`DescriptionList` コンポーネントは、キーと値のペアをリスト形式で表示するためのコンポーネントです。表示形式は水平または垂直を選択できます。

## 基本的な使い方 [](#基本的な使い方)

```
<DescriptionList
  columnNames={{ name: "名前", age: "年齢", job: "職業" }}
  item={{
    name: "山田太郎",
    age: 25,
    job: "エンジニア",
  }}
  direction="horizontal"
/>
```

![使用例](/images/view/description_list/usage.png)

![使用例\_垂直](/images/view/description_list/usage_vertical.png)

## 詳細なインターフェース [](#詳細なインターフェース)

| 名前 | 説明 | デフォルト値 |
| --- | --- | --- |
| columnNames | 各列の表示名を指定します。オブジェクト形式で指定します。表示名を指定していない列は非表示となります。 | なし |
| item | 表示する項目のオブジェクトを指定します。キーと値のペアで構成されます。 | なし |
| direction | リストの表示方向を指定します。'horizontal' または 'vertical' のいずれかを指定できます。 | 'horizontal' |

`direction` プロパティでリストの表示方向を指定します。'horizontal' を指定すると、項目名とその詳細が水平方向に並びます。一方、'vertical' を指定すると、項目名とその詳細が垂直方向に並びます。指定がない場合、デフォルトで 'horizontal' が適用されます。

[Table](/view/code_editor/data_display/view_table/) [Stat](/view/code_editor/data_display/view_stat/)
---
[ビュー](/view/)

[コードエディター](/view/code_editor/)

データ表示

Stat

# Stat

`Stat` コンポーネントは、ある項目とその値を表示するためのコンポーネントです。主にダッシュボードや統計情報の表示に使用できます。

## 基本的な使い方 [](#基本的な使い方)

```
<Stat title="アクティブユーザー" value="1,234" />
```

![使用例](/images/view/stat/usage.png)

## 詳細なインターフェース [](#詳細なインターフェース)

| 名前 | 説明 | 必須・任意 | デフォルト値 |
| --- | --- | --- | --- |
| title | 表示する項目の名前を指定します。 | 必須 | なし |
| value | 表示する項目の値を指定します。 | 必須 | なし |

[DescriptionList](/view/code_editor/data_display/view_description_list/) [Chart](/view/code_editor/data_display/view_chart/)
---
[ビュー](/view/)

[コードエディター](/view/code_editor/)

データ表示

Table

# Table

Tableコンポーネントは、データを表形式で表示するためのコンポーネントです。各行のデータ、各列の設定、そしてメニューバーの設定ができます。

表示できる行数には上限があります。デフォルトでは2000件まで表示され、それ以上の場合はテーブルの代わりに「表示件数が2000件を超えています。検索して絞り込んでください」というメッセージのみが表示されます。上限は `maxRows` プロパティで変更できます。

## 基本的な使い方 [](#基本的な使い方)

```
const rows = [
  { name: "山田太郎", age: 25, job: "エンジニア" },
  { name: "佐藤花子", age: 30, job: "デザイナー" },
  { name: "鈴木一郎", age: 18, job: "エンジニア" },
  { name: "田中二郎", age: 35, job: "プロジェクトマネージャー" },
  { name: "井上三郎", age: 45, job: "エンジニア" },
];
return (
  <Table
    rows={rows}
    onRowClick={(row, event) => console.log(row, event.ctrlKey)}
    rowDisabled={(row) => row.age > 40}
    rowColor={(row) => (row.age < 20 ? "green" : "white")}
    columnNames={{ name: "名前", age: "年齢", job: "職業" }}
    downloadable={true}
    downloadData={rows.map((user) => ({ 名前: user.name, 年齢: user.age }))}
  />
);
```

![使用例](/images/view/table/usage.png)

## 詳細なインターフェース [](#詳細なインターフェース)

| 名前 | 説明 | デフォルト値 |
| --- | --- | --- |
| rows | 表示する行データの配列を指定します。 | なし |
| onRowClick | 行をクリックしたときのイベントハンドラを指定します。行のデータと、 [MouseEvent (opens in a new tab)](https://react.dev/reference/react-dom/components/common#mouseevent-handler) が引数として渡されます。 | なし |
| rowDisabled | 行が無効かどうかを判定する関数を指定します。無効と判定された行はグレーアウトされ、クリック不可となります。関数には、行のデータが引数として渡されます。 | なし |
| rowColor | 行の色を設定する関数を指定します。関数の返り値は `white`, `gray`, `red`, `green`, `blue`, `yellow` のいずれかです。 | なし |
| columnNames | 各列の表示名を指定します。オブジェクト形式で指定します。表示名を指定していない列は非表示となります。 | なし |
| downloadable | ダウンロード可能かどうかを指定します。trueを指定すると、メニューバーにダウンロードボタンが表示されます。 | false |
| downloadData | JSONやCSVとしてダウンロード可能にしたいデータを指定します。表示する行データとは異なる形式を使用したい場合に設定します。 | rowsプロパティに設定した値 |
| csvDownloadOption | CSVダウンロード時のオプションを指定します。 `{ initialValue: { withBOM: true, withHeader: true, alwaysQuoteStrings: false }, hideOption: true }` のように指定します。 `initialValue`: 「BOM を付与する」・「ヘッダを含める」・「文字列の値を常にダブルクォーテーションで囲む」オプションの初期値を指定します。それぞれ、 `withBOM` ・ `withHeader` ・ `alwaysQuoteStrings` プロパティで指定します。 `hideOption`: `true` を指定すると、上記オプションを画面上から変更不可にできます。 | なし |
| searchDisabled | 検索可能かどうかを指定します。trueを指定すると、メニューバーの検索フォームが非表示になります。ただし、表示する行数が `maxRows` を超える場合は、searchDisabledの設定に関わらず検索フォームが表示されます。 | false |
| maxRows | テーブルに表示する最大行数を指定します。 `rows` の件数がこの値を超えるとテーブルは表示されず、件数超過のメッセージのみが表示されます。 | 2000 |
| wordBreak | テーブルの幅に対してセルの内容が長すぎた場合の、折り返し方法を指定します。 `normal`, `words`, `all`, `keep` のいずれかを指定可能です。 | keep |

`rows` はオブジェクトの配列で、各オブジェクトが1つの行を表します。また、 `columnNames` は各列の表示名を指定するためのオブジェクトで、キーが列のID（オブジェクトのキー）、値がその列の表示名です。

このコンポーネントには、行がクリックされたときに呼び出されるonRowClick関数も提供されています。この関数は、クリックされた行のデータを引数として受け取ります。

また、 `downloadable` プロパティをtrueに設定すると、表データをダウンロードするためのボタンが表示されます。

[Drawer](/view/code_editor/layout/view_drawer/) [DescriptionList](/view/code_editor/data_display/view_description_list/)
---
[ビュー](/view/)

[コードエディター](/view/code_editor/)

型定義ファイルのダウンロード

# `@basemachina/view` の型定義ファイルのダウンロード

コードエディターで使用できる `@basemachina/view` の型定義ファイルはダウンロードが可能です。

[コード取得設定](/view/code_editor/git_management/) 機能などを利用して、手元のエディターでビューのコードを編集する場合などにご活用ください。

※一部型が未定義の関数/コンポーネントに関しましては、今後型定義を追加する予定です。

**※この機能は将来、別の機能による代替または廃止になる可能性があります。**

![「コードエディターの型定義ファイルのダウンロード」ボタン](/images/download_view_dts_file.png)

## ダウンロード方法 [](#ダウンロード方法)

以下の手順でダウンロードできます。

1. 右上のメニューから「設定」を選択します。
1. サイドバーのメニューから「開発設定」を選択します。
1. 「コードエディターの型定義ファイルのダウンロード」ボタンをクリックすると、ダウンロードできます。

[Git管理](/view/code_editor/git_management/) [バージョン/有効化設定](/view/versions/)
---
[ビュー](/view/)

[コードエディター](/view/code_editor/)

外部ライブラリ

# 外部ライブラリ

## 利用可能な外部ライブラリ一覧 [](#利用可能な外部ライブラリ一覧)

コードエディターでは、下記の外部ライブラリをインポートして使用できます。

| 名前 | URL |
| --- | --- |
| react | [https://www.npmjs.com/package/react (opens in a new tab)](https://www.npmjs.com/package/react) |
| dayjs | [https://www.npmjs.com/package/dayjs (opens in a new tab)](https://www.npmjs.com/package/dayjs) |
| @chakra-ui/react | [https://www.npmjs.com/package/@chakra-ui/react (opens in a new tab)](https://www.npmjs.com/package/@chakra-ui/react) |
| react-chartjs-2 | [https://www.npmjs.com/package/react-chartjs-2 (opens in a new tab)](https://www.npmjs.com/package/react-chartjs-2) |

## dayjs [](#dayjs)

dayjsは日付操作の関数を提供するライブラリです。

### dayjs の使用例 [](#dayjs-の使用例)

```
import { useState } from "react";
import dayjs from "dayjs";
import { Button, Box, Card, VStack } from "@basemachina/view";
 
const date = dayjs().format("YYYY-MM-DD HH:mm:ss");
 
const App = () => {
  const [showDate, setShowDate] = useState(false);
  const handleClick = () => {
    setShowDate(true);
  };
 
  return (
    <Card>
      <VStack>
        <Box>{`日付: ${showDate ? date : ""}`}</Box>
        <Button title="日付を表示する" onClick={handleClick} />
      </VStack>
    </Card>
  );
};
 
export default App;
```

![dayjsの利用例](/images/view/external_libs/dayjs.png)

## @chakra-ui/react [](#chakra-uireact)

@chakra-ui/reactは、汎用的なコンポーネントやフックを提供するライブラリです。

@chakra-ui/reactは `'@chakra-ui/react'` と `'@chakra-ui/react@2'` からインポートできます。
`'@chakra-ui/react'` からのインポートでは現在Chakra UIのv2系を利用できますが、v3系へのメジャーバージョンアップにより互換性を失う可能性があります。
`'@chakra-ui/react@2'` からのインポートは@chakra-ui/reactのv2系に固定されます。

Chakra UI v2の使い方については [公式ドキュメント (opens in a new tab)](https://v2.chakra-ui.com/docs/components) をご参照ください。

### @chakra-ui/react の使用例 [](#chakra-uireact-の使用例)

```
import {
  Modal,
  ModalOverlay,
  ModalContent,
  ModalHeader,
  ModalFooter,
  ModalBody,
  ModalCloseButton,
  useDisclosure,
  Button,
} from "@chakra-ui/react";
 
function App() {
  const { isOpen, onOpen, onClose } = useDisclosure();
 
  return (
    <>
      <Button onClick={onOpen}>開く</Button>
      <Modal
        isCentered
        onClose={onClose}
        isOpen={isOpen}
        motionPreset="slideInBottom"
      >
        <ModalOverlay />
        <ModalContent>
          <ModalHeader>タイトル</ModalHeader>
          <ModalCloseButton />
          <ModalBody>内容</ModalBody>
          <ModalFooter>
            <Button colorScheme="blue" mr={3} onClick={onClose}>
              保存
            </Button>
            <Button variant="ghost">キャンセル</Button>
          </ModalFooter>
        </ModalContent>
      </Modal>
    </>
  );
}
 
export default App;
```

![chakra-uiの利用例](/images/view/external_libs/chakra-ui.png)

## react-chartjs-2 [](#react-chartjs-2)

react-chartjs-2は、グラフ表示のライブラリである [Chart.js (opens in a new tab)](https://www.chartjs.org/) をReactのコンポーネントとして提供するライブラリです。

react-chartjs-2は `'react-chartjs-2'` と `'react-chartjs-2@5'` からインポートできます。
`'react-chartjs-2'` からのインポートはreact-chartjs-2のメジャーバージョンアップにより互換性を失う可能性があります。
`'react-chartjs-2@5'` からのインポートはreact-chartjs-2のv5系に固定されます。

### react-chartjs-2 の使用例 [](#react-chartjs-2-の使用例)

```
import { Bar } from "react-chartjs-2";
 
export const options = {
  responsive: true,
  plugins: {
    legend: {
      position: "top",
    },
    title: {
      display: true,
      text: "新規登録数",
    },
  },
};
 
const labels = ["January", "February", "March", "April", "May", "June"];
 
export const data = {
  labels,
  datasets: [
    {
      label: "昨年",
      data: [100, 120, 150, 180, 230, 250],
      backgroundColor: "rgba(255, 99, 132, 0.5)",
    },
    {
      label: "今年",
      data: [100, 150, 130, 200, 300, 350],
      backgroundColor: "rgba(53, 162, 235, 0.5)",
    },
  ],
};
 
function App() {
  return <Bar options={options} data={data} />;
}
 
export default App;
```

![react-chartjs-2 の利用例](/images/view/external_libs/react-chartjs-2.png)

[PaginationPageText](/view/code_editor/other/view_pagination_page_text/) [Git管理](/view/code_editor/git_management/)
---
[ビュー](/view/)

[コードエディター](/view/code_editor/)

フォーム

# フォーム

ベースマキナには、フォームを作成するための組み込みのコンポーネントが用意されています。

状態は [Form](/view/code_editor/form/view_form/) コンポーネントによって管理されており、以下の入力コンポーネントを組み合わせて使うことで、少ないコード量でフォームを作成できます。

- [TextInput](/view/code_editor/form/view_text_input/)
- [Textarea](/view/code_editor/form/view_textarea/)
- [Input](/view/code_editor/form/view_input/)
- [Select](/view/code_editor/form/view_select/)
- [DatePicker](/view/code_editor/form/view_date_picker/)
- [DateTimePicker](/view/code_editor/form/view_date_time_picker/)
- [Checkbox](/view/code_editor/form/view_checkbox/)
- [FileInput](/view/code_editor/form/view_file_input/)
- [Button](/view/code_editor/form/view_button/)

また、外部ライブラリの [@chakra-ui/react](/view/code_editor/external_libs/#chakra-ui/react) を使ってもフォームを作成できます。
その場合、組み込みのFormコンポーネントによる状態管理は使えないため、「 [コード取得設定](/view/code_editor/git_management/#%E3%82%B3%E3%83%BC%E3%83%89%E5%8F%96%E5%BE%97%E8%A8%AD%E5%AE%9A) 」を活用して、react-hook-formなどの使い慣れたフォームの状態管理ライブラリを利用することもおすすめです。

## 基本的な使い方 [](#基本的な使い方)

以下は、Formコンポーネントと各種入力コンポーネントを組み合わせた基本的な使用例です。

```
import {
  DateTimePicker,
  Grid,
  Flexbox,
  Box,
  Form,
  TextInput,
  Button,
  executeAction,
} from "@basemachina/view";
 
const App = () => {
  const handleSubmit = ({ values }) => {
    executeAction("action-id", {
      id: values.id,
      email: values.email,
      registered_at_from: values.registered_at_from,
      registered_at_to: values.registered_at_to,
    });
  };
 
  return (
    <Form
      initialValues={{
        email: "sample@test.com",
        id: "sample",
        registered_at_from: "2020-04-01T10:00",
        registered_at_to: "2028-03-31T18:00",
      }}
      onSubmit={handleSubmit}
    >
      <Flexbox direction="col">
        <Grid repeatCount={3}>
          <Box>
            <TextInput name="id" label="ID" />
          </Box>
          <Box>
            <TextInput name="email" label="メールアドレス" />
          </Box>
          <Box>
            <p className="text-sm font-bold">登録日時</p>
            <Flexbox items="center" justify="between">
              <DateTimePicker name="registered_at_from" />
              <span>-</span>
              <DateTimePicker name="registered_at_to" />
            </Flexbox>
          </Box>
        </Grid>
        <Button type="submit" title="検索" color="blue" />
      </Flexbox>
    </Form>
  );
};
export default App;
```

![使用例](/images/view/form/usage.png)

- Formの `initialValues` propsで、フォームの初期値を設定できます。オブジェクトのプロパティ名は、各入力コンポーネントの `name` propsの値と一致している必要があります。
- Formの `onSubmit` propsで、フォームの送信時の処理を定義できます。第一引数の `values` プロパティに、フォームの入力値のオブジェクトが渡されるので、これを利用して送信処理を実行します。 `values` もオブジェクトであり、プロパティ名は各入力コンポーネントの `name` propsの値と一致しています。

入力コンポーネントの詳細な使い方については、各コンポーネントのページをご覧ください。

## `value`, `onChange` propsの使い方 [](#value-onchange-propsの使い方)

「特定のCheckboxの値が変化したときに別のTextInputの値を変更する」といったような複雑なユースケースを実現したい場合、入力コンポーネントに `value` と `onChange` propsを設定する必要があります。

```
import { Form, Checkbox, TextInput, Button, Flexbox } from "@basemachina/view";
import { useState } from "react";
 
const App = () => {
  const [email, setEmail] = useState("customer@basemachina.com");
 
  return (
    <Form onSubmit={console.log}>
      <Flexbox direction="col">
        <Checkbox
          name="isActive"
          label="有効化する"
          onChange={(e) => setEmail("")}
        />
        <TextInput
          name="email"
          label="メールアドレス"
          value={email}
          onChange={(e) => setEmail(e.target.value)}
        />
        <Button type="submit" title="送信" color="blue" />
      </Flexbox>
    </Form>
  );
};
export default App;
```

![value, onChange propsの使用例](/images/view/form/value_onchange.png)

この例では、TextInputの値を `useState` で管理し、Checkboxが変更されたときにTextInputの値を空にしています。

### 注意点 [](#注意点)

`value` と `onChange` propsを設定している場合でも、Formの `onSubmit` propsでは現在のフォームの状態のオブジェクトが渡されます。
ただし、入力コンポーネントに `value` で渡している値と、Formの `onSubmit` propsで受け取れる値が一致しないこともあります。
上記の例では、画面が表示されたあと、メールアドレスを変更せずにそのまま送信ボタンを押した場合、Formの `onSubmit` propsに渡される引数からは `email` の値を取得できません。
この問題は次のいずれかの方法で回避できます。

- Formの `initialValues` の `email` プロパティに `useState` の引数と同じ値（ここでは `"customer@basemachina.com"` ）を設定する
- Formの `onSubmit` propsで引数を利用せず、 `useState` で管理している値（ここでは `email` ）を直接利用する

[Chart](/view/code_editor/data_display/view_chart/) [Form](/view/code_editor/form/view_form/)
---
[ビュー](/view/)

[コードエディター](/view/code_editor/)

[フォーム](/view/code_editor/form/)

Button

# Button

Buttonコンポーネントは、ユーザーがクリックすることで指定された操作するためのコンポーネントです。色、サイズ、形式（ボタン、送信）をカスタマイズが可能です。

## 基本的な使い方 [](#基本的な使い方)

```
import { Card, Form, Flexbox, Button } from "@basemachina/view";
 
const App = () => {
  return (
    <Card>
      <Form
        onSubmit={() => {
          console.log("clicked");
        }}
      >
        <Flexbox direction="col">
          <Button type="submit" title="送信" color="blue" />
        </Flexbox>
      </Form>
    </Card>
  );
};
export default App;
```

![使用例](/images/view/button/usage.png)

## 詳細なインターフェース [](#詳細なインターフェース)

| 名前 | 説明 | 必須・任意 | デフォルト値 |
| --- | --- | --- | --- |
| title | ボタンのテキストを指定します。 | 必須 | なし |
| color | ボタンの色を指定します。 `blue` 、 `red` 、 `white` の中から選択可能です。 | 任意 | `white` |
| size | ボタンのサイズを指定します。 `xs` 、 `sm` 、 `md` 、 `lg` 、 `xl` の中から選択可能です。 | 任意 | `md` |
| disabled | ボタンが無効化されているかどうかを指定します。 `true` の場合、ボタンはクリックできません。 | 任意 | `false` |
| type | ボタンのタイプを指定します。 `button` または `submit` を選択可能です。 | 任意 | `button` |
| onClick | ボタンがクリックされたときに実行する関数を指定します。 | 任意 | なし |

[Form](/view/code_editor/form/view_form/) [TextInput](/view/code_editor/form/view_text_input/)
---
[ビュー](/view/)

[コードエディター](/view/code_editor/)

[フォーム](/view/code_editor/form/)

Checkbox

# Checkbox

Checkboxコンポーネントは、チェックボックスの入力に使うコンポーネントです。

## 基本的な使い方 [](#基本的な使い方)

「 [フォーム#基本的な使い方](/view/code_editor/form/#%E5%9F%BA%E6%9C%AC%E7%9A%84%E3%81%AA%E4%BD%BF%E3%81%84%E6%96%B9) 」にあるように、Formコンポーネントの `initialValues` propsを使ってCheckboxの初期値を設定できます。
初期値には真偽値か、Checkboxの `value` の配列を指定します。

### 単一のCheckboxの場合 [](#単一のcheckboxの場合)

単一のCheckboxの場合、 `initialValues` に真偽値を指定します。 `true` の場合、チェックボックスは選択された状態になり、 `false` の場合は選択されていない状態になります。
`initialValues` を指定しなければ `false` 扱いになります。

```
import { Card, Form, Flexbox, Checkbox, Button } from "@basemachina/view";
 
const App = () => {
  return (
    <Card>
      <Form onSubmit={() => {}} initialValues={{ isActive: true }}>
        <Flexbox direction="col">
          <Checkbox name="isActive" label="有効化する" />
          <Button type="submit" title="送信" color="blue" />
        </Flexbox>
      </Form>
    </Card>
  );
};
export default App;
```

![使用例](/images/view/checkbox/usage.png)

Formの `onSubmit` propsで受け取れる値も真偽値になります。

### 複数のCheckboxの場合 [](#複数のcheckboxの場合)

また、複数のCheckboxの場合はCheckboxの `value` の配列を `initialValues` に指定します。空配列を指定すると、すべてのCheckboxが選択されていない状態になります。

```
import { Form, Checkbox, Flexbox, Card, Button } from "@basemachina/view";
 
const App = () => {
  return (
    <Card>
      <Form onSubmit={() => {}} initialValues={{ fruits: ["apple", "orange"] }}>
        <Flexbox direction="col">
          <Flexbox>
            <Checkbox name="fruits" label="りんご" value="apple" />
            <Checkbox name="fruits" label="バナナ" value="banana" />
            <Checkbox name="fruits" label="オレンジ" value="orange" />
          </Flexbox>
          <Button type="submit" title="送信" color="blue" />
        </Flexbox>
      </Form>
    </Card>
  );
};
 
export default App;
```

![初期値を配列で指定した場合の使用例](/images/view/checkbox/usage_array_initial_value.png)

この例では、 `value` として `"apple"` と `"orange"` を持つCheckboxが選択された状態になります。

Formの `onSubmit` propsで受け取れる値も `value` の配列になります。

## 詳細なインターフェース [](#詳細なインターフェース)

| 名前 | 説明 | 必須・任意 | デフォルト値 |
| --- | --- | --- | --- |
| name | フィールドの名前を指定します。 | 必須 | なし |
| label | チェックボックスのラベルを指定します。 | 任意 | なし |
| value | チェックボックスが選択されたときの値を指定します。 | 任意 | なし |
| disabled | チェックボックスが無効化されているかどうかを指定します。 `true` の場合、チェックボックスはクリックできません。 | 任意 | `false` |
| checked | チェックボックスが選択されているかどうかを指定します。 | 任意 | `false` |
| onChange | チェックボックスの選択状態が変更されたときに呼び出される関数を指定します。引数として [Reactイベントオブジェクト (opens in a new tab)](https://ja.react.dev/reference/react-dom/components/common#react-event-object) が渡されます。 | 任意 | なし |

### `value`, `onChange`, `checked` propsの使い方 [](#value-onchange-checked-propsの使い方)

`value` を使う場合は「 [フォーム#value, onChange propsの使い方](/view/code_editor/form/#value-onchange-props%E3%81%AE%E4%BD%BF%E3%81%84%E6%96%B9) 」をご覧ください。

また、Checkboxは他の入力コンポーネントにはない `checked` propsを持っています。 `checked` を使う場合は真偽値を `useState` 等で状態管理してください。

```
import { useState } from "react";
import { Checkbox, Form } from "@basemachina/view";
 
const App = () => {
  const [checked, setChecked] = useState(false);
  return (
    <Form>
      <Checkbox
        name="isActive"
        label="有効化する"
        checked={checked}
        onChange={(e) => setChecked(e.target.checked)}
      />
    </Form>
  );
};
export default App;
```

[DateTimePicker](/view/code_editor/form/view_date_time_picker/) [FileInput](/view/code_editor/form/view_file_input/)
---
[ビュー](/view/)

[コードエディター](/view/code_editor/)

[フォーム](/view/code_editor/form/)

DatePicker

# DatePicker

DatePickerコンポーネントは、日付を入力するためのコンポーネントです。

## 基本的な使い方 [](#基本的な使い方)

```
import { Card, Form, Flexbox, DatePicker, Button } from "@basemachina/view";
 
const App = () => {
  return (
    <Card>
      <Form onSubmit={() => {}}>
        <Flexbox direction="col">
          <DatePicker name="date" label="日付" />
          <Button type="submit" title="送信" color="blue" />
        </Flexbox>
      </Form>
    </Card>
  );
};
export default App;
```

![使用例](/images/view/datepicker/usage.png)

## 詳細なインターフェース [](#詳細なインターフェース)

| 名前 | 説明 | 必須・任意 | デフォルト値 |
| --- | --- | --- | --- |
| name | フィールドの名前を指定します。 | 必須 | なし |
| label | ラベルを指定します。 | 任意 | なし |
| value | 日付値を指定します。形式は `"2006-01-02"` のような文字列です。 | 任意 | なし |
| defaultValue（非推奨） | デフォルトの日付値を指定します。 `value` を指定した場合は無視されます。 | 任意 | なし |
| format | 日付のフォーマットを指定します。 | 任意 | 'YYYY-MM-DD' |
| required | 入力が必須かどうかを指定します。 `true` の場合、入力が必須になり、ラベルに赤い `*` が表示されます。 | 任意 | `false` |
| max | 日時の最大値を指定します。形式は `"2006-01-02"` のような文字列です。 | 任意 | なし |
| min | 日時の最小値を指定します。形式は `"2006-01-02"` のような文字列です。 | 任意 | なし |
| onChange | 入力内容の変更を検知するイベントハンドラー関数を指定します。第一引数に `format` propsの形式にフォーマットされた文字列が、第二引数に `"2006-01-02"` の形式の文字列が渡されます。 | 任意 | なし |

### `value`, `onChange` propsの使い方 [](#value-onchange-propsの使い方)

「 [フォーム#value, onChange propsの使い方](/view/code_editor/form/#value-onchange-props%E3%81%AE%E4%BD%BF%E3%81%84%E6%96%B9) 」をご覧ください。

[Select](/view/code_editor/form/view_select/) [DateTimePicker](/view/code_editor/form/view_date_time_picker/)
---
[ビュー](/view/)

[コードエディター](/view/code_editor/)

[フォーム](/view/code_editor/form/)

DateTimePicker

# DateTimePicker

DateTimePickerコンポーネントは、日時を入力するためのコンポーネントです。

## 基本的な使い方 [](#基本的な使い方)

```
import { Card, Form, Flexbox, DateTimePicker, Button } from "@basemachina/view";
 
const App = () => {
  return (
    <Card>
      <Form onSubmit={() => {}}>
        <Flexbox direction="col">
          <DateTimePicker name="datetime" label="日時" />
          <Button type="submit" title="送信" color="blue" />
        </Flexbox>
      </Form>
    </Card>
  );
};
export default App;
```

![使用例](/images/view/datetimepicker/usage.png)

## 詳細なインターフェース [](#詳細なインターフェース)

| 名前 | 説明 | 必須・任意 | デフォルト値 |
| --- | --- | --- | --- |
| name | フィールドの名前を指定します。 | 必須 | なし |
| label | ラベルを指定します。 | 任意 | なし |
| value | 日時値を指定します。形式は `"2006-01-02T15:04"` のような文字列です。 | 任意 | なし |
| defaultValue（非推奨） | デフォルトの日時値を指定します。 `value` を指定した場合は無視されます。 | 任意 | なし |
| format | 日時のフォーマットを指定します。 | 任意 | 'YYYY-MM-DDTHH:mm' |
| required | 入力が必須かどうかを指定します。 `true` の場合、入力が必須になり、ラベルに赤い `*` が表示されます。 | 任意 | `false` |
| max | 日時の最大値を指定します。形式は `"2006-01-02T15:04"` のような文字列です。 | 任意 | なし |
| min | 日時の最小値を指定します。形式は `"2006-01-02T15:04"` のような文字列です。 | 任意 | なし |
| onChange | 入力内容の変更を検知するイベントハンドラー関数を指定します。第一引数に `format` propsの形式にフォーマットされた文字列が、第二引数に `"2006-01-02T15:04"` の形式の文字列が渡されます。 | 任意 | なし |

### `value`, `onChange` propsの使い方 [](#value-onchange-propsの使い方)

「 [フォーム#value, onChange propsの使い方](/view/code_editor/form/#value-onchange-props%E3%81%AE%E4%BD%BF%E3%81%84%E6%96%B9) 」をご覧ください。

[DatePicker](/view/code_editor/form/view_date_picker/) [Checkbox](/view/code_editor/form/view_checkbox/)
---
[ビュー](/view/)

[コードエディター](/view/code_editor/)

[フォーム](/view/code_editor/form/)

FileInput

# FileInput

FileInputコンポーネントは、フォームでファイルを入力するためのコンポーネントです。

## 基本的な使い方 [](#基本的な使い方)

FileInputコンポーネントは、Formコンポーネント内で使用します。
入力したファイルは、 `useExecuteActionLazy` でアクションを呼び出してサーバーへの送信やストレージへの保存ができます。

初期値はFormコンポーネントの `initialValues` で `File` か `string` が設定できます。

```
import {
  Form,
  Button,
  FileInput,
  useExecuteAction,
  useExecuteActionLazy,
  LoadingIndicator,
} from "@basemachina/view";
 
const App = () => {
  const { data, loading } = useExecuteAction("get-user", { id: 123 });
  const [updateUserIcon] = useExecuteActionLazy("update-user-icon");
  const [uploadUserIcon] = useExecuteActionLazy("upload-user-icon");
 
  if (loading) return <LoadingIndicator />;
 
  const user = data.results[0].success;
 
  const handleSubmit = async ({ values }) => {
    // ファイルをストレージにアップロード
    const { data } = await uploadUserIcon({ id: user.id, icon: values.icon });
    // アップロードしたファイルのURLをDBに保存
    await updateUserIcon({
      id: user.id,
      icon: data.results[0].success,
    });
  };
 
  return (
    <Form initialValues={{ icon: user.icon }} onSubmit={handleSubmit}>
      <FileInput name="icon" label="アイコン" />
      <Button type="submit" title="保存" />
    </Form>
  );
};
 
export default App;
```

![使用例](/images/view/fileinput/usage.png)

## 詳細なインターフェース [](#詳細なインターフェース)

| 名前 | 説明 | デフォルト値 |
| --- | --- | --- |
| name | フィールドの名前を指定します。 | 必須 |
| label | ラベルを指定します。 | なし |
| disabled | フィールドを無効にするかどうかを指定します。 | false |
| maxHeight | ファイルのプレビューの高さの最大値を指定します。'xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl', 'full' のいずれかを指定できます。 | 'md' |
| onChange | ファイルが選択・削除されたときに呼び出される関数を指定します。引数として、選択したファイル（ [File (opens in a new tab)](https://developer.mozilla.org/ja/docs/Web/API/File) インスタンス）か、削除の場合は `undefined` が渡されます。 | なし |

セキュリティの都合上、FileInputには `value` を設定できません。

### `onChange` の使い方 [](#onchangeの使い方)

[フォーム#value, onChange propsの使い方](/view/code_editor/form/#value-onchange-props%E3%81%AE%E4%BD%BF%E3%81%84%E6%96%B9) をご覧ください。

[Checkbox](/view/code_editor/form/view_checkbox/) [Input](/view/code_editor/form/view_input/)
---
[ビュー](/view/)

[コードエディター](/view/code_editor/)

[フォーム](/view/code_editor/form/)

Form

# Form

Formコンポーネントは、状態を持つフォームを作成するためのコンポーネントです。
Formコンポーネントと一緒に [TextInput](/view/code_editor/form/view_text_input/) などの入力コンポーネントを組み合わせて使うことで、少ないコード量でフォームを作成できます。
使用例はフォームの「 [基本的な使い方](/view/code_editor/form/#%E5%9F%BA%E6%9C%AC%E7%9A%84%E3%81%AA%E4%BD%BF%E3%81%84%E6%96%B9) 」をご覧いただくこととし、このページでは詳細なインターフェースを紹介します。

## 詳細なインターフェース [](#詳細なインターフェース)

| 名前 | 説明 | デフォルト値 |
| --- | --- | --- |
| id | フォームのIDを指定します。 | なし |
| initialValues | フォームの初期値をオブジェクトとして指定します。プロパティ名は、各入力コンポーネントの `name` propsの値と一致している必要があります。 |  |
| onSubmit | フォームが送信されたときに呼び出される関数を指定します。第一引数に、 `values` プロパティを持ったオブジェクトが渡されます。この `values` もオブジェクトであり、プロパティ名は各入力コンポーネントの `name` propsの値と一致しています。 | 必須 |

[フォーム](/view/code_editor/form/) [Button](/view/code_editor/form/view_button/)
---
[ビュー](/view/)

[コードエディター](/view/code_editor/)

[フォーム](/view/code_editor/form/)

Input

# Input

Inputコンポーネントは、入力フィールドを作成するためのコンポーネントです。テキスト、URL、Eメール、パスワード、数値に対応しています。

## 基本的な使い方 [](#基本的な使い方)

```
import { Flexbox, Box, Form, Button, Input } from "@basemachina/view";
 
const App = () => {
  const handleSubmit = ({ values }) => {
    console.log(values);
  };
 
  return (
    <Form
      initialValues={{
        id: "user123",
        email: "user123@example.com",
        initialPoint: "50",
      }}
      onSubmit={handleSubmit}
    >
      <Flexbox direction="col">
        <Box>
          <Input
            label="ユーザーID"
            type="text"
            name="id"
            required
            minLength="5"
            maxLength="10"
            pattern="\w+"
          />
        </Box>
        <Box>
          <Input label="メールアドレス" type="email" name="email" required />
        </Box>
        <Box>
          <Input
            label="初期ポイント"
            type="number"
            name="initialPoint"
            min="0"
            max="100"
          />
        </Box>
        <Button type="submit" title="登録" color="blue" />
      </Flexbox>
    </Form>
  );
};
 
export default App;
```

![使用例](/images/view/input/usage.png)

## 詳細なインターフェース [](#詳細なインターフェース)

| 名前 | 説明 | 必須・任意 | デフォルト値 |
| --- | --- | --- | --- |
| name | 入力フィールドの名前を指定します。 | 必須 | なし |
| label | 入力フィールドのラベルを指定します。 | 任意 | なし |
| value | 入力値を指定します。 | 任意 | なし |
| type | 入力フィールドの種類を指定します。 `text` 、 `url` 、 `email` 、 `password` 、 `number` のいずれかを指定します。 | 任意 | `text` |
| required | 入力が必須かどうかを指定します。 `true` の場合、入力が必須になり、ラベルに赤い `*` が表示されます。 | 任意 | `false` |
| onChange | 入力内容の変更を検知するイベントハンドラー関数を指定します。引数として [Reactイベントオブジェクト (opens in a new tab)](https://ja.react.dev/reference/react-dom/components/common#react-event-object) が渡されます。 | 任意 | なし |

`type` が `text` 、 `url` 、 `email` 、 `password` の場合、さらに以下のプロパティを指定できます。

| 名前 | 説明 | 必須・任意 | デフォルト値 |
| --- | --- | --- | --- |
| maxLength | 入力可能な最大文字数を指定します。 | 任意 | なし |
| minLength | 入力が必要な最小文字数を指定します。 | 任意 | なし |
| pattern | 入力値が一致する必要のある正規表現のパターンを指定します。 | 任意 | なし |

プロパティの詳細な仕様については以下のドキュメントを参照してください。

- [<input type="text"> | MDN (opens in a new tab)](https://developer.mozilla.org/ja/docs/Web/HTML/Element/input/text#%E8%BF%BD%E5%8A%A0%E3%81%AE%E5%B1%9E%E6%80%A7)
- [<input type="url"> | MDN (opens in a new tab)](https://developer.mozilla.org/ja/docs/Web/HTML/Element/input/url#%E8%BF%BD%E5%8A%A0%E3%81%AE%E5%B1%9E%E6%80%A7)
- [<input type="email"> | MDN (opens in a new tab)](https://developer.mozilla.org/ja/docs/Web/HTML/Element/input/email#%E8%BF%BD%E5%8A%A0%E3%81%AE%E5%B1%9E%E6%80%A7)
- [<input type="password"> | MDN (opens in a new tab)](https://developer.mozilla.org/ja/docs/Web/HTML/Element/input/password#%E8%BF%BD%E5%8A%A0%E3%81%AE%E5%B1%9E%E6%80%A7)

`type` が `number` の場合、さらに以下のプロパティを指定できます。

| 名前 | 説明 | 必須・任意 | デフォルト値 |
| --- | --- | --- | --- |
| max | 入力の最大値を指定します。 | 任意 | なし |
| min | 入力の最小値を指定します。 | 任意 | なし |

プロパティの詳細な仕様については以下のドキュメントを参照してください。

- [<input type="number"> | MDN (opens in a new tab)](https://developer.mozilla.org/ja/docs/Web/HTML/Element/input/number#%E8%BF%BD%E5%8A%A0%E3%81%AE%E5%B1%9E%E6%80%A7)

### `value`, `onChange` propsの使い方 [](#value-onchange-propsの使い方)

「 [フォーム#value, onChange propsの使い方](/view/code_editor/form/#value-onchange-props%E3%81%AE%E4%BD%BF%E3%81%84%E6%96%B9) 」をご覧ください。

[FileInput](/view/code_editor/form/view_file_input/) [Link](/view/code_editor/link/view_link/)
---
[ビュー](/view/)

[コードエディター](/view/code_editor/)

[フォーム](/view/code_editor/form/)

Select

# Select

Selectコンポーネントは、セレクトボックス（ドロップダウンリスト）を作成するためのコンポーネントです。

## 基本的な使い方 [](#基本的な使い方)

```
import { Card, Form, Flexbox, Select, Button } from "@basemachina/view";
 
const App = () => {
  const options = [
    { label: "オプション1", value: "1" },
    { label: "オプション2", value: "2" },
    { label: "オプション3", value: "3" },
  ];
 
  return (
    <Card>
      <Form onSubmit={() => {}}>
        <Flexbox direction="col">
          <Select name="choice" label="選択" options={options} />
          <Button type="submit" title="送信" color="blue" />
        </Flexbox>
      </Form>
    </Card>
  );
};
export default App;
```

![使用例](/images/view/select/usage.png)

## 詳細なインターフェース [](#詳細なインターフェース)

| 名前 | 説明 | 必須・任意 | デフォルト値 |
| --- | --- | --- | --- |
| name | フィールドの名前を指定します。 | 必須 | なし |
| label | ラベルを指定します。 | 任意 | なし |
| value | 選択された値を指定します。 `options` の `value` のいずれかを指定します。 | 任意 | なし |
| options | 選択肢の配列を指定します。配列内の要素は `{label: '', value: ''}` の形式で指定してください。 | 必須 | なし |
| onChange | 入力内容の変更を検知するイベントハンドラー関数を指定します。引数として [Reactイベントオブジェクト (opens in a new tab)](https://ja.react.dev/reference/react-dom/components/common#react-event-object) が渡されます。 | 任意 | なし |

### `value`, `onChange` propsの使い方 [](#value-onchange-propsの使い方)

「 [フォーム#value, onChange propsの使い方](/view/code_editor/form/#value-onchange-props%E3%81%AE%E4%BD%BF%E3%81%84%E6%96%B9) 」をご覧ください。

[Textarea](/view/code_editor/form/view_textarea/) [DatePicker](/view/code_editor/form/view_date_picker/)
---
[ビュー](/view/)

[コードエディター](/view/code_editor/)

[フォーム](/view/code_editor/form/)

TextInput

# TextInput

TextInputコンポーネントは、テキスト入力フィールドを作成するためのコンポーネントです。

## 基本的な使い方 [](#基本的な使い方)

```
import { Card, Form, Flexbox, TextInput, Button } from "@basemachina/view";
 
const App = () => {
  return (
    <Card>
      <Form onSubmit={() => {}}>
        <Flexbox direction="col">
          <TextInput name="id" label="ID" />
          <Button type="submit" title="送信" color="blue" />
        </Flexbox>
      </Form>
    </Card>
  );
};
export default App;
```

![使用例](/images/view/textinput/usage.png)

## 詳細なインターフェース [](#詳細なインターフェース)

| 名前 | 説明 | 必須・任意 | デフォルト値 |
| --- | --- | --- | --- |
| name | フィールドの名前を指定します。 | 必須 | なし |
| label | ラベルを指定します。 | 任意 | なし |
| value | 入力値を指定します。 | 任意 | なし |
| placeholder | プレースホルダーを指定します。 | 任意 | なし |
| onChange | 入力内容の変更を検知するイベントハンドラー関数を指定します。引数として [Reactイベントオブジェクト (opens in a new tab)](https://ja.react.dev/reference/react-dom/components/common#react-event-object) が渡されます。 | 任意 | なし |

### `value`, `onChange` propsの使い方 [](#value-onchange-propsの使い方)

「 [フォーム#value, onChange propsの使い方](/view/code_editor/form/#value-onchange-props%E3%81%AE%E4%BD%BF%E3%81%84%E6%96%B9) 」をご覧ください。

[Button](/view/code_editor/form/view_button/) [Textarea](/view/code_editor/form/view_textarea/)
---
[ビュー](/view/)

[コードエディター](/view/code_editor/)

[フォーム](/view/code_editor/form/)

Textarea

# Textarea

Textareaコンポーネントは複数行のテキストを入力するためのコンポーネントです。

## 基本的な使い方 [](#基本的な使い方)

```
import { Form, Button, Textarea } from "@basemachina/view";
import { Stack } from "@chakra-ui/react";
 
const App = () => {
  const handleSubmit = ({ values }) => {
    console.log(values);
  };
 
  return (
    <Form
      initialValues={{
        comment: "よろしくお願いします。",
      }}
      onSubmit={handleSubmit}
    >
      <Stack>
        <Textarea
          label="コメント"
          name="comment"
          placeholder="例) よろしくお願いします。"
          rows={5}
          required
          maxLength={10}
          minLength={5}
        />
        <Button type="submit" title="登録" color="blue" />
      </Stack>
    </Form>
  );
};
 
export default App;
```

![使用例](/images/view/textarea/usage.png)

## 詳細なインターフェース [](#詳細なインターフェース)

| 名前 | 説明 | デフォルト値 |
| --- | --- | --- |
| name | 入力フィールドの名前を指定します。 | 必須 |
| label | 入力フィールドのラベルを指定します。 | 任意 |
| value | 入力値を指定します。 | 任意 |
| placeholder | 入力フィールドのプレースホルダーを指定します。 | 任意 |
| rows | 入力フィールドの行数を指定します。 | 任意 |
| required | 入力フィールドが必須かどうかを指定します。 `true` の場合、入力が必須になり、ラベルに赤い `*` が表示されます。 | `false` |
| disabled | 入力フィールドを無効にするかどうかを指定します。 `true` の場合、入力フィールドが無効になります。 | `false` |
| maxLength | 入力可能な最大文字数を指定します。 | 任意 |
| minLength | 入力が必要な最小文字数を指定します。 | 任意 |
| onChange | 入力内容の変更を検知するイベントハンドラー関数を指定します。引数として [Reactイベントオブジェクト (opens in a new tab)](https://ja.react.dev/reference/react-dom/components/common#react-event-object) が渡されます。 | 任意 |

### `value`, `onChange` propsの使い方 [](#value-onchange-propsの使い方)

「 [フォーム#value, onChange propsの使い方](/view/code_editor/form/#value-onchange-props%E3%81%AE%E4%BD%BF%E3%81%84%E6%96%B9) 」をご覧ください。

[TextInput](/view/code_editor/form/view_text_input/) [Select](/view/code_editor/form/view_select/)
---
[ビュー](/view/)

[コードエディター](/view/code_editor/)

関数

copyToClipboard

# copyToClipboard

`copyToClipboard` は、指定された文字列をクリップボードにコピーするための関数です。また、コピーが成功したことを示すトーストメッセージも表示します。

## 基本的な使い方 [](#基本的な使い方)

```
import { copyToClipboard } from "@basemachina/view";
 
const App = () => {
  const handleClick = () => {
    copyToClipboard("user-id", "ユーザーIDをコピーしました！");
  };
 
  return <button onClick={handleClick}>コピー</button>;
};
```

## 詳細なインターフェース [](#詳細なインターフェース)

### 引数 [](#引数)

| 引数名 | 型 | 説明 | 例 |
| --- | --- | --- | --- |
| `value` | `string` | クリップボードにコピーする文字列。 | `value` |
| `message` | `string` (任意) | コピー成功時に表示するカスタムメッセージ。指定がない場合、デフォルトのメッセージ `'コピーしました'` が表示されます。 | `'コピーしました！'` |

### 戻り値 [](#戻り値)

この関数は戻り値を返しません。

[useURLQueries](/view/code_editor/function/view_use_url_queries/) [showSuccessToast / showErrorToast](/view/code_editor/function/view_show_toast/)
---
[ビュー](/view/)

[コードエディター](/view/code_editor/)

関数

createActionJob

# createActionJob

`createActionJob` は、アクションをジョブとして実行する関数です。

## 基本的な使い方 [](#基本的な使い方)

```
import {
  createActionJob,
  showSuccessToast,
  showErrorToast,
  Form,
  VStack,
  Box,
  TextInput,
  Checkbox,
  DateTimePicker,
  Button,
} from "@basemachina/view";
 
const App = () => {
  const initialValues = {
    // アクションの引数
    message: "",
    // 以下、createActionJob関数のオプション
    scheduledAt: null,
    redirect: true,
  };
 
  const handleSubmit = async ({ values }) => {
    const { message, redirect, scheduledAt } = values;
    try {
      const { actionJobId } = await createActionJob(
        // actionId
        "job-test",
        // args
        { message },
        // options
        { redirect, scheduledAt },
      );
      showSuccessToast(`ジョブ: ${actionJobId} を作成しました`);
    } catch (err) {
      showErrorToast(err.message);
    }
  };
 
  return (
    <Form initialValues={initialValues} onSubmit={handleSubmit}>
      <VStack>
        <Box>
          <TextInput name="message" label="メッセージ" />
        </Box>
        <Box>
          <DateTimePicker name="scheduledAt" label="予約実行日時" />
        </Box>
        <Checkbox name="redirect" label="自動でジョブ詳細に遷移する" />
        <Button type="submit" title="ジョブを作成する" color="blue" />
      </VStack>
    </Form>
  );
};
 
export default App;
```

## 詳細なインターフェース [](#詳細なインターフェース)

### 引数 [](#引数)

| 引数名 | 型 | 必須 ・ 任意 | 説明 | 例 |
| --- | --- | --- | --- | --- |
| `actionId` | `string` | 必須 | 実行するアクションのID、または識別子。 | `'c3hc2ii23akg0sokf9j0'`, `'get-user'` |
| `args` | `object` | 任意 | アクションを実行するための引数で、 キーがパラメータ名、値がパラメータに渡す値のオブジェクト。 | `{ username: 'JohnDoe' }` |
| `options` | `object` | 任意 | ジョブの詳細設定。 | `{ scheduledAt: 1609459200 }` |
| `options.scheduledAt` | `Date | string | number` | 任意 | ジョブの予約実行日時。 `string` は `Date` 型に変換できる値、 `number` はUnixTimestamp (秒)を入力してください。日時は現在から30日以内の値を指定できます。 | `new Date()`, `'2023-01-01'`, `1609459200` |
| `options.redirect` | `boolean` | 任意 | ジョブの作成後に、自動的にジョブ詳細画面へ移動する設定。 | `true`, `false` |

なおパラメータの種類ごとに `args` へ渡せる値の型は以下です。

| 種類 | 型 | 説明 | 例 |
| --- | --- | --- | --- |
| テキスト | `string | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ company_name: '株式会社ベースマキナ' }` |
| 数値 | `number | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ user_id: 123 }` |
| 日付 | `Date | string | number | null | undefined` | `string` は `Date` 型に変換できる値、 `number` はUnixTimestamp (秒)を入力してください。 `null` や `undefined` の場合は未入力として扱われます。 | `{ created: '2023-01-01', updated: new Date(), deleted: 1609459200 }` |
| ファイル | `File | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ upload_text: new File(['test'], 'test.txt', { type: 'text/plain' }) }` |
| 真偽値 | `boolean | null | undefined` | `null` や `undefined` の場合は `false` として扱われます。 | `{ checked: true }` |
| JSON値 | `string | number | Date | null | undefined` | JSON値の種類ごとに型が異なります。 テキストなら `string | null | undefined` 、数値なら `number | null | undefined` 、日付なら `string | number | Date | null | undefined` を渡せます。 日付の場合 `string` は `Date` 型に変換できる値、 `number` はUnixTimestamp (秒)を入力してください。 `null` や `undefined` の場合は `null` として扱われます。 | `{ company_name: '株式会社ベースマキナ', user_id: 123, created: '2023-01-01', deleted: null }` |
| SQL | `string | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ query: 'SELECT * FROM users;' }` |
| システム値 | `string | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ offset: '20' }` |
| 配列 | `Array | null | undefined` | 各要素の種類の型は、各種類の型と同じです。 `null` や `undefined` の場合は空配列として扱われます。 | `{ user_ids: [10, 11, 12] }` |
| タプル | `Array` | 各要素の種類の型は、各種類の型と同じです。 | `{ id_and_name: [123, 'taro'] }` |

### 戻り値 [](#戻り値)

| プロパティ名 | 型 | 説明 | 例 |
| --- | --- | --- | --- |
| `actionJobId` | `string` | 作成したジョブのID。 | `cpt8gkab5gv1ibk8r5h0` |

[showSuccessToast / showErrorToast](/view/code_editor/function/view_show_toast/) [getActionJobResult](/view/code_editor/function/view_get_action_job_result/)
---
[ビュー](/view/)

[コードエディター](/view/code_editor/)

関数

createReviewRequest

# createReviewRequest

`createReviewRequest` は、アクションのレビュー依頼を作成する関数です。

※レビュー依頼を作成するには、事前に対象のアクションに [レビュー設定](/action/review/) が必要です。

## 基本的な使い方 [](#基本的な使い方)

```
import {
  createReviewRequest,
  showSuccessToast,
  showErrorToast,
  Form,
  VStack,
  Box,
  TextInput,
  Checkbox,
  DateTimePicker,
  Button,
} from "@basemachina/view";
 
const App = () => {
  const initialValues = {
    // アクションの引数
    message: "",
    // 以下、createReviewRequest関数のオプション
    redirect: true,
    description: "",
    neverExpires: false,
    expiresIn: null,
  };
 
  const handleSubmit = async ({ values }) => {
    const { message, redirect, description, neverExpires, expiresIn } = values;
    try {
      const { reviewRequestId } = await createReviewRequest(
        // actionId
        "review-test",
        // args
        { message },
        // options
        { redirect, description, neverExpires, expiresIn },
      );
      showSuccessToast(`レビュー依頼: ${reviewRequestId} を作成しました`);
    } catch (err) {
      showErrorToast(err.message);
    }
  };
 
  return (
    <Form initialValues={initialValues} onSubmit={handleSubmit}>
      <VStack>
        <Box>
          <TextInput name="message" label="メッセージ" />
        </Box>
        <Box>
          <TextInput name="description" label="レビューの説明" />
        </Box>
        <Checkbox name="redirect" label="自動でレビュー依頼に遷移する" />
        <Checkbox name="neverExpires" label="レビューを無期限にする" />
        <Box>
          <DateTimePicker name="expiresIn" label="レビュー期限" />
        </Box>
        <Button type="submit" title="レビュー依頼を作成する" color="blue" />
      </VStack>
    </Form>
  );
};
 
export default App;
```

## 詳細なインターフェース [](#詳細なインターフェース)

### 引数 [](#引数)

| 引数名 | 型 | 必須 ・ 任意 | 説明 | 例 |
| --- | --- | --- | --- | --- |
| `actionId` | `string` | 必須 | 実行するアクションのID、または識別子。 | `'c3hc2ii23akg0sokf9j0'`, `'get-user'` |
| `args` | `object` | 任意 | アクションを実行するための引数で、 キーがパラメータ名、値がパラメータに渡す値のオブジェクト。 | `{ username: 'JohnDoe' }` |
| `options` | `object` | 任意 | レビュー依頼の詳細設定。 | `{ description: 'レビュー依頼の説明' }` |
| `options.description` | `string` | 任意 | レビュー依頼の説明。最大文字数は1000文字です。指定しない場合、 [レビュー設定](/action/review/#%E3%83%AC%E3%83%93%E3%83%A5%E3%83%BC%E4%BE%9D%E9%A0%BC%E3%81%AE%E3%83%87%E3%83%95%E3%82%A9%E3%83%AB%E3%83%88%E8%A8%AD%E5%AE%9A) のデフォルト値が使用されます。 | `'レビュー依頼の説明'` |
| `options.neverExpires` | `boolean` | 任意 | レビュー依頼の期限を無期限に指定します。 `expiresIn` と同時に指定することはできません。指定しない場合、 [レビュー設定](/action/review/#%E3%83%AC%E3%83%93%E3%83%A5%E3%83%BC%E4%BE%9D%E9%A0%BC%E3%81%AE%E3%83%87%E3%83%95%E3%82%A9%E3%83%AB%E3%83%88%E8%A8%AD%E5%AE%9A) のデフォルト値が使用されます。 | `true`, `false` |
| `options.expiresIn` | `Date | string | number` | 任意 | レビュー依頼の期限。 `string` は `Date` 型に変換できる値、 `number` はUnixTimestamp (秒)を入力してください。時間は過去に設定できません。また、 `neverExpires` と同時に指定できません。 | `new Date()`, `'2023-01-01'`, `1609459200` |
| `options.redirect` | `boolean` | 任意 | レビュー依頼の作成後に、自動的にレビュー依頼詳細画面へ移動する設定。 | `true`, `false` |
| `options.autoExecuteOnApproval` | `boolean` | 任意 | 承認されたら自動で実行するかどうか（依頼者の権限で実行されます）。指定しない場合、 [レビュー設定](/action/review/#%E6%89%BF%E8%AA%8D%E5%BE%8C%E3%81%AE%E8%87%AA%E5%8B%95%E5%AE%9F%E8%A1%8C) の「承認後の自動実行」の設定に従います。「必ず手動で実行」が設定されたアクションで `true` を、「必ず承認と同時に実行する」が設定されたアクションで `false` を指定するとエラーになります。 | `true`, `false` |

なおパラメータの種類ごとに `args` へ渡せる値の型は以下です。

| 種類 | 型 | 説明 | 例 |
| --- | --- | --- | --- |
| テキスト | `string | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ company_name: '株式会社ベースマキナ' }` |
| 数値 | `number | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ user_id: 123 }` |
| 日付 | `Date | string | number | null | undefined` | `string` は `Date` 型に変換できる値、 `number` はUnixTimestamp (秒)を入力してください。 `null` や `undefined` の場合は未入力として扱われます。 | `{ created: '2023-01-01', updated: new Date(), deleted: 1609459200 }` |
| ファイル | `File | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ upload_text: new File(['test'], 'test.txt', { type: 'text/plain' }) }` |
| 真偽値 | `boolean | null | undefined` | `null` や `undefined` の場合は `false` として扱われます。 | `{ checked: true }` |
| JSON値 | `string | number | Date | null | undefined` | JSON値の種類ごとに型が異なります。 テキストなら `string | null | undefined` 、数値なら `number | null | undefined` 、日付なら `string | number | Date | null | undefined` を渡せます。 日付の場合 `string` は `Date` 型に変換できる値、 `number` はUnixTimestamp (秒)を入力してください。 `null` や `undefined` の場合は `null` として扱われます。 | `{ company_name: '株式会社ベースマキナ', user_id: 123, created: '2023-01-01', deleted: null }` |
| SQL | `string | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ query: 'SELECT * FROM users;' }` |
| システム値 | `string | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ offset: '20' }` |
| 配列 | `Array | null | undefined` | 各要素の種類の型は、各種類の型と同じです。 `null` や `undefined` の場合は空配列として扱われます。 | `{ user_ids: [10, 11, 12] }` |
| タプル | `Array` | 各要素の種類の型は、各種類の型と同じです。 | `{ id_and_name: [123, 'taro'] }` |

### 戻り値 [](#戻り値)

| プロパティ名 | 型 | 説明 | 例 |
| --- | --- | --- | --- |
| `reviewRequestId` | `string` | 作成したレビュー依頼のID。 | `cpt8gkab5gv1ibk8r5h0` |

[getActionJobResult](/view/code_editor/function/view_get_action_job_result/) [useCheckActionAvailability](/view/code_editor/function/view_use_check_action_availability/)
---
[ビュー](/view/)

[コードエディター](/view/code_editor/)

関数

executeAction

# executeAction

`executeAction` は、アクションを実行するための関数です。アクションの識別子とパラメータを指定することで、アクションを実行できます。

コールバック関数内で複数のアクションを連続して呼びたいケースなどでご活用いただけます。

アクションの実行状態をReactアプリケーションのstateとして使用したい場合は [useExecuteAction](/view/code_editor/function/view_use_execute_action/) および [useExecuteActionLazy](/view/code_editor/function/view_use_execute_action_lazy/) の使用をおすすめします。

## 基本的な使い方 [](#基本的な使い方)

```
const App = () => {
    ...
    const [address, setAddress] = useState(null)
    const handleClick = async () => {
      const { results: getCompanyResults } = await executeAction("get-company", {
        company_id: companyId,
      })
      const companyPostalCode = getCompanyResults[0].success.postal_code
      const { results: getAddressResults } = await executeAction("get-address-from-postal-code", {
        postal_code: companyPostalCode,
      })
      setAddress(getAddressResults[0].success.address)
    }
    ...
}
```

## 詳細なインターフェース [](#詳細なインターフェース)

### 引数 [](#引数)

| 引数名 | 型 | 必須 | 説明 | 例 |
| --- | --- | --- | --- | --- |
| `actionId` | `string` | ✓ | 実行するアクションのID、または識別子。 | `c3hc2ii23akg0sokf9j0`, `get-user` |
| `args` | `object` |  | アクションを実行するための引数で、 キーがパラメータ名、値がパラメータに渡す値のオブジェクトです。 | `{ username: 'JohnDoe' }` |

なおパラメータの種類ごとに `args` のプロパティの値に渡せる値の型は以下です。

| 種類 | 型 | 説明 | 例 |
| --- | --- | --- | --- |
| テキスト | `string | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ company_name: '株式会社ベースマキナ' }` |
| 数値 | `number | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ user_id: 123 }` |
| 日付 | `Date | string | number | null | undefined` | `string` は `Date` 型に変換できる値、 `number` はUnixTimestamp (秒)を入力してください。 `null` や `undefined` の場合は未入力として扱われます。 | `{ created: '2023-01-01', updated: new Date(), deleted: 1609459200 }` |
| ファイル | `File | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ upload_text: new File(['test'], 'test.txt', { type: 'text/plain' }) }` |
| 真偽値 | `boolean | null | undefined` | `null` や `undefined` の場合は `false` として扱われます。 | `{ checked: true }` |
| JSON値 | `string | number | Date | null | undefined` | JSON値の種類ごとに型が異なります。 テキストなら `string | null | undefined` 、数値なら `number | null | undefined` 、日付なら `string | number | Date | null | undefined` を渡せます。 日付の場合 `string` は `Date` 型に変換できる値、 `number` はUnixTimestamp (秒)を入力してください。 `null` や `undefined` の場合は `null` として扱われます。 | `{ company_name: '株式会社ベースマキナ', user_id: 123, created: '2023-01-01', deleted: null }` |
| SQL | `string | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ query: 'SELECT * FROM users;' }` |
| システム値 | `string | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ offset: '20' }` |
| 配列 | `Array | null | undefined` | 各要素の種類の型は、各種類の型と同じです。 `null` や `undefined` の場合は空配列として扱われます。 | `{ user_ids: [10, 11, 12] }` |
| タプル | `Array` | 各要素の種類の型は、各種類の型と同じです。 | `{ id_and_name: [123, 'taro'] }` |

### 戻り値 [](#戻り値)

| プロパティ名 | 型 | 説明 | 例 |
| --- | --- | --- | --- |
| `results` | `Array` | アクションの実行結果の配列。各要素には `success` と `failure` のプロパティが含まれます。 | `[{"success":[{"id":1,"name":"山田太郎"}]}]` |

[useExecuteActionLazy](/view/code_editor/function/view_use_execute_action_lazy/) [openLink](/view/code_editor/function/view_open_link/)
---
[ビュー](/view/)

[コードエディター](/view/code_editor/)

関数

getActionJobResult

# getActionJobResult

`getActionJobResult` は、ジョブの結果を取得する関数です。

## 基本的な使い方 [](#基本的な使い方)

```
import { useCallback, useState } from "react";
import {
  getActionJobResult,
  showErrorToast,
  Form,
  VStack,
  Box,
  TextInput,
  Button,
  Heading,
} from "@basemachina/view";
 
const App = () => {
  const [jobResult, setJobResult] = useState();
  const handleSubmit = async ({ values }) => {
    const { actionJobId } = values;
    try {
      const jobResult = await getActionJobResult(actionJobId);
      setJobResult(jobResult);
    } catch (err) {
      showErrorToast(err.message);
    }
  };
 
  return (
    <>
      <Form onSubmit={handleSubmit}>
        <VStack>
          <Box>
            <TextInput name="actionJobId" label="ジョブID" />
          </Box>
          <Button type="submit" title="ジョブの結果を取得する" color="blue" />
        </VStack>
      </Form>
      <VStack>
        <Heading text="ジョブの結果" />
        <pre>{JSON.stringify(jobResult, null, 2)}</pre>
      </VStack>
    </>
  );
};
 
export default App;
```

## 詳細なインターフェース [](#詳細なインターフェース)

### 引数 [](#引数)

| 引数名 | 型 | 必須 ・ 任意 | 説明 | 例 |
| --- | --- | --- | --- | --- |
| `actionJobId` | `string` | 必須 | 結果を取得するジョブのID。ジョブのIDは、ジョブの詳細ページのURL末尾か、createActionJob関数の戻り値から取得できます。 | `'c3hc2ii23akg0sokf9j0'` |

### 戻り値 [](#戻り値)

| プロパティ名 | 型 | 説明 | 例 |
| --- | --- | --- | --- |
| `results` | `Array` | ジョブの結果の配列。形式はアクションの実行結果と同じです。配列の各要素は、 `success` と `failure` のプロパティを持ちます。 | `[{"success":[{"id":1,"name":"山田太郎"}]}]` |
| `byteSize` | `number` | 結果のバイトサイズ。大きすぎるジョブの結果を画面表示に使うかどうかの分岐などに使うことができます。 | `126` |

### エラー [](#エラー)

以下の条件に該当する場合、 `getActionJobResult` はエラーをthrowします。 `try...catch` で適切にハンドリングしてください。

| 条件 | エラーメッセージ |
| --- | --- |
| ジョブが完了していない場合 | `ジョブが完了していないため、結果を取得できませんでした。` |
| ジョブがキャンセルされた場合 | `ジョブがキャンセルされたため、結果を取得できませんでした。` |
| ジョブの閲覧権限がない場合 | `ジョブの閲覧権限がないため、結果を取得できませんでした。` |

[createActionJob](/view/code_editor/function/view_create_action_job/) [createReviewRequest](/view/code_editor/function/view_create_review_request/)
---
[ビュー](/view/)

[コードエディター](/view/code_editor/)

関数

openActionLink

# openActionLink

`openActionLink` は、指定したアクションへのリンクを開くための関数です。リンクを開く際に、引数やオプションを指定できます。

## 基本的な使い方 [](#基本的な使い方)

```
import { openActionLink } from "@basemachina/view";
 
const App = () => {
  const handleClick = () => {
    openActionLink(
      "action-id",
      {
        param1: "value1",
        param2: "value2",
      },
      {
        newTab: true,
        openAndRun: true,
      },
    );
  };
 
  return <button onClick={handleClick}>Open link</button>;
};
```

## 詳細なインターフェース [](#詳細なインターフェース)

### 引数 [](#引数)

| 引数名 | 型 | 説明 | 例 |
| --- | --- | --- | --- |
| `actionId` | `string` | 開きたいアクションのID、または識別子。 | `c3hc2ii23akg0sokf9j0`, `get-user` |
| `params` | `object` | アクションを開く際に指定する引数。引数の名前と値のペアを持つオブジェクトです。 | `{ param1: "value1", param2: "value2" }` |
| `options` | `object` | リンクを開くオプションを指定するオブジェクト。新しいタブで開くかどうかを指定する `newTab` プロパティと、リンクを開いたときにアクションを即時実行する `openAndRun` プロパティを持つことができます。 | `{ newTab: true, openAndRun: true }` |

### 戻り値 [](#戻り値)

`openActionLink` 関数は戻り値を返しません。

ただし、関数の実行によりアクションへのリンクが開かれ、その結果が画面に表示されます。

[openLink](/view/code_editor/function/view_open_link/) [openViewLink](/view/code_editor/function/view_open_view_link/)
---
[ビュー](/view/)

[コードエディター](/view/code_editor/)

関数

openLink

# openLink

`openLink` は、指定されたURLを新しいタブまたは現在のタブで開くための関数です。URLとオプションを指定することで、リンクを開く動作を制御できます。

## 基本的な使い方 [](#基本的な使い方)

```
import { openLink } from "@basemachina/view";
 
const App = () => {
  const handleClick = () => {
    openLink("https://example.com", { newTab: true });
  };
 
  return <button onClick={handleClick}>Open link</button>;
};
```

## 詳細なインターフェース [](#詳細なインターフェース)

### 引数 [](#引数)

| 引数名 | 型 | 説明 | 例 |
| --- | --- | --- | --- |
| `href` | `string` | 開くリンクのURL。 | `"https://example.com"` |
| `options` | `object` | リンクを開くためのオプションで、 `newTab` プロパティを持つオブジェクトです。 `newTab` が `true` の場合、新しいタブでリンクが開きます。デフォルトは `true` です。 | `{ newTab: true }` |

### 戻り値 [](#戻り値)

この関数は特に戻り値を返しません。

[executeAction](/view/code_editor/function/view_execute_action/) [openActionLink](/view/code_editor/function/view_open_action_link/)
---
[ビュー](/view/)

[コードエディター](/view/code_editor/)

関数

openViewLink

# openViewLink

`openViewLink` は、指定されたビューを開くための関数です。この関数は表示するビューの識別子とそのビューに対するパラメータを引数として取ります。また、オプションとして新しいタブでビューを開くことができます。

## 基本的な使い方 [](#基本的な使い方)

```
import { openViewLink } from "@basemachina/view";
 
const App = () => {
  const handleClick = () => {
    openViewLink(
      "view-id",
      { param1: "value1", param2: "value2" },
      { newTab: true },
    );
  };
 
  return <button onClick={handleClick}>Open link</button>;
};
```

## 詳細なインターフェース [](#詳細なインターフェース)

### 引数 [](#引数)

| 引数名 | 型 | 説明 | 例 |
| --- | --- | --- | --- |
| `displayId` | `string` | 開くビューの識別子。 | `"user-search"` |
| `params` | `object` | ビューに渡す引数を表すオブジェクト。 | `{param1: "value1", param2: "value2"}` |
| `options` | `object` | ビューを開くためのオプション。新しいタブで開くかどうかを指定する `newTab` プロパティを持つことができます。 | `{newTab: true}` |

### 戻り値 [](#戻り値)

この関数は戻り値を返さないため、戻り値のテーブルはありません。

`openViewLink` 関数は、指定された `displayId` （ビューの識別子）と `params` （ビューに渡すパラメータ）を用いてビューを開きます。 `newTab` オプションが指定されている場合、ビューは新しいタブで開かれます。

[openActionLink](/view/code_editor/function/view_open_action_link/) [useBaseMachinaContext](/view/code_editor/function/view_use_basemachina_context/)
---
[ビュー](/view/)

[コードエディター](/view/code_editor/)

関数

showSuccessToast / showErrorToast

# showSuccessToast / showErrorToast

showSuccessToast / showErrorToastは、成功・失敗時にトーストを表示する関数です。

## 使い方 [](#使い方)

```
import {
  Card,
  HStack,
  Button,
  showSuccessToast,
  showErrorToast,
} from "@basemachina/view";
 
const App = () => {
  return (
    <Card>
      <HStack>
        <Button
          title="成功"
          type="button"
          color="blue"
          onClick={() =>
            showSuccessToast("処理が完了しました", {
              details: [
                "ユーザー情報を更新しました",
                "メール通知を送信しました",
                "ログに記録しました",
              ],
            })
          }
        />
        <Button
          title="失敗"
          type="button"
          color="red"
          onClick={() =>
            showErrorToast("エラーが発生しました", {
              details: [
                "ユーザー名は10文字以下で設定してください",
                "パスワードに記号を含めてください",
              ],
            })
          }
        />
      </HStack>
    </Card>
  );
};
 
export default App;
```

![showSuccessToastの使用例](/images/view/show_toast/usage_success.png)

![showErrorToastの使用例](/images/view/show_toast/usage_error.png)

## 詳細なインターフェース [](#詳細なインターフェース)

### 引数 [](#引数)

| 引数名 | 型 | 必須・任意 | 説明 | 例 |
| --- | --- | --- | --- | --- |
| `message` | `string` | 必須 | トーストに表示するメッセージ | `"エラーが発生しました"` |
| `options` | `object` | 任意 | 詳細オプション | `{ details: ["ユーザー名は10文字以下で設定してください", "パスワードに記号を含めてください"] }` |

#### optionsオブジェクトのプロパティ [](#optionsオブジェクトのプロパティ)

| プロパティ名 | 型 | 必須・任意 | 説明 | 例 |
| --- | --- | --- | --- | --- |
| `details` | `string[]` | 任意 | 詳細メッセージの配列 | `["ユーザー名は10文字以下で設定してください", "パスワードに記号を含めてください"]` |

### 戻り値 [](#戻り値)

この関数は戻り値を返しません。

[copyToClipboard](/view/code_editor/function/view_copy_to_clipboard/) [createActionJob](/view/code_editor/function/view_create_action_job/)
---
[ビュー](/view/)

[コードエディター](/view/code_editor/)

関数

useBaseMachinaContext

# useBaseMachinaContext

`useBaseMachinaContext` は、ユーザーコンテキストに関連する情報（ユーザー、プロジェクト、環境）を取得するためのフックです。これらの情報は、一般的にユーザー認証や権限管理などの機能を実装する際に役立ちます。

## 基本的な使い方 [](#基本的な使い方)

```
import {
    useBaseMachinaContext,
} from '@basemachina/view';
 
const App = () => {
    ...
    const basemachinaContext = useBaseMachinaContext();
 
    return (
        <div>
            <p>ユーザー名: {basemachinaContext.user.name}</p>
            <p>環境名: {basemachinaContext.environment.name}</p>
            <p>グループ一覧: {basemachinaContext.groups.map(group => group.name).join(', ')}</p>
        </div>
    )
}
```

## 詳細なインターフェース [](#詳細なインターフェース)

### 引数 [](#引数)

このフックは引数を受け付けません。

### 戻り値 [](#戻り値)

| プロパティ名 | 型 | 説明 | 例 |
| --- | --- | --- | --- |
| `user` | `object` | 現在のユーザーに関する情報を含むオブジェクト。 `id`, `email`, `name`, `groups`, `isTenantAdmin` のプロパティを含みます。 | 詳細は後述します。 |
| `environment` | `object` | 現在の環境に関する情報を含むオブジェクト。 `id`, `name` のプロパティを含みます。 | `{ id: '1', name: 'Environment Name' }` |
| `environmentVariables` | `object` | キーが環境変数の名前、値が環境変数の値のオブジェクト。 | `{ USER_NAME: 'example-user', PROJECT: 'example-project' }` |
| `groups` | `Array` | 現在のプロジェクトに存在するグループに関する情報を含むオブジェクトの配列。各オブジェクトは `id`, `name` のプロパティを含みます。 | `[{ id: '1', name: 'Group1' }, { id: '2', name: 'Group2' }]` |

なお、 `user` プロパティのオブジェクトの各プロパティは以下の通りです。

| プロパティ名 | 型 | 説明 | 例 |
| --- | --- | --- | --- |
| `id` | `string` | ユーザーのID | `'1'` |
| `email` | `string` | ユーザーのメールアドレス | `'user@example.com'` |
| `name` | `string` | ユーザー名 | `'User Name'` |
| `groups` | `Array` | ユーザーが所属するグループに関する情報を含むオブジェクトの配列。 | `[{ id: '1', name: 'Group1' }]` |
| `isTenantAdmin` | `boolean` | ユーザーが企業アカウント管理者であれば `true` です。 | `true` |

[openViewLink](/view/code_editor/function/view_open_view_link/) [useURLQueries](/view/code_editor/function/view_use_url_queries/)
---
[ビュー](/view/)

[コードエディター](/view/code_editor/)

関数

useCheckActionAvailability

# useCheckActionAvailability

`useCheckActionAvailability` は、指定したアクションの「通常のアクション実行（ `execution` ）」「ジョブとして実行（ `job` ）」「レビュー依頼の作成（ `reviewRequest` ）」が可能かを判定するフックです。

各操作が可能かを示す `isAvailable` を返します。 `isAvailable` が `false` の場合は、 `reason` と `message` に操作できない理由を返します。読み込み中は `null` を返します。

## 基本的な使い方 [](#基本的な使い方)

```
import { useEffect, useState } from "react";
import {
  useCheckActionAvailability,
  Alert,
  Button,
  HStack,
  VStack,
  LoadingIndicator,
} from "@basemachina/view";
 
const App = () => {
  const actionId = "get-user"; // アクションのIDまたは識別子
  const availability = useCheckActionAvailability(actionId);
 
  if (!availability) {
    return <LoadingIndicator />;
  }
 
  const { execution, job, reviewRequest } = availability;
 
  return (
    <VStack>
      <HStack>
        <Button
          title="通常のアクション実行"
          disabled={!execution.isAvailable}
          onClick={() => {
            /* 実行処理 */
          }}
        />
        <Button
          title="ジョブとして実行"
          disabled={!job.isAvailable}
          onClick={() => {
            /* ジョブ作成処理 */
          }}
        />
        <Button
          title="レビュー依頼を作成"
          disabled={!reviewRequest.isAvailable}
          onClick={() => {
            /* レビュー依頼作成処理 */
          }}
        />
      </HStack>
 
      {!execution.isAvailable && (
        <Alert
          color="gray"
          message={`通常のアクション実行不可: ${execution.reason} - ${execution.message}`}
        />
      )}
      {!job.isAvailable && (
        <Alert
          color="gray"
          message={`ジョブとしての実行不可: ${job.reason} - ${job.message}`}
        />
      )}
      {!reviewRequest.isAvailable && (
        <Alert
          color="gray"
          message={`レビュー依頼の作成不可: ${reviewRequest.reason} - ${reviewRequest.message}`}
        />
      )}
    </VStack>
  );
};
 
export default App;
```

## 詳細なインターフェース [](#詳細なインターフェース)

### 引数 [](#引数)

| 引数名 | 型 | 必須 ・ 任意 | 説明 | 例 |
| --- | --- | --- | --- | --- |
| `actionId` | `string` | 必須 | アクションのID、または識別子。 | `'c3hc2ii23akg0sokf9j0'`, `'get-user'` |

### 戻り値 [](#戻り値)

以下の型の値を返します（読み込み中は `null` ）。

```
type CommonReason =
  | "notFound"
  | "noPermission"
  | "dataSourceDeleted"
  | "noCurrentEnvironmentDataSource"
  | "environmentInvisible"
  | "reviewSettingDeleted";
 
type Returns = {
  execution:
    | { isAvailable: true }
    | {
        isAvailable: false;
        reason: CommonReason | "reviewRequired" | "jobQueueSet";
        message: string;
      };
  job:
    | { isAvailable: true }
    | {
        isAvailable: false;
        reason: CommonReason | "reviewRequired";
        message: string;
      };
  reviewRequest:
    | { isAvailable: true }
    | {
        isAvailable: false;
        reason:
          | CommonReason
          | "noReviewSetting"
          | "environmentNotRequiringReview";
        message: string;
      };
} | null;
```

#### 共通の理由（CommonReason） [](#共通の理由commonreason)

| `reason` | `message` |
| --- | --- |
| `notFound` | 存在しないアクションのIDまたは識別子です。 |
| `noPermission` | 実行権限がありません。 |
| `dataSourceDeleted` | データソースが削除されています。 |
| `noCurrentEnvironmentDataSource` | この環境のデータソース設定がありません。 |
| `environmentInvisible` | この環境ではアクションが非表示になっています。 |
| `reviewSettingDeleted` | レビュー設定が削除されています。 |

#### 操作別の理由 [](#操作別の理由)

| 操作 | `reason` | `message` |
| --- | --- | --- |
| `execution` | `reviewRequired` | この環境では実行前レビューが必要です。 |
| `execution` | `jobQueueSet` | ジョブキューが設定されているため、ジョブでのみ実行可能です。 |
| `job` | `reviewRequired` | この環境では実行前レビューが必要です。 |
| `reviewRequest` | `noReviewSetting` | レビュー設定が使用されていません。 |
| `reviewRequest` | `environmentNotRequiringReview` | この環境で実行前レビューが有効化されていません。 |

[createReviewRequest](/view/code_editor/function/view_create_review_request/) [Accordion](/view/code_editor/other/view_accordion/)
---
[ビュー](/view/)

[コードエディター](/view/code_editor/)

関数

useExecuteAction

# useExecuteAction

`useExecuteAction` は、ビューの表示時にアクションを実行するためのフックです。アクションの識別子とパラメータの値を指定することで、アクションを実行できます。

## 基本的な使い方 [](#基本的な使い方)

以下のようにhookを呼び出すだけでアクションを実行できます。

```
const App = () => {
    ...
    const { data, loading } = useExecuteAction("action-id", {
        company_name: '株式会社ベースマキナ',
        user_id: 123,
        checked: true,
        created: '2023-01-01',
    })
 
    return (
        <>
            {loading && <LoadingIndicator />}
            {data && <Table rows={data.results[0].success ?? []}/>}
        </>
    )
}
```

さらに `execute` 関数を使うことで、パラメーターの値を変更してアクションを再実行できます。

```
const App = () => {
    ...
    const initialArgs = {
        company_name: '株式会社ベースマキナ',
        user_id: 123,
        checked: true,
        created: '2023-01-01',
    }
    const { data, loading, execute } = useExecuteAction("action-id", initialArgs)
 
    const [searchTerm, setSearchTerm] = useState('')
    const handleSearch = (searchTerm) => {
        // 別のパラメータの値でアクションを再実行
        execute({
            ...initialArgs,
            company_name: searchTerm,
        })
    }
 
    return (
        <>
            {loading && <LoadingIndicator />}
            {data && <Table rows={data.results[0].success ?? []}/>}
            <input
                type="text"
                value={searchTerm}
                onChange={(e) => setSearchTerm(e.target.value)}
            />
            <button onClick={() => handleSearch(searchTerm)}>検索</button>
        </>
    )
}
```

## 詳細なインターフェース [](#詳細なインターフェース)

### 引数 [](#引数)

| 引数名 | 型 | 説明 | 例 |
| --- | --- | --- | --- |
| `actionId` | `string` | 実行するアクションのID、または識別子。 | `c3hc2ii23akg0sokf9j0`, `get-user` |
| `args` | `object` | アクションを実行するための引数で、 キーがパラメータ名、値がパラメータに渡す値のオブジェクトです。 | `{ username: 'JohnDoe' }` |

なおパラメータの種類ごとに `args` のプロパティの値に渡せる値の型は以下です。

| 種類 | 型 | 説明 | 例 |
| --- | --- | --- | --- |
| テキスト | `string | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ company_name: '株式会社ベースマキナ' }` |
| 数値 | `number | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ user_id: 123 }` |
| 日付 | `Date | string | number | null | undefined` | `string` は `Date` 型に変換できる値、 `number` はUnixTimestamp (秒)を入力してください。 `null` や `undefined` の場合は未入力として扱われます。 | `{ created: '2023-01-01', updated: new Date(), deleted: 1609459200 }` |
| ファイル | `File | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ upload_text: new File(['test'], 'test.txt', { type: 'text/plain' }) }` |
| 真偽値 | `boolean | null | undefined` | `null` や `undefined` の場合は `false` として扱われます。 | `{ checked: true }` |
| JSON値 | `string | number | Date | null | undefined` | JSON値の種類ごとに型が異なります。 テキストなら `string | null | undefined` 、数値なら `number | null | undefined` 、日付なら `string | number | Date | null | undefined` を渡せます。 日付の場合 `string` は `Date` 型に変換できる値、 `number` はUnixTimestamp (秒)を入力してください。 `null` や `undefined` の場合は `null` として扱われます。 | `{ company_name: '株式会社ベースマキナ', user_id: 123, created: '2023-01-01', deleted: null }` |
| SQL | `string | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ query: 'SELECT * FROM users;' }` |
| システム値 | `string | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ offset: '20' }` |
| 配列 | `Array | null | undefined` | 各要素の種類の型は、各種類の型と同じです。 `null` や `undefined` の場合は空配列として扱われます。 | `{ user_ids: [10, 11, 12] }` |
| タプル | `Array` | 各要素の種類の型は、各種類の型と同じです。 | `{ id_and_name: [123, 'taro'] }` |

### 戻り値 [](#戻り値)

| プロパティ名 | 型 | 説明 | 例 |
| --- | --- | --- | --- |
| `loading` | `boolean` | アクションが現在実行中かどうかを示すブール値。 | `true` |
| `data` | `object | undefined` | アクションの実行結果。このオブジェクトは `results` という名前の配列を持っており `success` と `failure` のプロパティが含まれます。なお、 **アクションの実行が完了するまでは `undefined` となります。** | `{"results":[{"success":[{"id":1,"name":"山田太郎"}]}]}` |
| `error` | `object` | アクションの実行中に発生したエラー。 | - |
| `execute` | `async function` | 引数としてアクションのパラメータを受け取り、アクションを実行する関数。 `data` をプロパティに持つオブジェクトの `Promise` を返します。 | - |

なお `execute` 関数の引数のパラメータは、キーがパラメータ名、値がパラメータに渡す値のオブジェクト（例： `{ username: 'JohnDoe' }` ）となり、パラメータの種類ごとにプロパティの値に渡せる値の型は以下です。

| 種類 | 型 | 説明 | 例 |
| --- | --- | --- | --- |
| テキスト | `string | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ company_name: '株式会社ベースマキナ' }` |
| 数値 | `number | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ user_id: 123 }` |
| 日付 | `Date | string | number | null | undefined` | `string` は `Date` 型に変換できる値、 `number` はUnixTimestamp (秒)を入力してください。 `null` や `undefined` の場合は未入力として扱われます。 | `{ created: '2023-01-01', updated: new Date(), deleted: 1609459200 }` |
| ファイル | `File | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ upload_text: new File(['test'], 'test.txt', { type: 'text/plain' }) }` |
| 真偽値 | `boolean | null | undefined` | `null` や `undefined` の場合は `false` として扱われます。 | `{ checked: true }` |
| JSON値 | `string | number | Date | null | undefined` | JSON値の種類ごとに型が異なります。 テキストなら `string | null | undefined` 、数値なら `number | null | undefined` 、日付なら `string | number | Date | null | undefined` を渡せます。 日付の場合 `string` は `Date` 型に変換できる値、 `number` はUnixTimestamp (秒)を入力してください。 `null` や `undefined` の場合は `null` として扱われます。 | `{ company_name: '株式会社ベースマキナ', user_id: 123, created: '2023-01-01', deleted: null }` |
| SQL | `string | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ query: 'SELECT * FROM users;' }` |
| システム値 | `string | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ offset: '20' }` |
| 配列 | `Array | null | undefined` | 各要素の種類の型は、各種類の型と同じです。 `null` や `undefined` の場合は空配列として扱われます。 | `{ user_ids: [10, 11, 12] }` |
| タプル | `Array` | 各要素の種類の型は、各種類の型と同じです。 | `{ id_and_name: [123, 'taro'] }` |

[Avatar](/view/code_editor/media/view_avatar/) [useExecuteActionLazy](/view/code_editor/function/view_use_execute_action_lazy/)
---
[ビュー](/view/)

[コードエディター](/view/code_editor/)

関数

useExecuteActionLazy

# useExecuteActionLazy

`useExecuteActionLazy` はアクションの実行を遅延させるためのフックです。このフックはアクションの識別子を引数として受け取り、そのアクションの実行を開始する関数とアクションの実行状態を返します。

## 基本的な使い方 [](#基本的な使い方)

```
const App = () => {
  const [execute, { data, loading, error }] = useExecuteActionLazy("action-id");
 
  const handleClick = () => {
    execute({
      company_name: "株式会社ベースマキナ",
      user_id: 123,
      checked: true,
      created: "2023-01-01",
    });
  };
 
  return (
    <div>
      <button onClick={handleClick}>Execute Action</button>
      {loading && <LoadingIndicator />}
      {data && <Table rows={data.results[0].success ?? []} />}
    </div>
  );
};
```

## 詳細なインターフェース [](#詳細なインターフェース)

### 引数 [](#引数)

| 引数名 | 型 | 説明 | 例 |
| --- | --- | --- | --- |
| `actionId` | `string` | 実行するアクションのID、または識別子。 | `c3hc2ii23akg0sokf9j0`, `get-user` |

### 戻り値 [](#戻り値)

| プロパティ名 | 型 | 説明 | 例 |
| --- | --- | --- | --- |
| `execute` | `async function` | 引数としてアクションのパラメータを受け取り、アクションを実行する関数。 `data` をプロパティに持つオブジェクトの `Promise` を返します。 | - |
| `state` | `object` | アクションの実行状態を表すオブジェクト。このオブジェクトは `loading` 、 `data` 、 `error` の3つのプロパティを持ちます。 | - |
| `state.loading` | `boolean` | アクションが現在実行中かどうかを示すブール値。 | `true` |
| `state.data` | `object` | アクションの実行結果。このオブジェクトは `results` という名前の配列を持っており `success` と `failure` のプロパティが含まれます。 | `{"results":[{"success":[{"id":1,"name":"山田太郎"}]}]}` |
| `state.error` | `object` | アクションの実行中に発生したエラー。 | - |

なお `execute` 関数の引数のパラメータは、キーがパラメータ名、値がパラメータに渡す値のオブジェクト（例： `{ username: 'JohnDoe' }` ）となり、パラメータの種類ごとにプロパティの値に渡せる値の型は以下です。

| 種類 | 型 | 説明 | 例 |
| --- | --- | --- | --- |
| テキスト | `string | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ company_name: '株式会社ベースマキナ' }` |
| 数値 | `number | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ user_id: 123 }` |
| 日付 | `Date | string | number | null | undefined` | `string` は `Date` 型に変換できる値、 `number` はUnixTimestamp (秒)を入力してください。 `null` や `undefined` の場合は未入力として扱われます。 | `{ created: '2023-01-01', updated: new Date(), deleted: 1609459200 }` |
| ファイル | `File | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ upload_text: new File(['test'], 'test.txt', { type: 'text/plain' }) }` |
| 真偽値 | `boolean | null | undefined` | `null` や `undefined` の場合は `false` として扱われます。 | `{ checked: true }` |
| JSON値 | `string | number | Date | null | undefined` | JSON値の種類ごとに型が異なります。 テキストなら `string | null | undefined` 、数値なら `number | null | undefined` 、日付なら `string | number | Date | null | undefined` を渡せます。 日付の場合 `string` は `Date` 型に変換できる値、 `number` はUnixTimestamp (秒)を入力してください。 `null` や `undefined` の場合は `null` として扱われます。 | `{ company_name: '株式会社ベースマキナ', user_id: 123, created: '2023-01-01', deleted: null }` |
| SQL | `string | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ query: 'SELECT * FROM users;' }` |
| システム値 | `string | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 | `{ offset: '20' }` |
| 配列 | `Array | null | undefined` | 各要素の種類の型は、各種類の型と同じです。 `null` や `undefined` の場合は空配列として扱われます。 | `{ user_ids: [10, 11, 12] }` |
| タプル | `Array` | 各要素の種類の型は、各種類の型と同じです。 | `{ id_and_name: [123, 'taro'] }` |

[useExecuteAction](/view/code_editor/function/view_use_execute_action/) [executeAction](/view/code_editor/function/view_execute_action/)
---
[ビュー](/view/)

[コードエディター](/view/code_editor/)

関数

useURLQueries

# useURLQueries

`useURLQueries` は、現在のURLのクエリパラメータを取得するためのフックです。これにより、アプリケーション内の各コンポーネントがURLパラメータを使用して動作を調整することが可能になります。

## 基本的な使い方 [](#基本的な使い方)

```
import {
    useURLQueries
} from '@basemachina/view'
 
const App = () => {
    const urlQueries = useURLQueries();
    console.log(urlQueries); // クエリパラメータのオブジェクトが出力されます
    ...
}
```

## 詳細なインターフェース [](#詳細なインターフェース)

### 引数 [](#引数)

このフックは引数を取りません。

### 戻り値 [](#戻り値)

| 型 | 説明 | 例 |
| --- | --- | --- |
| `object` | URLのクエリパラメータを表すオブジェクト。キーはクエリパラメータの名前で、値はそのパラメータの値を表します。パラメータが存在しない場合、その値は空オブジェクトとなります。 | `{ query1: 'value1', query2: 'value2' }` |

なお、戻り値のオブジェクトは、各プロパティの値が `string | string[] | undefined` 型になります。

これは、同一のクエリパラメータ名がURL内に複数存在する場合、その値を配列として表現するためです。例えば、URLが `http://example.com?query=value1&query=value2` の場合、戻り値のオブジェクトは `{ query: ['value1', 'value2'] }` となります。

[useBaseMachinaContext](/view/code_editor/function/view_use_basemachina_context/) [copyToClipboard](/view/code_editor/function/view_copy_to_clipboard/)
---
[ビュー](/view/)

[コードエディター](/view/code_editor/)

Git管理

# Git管理

コードエディターでは、基本的にブラウザ上のエディターでコードを編集しますが、「コード取得設定」を有効化することで、アクション経由でコードを取得可能になります。

この機能をGitHubやGitLabなどのワークフローと組み合わせることで、ビューのコードをバージョン管理できます。

活用例は、以下の通りです。

- ファイル分割
- TypeScriptの利用
- 環境ごとに合わせたbranchの切り替え
- 任意のライブラリの使用

また、ビューのコード取得設定を導入しやすくするため、 [ボイラープレートのリポジトリ (opens in a new tab)](https://github.com/basemachina/view-project-boilerplates) と、 [ローカル環境で編集中のビューをプレビューするためのツール (opens in a new tab)](https://github.com/basemachina/bm-view-preview) を提供しています。

## コード取得設定 [](#コード取得設定)

コード取得設定を有効化すると、アクション経由でビューのコードを取得できます。

取得方法の例としては、以下のものが挙げられます。

- HTTP APIアクションで、GitHub API経由でビューのコードを取得する
- GCSアクションまたはS3アクションで、バケットからビューのコードを取得する

加えて、変数・シークレットの機能と組み合わせることで、環境ごとに別のコードを取得することも可能となります。
通常のビューでは、全環境で共通のコードを使用するので、コード取得設定を有効化する大きな利点となります。

## 利用方法 [](#利用方法)

1. ビューの作成・編集画面で、「コードをアクションで取得する」を選択する

![「コードをアクションで取得する」のトグルスイッチ](/images/view/git_management/enable-code-fetch-setting.png)

1. コードの取得元となるアクションを選択する
  - 例えば、GCSアクションやS3アクションを選択します
1. コードの取得元となるアクションの引数を入力して、実行する
  - 例えば、GCSアクションに `objectName` を指定して実行すると、その結果のコードを実行してビューとして表示します
  - S3アクションの場合は `key` を指定して実行します

**コード例 (GCSまたはS3にアップロードされたview-code.jsx)**

```
import { Alert } from "@basemachina/view";
const App = () => <Alert message="サンプル" />;
export default App;
```

**実行例**

![GCSアクションを実行して、ビューを表示した例](/images/view/git_management/run-code-fetch-setting-action.png)

1. 保存する
  - 次回以降、保存したビューを表示するたびにアクション経由でコードを取得するようになります

## 活用方法 [](#活用方法)

### ファイル分割・TypeScriptの利用 [](#ファイル分割typescriptの利用)

「利用方法」の例のように、JSXファイルを単にアクション経由で取得する形も可能ですし、WebpackとBabelを利用して、分割したTypeScript・TSXファイルをトランスパイルしたうえでバンドルする形でも利用可能です。

実際の設定例は、 [GCSのサンプル (opens in a new tab)](https://github.com/basemachina/view-project-boilerplates/tree/main/gcs-boilerplate) をご覧ください。S3アクションでも同様の方法で利用可能です。

### branchの切り替え [](#branchの切り替え)

例えばGCSアクションやS3アクションを使う場合、環境ごとに合わせたbranch名を [変数](/view/action/vars_secrets/) に登録することで、本番環境ではmain branchの、開発環境ではdevelop branchのコードを使うといったことが可能となります。

以下のように、変数を登録し、アクションを設定することで実現できます。

#### 変数の登録例 [](#変数の登録例)

![変数にVIEW\_CODE\_BRANCH\_NAMEという値を追加し、developと設定する例](/images/view/git_management/view-code-branch-name-var.png)

#### GCSアクションの設定例 [](#gcsアクションの設定例)

![GCSのオブジェクト名にvars.VIEW\_CODE\_BRANCH\_NAMEをPrefixとして使う例](/images/view/git_management/view-code-branch-name-gcs-config.png)

[GCSのサンプル (opens in a new tab)](https://github.com/basemachina/view-project-boilerplates/tree/main/gcs-boilerplate) では、branch名ごとにPrefixを分けてファイルをアップロードするように初めから設定されています。

### 任意のライブラリの使用 [](#任意のライブラリの使用)

「ファイル分割・TypeScriptの利用」の例と同様、Webpackを利用することで任意のサードパーティのライブラリをバンドルして使用できます。

ただし、ライブラリのサイズによってはビューの読み込みに時間がかかってしまう点、およびブラウザ上で動作しないライブラリは使用できない点に注意してください。

[GCSのサンプル (opens in a new tab)](https://github.com/basemachina/view-project-boilerplates/tree/main/gcs-boilerplate) の設定内容は、 `npm install` で追加したpackageがバンドル対象となります。

### マスターデータ取得設定の利用 [](#マスターデータ取得設定の利用)

ファイルの指定に使うパラメーターで [マスターデータ取得設定](/view/action/parameter/master_data_fetch_setting/) を利用することで、ファイル名入力の手間を省くことができます。

[外部ライブラリ](/view/code_editor/external_libs/) [型定義ファイルのダウンロード](/view/code_editor/download_dts_file/)
---
[ビュー](/view/)

[コードエディター](/view/code_editor/)

レイアウト

Box

# Box

Boxコンポーネントは、レイアウトや配置を制御するためのコンテナです。サイズやオーバーフローの制御が可能です。

## 基本的な使い方 [](#基本的な使い方)

```
<Box flex={1} width="md" height="lg">
  ここにコンテンツが表示されます。
</Box>
```

## 詳細なインターフェース [](#詳細なインターフェース)

| 名前 | 説明 | デフォルト値 |
| --- | --- | --- |
| flex | サイズを調整するためのプロパティです。1, 2, 3, 'auto', 'initial' のいずれかを指定できます。 | 'auto' |
| overflow | オーバーフローを制御するためのプロパティです。'auto', 'hidden', 'scroll', 'visible' などが指定できます。 | 'visible' |
| width | 幅を制御するためのプロパティです。'auto', 'full', 'xs', 'sm', 'md', 'lg', 'xl', '2xl' のいずれかを指定できます。 | 'auto' |
| height | 高さを制御するためのプロパティです。'auto', 'full', 'xs', 'sm', 'md', 'lg', 'xl', '2xl' のいずれかを指定できます。 | 'auto' |
| children | Boxコンポーネント内に表示するコンテンツを指定します。 | なし |

[Card](/view/code_editor/layout/view_card/) [Grid](/view/code_editor/layout/view_grid/)
---
[ビュー](/view/)

[コードエディター](/view/code_editor/)

レイアウト

Card

# Card

Cardコンポーネントはコンテンツを表示するためのコンテナです。内側のパディング、ボーダー、角丸がデフォルトで適用されています。

## 使用例 [](#使用例)

```
<Card flex={1}>ここにコンテンツが表示されます。</Card>
```

![使用例](/images/view/card/usage.png)

## インターフェース [](#インターフェース)

| 名前 | 説明 | デフォルト値 |
| --- | --- | --- |
| flex | サイズを調整するためのプロパティです。1, 2, 3, 'auto', 'initial' のいずれかを指定できます。 | 'auto' |
| children | Cardコンポーネント内に表示するコンテンツを指定します。 | なし |

[コードエディター](/view/code_editor/) [Box](/view/code_editor/layout/view_box/)
---
[ビュー](/view/)

[コードエディター](/view/code_editor/)

レイアウト

Drawer

# Drawer

Drawerコンポーネントは、一時的に開くサイドバーの表示に使うコンポーネントです。
サイドバーはページの右側に表示され、×ボタンをクリックするか、サイドバー外の領域をクリックすることで閉じることができます。
タイトルおよび、表示する内容を指定できます。

開閉状態は、 `useState` を使ってDrawerコンポーネント外で管理する必要があります。

## 基本的な使い方 [](#基本的な使い方)

```
import { useState } from "react";
import { Box, Drawer, Button } from "@basemachina/view";
 
const App = () => {
  const [open, setOpen] = useState(false);
  return (
    <>
      <Button title="サイドバーを開く" onClick={() => setOpen(true)} />
      <Drawer title="タイトル" open={open} onClose={() => setOpen(false)}>
        <Box>表示内容</Box>
      </Drawer>
    </>
  );
};
 
export default App;
```

![使用例](/images/view/drawer/usage.png)

## 詳細なインターフェース [](#詳細なインターフェース)

| 名前 | 説明 | デフォルト値 |
| --- | --- | --- |
| open | Drawerの開閉状態を指定します。 | 必須 |
| onClose | Drawerを閉じる関数を指定します。 | 必須 |
| title | Drawerに表示するタイトル文字列を指定します。 | 必須 |
| children | Drawerコンポーネント内に表示するコンテンツを指定します。 | なし |

[HStack / VStack](/view/code_editor/layout/view_stack/) [Table](/view/code_editor/data_display/view_table/)
---
[ビュー](/view/)

[コードエディター](/view/code_editor/)

レイアウト

Flexbox

# Flexbox

Flexboxコンポーネントは、フレキシブルボックスレイアウトを実現するためのコンテナです。方向、配置、アイテムの並び方、折り返し、オーバーフロー、幅、高さを設定できます。

## 基本的な使い方 [](#基本的な使い方)

```
<Flexbox
  direction="row"
  justify="center"
  align="center"
  items="center"
  wrap="wrap"
>
  <Card>ここにコンテンツが表示されます。</Card>
  <Card>ここにもコンテンツが表示されます。</Card>
</Flexbox>
```

![使用例](/images/view/flexbox/usage.png)

## 詳細なインターフェース [](#詳細なインターフェース)

| 名前 | 説明 | デフォルト値 |
| --- | --- | --- |
| direction | フレックスボックスの方向を指定します。'row' または 'col' のいずれかを指定できます。 | 'row' |
| justify | コンテンツの水平方向の配置を指定します。'start', 'end', 'center', 'between' のいずれかを指定できます。 | 'start' |
| align | コンテンツの垂直方向の配置を指定します。'start', 'end', 'center', 'between' のいずれかを指定できます。 | 'start' |
| items | アイテムの配置を指定します。'start', 'end', 'center' のいずれかを指定できます。 | 'start' |
| wrap | 折り返しの設定を指定します。'wrap', 'nowrap', 'wrap-reverse' のいずれかを指定できます。 | 'wrap' |
| overflow | オーバーフローを制御するためのプロパティです。 | 'visible' |
| width | 幅を制御するためのプロパティです。'auto', 'full', 'xs', 'sm', 'md', 'lg', 'xl', '2xl' のいずれかを指定できます。 | 'auto' |
| height | 高さを制御するためのプロパティです。'auto', 'full', 'xs', 'sm', 'md', 'lg', 'xl', '2xl' のいずれかを指定できます。 | 'auto' |
| children | Flexboxコンポーネント内に表示するコンテンツを指定します。 | なし |

[Grid](/view/code_editor/layout/view_grid/) [HStack / VStack](/view/code_editor/layout/view_stack/)
---
[ビュー](/view/)

[コードエディター](/view/code_editor/)

レイアウト

Grid

# Grid

Gridコンポーネントは、グリッドレイアウトを実現するためのコンテナです。方向、繰り返し回数、ギャップ、幅、高さを設定できます。

## 基本的な使い方 [](#基本的な使い方)

```
<Grid direction="row" repeatCount={2} gap={4} width="xl" height="lg">
  <Card>ここにコンテンツが表示されます。</Card>
  <Card>ここにもコンテンツが表示されます。</Card>
</Grid>
```

![使用例](/images/view/grid/usage.png)

## 詳細なインターフェース [](#詳細なインターフェース)

| 名前 | 説明 | デフォルト値 |
| --- | --- | --- |
| direction | グリッドの方向を指定します。'row' または 'col' のいずれかを指定できます。 | 'col' |
| repeatCount | グリッドの繰り返し回数を指定します。1, 2, 3, 4, 5, 6, 7, 8, 'auto' のいずれかを指定できます。 | 2 |
| gap | グリッドのギャップを指定します。0, 1, 2, 3, 4, 5, 6, 7, 8 のいずれかを指定できます。 | 4 |
| width | 幅を制御するためのプロパティです。'auto', 'full', 'xs', 'sm', 'md', 'lg', 'xl', '2xl' のいずれかを指定できます。 | 'auto' |
| height | 高さを制御するためのプロパティです。'auto', 'full', 'xs', 'sm', 'md', 'lg', 'xl', '2xl' のいずれかを指定できます。 | 'auto' |
| children | Gridコンポーネント内に表示するコンテンツを指定します。 | なし |

[Box](/view/code_editor/layout/view_box/) [Flexbox](/view/code_editor/layout/view_flexbox/)
---
[ビュー](/view/)

[コードエディター](/view/code_editor/)

レイアウト

HStack / VStack

# HStack / VStack

HStack / VStackコンポーネントは、横方向（HStack）、または縦方向（VStack）のレイアウトを簡易的に組むためのコンポーネントです。
このコンポーネントの内側の要素は、スペースを空けた上で配置されます。

## 基本的な使い方 [](#基本的な使い方)

```
<VStack>
  <HStack>
    <Box>A</Box>
    <Box>B</Box>
    <Box>C</Box>
  </HStack>
  <Box>D</Box>
  <Box>E</Box>
  <Box>F</Box>
</VStack>
```

## 詳細なインターフェース [](#詳細なインターフェース)

追加の設定項目は存在しません。

[Flexbox](/view/code_editor/layout/view_flexbox/) [Drawer](/view/code_editor/layout/view_drawer/)
---
[ビュー](/view/)

[コードエディター](/view/code_editor/)

リンク

ActionLink

# ActionLink

ActionLinkコンポーネントは、ユーザーがクリックすることで指定されたアクション実行画面に画面移動するためのコンポーネントです。ボタンまたはテキストの形式で表示できます。

## 基本的な使い方 [](#基本的な使い方)

```
import { Card, ActionLink } from "@basemachina/view";
 
const App = () => {
  return (
    <Card>
      <ActionLink
        actionId="sampleActionId"
        params={{
          param1: "value1",
          param2: "value2",
        }}
        color="red"
        type="button"
        newTab={true}
      >
        Run Action
      </ActionLink>
    </Card>
  );
};
export default App;
```

![使用例](/images/view/actionlink/usage.png)

## 詳細なインターフェース [](#詳細なインターフェース)

| 名前 | 説明 | 必須・任意 | デフォルト値 |
| --- | --- | --- | --- |
| actionId | 実行するアクションのID、または識別子を指定します。 | 必須 | なし |
| params | アクションに渡すパラメータを指定します。オブジェクト形式で複数のパラメータを設定可能です。 | 任意 |  |
| openAndRun | 新しいタブでアクションを開き、同時に実行するかどうかを指定します。 `true` の場合、画面移動直後にアクションが自動で実行されます。 | 任意 | `false` |
| type | リンクの表示形式を指定します。 `button` または `text` を選択可能です。 `type="button"` の場合、 `size` プロパティでサイズを指定できます。 | 任意 | `text` |
| newTab | アクションを新しいタブで開くかどうかを指定します。 `true` の場合、新しいタブで開きます。 | 任意 | `false` |
| children | リンクのテキストを指定します。 | 必須 | なし |
| color | リンクの色を指定します。 `blue` または `red` を選択可能です。 | 任意 | `blue` |
| size | `type="button"` の場合のみ適用されます。ボタンのサイズを指定します。 `xs` 、 `sm` 、 `md` 、 `lg` 、 `xl` の中から選択可能です。 | 任意 | `md` |

[Link](/view/code_editor/link/view_link/) [ViewLink](/view/code_editor/link/view_view_link/)
---
[ビュー](/view/)

[コードエディター](/view/code_editor/)

リンク

Link

# Link

Linkコンポーネントは、ユーザーがクリックすることで指定されたURLに移動するためのコンポーネントです。ボタンまたはテキストの形式で表示が可能です。

## 基本的な使い方 [](#基本的な使い方)

```
import { Card, Link } from "@basemachina/view";
 
const App = () => {
  return (
    <Card>
      <Link
        href="https://www.example.com"
        color="blue"
        type="text"
        newTab={true}
      >
        Visit example
      </Link>
    </Card>
  );
};
 
export default App;
```

![使用例](/images/view/link/usage.png)

## 詳細なインターフェース [](#詳細なインターフェース)

| 名前 | 説明 | 必須・任意 | デフォルト値 |
| --- | --- | --- | --- |
| href | リンク先のURLを指定します。 | 必須 | なし |
| type | リンクの表示スタイルを指定します。 `button` または `text` を選択可能です。 `type="button"` の場合、 `size` プロパティでサイズを指定できます。 | 任意 | `text` |
| newTab | リンクを新しいタブで開くかどうかを指定します。 `true` の場合、新しいタブで開きます。 | 任意 | `true` |
| children | リンクのテキストを指定します。 | 必須 | なし |
| color | リンクの色を指定します。 `blue` または `red` を選択可能です。 | 任意 | `blue` |
| size | `type="button"` の場合のみ適用されます。ボタンのサイズを指定します。 `xs` 、 `sm` 、 `md` 、 `lg` 、 `xl` の中から選択可能です。 | 任意 | `md` |

[Input](/view/code_editor/form/view_input/) [ActionLink](/view/code_editor/link/view_action_link/)
---
[ビュー](/view/)

[コードエディター](/view/code_editor/)

リンク

ViewLink

# ViewLink

ViewLinkコンポーネントは、ビューに移動するためのリンクを生成するためのコンポーネントです。ボタンまたはテキストの形式で表示が可能です。

## 基本的な使い方 [](#基本的な使い方)

```
import { Card, ViewLink } from "@basemachina/view";
 
const App = () => {
  return (
    <Card>
      <ViewLink
        viewId="displayIdExample"
        type="text"
        newTab={true}
        color="blue"
      >
        遷移先のタイトル
      </ViewLink>
    </Card>
  );
};
 
export default App;
```

![使用例](/images/view/viewlink/usage.png)

## 詳細なインターフェース [](#詳細なインターフェース)

| 名前 | 説明 | 必須・任意 | デフォルト値 |
| --- | --- | --- | --- |
| viewId | 移動先のビューの識別子を指定します。 | 必須 | なし |
| params | 移動先のビューに渡すパラメータを指定します。 | 任意 |  |
| type | リンクの表示形式を指定します。 `button` または `text` を選択可能です。 `type="button"` の場合、 `size` プロパティでサイズを指定できます。 | 任意 | `text` |
| newTab | リンクを新しいタブで開くかどうかを指定します。 `true` の場合、新しいタブで開きます。 | 任意 | `false` |
| children | リンクのテキストを指定します。 | 必須 | なし |
| color | リンクの色を指定します。 `blue` または `red` を選択可能です。 | 任意 | `blue` |
| size | `type="button"` の場合のみ適用されます。ボタンのサイズを指定します。 `xs` 、 `sm` 、 `md` 、 `lg` 、 `xl` の中から選択可能です。 | 任意 | `md` |

[ActionLink](/view/code_editor/link/view_action_link/) [Image](/view/code_editor/media/view_image/)
---
[ビュー](/view/)

[コードエディター](/view/code_editor/)

画像・動画

Avatar

# Avatar

Avatarコンポーネントは、アバター画像を表示するためのコンポーネントです。

## 基本的な使い方 [](#基本的な使い方)

```
import { Card, Avatar } from "@basemachina/view";
 
const App = () => {
  return (
    <Card>
      <Avatar
        url="https://example.com/images/cute_cat.png"
        size="lg"
        shape="circle"
      />
    </Card>
  );
};
 
export default App;
```

![使用例](/images/view/avatar/usage.png)

## 詳細なインターフェース [](#詳細なインターフェース)

| 名前 | 説明 | 必須・任意 | デフォルト値 |
| --- | --- | --- | --- |
| url | アバターの画像のURLを指定します。 | 必須 | なし |
| size | アバターのサイズを指定します。 `sm`, `md`, `lg`, `xl` のいずれかを指定できます。 | 任意 | `md` |
| shape | アバターの形状を指定します。 `circle` または `square` を指定できます。 | 任意 | `circle` |

[Video](/view/code_editor/media/view_video/) [useExecuteAction](/view/code_editor/function/view_use_execute_action/)
---
[ビュー](/view/)

[コードエディター](/view/code_editor/)

画像・動画

Image

# Image

Imageコンポーネントは、画像を表示するためのコンポーネントです。

## 基本的な使い方 [](#基本的な使い方)

```
import { Card, Image } from "@basemachina/view";
 
const App = () => {
  return (
    <Card>
      <Image url="https://example.com/images/cute_cat.png" objectFit="cover" />
    </Card>
  );
};
 
export default App;
```

![使用例](/images/view/image/usage.png)

## 詳細なインターフェース [](#詳細なインターフェース)

| 名前 | 説明 | 必須・任意 | デフォルト値 |
| --- | --- | --- | --- |
| url | 表示する画像のURLを指定します。 | 必須 | なし |
| objectFit | 画像の表示方法を指定します。 `cover`, `contain`, `fill`, `none`, `scale-down` のいずれかを指定できます。 | 任意 | `cover` |

[ViewLink](/view/code_editor/link/view_view_link/) [Video](/view/code_editor/media/view_video/)
---
[ビュー](/view/)

[コードエディター](/view/code_editor/)

画像・動画

Video

# Video

Videoコンポーネントは、動画を表示するためのコンポーネントです。

## 基本的な使い方 [](#基本的な使い方)

```
import { Card, Video } from "@basemachina/view";
 
const App = () => {
  return (
    <Card>
      <Video url="https://example.com/videos/cute_cat.mp4" />
    </Card>
  );
};
 
export default App;
```

![使用例](/images/view/video/usage.png)

## 詳細なインターフェース [](#詳細なインターフェース)

| 名前 | 説明 | 必須・任意 | デフォルト値 |
| --- | --- | --- | --- |
| url | 表示する動画のURLを指定します。 | 必須 | なし |

[Image](/view/code_editor/media/view_image/) [Avatar](/view/code_editor/media/view_avatar/)
---
[ビュー](/view/)

[コードエディター](/view/code_editor/)

その他

Accordion

# Accordion

Accordionコンポーネントは、開閉可能なコンテンツを表示するためのコンポーネントです。

## 基本的な使い方 [](#基本的な使い方)

```
import { Card, Accordion } from "@basemachina/view";
 
const App = () => {
  return (
    <Accordion title="タイトル">
      <Card>コンテンツ</Card>
    </Accordion>
  );
};
 
export default App;
```

![使用例](/images/view/accordion/usage.png)

## 詳細なインターフェース [](#詳細なインターフェース)

| 名前 | 説明 | デフォルト値 |
| --- | --- | --- |
| title | アコーディオンメニューのボタンに表示するテキストを指定します。 | 必須 |
| defaultOpen | アコーディオンメニューを初めから開いた状態にするかどうかをbooleanで設定します。 | `false` |
| children | アコーディオンメニュー内に表示するコンテンツを指定します。 | なし |

[useCheckActionAvailability](/view/code_editor/function/view_use_check_action_availability/) [Alert](/view/code_editor/other/view_alert/)
---
[ビュー](/view/)

[コードエディター](/view/code_editor/)

その他

Alert

# Alert

Alertコンポーネントは、アラートを表示するためのコンポーネントです。

## 基本的な使い方 [](#基本的な使い方)

```
import { Card, Alert } from "@basemachina/view";
 
const App = () => {
  return (
    <Card>
      <Alert message="メッセージ" color="blue" />
    </Card>
  );
};
 
export default App;
```

![使用例](/images/view/alert/usage.png)

## 詳細なインターフェース [](#詳細なインターフェース)

| 名前 | 説明 | 必須・任意 | デフォルト値 |
| --- | --- | --- | --- |
| message | アラートに表示するテキストを指定します。 | 必須 | なし |
| color | アラートの色を指定します。 `blue`, `red`, `green`, `yellow`, `gray` のいずれかを指定できます。 | 任意 | `blue` |

[Accordion](/view/code_editor/other/view_accordion/) [Badge](/view/code_editor/other/view_badge/)
---
[ビュー](/view/)

[コードエディター](/view/code_editor/)

その他

Badge

# Badge

Badgeコンポーネントは、バッジを表示するためのコンポーネントです。

## 基本的な使い方 [](#基本的な使い方)

```
import { Card, Badge } from "@basemachina/view";
 
const App = () => {
  return (
    <Card>
      <Badge title="タイトル" color="blue" />
    </Card>
  );
};
 
export default App;
```

![使用例](/images/view/badge/usage.png)

## 詳細なインターフェース [](#詳細なインターフェース)

| 名前 | 説明 | デフォルト値 |
| --- | --- | --- |
| title | バッジに表示するテキストを指定します。 | 必須 |
| color | バッジの色を指定します。 `blue`, `red`, `green`, `yellow`, `gray` のいずれかを指定できます。 | `blue` |

[Alert](/view/code_editor/other/view_alert/) [ClipboardButton](/view/code_editor/other/view_clipboard_button/)
---
[ビュー](/view/)

[コードエディター](/view/code_editor/)

その他

ClipboardButton

# ClipboardButton

ClipboardButtonコンポーネントは、テキストをクリップボードにコピーするためのボタンコンポーネントです。

## 基本的な使い方 [](#基本的な使い方)

```
import { ClipboardButton } from "@basemachina/view";
 
const App = () => {
  return <ClipboardButton text="コピーしたいテキスト" />;
};
 
export default App;
```

![使用例](/images/view/clipboard_button/usage.png)

## 詳細なインターフェース [](#詳細なインターフェース)

| 名前 | 説明 | デフォルト値 |
| --- | --- | --- |
| text | クリップボードにコピーするテキストを指定します。 | 必須 |

[Badge](/view/code_editor/other/view_badge/) [Heading](/view/code_editor/other/view_heading/)
---
[ビュー](/view/)

[コードエディター](/view/code_editor/)

その他

Heading

# Heading

Headingコンポーネントは、見出しを表示するためのコンポーネントです。

## 基本的な使い方 [](#基本的な使い方)

```
import { Card, Heading } from "@basemachina/view";
 
const App = () => {
  return (
    <Card>
      <Heading text="タイトル" size="md" />
    </Card>
  );
};
 
export default App;
```

![使用例](/images/view/heading/usage.png)

## 詳細なインターフェース [](#詳細なインターフェース)

| 名前 | 説明 | デフォルト値 |
| --- | --- | --- |
| text | 見出しに表示するテキストを指定します。 | 必須 |
| size | 見出しの大きさを指定します。 `md`, `lg`, `xl` のいずれかを指定できます。 | `md` |

[ClipboardButton](/view/code_editor/other/view_clipboard_button/) [LoadingIndicator](/view/code_editor/other/view_loading_indicator/)
---
[ビュー](/view/)

[コードエディター](/view/code_editor/)

その他

LoadingIndicator

# LoadingIndicator

LoadingIndicatorコンポーネントは、インジケーターを表示するためのコンポーネントです。

## 基本的な使い方 [](#基本的な使い方)

```
import { Card, LoadingIndicator } from "@basemachina/view";
 
const App = () => {
  return (
    <Card>
      <LoadingIndicator type="spin" color="#6366f1" />
    </Card>
  );
};
 
export default App;
```

![使用例](/images/view/indicator/usage.png)

## 詳細なインターフェース [](#詳細なインターフェース)

| 名前 | 説明 | デフォルト値 |
| --- | --- | --- |
| type | インジケーターの種類を指定します。 `blank`, `balls`, `bars`, `bubbles`, `cubes`, `cylon`, `spin`, `spinningBubbles`, `spokes` のいずれかを指定できます。 | `spin` |
| color | インジケーターの色を指定します。カラーコードで指定できます。 | `#6366f1` |

[Heading](/view/code_editor/other/view_heading/) [Pagination](/view/code_editor/other/view_pagination/)
---
[ビュー](/view/)

[コードエディター](/view/code_editor/)

その他

Pagination

# Pagination

Paginationコンポーネントは、ページネーションをするためのコンポーネントです。

## 基本的な使い方 [](#基本的な使い方)

```
import { useState } from "react";
import { Card, Pagination } from "@basemachina/view";
 
const App = () => {
  const [page, setPage] = useState(1);
  return (
    <Card>
      <Pagination
        currentPage={page}
        itemsPerPage={10}
        totalItems={100}
        onChange={(page) => setPage(page)}
      />
    </Card>
  );
};
 
export default App;
```

![Paginationコンポーネントの基本的な使用例](/images/view/pagination/usage.png)

## 最初と最後のページへ移動するボタンを表示する [](#最初と最後のページへ移動するボタンを表示する)

`showFirstLastButtons` を `true` に設定すると、最初と最後のページへ移動するボタンを表示できます。

```
import { useState } from "react";
import { Card, Pagination } from "@basemachina/view";
 
const App = () => {
  const [page, setPage] = useState(1);
  return (
    <Card>
      <Pagination
        showFirstLastButtons
        currentPage={page}
        itemsPerPage={10}
        totalItems={100}
        onChange={(page) => setPage(page)}
      />
    </Card>
  );
};
 
export default App;
```

![showFirstLastButtonsを使用したPaginationコンポーネントの使用例](/images/view/pagination/show_first_last_buttons_usage.png)

## 詳細なインターフェース [](#詳細なインターフェース)

| 名前 | 説明 | デフォルト値 |
| --- | --- | --- |
| currentPage | 現在のページ番号を指定します。 | 必須 |
| itemsPerPage | 1ページあたりのアイテム数を指定します。 | 必須 |
| totalItems | 全アイテム数を指定します。 | 必須 |
| onChange | ページ変更時に実行する関数を指定します。 | 必須 |
| siblingCount | 現在のページの前後に表示するページ番号の数を指定します。 | 2 |
| showFirstLastButtons | 最初と最後のページへ移動するボタンを表示するかどうかを指定します。 | false |

[LoadingIndicator](/view/code_editor/other/view_loading_indicator/) [PaginationPageText](/view/code_editor/other/view_pagination_page_text/)
---
[ビュー](/view/)

[コードエディター](/view/code_editor/)

その他

PaginationPageText

# PaginationPageText

PaginationPageTextコンポーネントは、ページネーションの件数を表示するためのコンポーネントです。

現在表示されているアイテムの範囲と全体の件数を「1 - 10件（全100件）」のような形式で表示します。
通常、 [Pagination](/view/code_editor/other/view_pagination/) コンポーネントと組み合わせて使用することで、ユーザーにページネーションの状態をわかりやすく伝えることができます。

## 基本的な使い方 [](#基本的な使い方)

PaginationコンポーネントとPaginationPageTextコンポーネントを併用して、ページネーション機能と件数表示を実装します。
両方のコンポーネントに同じ `currentPage` 、 `itemsPerPage` 、 `totalItems` の値を渡すことで、ページ操作と件数表示が連動します。

```
import { useState } from "react";
import { Card, Pagination, PaginationPageText } from "@basemachina/view";
 
const App = () => {
  const [page, setPage] = useState(1);
  return (
    <Card>
      <div className="flex items-center space-x-2">
        <Pagination
          currentPage={page}
          itemsPerPage={10}
          totalItems={100}
          onChange={(page) => setPage(page)}
        />
        <PaginationPageText
          currentPage={page}
          itemsPerPage={10}
          totalItems={100}
        />
      </div>
    </Card>
  );
};
 
export default App;
```

![PaginationPageTextコンポーネントの使用例](/images/view/pagination_page_text/usage.png)

## 詳細なインターフェース [](#詳細なインターフェース)

| 名前 | 説明 | 必須・任意 | デフォルト値 |
| --- | --- | --- | --- |
| currentPage | 現在のページ番号を指定します。 | 必須 | なし |
| itemsPerPage | 1ページあたりのアイテム数を指定します。 | 必須 | なし |
| totalItems | 全アイテム数を指定します。 | 必須 | なし |

[Pagination](/view/code_editor/other/view_pagination/) [外部ライブラリ](/view/code_editor/external_libs/)
---
[ビュー](/view/)

バージョン/有効化設定

# バージョン/有効化設定

## バージョン/有効化設定とは [](#バージョン有効化設定とは)

ビューを保存すると、その内容が「バージョン」として保存されます。この機能では、 [環境](/admin/environment/what_is_environment/) ごとに次の2つを管理できます。

- どのバージョンのビューを使うか
- ビューを有効にするか（無効にすると、その環境ではビューを表示しません）

これにより、ビューを安全にリリースできます。バージョンは、たとえば次のように使い分けられます。

- 開発環境：常に最新のバージョンを使用して開発
- 検証環境：リリース候補のバージョンで動作確認
- 本番環境：動作確認済みの安定したバージョンを固定して使用

コード取得設定を使って外部のGitリポジトリでコードを管理しているビューは、バージョン管理・有効化設定の対象外です。

## 事前準備 [](#事前準備)

この機能を使用するには、プロジェクト設定で「開発環境」を指定する必要があります。詳細は、 [開発環境](/admin/environment/development_environment/) を参照してください。

## 機能説明 [](#機能説明)

### バージョンが作成されるタイミング [](#バージョンが作成されるタイミング)

開発環境が設定されたプロジェクトでは、ビューを保存するたびに自動的に新しいバージョンが作成されます。

### バージョン管理されるビューの設定項目 [](#バージョン管理されるビューの設定項目)

バージョンごとに保存される項目は、ビューの作成方法によって異なります。

ビジュアルエディターで作成したビューの場合、次の項目が保存されます。

- ビューの名前
- 画面の構成
- クエリパラメータの定義

コードエディターで作成したビューの場合、次の項目が保存されます。

- ビューの名前
- ビューのコード

### バージョン/有効化設定を変更できる権限 [](#バージョン有効化設定を変更できる権限)

プロジェクト管理者、開発責任者、アクション運用責任者はバージョン/有効化設定を変更できます。詳しくは [プロジェクトの各設定の管理権限](/authorities/#%E3%83%97%E3%83%AD%E3%82%B8%E3%82%A7%E3%82%AF%E3%83%88%E3%81%AE%E5%90%84%E8%A8%AD%E5%AE%9A%E3%81%AE%E7%AE%A1%E7%90%86%E6%A8%A9%E9%99%90) をご参照ください。

## 設定方法 [](#設定方法)

### ビューのバージョン/有効化設定画面 [](#ビューのバージョン有効化設定画面)

ビュー一覧の各行にある「バージョン設定」ボタンをクリックすると、ビューのバージョン/有効化設定画面に移動します。

![ビュー一覧の各行にある「バージョン設定」ボタン](/images/view_versions/link_to_update_environment_view_settings.png)

この画面では、選択したビューの、各環境におけるバージョン/有効化設定をまとめて変更できます。

![ビューのバージョン/有効化設定画面](/images/view_versions/update_environment_view_settings.png)

### ビューのバージョン/有効化一括設定画面 [](#ビューのバージョン有効化一括設定画面)

ビュー一覧のヘッダーにある「ビューのバージョン/有効化一括設定」ボタンをクリックすると、一括設定画面に移動します。

![ビュー一覧ヘッダーの「ビューのバージョン/有効化一括設定」ボタン](/images/view_versions/link_to_update_environment_view_settings_bulk.png)

この画面では、現在利用中の環境の、各ビューのバージョン/有効化設定をまとめて変更できます。「全ビューを最新バージョンに設定」ボタンで全ビューを常に最新のバージョンを使う設定に、「全ビューを有効化する」ボタンで全ビューを有効な状態に、それぞれ一括で変更できます。

![ビューのバージョン/有効化一括設定画面](/images/view_versions/update_environment_view_settings_bulk.png)

設定を変更したら、「保存する」ボタンをクリックして保存します。

現在の環境が開発環境の場合、この画面の設定は変更できません。

### バージョンを環境別に切り替える [](#バージョンを環境別に切り替える)

![バージョン設定画面のバージョンのセレクトボックス](/images/view_versions/version_select_box.png)

環境・ビューごとに使用するバージョンを切り替えることができます。開発環境では、常に最新のバージョンが使用される設定で固定されており、変更はできません。

#### 常に最新のバージョンを使う [](#常に最新のバージョンを使う)

デフォルトの設定です。ビューが更新されるたびに自動で最新のバージョンが適用されるため、都度バージョンを切り替えることなく開発を進めることができます。

#### 特定のバージョンを使う [](#特定のバージョンを使う)

特定のバージョンを選択して使用できます。これにより、テスト済みの安定したバージョンを本番環境に適用するなど、段階的なリリースを安全に進められます。

## ビューの有効化 / 無効化 [](#ビューの有効化--無効化)

環境ごとに、ビューを有効・無効にできます。無効化したビューは、その環境では表示されません。

開発環境ではビューを無効化できません。

[型定義ファイルのダウンロード](/view/code_editor/download_dts_file/) [ナビゲーション](/navigation/)
---
[ビュー](/view/)

ビジュアルエディター

# ビジュアルエディターとは

ビジュアルエディターは、画面上の直感的な操作によってビューを作成するためのツールです。
ビジュアルエディターによって、 [アクション](/action/) を実行するためのフォームや結果を表示するテーブルなどを直感的に配置でき、典型的な管理画面を素早く簡単に作成することが可能になります。

## 基本的な使い方 [](#基本的な使い方)

ここでは、「【サンプル】ユーザーの一覧取得」という自動で作成されたアクションを使ってユーザー一覧を表示する画面を作成することで、
ビジュアルエディターの基本的な使い方を学びます。
各種コンポーネントの詳しい使い方は後ほど「 [コンポーネント](/view/visual_editor/components/) 」をご覧いただくこととし、ここでは大まかな作成フローを説明いたします。

### 作成画面へ移動 [](#作成画面へ移動)

まず、ビューの一覧・作成画面には画面右上の下記のアイコンをクリックすることで移動できます。

![アイコン](/images/what_is_view/menubar_icon.png)

「ビューの一覧」画面から、「ビジュアルエディターで作成」ボタンをクリックすることで、ビューの作成画面へ移動します。

![ビジュアルエディターで作成](/images/visual_editor/create_with_ve.png)

### 名前と識別子を設定する [](#名前と識別子を設定する)

ビューの「名前」と「識別子」を設定します。名前はビューの一覧画面上でのみ使われる値で、検索する際にも利用できます。
識別子はビューのURLとして使われるほか、別のビューからリンクを貼るときにも活用できます（詳細は「 [テーブル - 列のカスタマイズ](/view/visual_editor/components/action_table/#%E5%88%97%E3%81%AE%E3%82%AB%E3%82%B9%E3%82%BF%E3%83%9E%E3%82%A4%E3%82%BA) 」をご覧ください）。

画面左上の編集アイコンをクリックすると、設定画面が開きます。
ここでは、名前を「ユーザー一覧」、識別子を「user-list」とします。

![設定画面を開くボタン](/images/visual_editor/edit_basic_setting_button.png)

![設定画面](/images/visual_editor/basic_setting.png)

### コンポーネントの追加 [](#コンポーネントの追加)

ユーザーの一覧をテーブルで表示してみましょう。
左側の「コンポーネント一覧」の「追加」ボタンをクリックするとコンポーネント選択画面が開くので、そこから「テーブル」を選択します。

![コンポーネント追加](/images/visual_editor/add_component.png)

![コンポーネント選択画面](/images/visual_editor/component_selection.png)

すると、左側の「コンポーネント一覧」がテーブルの設定に切り替わるので、アクション設定からアクションを選択します。
ここで選択したアクションはビューを表示したタイミングで実行され、アクションの結果がテーブルに表示されます。
ここでは「【サンプル】ユーザーの一覧取得」を選択します。

![アクション選択](/images/visual_editor/table_config_example.png)

アクションを選択できたら、「完了」ボタンをクリックしてください。そうすると、右側の「ここにプレビューが表示されます」と書かれていたエリアにテーブルが表示されます。
画面右側はプレビューになっており、コンポーネントを追加したり設定を変更すると、変更内容が反映されます。

![テーブル](/images/visual_editor/table_preview.png)

### ビューを保存する [](#ビューを保存する)

画面右上の「保存」ボタンをクリックするとビューの作成が完了し、自動でビューの一覧画面へ移動します。
一覧画面から「ユーザー一覧」という名前のビューの行をクリックすると、作成したビューを閲覧できます。また、行の中の「編集」というリンクをクリックすると作成したビューの編集画面へ移動します。

## 高度な使い方 [](#高度な使い方)

以上がビジュアルエディターの基本的な使い方となります。
今回作成したのは非常にシンプルな画面ですが、ビジュアルエディターはより高度な機能を提供しています。

- テーブルの列をカスタマイズしてアクションや別のビューへのリンクを表示
  - ユーザー一覧から、特定のユーザーの詳細情報を表示する画面への移動などが実現可能です
- フォームコンポーネントを設置して、そこから実行したアクションの結果をテーブルコンポーネントに表示する
  - データ検索用のアクションを用意すれば、検索画面としてご利用になれます

[ビュー](/view/) [コンポーネント](/view/visual_editor/components/)
---
[ビュー](/view/)

[ビジュアルエディター](/view/visual_editor/)

コンポーネント

# コンポーネント

コンポーネントはビューの画面を構成する部品です。ビジュアルエディターでは、コードを書くことなく直感的な操作によってコンポーネントを配置してビューを作成できます。

コンポーネントにはいくつかの種類があります。

- [フォーム](/view/visual_editor/components/action_form/)
- [テーブル](/view/visual_editor/components/action_table/)
- [詳細テーブル](/view/visual_editor/components/action_detail_table/)
- [タブグループ](/view/visual_editor/components/tab/)

それぞれ用途や独自の機能を持っていますが、詳細はそれぞれのコンポーネントのページをご覧ください。
このページでは、すべてのコンポーネントに共通する操作について説明します。

## コンポーネントを追加する [](#コンポーネントを追加する)

画面左側にはコンポーネントの一覧が表示されています。
コンポーネントの一覧の右下に「追加」ボタンがあるので、それをクリックするとコンポーネント選択画面が開きます。
そこで追加したいコンポーネントの種類を選択すると、コンポーネントの一覧が設定画面に切り替わります。

![コンポーネント追加](/images/visual_editor/add_component.png)

![コンポーネント選択画面](/images/visual_editor/component_selection.png)

## 各種コンポーネントに共通の設定 [](#各種コンポーネントに共通の設定)

### 名前 [](#名前)

「名前」はコンポーネント一覧に表示される名前で、ビューには表示されないものです。

![名前の設定](/images/visual_editor/components/component_name.png)

### タイトル [](#タイトル)

「タイトル」はビューに表示されるコンポーネントの見出しです。

![タイトルの設定](/images/visual_editor/components/component_title.png)

### 補足事項 [](#補足事項)

「補足事項」は、コンポーネントのタイトルの下に表示する補足説明です。
入力時の注意点や、表示しているデータの意味などを利用者へ伝えるために使えます。
「補足事項を表示する」をオンにすると、表示内容とそのスタイルを設定できます。

![補足事項の設定](/images/visual_editor/components/component_description.png)

#### スタイル [](#スタイル)

表示内容のスタイルは、次の3種類から選択できます。

- **テキスト**: 装飾なしのテキストとして表示します。
- **警告**: 黄色の警告として表示します。注意を促したいときに使います。
- **情報**: 青色の情報として表示します。補足的な案内に使います。

#### 表示内容に値を埋め込む [](#表示内容に値を埋め込む)

表示内容には `{{ }}` で囲んでテンプレート変数を埋め込めます。クエリパラメーターやアクションの実行結果などの値を、表示内容に動的に表示できます。

利用できる変数は次のとおりです。

- `urlQueries`: [クエリパラメーター](/view/visual_editor/query_parameter_setting/) の値
- `vars`: 変数
- `results`: アクションの実行結果（フォームの場合は [初期値用アクション](/view/visual_editor/components/action_form/#%E5%88%9D%E6%9C%9F%E5%80%A4%E7%94%A8%E3%82%A2%E3%82%AF%E3%82%B7%E3%83%A7%E3%83%B3) の実行結果）
- `success`: `results[0].success`

タブグループのコンポーネントはアクションを持たないため、 `results` と `success` は利用できません。 `urlQueries` と `vars` のみ利用できます。

たとえば、クエリパラメーターの `user_id` を表示内容に埋め込むには、次のように書きます。

```
ユーザーID: {{ urlQueries.user_id }}
```

ネストしたキーはドット記法でつなげて参照します。 `-` （ハイフン）を含むキー名もそのまま指定できます。

```
ユーザー名: {{ urlQueries.user-name }}
```

配列の要素は、ブラケットにインデックスを指定して参照します。

```
1件目の結果: {{ results[0].success }}
```

テンプレート変数で参照できる値の考え方は「 [式](/view/visual_editor/expression/) 」と同様です。あわせてご覧ください。

#### 表示内容の種類（フォームのみ） [](#表示内容の種類フォームのみ)

フォームのコンポーネントでは、「表示内容の種類」を次の2つから選択できます。

- **カスタム**: 入力した表示内容をそのまま表示します。
- **アクションの説明文**: フォームに紐づくアクションの説明文を表示します。

## コンポーネントの編集を完了する [](#コンポーネントの編集を完了する)

設定が完了したら、「完了」ボタンをクリックすると、右側のプレビューに変更が反映され、設定画面が「コンポーネント一覧」に切り替わります。
ただし、設定内容に不備がある場合はエラーが表示され「コンポーネント一覧」には戻らないため、不備を修正したのち再度「完了」ボタンを押してください。

![削除・プレビューに反映・完了ボタン](/images/visual_editor/components/component_setting_action_buttons.png)

## プレビューに反映する [](#プレビューに反映する)

設定を完了せずに、右側のプレビューに変更を反映するためには「完了」ボタン左の「プレビューに反映」ボタンを押してください。
ただし、完了ボタンと同様、設定に不備がある場合は反映されませんのでご注意ください。

また、コンポーネントの設定画面には以下のようなタブがあり、タブを切り替えるタイミングでもプレビューに反映されます。

![タブ](/images/visual_editor/components/component_setting_tabs.png)

## コンポーネントを削除する [](#コンポーネントを削除する)

「プレビューに反映」ボタン左の「削除」ボタンを押すと、コンポーネントを削除できます。

## コンポーネントを編集する [](#コンポーネントを編集する)

コンポーネント一覧画面からコンポーネント名をクリックすると、作成時のようにそのコンポーネントの設定画面に切り替わります。

![編集](/images/visual_editor/components/component_edit.png)

[ビジュアルエディター](/view/visual_editor/) [フォーム](/view/visual_editor/components/action_form/)
---
[ビュー](/view/)

[ビジュアルエディター](/view/visual_editor/)

[コンポーネント](/view/visual_editor/components/)

詳細テーブル

# 詳細テーブル

詳細テーブルは、アクションの実行結果を画面に表示するためのコンポーネントです。
「テーブル」が複数のデータを一覧表示するためのコンポーネントであるのに対して、「詳細テーブル」は1つのデータを表示する目的で使われます。
管理画面で言うところの詳細画面を作成するために利用できます。

![詳細テーブルコンポーネントの例](/images/visual_editor/components/action_detail_table/example.png)

## アクション設定 [](#アクション設定)

実行結果を表示したいアクションの設定です。実行方法には2種類あります。

- コンポーネントの表示時に実行
- フォームで実行

### コンポーネントの表示時に実行 [](#コンポーネントの表示時に実行)

ビューを開いてコンポーネントが表示されるときに、選択したアクションが自動的に実行され、その結果が表示されます。

![コンポーネントの表示時に実行](/images/visual_editor/on_component_render.png)

#### 選択できないアクション [](#選択できないアクション)

以下の条件に該当するアクションは選択できません。

- ファイルパラメーターを持つ
- 非推奨の「システム値」パラメーターを持つ
- データソースが削除されている
- ジョブキューが設定されている（⚠️限定公開の機能です）

#### パラメーターの値 [](#パラメーターの値)

[パラメーター](/action/parameter/action_parameter/) を持つアクションを選択すると、アクションのパラメーターの値を入力できます。
入力された値はアクションを実行するときに使用されます。

![コンポーネントの表示時に実行 - パラメーターの値](/images/visual_editor/on_component_render_parameters.png)

##### 入力方法 [](#入力方法)

パラメーターの値は、アクション実行画面と同じフォームでの入力が可能です。利用できるフォームについては、各種 [パラメーター](/action/parameter/action_parameter/) のドキュメントをご覧ください。

また、「値を式で設定する」を有効にすると、JavaScriptを使って柔軟に値を設定できます。詳細については「 [式](/view/visual_editor/expression/) 」をご覧ください。

![値を式で設定する](/images/visual_editor/parameter_type_expression.png)

なお、式では以下の値が使用できます。値の詳しい説明についてはドキュメントの各セクションをご覧ください。

- [`urlQueries`](/view/visual_editor/expression/#urlqueries)

### フォームで実行 [](#フォームで実行)

「 [フォーム](/view/visual_editor/components/action_form/) 」コンポーネントで設定したアクションの結果を表示するオプションです。
アクションは自動ではなく、ビューでの画面操作によって実行されます。

![フォームで実行](/images/visual_editor/on_action_form_submit.png)

このオプションを利用する場合はフォームコンポーネントを選択する必要があります。
ビューからフォームを操作してアクションを実行すると、その実行結果が表示されます。

## アクションの実行結果の扱い [](#アクションの実行結果の扱い)

アクションの種類によっては実行結果が複数になる場合がありますが、デフォルトでは1番目の実行結果が表示されます。
例えば、 [MySQLアクション](/action/datasources/mysql_integration/) ではクエリを複数登録でき、それぞれのクエリに対応する実行結果がアクションの実行結果となります。

このようなケースでは、「結果の加工」機能を使うことでどの実行結果を表示するか選択できます。
詳細については [「結果の加工」のドキュメント](/view/visual_editor/result_transformation/) をご覧ください。

## コンポーネントが求めるアクションの実行結果の形式 [](#コンポーネントが求めるアクションの実行結果の形式)

コンポーネントにはそれぞれ、表示できる実行結果の形式が定められています。

詳細テーブルで表示可能なデータ形式は [JavaScriptのオブジェクト (opens in a new tab)](https://developer.mozilla.org/ja/docs/Web/JavaScript/Guide/Working_with_objects) です。
例えば、以下のようなデータが表示可能です。

```
{
  "id": 1,
  "email": "you-know-who@example.com",
}
```

逆に、実行結果がただの文字列や数字、配列であるような場合はエラーが表示されます。
以下は、実行結果が `"you-know-who@example.com"` という文字列の場合のエラーです。

![実行結果がただの文字列や数字、配列であるような場合のエラー](/images/visual_editor/components/action_detail_table/data_format_error.png)

こういった場合も、「 [結果の加工](/view/visual_editor/result_transformation/) 」を用いることで表示が可能になります。

## レイアウト方向 [](#レイアウト方向)

「レイアウト方向」では、詳細テーブルの表示レイアウトを次の2つから選択できます。

- **横並び**: ラベルと値を左右に並べます。幅の広い画面向けです。
- **縦並び**: ラベルの下に値を表示します。狭い領域や長文の値がある場合に読みやすくなります。

### 縦並びの最大列数 [](#縦並びの最大列数)

「縦並び」を選択した場合、「縦並びの最大列数」で項目を複数の列に分けて表示できます。
最大列数は1列から4列まで選択でき、画面幅に応じて列数は自動調整されます。

## 結果の加工 [](#結果の加工)

複数の実行結果を返すアクションを利用している場合は、「結果の加工」機能を使うことでどの結果を表示するか選択できます。
詳細については [「結果の加工」](/view/visual_editor/result_transformation/) をご覧ください。

## 項目のカスタマイズ [](#項目のカスタマイズ)

「項目のカスタマイズ」機能によって、以下のような詳細テーブルの表示内容の変更が可能になります。

- 項目名の変更
- 複数の項目の値を使って新しい項目を作る（例：「姓」と「名」の項目を結合して「名前」の項目を追加する）
- 項目の値をアクション実行画面やビューへのリンクにする

### デフォルトの項目 [](#デフォルトの項目)

「項目のカスタマイズ」が未設定の場合、詳細テーブルには自動で項目が追加されています。
実行結果であるオブジェクトのキーを項目名とし、その値を各項目の値として表示します。

アクションの実行結果が次のような場合を例に取ります。

```
{
  id: 1,
  name: "ベース太郎",
}
```

この場合、 `id` と `name` がオブジェクトのキーとなるので、この2つの項目が詳細テーブルに表示されます。

![「項目のカスタマイズ」未使用の場合の挙動](/images/visual_editor/components/action_detail_table/without_item_customization.png)

### 「項目のカスタマイズ」を使用した場合 [](#項目のカスタマイズを使用した場合)

「項目のカスタマイズ」を設定している場合は、設定した項目のみが詳細テーブルに表示されます。
つまり、上記の例で表示されていたデフォルトの `id` と `name` の項目は表示されず、明示的に追加された項目のみが表示されます。

### 項目の追加 [](#項目の追加)

設定画面上部の「追加」あるいは「一括追加」ボタンから項目を追加できます。

![項目の追加](/images/visual_editor/components/action_detail_table/add_item.png)

「追加」ボタンを押すと、新しい項目を設定できるようになります（詳しい設定方法は後述します）。

![空の項目の設定](/images/visual_editor/components/action_detail_table/empty_item_setting.png)

「一括追加」ボタンを押すと、「項目の一括追加」画面が開きます。

![項目の一括追加](/images/visual_editor/components/action_detail_table/add_multiple_items.png)

「項目の一括追加」画面にはデフォルトの項目名が一覧で表示されており、これらの中から必要に応じて項目を選択できます。
「追加」ボタンを押すと、選択した分の項目が追加されます。

### 項目の設定 [](#項目の設定)

#### 項目名 [](#項目名)

詳細テーブルの左側に表示される項目名を設定できます。

![項目名](/images/visual_editor/components/action_detail_table/item_name.png)

![項目名の例](/images/visual_editor/components/action_detail_table/item_name_example.png)

#### 項目の種類 [](#項目の種類)

表示する値をカスタマイズしたり、ビューやアクション実行画面へのリンクにするための設定です。
以下の中から選択します。

- 値の形式に合わせて表示
- 日時
- カスタムラベル
- アクション実行画面へのリンク
- ビューへのリンク
- リンク

##### 値の形式に合わせて表示 [](#値の形式に合わせて表示)

次のように、値に応じて自動で表示形式が決まります。

- 画像・動画と判別可能なURL：画像・動画として表示されます（詳細は「 [画像や動画の表示](/action/action_media_result/) 」をご覧ください）
- その他のURL：リンクテキストになります
- 画像・動画・PDFファイル：それぞれプレビューされます
- etc...

例えば、以下は `id` の項目が通常のテキスト、 `url` の項目がリンクテキストになる例です。

```
// アクションの実行結果
{
  id: 1,
  url: "https://basemachina.example/users/1",
}
```

![値の形式に合わせて表示の例](/images/visual_editor/components/action_detail_table/auto_item_example.png)

また、PDFの場合は次のようにプレビューが表示されます。

![PDFのプレビュー](/images/visual_editor/components/action_detail_table/auto_item_pdf_preview.png)

###### 値 - 項目から選択 [](#値---項目から選択)

「値の形式に合わせて表示」では項目の値に表示する値を設定できます。

![値](/images/visual_editor/components/action_detail_table/auto_item_value.png)

まず、「項目から選択」では、デフォルトの項目の値をそのまま使います。

![値 - 項目から選択の例](/images/visual_editor/components/action_detail_table/auto_item_value_key.png)

例えば、 `{ "id": 1, "name": "ベース太郎" }` という実行結果の場合は、 `name` を選択すると `ベース太郎` が表示されます。

###### 値 - 式で設定 [](#値---式で設定)

「式で設定」では、JavaScriptの式を使って値を設定できます。詳しくは [「式」](/view/visual_editor/expression/) をご覧ください。

なお、式では以下の値が使用できます。値の詳しい説明についてはドキュメントの各セクションをご覧ください。

- [`urlQueries`](/view/visual_editor/expression/#urlqueries)
- [`data`](/view/visual_editor/expression/#data)

###### 値 - 固定の値 [](#値---固定の値)

なんらかの固定の値を表示したい場合に利用できます。

###### スタイリング [](#スタイリング)

項目の値に応じて見た目を変更するためのスタイリングルールを設定できます。
ルールは複数追加でき、それぞれに「適用する値」と見た目を設定します。
項目の値が「適用する値」と完全一致する場合に、設定した見た目が適用されます。

現在はバッジに対応しており、バッジの色を選択できます。

![スタイリングの設定画面](/images/visual_editor/components/action_detail_table/auto_item_styling.png)

![バッジの表示例](/images/visual_editor/components/action_detail_table/auto_item_badge_example.png)

##### 日時 [](#日時)

このオプションを使うと、項目の日時の値を読みやすい形式で表示できます。
ISO8601形式またはタイムスタンプ（エポック秒）の日時の値を、指定した表示形式で表示します。

![「日時」の設定画面](/images/visual_editor/components/action_detail_table/cell_customization_datetime.png)

###### 値 [](#値)

表示する日時の値を設定します。

対応する値の形式は以下の通りです。

- ISO8601形式の文字列（例： `"2001-02-03T04:05:06Z"` ）
- タイムスタンプ（エポック秒）の数値（例： `1580702700` ）

空文字、 `null` 、 `undefined` の場合、何も表示されません。

###### 表示形式 [](#表示形式)

表示形式は以下から選択できます。

| 形式 | 表示例 |
| --- | --- |
| 年/月/日 | 2001/02/03 |
| 年/月/日 時:分 | 2001/02/03 04:05 |
| 年/月/日 時:分:秒 | 2001/02/03 04:05:06 |

##### カスタムラベル [](#カスタムラベル)

このオプションを使うと、項目の値を任意のラベルに変換して表示できます。
例えば、データ上は `1` や `2` といった数値で管理されているステータスを、「有効」「無効」といったわかりやすいラベルに変換して表示するような使い方が可能です。

###### 値 [](#値-1)

変換対象となる値を設定します。値の入力方法は「値の形式に合わせて表示」の値と同じ仕様に従います。

###### 変換する値とラベル [](#変換する値とラベル)

「変換する値」と「ラベル」のペアを複数設定できます。
項目の値が設定した「変換する値」と完全一致する場合に、対応する「ラベル」が表示されます。

###### バッジの色 [](#バッジの色)

各「変換する値」と「ラベル」のペアに対して、バッジの色を設定できます。
バッジの色を設定すると、ラベルが指定した色のバッジとして表示されます。

![カスタムラベルのバッジ色設定](/images/visual_editor/components/action_detail_table/custom_label_badge_color.png)

![カスタムラベルのバッジ表示例](/images/visual_editor/components/action_detail_table/custom_label_badge_example.png)

##### アクション実行画面へのリンク [](#アクション実行画面へのリンク)

このオプションを使うと、項目の値が選択したアクションの実行画面へのリンクになります。

![アクション実行画面へのリンク](/images/visual_editor/components/action_detail_table/action_link_item.png)

利用ケースとしては、詳細テーブルを使った詳細画面から、特定のデータを編集するアクションの実行画面を開くような使い方が可能になります。

###### リンクテキスト [](#リンクテキスト)

項目に表示されるアクション実行画面へのリンクのテキストに関する設定です。「値の形式に合わせて表示」の値と同じ仕様に従います。

###### パラメーターの初期値 [](#パラメーターの初期値)

選択したアクションのパラメーターに初期値を設定すると、フォームの初期値が入力された状態で実行画面を開くことが可能になります。
これも入力する値に関しては「値の形式に合わせて表示」の値と同じ仕様に従います。

ただし、「式」で設定する場合はパラメーターの種類に応じた適切な値を設定する必要があります。
詳しくは「 [式](/view/visual_editor/expression/#%E5%BC%8F%E3%81%AE%E7%B5%90%E6%9E%9C%E3%81%AE%E5%9E%8B%E3%81%AB%E3%81%A4%E3%81%84%E3%81%A6) 」をご覧ください。

###### 移動時に自動でアクションを実行する [](#移動時に自動でアクションを実行する)

リンクをクリックし実行画面へ移動したときに、そのまま自動でアクションを実行するかどうかを設定できます。

###### 新しいタブで開く [](#新しいタブで開く)

リンクをクリックしたときに、実行画面を新しいタブで開くかどうかを設定できます。

##### ビューへのリンク [](#ビューへのリンク)

このオプションを使うと、項目の値が選択したビューへのリンクになります。

![ビューへのリンク](/images/visual_editor/components/action_detail_table/view_link_item.png)

利用ケースとしては、詳細テーブルを使った詳細画面から、関連する他のビューを開くような使い方が可能になります。

###### リンクテキスト [](#リンクテキスト-1)

項目に表示されるビューへのリンクのテキストに関する設定です。「値の形式に合わせて表示」の値と同じ仕様に従います。

###### クエリパラメーター [](#クエリパラメーター)

ビューへのリンクに付与するクエリパラメーターを設定します。
クエリパラメーターは、複数の「名前」と「値」の組み合わせで設定します。

リンク先のビューに「 [クエリパラメーター設定](/view/visual_editor/query_parameter_setting/) 」を設定している場合は、そこで指定されたクエリパラメーターのみをここで設定します。
例えば、以下の例ではリンク先のビューで `user_id` というクエリパラメーターが設定されています。

![クエリパラメーター（リンク先のビューにクエリパラメーター設定がある場合）](/images/visual_editor/components/action_detail_table/view_link_item_query_parameter_with_setting.png)

リンク先のビューにクエリパラメーター設定がない場合は、自由にクエリパラメーターを設定できます。

![クエリパラメーター（リンク先のビューにクエリパラメーター設定がない場合）](/images/visual_editor/components/action_detail_table/view_link_item_query_parameter_without_setting.png)

どちらの場合も、クエリパラメーターの値の入力方法は「値の形式に合わせて表示」の値と同じ仕様に従います。

###### 新しいタブで開く [](#新しいタブで開く-1)

リンクをクリックしたときに、実行画面を新しいタブで開くかどうかを設定できます。

##### リンク [](#リンク)

「値の形式に合わせて表示」でもURLは自動でリンクになりますが、このオプションを使うとリンクテキストとリンク先URLをそれぞれ個別に設定できます。

###### リンクテキスト [](#リンクテキスト-2)

項目に表示されるリンクのテキストに関する設定です。「値の形式に合わせて表示」の値と同じ仕様に従います。

###### URL [](#url)

リンク先のURLに関する設定です。「値の形式に合わせて表示」の値と同じ仕様に従います。

###### クエリパラメーター [](#クエリパラメーター-1)

リンクのURLに付与するクエリパラメーターを設定します。
クエリパラメーターは、複数の「名前」と「値」の組み合わせで設定します。

クエリパラメーターの値の入力方法は「値の形式に合わせて表示」の値と同じ仕様に従います。

###### 新しいタブで開く [](#新しいタブで開く-2)

リンクをクリックしたときに、リンク先を新しいタブで開くかどうかを設定できます。

[テーブル](/view/visual_editor/components/action_table/) [タブグループ](/view/visual_editor/components/tab/)
---
[ビュー](/view/)

[ビジュアルエディター](/view/visual_editor/)

[コンポーネント](/view/visual_editor/components/)

フォーム

# フォーム

フォームは、アクションのパラメーターの値を入力し実行できる画面を作成するためのコンポーネントです。ビューの利用者は、必要に応じてパラメーターの値を入力し、実行ボタンを押すことでアクションを実行できます。

![フォームコンポーネントの例](/images/visual_editor/components/action_form/example.png)

アクションの実行結果は「 [テーブル](/view/visual_editor/components/action_table/) 」「 [詳細テーブル](/view/visual_editor/components/action_detail_table/) 」から利用できます。
詳しい利用方法についてはそれぞれのドキュメントをご参照ください。

## アクション設定 [](#アクション設定)

ビューの利用者が実行するアクションを選択します。

![アクション設定](/images/visual_editor/components/action_form/action_setting_action.png)

### 選択できないアクション [](#選択できないアクション)

以下の条件に該当するアクションは選択できません。

- 非推奨の「システム値」パラメーターを持つ
- データソースが削除されている
- ジョブキューが設定されている（⚠️限定公開の機能です）

### パラメーターの初期値 [](#パラメーターの初期値)

[パラメーター](/action/parameter/action_parameter/) を持つアクションを選択すると、アクションのパラメーターの初期値を入力できます。
入力した初期値は、ビューを開いたときに自動的にフォームの各要素に入力される値です。
ビューの利用者は初期値のままでもアクションを実行できますし、編集してからの実行も可能です。

⚠️

[ファイルパラメーター](/action/parameter/file_parameter/) に対しては初期値を設定できません。

#### 入力方法 [](#入力方法)

パラメーターの初期値は、アクション実行画面と同じフォームでの入力が可能です。利用できるフォームについては、各種 [パラメーター](/action/parameter/action_parameter/) をご覧ください。

各パラメーターは折りたたみ式のカードとして一覧表示されます。見出しを押すとカードが開き、初期値を入力できます。既定では閉じており、入力エラーがあるカードは自動的に開きます。パラメーターに説明がある場合は、カードを開くと初期値の入力欄の上に表示されます。

![パラメーターの初期値](/images/visual_editor/components/action_form/action_setting_action_parameters.png)

また、「値を式で設定する」を有効にすると、JavaScriptを使って柔軟に値を設定できます。詳細については「 [式](/view/visual_editor/expression/) 」をご覧ください。

![値を式で設定する](/images/visual_editor/parameter_type_expression.png)

なお、式では以下の値が使用できます。値の詳しい説明についてはドキュメントの各セクションをご覧ください。

- [`urlQueries`](/view/visual_editor/expression/#urlqueries)
- [`results`](/view/visual_editor/expression/#results)

`results` は「初期値用アクション」を設定すると利用可能になります。

### フォームに表示しない [](#フォームに表示しない)

パラメーターごとに「フォームに表示しない」チェックボックスを設定できます。
このチェックボックスを有効にすると、ビューの利用者にはそのパラメーターの入力欄が表示されなくなり、設定した初期値が自動的に使用されます。

たとえば、データの更新フォームを作成する場合に、更新対象のレコードIDをURLの [クエリパラメーター](/view/visual_editor/query_parameter_setting/) から受け取るケースを考えます。
IDパラメーターの初期値を「値を式で設定する」で `urlQueries.id` のように設定し、「フォームに表示しない」を有効にします。
これにより、ビューの利用者にはIDの入力欄が表示されず、URLから自動的にIDが設定された状態でアクションを実行できます。

### パラメーターのレイアウト [](#パラメーターのレイアウト)

関連するパラメーターをグループにまとめると、フォーム上で横並びに表示できます。たとえば「姓」と「名」や、「開始日」と「終了日」のようにセットで入力する項目を並べて配置できます。画面の幅が狭いときは、自動的に縦並びへ切り替わります。

初期値を入力するパラメーターの一覧上でグループ化します。横並びにしたいパラメーターのチェックボックスを2つ以上選び、一覧の上部にある「グループ化」ボタンを押すとグループになります。

- グループには名前を付けられます。名前を入力すると、フォームのグループの上に見出しとして表示されます。空欄のままにもできます。
- グループは複数作成できます。
- グループの中に別のグループを入れることはできません。
- ドラッグ&ドロップで、グループの位置や並び順を変更できます。パラメーターは、別のグループへ移したり、グループから出して単独の行にしたりもできます。
- グループの右上にあるグループ解除のアイコンを押すと、各パラメーターが単独の行に戻ります。

この設定はフォームの見た目だけに影響します。アクションに渡される値や実行の挙動は変わりません。

### フォームの表示時に初期値で実行する [](#フォームの表示時に初期値で実行する)

「フォームの表示時に初期値で実行する」オプションを有効にすると、フォームコンポーネントの表示時に初期値を使ってアクションを自動実行します。

このオプションは例えば、開いたときには全件を表示しその後絞り込める検索画面を作るようなケースでご活用いただけます。実行結果は「フォームで実行」を設定している「 [テーブル](/view/visual_editor/components/action_table/) 」や「 [詳細テーブル](/view/visual_editor/components/action_detail_table/) 」で表示されます。

ビューからフォームを手動で実行すると、新しい結果で上書きされます。

⚠️

[ファイルパラメーター](/action/parameter/file_parameter/) を持つアクションでは、ファイルに初期値を設定できないため、このオプションを有効にしても表示時の自動実行はスキップされます。

⚠️

[レビュー設定](/action/review/) が有効なアクションでは、このオプションは使用できません。

## 初期値用アクション [](#初期値用アクション)

初期値用アクションはフォームの初期値にアクションの実行結果を設定できる機能で、データを更新する画面などを作る際に使用できます。

![初期値用アクション](/images/visual_editor/components/action_form/initial_value_action.png)

### 選択できないアクション [](#選択できないアクション-1)

以下の条件に該当するアクションは選択できません。

- ファイルパラメーターを持つ
- 非推奨の「システム値」パラメーターを持つ
- データソースが削除されている
- ジョブキューが設定されている（⚠️限定公開の機能です）

### パラメーターの値 [](#パラメーターの値)

パラメーターを持つ初期値用アクションを実行するために、パラメーターの値を入力する必要があります。
初期値用アクションはビューが表示されたときに自動で実行されます。
入力した初期値用アクションのパラメーターの値はその際に使用され、ビューの利用者からは見えません。

#### 入力方法 [](#入力方法-1)

入力方法は「アクション設定」のパラメーターの初期値と同様です。ただし、「値を式で設定する」において初期値用アクションの結果を使うことはできません。

## レビュー設定が有効なアクション [](#レビュー設定が有効なアクション)

[レビュー設定](/action/review/) が紐づいているアクションをフォームに設定すると、ビューの利用者はアクションを直接実行する代わりにレビュー依頼ができます。

### アクション選択時の表示 [](#アクション選択時の表示)

レビュー設定が紐づいているアクションは、アクション選択のドロップダウンリストで「（レビュー設定あり）」というラベルが表示されます。

### レビューが有効な環境の確認 [](#レビューが有効な環境の確認)

レビュー設定が紐づいているアクションを選択すると、設定画面に「レビューが有効な環境」が表示されます。ここでは、どの環境でレビューが必要になるかを確認できます。

### ビュー利用者の操作 [](#ビュー利用者の操作)

レビューが有効な環境でビューを開くと、通常の「実行する」ボタンの代わりに「レビューを依頼する」ボタンが表示されます。ビューの利用者は、パラメーターの値を入力した後にレビュー依頼を作成できます。

レビュー依頼の詳細については「 [レビュー設定](/action/review/) 」をご覧ください。

## 実行後の動作 [](#実行後の動作)

フォームコンポーネントの実行が成功したときに、指定した別の画面へ自動で移動する設定です。移動先には、フォームの実行結果などを引き継いで渡すことができます。

たとえば、レコードの登録フォームで登録が成功した後に、作成されたレコードの詳細を表示するビューへ自動で移動できます。このとき、作成されたレコードのIDを移動先へ引き継げます。

画面移動を設定した場合、実行結果は移動先の画面で扱います。そのため、結果を表示するための「テーブル」「詳細テーブル」を同じビューに配置する必要はありません。

### 設定方法 [](#設定方法)

フォームコンポーネントの設定画面にある「実行後の動作」タブを開き、「実行成功時」の「別の画面へ移動する」を有効にします。続けて、移動先として「ビュー」または「アクション」を選択します。

この設定を有効にしない限り、フォームの挙動は変わりません。

![「実行後の動作」タブの設定画面](/images/visual_editor/components/action_form/post_execution_setting.png)

### 移動先がビューの場合 [](#移動先がビューの場合)

移動先のビューを選択し、必要に応じて移動先へ渡すクエリパラメーターを設定します。

- 移動先のビューに [クエリパラメーター設定](/view/visual_editor/query_parameter_setting/) がある場合は、各クエリパラメーターの値を入力できます。
- それ以外のビューでは、「クエリパラメーターを追加」から渡したいクエリパラメーターの名前と値を追加できます。

各クエリパラメーターの値は、「値を式で設定する」を有効にすると式（JavaScript）で動的に設定できます。たとえば、値の式に `results[0].success.data.id` と設定すると、フォームの実行結果からIDを取り出して移動先のクエリパラメーターに渡せます。

### 移動先がアクションの場合 [](#移動先がアクションの場合)

移動先のアクションを選択し、必要に応じてパラメーターの初期値を設定します。

- パラメーターの初期値は、「値を式で設定する」を有効にすると式（JavaScript）で設定できます。
- 「移動時に自動でアクションを実行する」を有効にすると、移動先のアクション実行画面を開いた時点で、設定した初期値を使ってアクションを自動的に実行します。

### 式で使用できる値 [](#式で使用できる値)

クエリパラメーターやパラメーターの初期値を式で設定する場合、以下の値を参照できます。値の詳しい説明については「 [式](/view/visual_editor/expression/) 」をご覧ください。

- [`results`](/view/visual_editor/expression/#results): フォームの実行結果。アクションの実行結果は複数になる場合があるため配列形式です（例： `results[0].success.data.id` ）。
- [`urlQueries`](/view/visual_editor/expression/#urlqueries): 現在のビューのクエリパラメーターの値。
- [`vars`](/view/visual_editor/expression/#vars): [変数・シークレット](/action/parameter/vars_secrets/) で設定した変数の値。

### 移動するタイミングと制約 [](#移動するタイミングと制約)

- 移動するのは、ビューの利用者がフォームからアクションを実行し、成功したときのみです。
- 「 [フォームの表示時に初期値で実行する](/view/visual_editor/components/action_form/#%E3%83%95%E3%82%A9%E3%83%BC%E3%83%A0%E3%81%AE%E8%A1%A8%E7%A4%BA%E6%99%82%E3%81%AB%E5%88%9D%E6%9C%9F%E5%80%A4%E3%81%A7%E5%AE%9F%E8%A1%8C%E3%81%99%E3%82%8B) 」による表示時の自動実行では移動しません。
- [レビュー設定](/action/review/) が有効なアクションは、この機能の対象外です。
- 移動先のビュー・アクションが削除されている場合や、式の評価でエラーが発生した場合は、移動せずにエラーメッセージを表示します。この場合もアクションの実行自体は成功しています。

### エディターのプレビューでの挙動 [](#エディターのプレビューでの挙動)

ビジュアルエディターのプレビューでは、実際には移動しません。移動するとエディターの編集内容が失われるため、フォームの実行が成功した後に「移動先を新しいタブで開く」リンクを表示します。設定にエラーがある場合は、その内容をプレビュー上に表示します。

### 実行後にメッセージを表示する [](#実行後にメッセージを表示する)

フォームからアクションを実行した後、成功時・失敗時それぞれで任意のメッセージをトーストで表示できます。実行結果に応じた内容を利用者へ伝えたい場合に使用します。

「実行後の動作」タブの「実行成功時」「実行失敗時」で、それぞれ「メッセージを表示する」を有効にして表示するメッセージを入力します。実行成功時のメッセージは画面移動と併用でき、両方を設定した場合は移動する前にメッセージを表示します。

メッセージを設定しない場合は、次の既定のメッセージを表示します。

- 実行成功時は「実行に成功しました」と表示します。
- 実行失敗時は「アクション『アクション名』の実行に失敗しました」と表示します。

#### メッセージ内で値を展開する [](#メッセージ内で値を展開する)

メッセージには `{{ }}` で囲んだテンプレート構文を記述でき、実行結果などの値を埋め込めます。たとえば `{{ success.data.name }}を登録しました` と設定すると、実行結果の値を差し込んだメッセージを表示します。

参照できる値は、実行成功時と実行失敗時で異なります。

実行成功時に参照できる値は次のとおりです。

- `results`: フォームの実行結果。アクションの実行結果は複数になる場合があるため配列形式です（例： `{{ results[0].success.data.id }}` ）。
- `success`: 先頭の実行結果の成功データです（ `results[0].success` と同じです）。
- `urlQueries`: 現在のビューのクエリパラメーターの値。
- `vars`: [変数・シークレット](/action/parameter/vars_secrets/) で設定した変数の値。

実行失敗時に参照できる値は次のとおりです。

- `results`: フォームの実行結果。
- `failure`: 先頭の実行結果の失敗データです（ `results[0].failure` と同じです。例： `{{ failure.message }}` ）。
- `urlQueries`: 現在のビューのクエリパラメーターの値。
- `vars`: [変数・シークレット](/action/parameter/vars_secrets/) で設定した変数の値。

指定した変数が見つからない場合や、表示できない値の場合は、その部分を展開せずにそのまま残します。ビジュアルエディターのプレビューでは、展開できなかった内容を通知します。

[コンポーネント](/view/visual_editor/components/) [テーブル](/view/visual_editor/components/action_table/)
---
[ビュー](/view/)

[ビジュアルエディター](/view/visual_editor/)

[コンポーネント](/view/visual_editor/components/)

テーブル

# テーブル

テーブルは、アクションの実行結果を画面に表示するためのコンポーネントです。
「詳細テーブル」が1つのデータを表示するためのコンポーネントであるのに対して、「テーブル」は複数のデータを一覧表示するためのコンポーネントです。
管理画面で言うところの一覧画面や検索画面を作成するために利用できます。

![テーブルコンポーネントの例](/images/visual_editor/components/action_table/example.png)

## アクション設定 [](#アクション設定)

実行結果を表示したいアクションの設定です。実行方法には2種類あります。

- コンポーネントの表示時に実行
- フォームで実行

### コンポーネントの表示時に実行 [](#コンポーネントの表示時に実行)

ビューを開いてコンポーネントが表示されるときに、選択したアクションが自動的に実行され、その結果が表示されます。

![コンポーネントの表示時に実行](/images/visual_editor/on_component_render.png)

#### 選択できないアクション [](#選択できないアクション)

以下の条件に該当するアクションは選択できません。

- ファイルパラメーターを持つ
- 非推奨の「システム値」パラメーターを持つ
- データソースが削除されている
- ジョブキューが設定されている（⚠️限定公開の機能です）

#### パラメーターの値 [](#パラメーターの値)

[パラメーター](/action/parameter/action_parameter/) を持つアクションを選択すると、アクションのパラメーターの値を入力できます。
入力された値はアクションを実行するときに使用されます。

![コンポーネントの表示時に実行 - パラメーターの値](/images/visual_editor/on_component_render_parameters.png)

##### 入力方法 [](#入力方法)

パラメーターの値は、アクション実行画面と同じフォームでの入力が可能です。利用できるフォームについては、各種 [パラメーター](/action/parameter/action_parameter/) のドキュメントをご覧ください。

また、「値を式で設定する」を有効にすると、JavaScriptを使って柔軟に値を設定できます。詳細については「 [式](/view/visual_editor/expression/) 」をご覧ください。

![値を式で設定する](/images/visual_editor/parameter_type_expression.png)

なお、式では以下の値が使用できます。値の詳しい説明についてはドキュメントの各セクションをご覧ください。

- [`urlQueries`](/view/visual_editor/expression/#urlqueries)

### フォームで実行 [](#フォームで実行)

「 [フォーム](/view/visual_editor/components/action_form/) 」コンポーネントで設定したアクションの結果を表示するオプションです。
アクションは自動ではなく、ビューでの画面操作によって実行されます。

![フォームで実行](/images/visual_editor/on_action_form_submit.png)

このオプションを利用する場合はフォームコンポーネントを選択する必要があります。
ビューからフォームを操作してアクションを実行すると、その実行結果が表示されます。

## アクションの実行結果の扱い [](#アクションの実行結果の扱い)

アクションの種類によっては実行結果が複数になる場合がありますが、デフォルトでは1番目の実行結果が表示されます。
例えば、 [MySQLアクション](/action/datasources/mysql_integration/) ではクエリを複数登録でき、それぞれのクエリに対応する実行結果がアクションの実行結果となります。

このようなケースでは、「結果の加工」機能を使うことでどの実行結果を表示するか選択できます。
詳細については [「結果の加工」のドキュメント](/view/visual_editor/result_transformation/) をご覧ください。

## コンポーネントが求めるアクションの実行結果の形式 [](#コンポーネントが求めるアクションの実行結果の形式)

コンポーネントにはそれぞれ、表示できる実行結果の形式が定められています。

テーブルで表示可能なデータ形式は [JavaScriptのオブジェクト (opens in a new tab)](https://developer.mozilla.org/ja/docs/Web/JavaScript/Guide/Working_with_objects) の配列です。
例えば、以下のようなデータが表示可能です。

```
[
  { id: 1, name: "ベース太郎" },
  { id: 2, name: "ベース花子" },
];
```

逆に、実行結果が文字列や数字の配列、ただのオブジェクトであるような場合はエラーが表示されます。
以下は、実行結果が `"[1, 2, 3]` という数字の配列の場合のエラーです。

![実行結果が数字の配列の場合のエラー](/images/visual_editor/components/action_table/data_format_error.png)

こういった場合も、「 [結果の加工](/view/visual_editor/result_transformation/) 」を用いることで表示が可能になります。

## 結果の加工 [](#結果の加工)

複数の実行結果を返すアクションを利用している・実行結果が配列でないなどの場合は、「結果の加工」機能を使うことで表示をカスタマイズできます。
詳細については [「結果の加工」](/view/visual_editor/result_transformation/) をご覧ください。

## 列のカスタマイズ [](#列のカスタマイズ)

「列のカスタマイズ」機能によって、以下のようなテーブルの表示内容の変更が可能になります。

- 列名の変更
- 複数の列の値を使って新しい列を作る（例：「姓」と「名」の列を結合して「名前」の列を追加する）
- 列の値をアクション実行画面やビューへのリンクにする

### デフォルトの列 [](#デフォルトの列)

「列のカスタマイズ」が未設定の場合、テーブルには自動で列が追加されています。
実行結果の配列の最初の要素であるオブジェクトのキーを列名とし、その値を各行の列の値として表示します。

アクションの実行結果が次のような場合を例に取ります。

```
[
  { id: 1, name: "山田太郎" },
  { id: 2, name: "山田花子" },
];
```

この場合、 `id` と `name` がオブジェクトのキーとなるので、この2つの列がテーブルに表示されます。

![「列のカスタマイズ」未使用の場合の挙動](/images/visual_editor/components/action_table/without_column_customization.png)

### 「列のカスタマイズ」を使用した場合 [](#列のカスタマイズを使用した場合)

「列のカスタマイズ」を設定している場合は、設定した列のみがテーブルに表示されます。
つまり、上記の例で表示されていたデフォルトの `id` と `name` の列は表示されず、明示的に追加された列のみが表示されます。

### 列の追加 [](#列の追加)

設定画面上部の「追加」あるいは「一括追加」ボタンから列を追加できます。

![列の追加](/images/visual_editor/components/action_table/add_column.png)

「追加」ボタンを押すと、新しい列を設定できるようになります（詳しい設定方法は後述します）。

![空の列の設定](/images/visual_editor/components/action_table/empty_column_setting.png)

「一括追加」ボタンを押すと、「列の一括追加」画面が開きます。

![列の一括追加](/images/visual_editor/components/action_table/add_multiple_columns.png)

「列の一括追加」画面にはデフォルトの列名が一覧で表示されており、これらの中から必要に応じて列を選択できます。
「追加」ボタンを押すと、選択した分の列が追加されます。

### 列の設定 [](#列の設定)

#### 列名 [](#列名)

テーブルの一番上に表示される列名を設定できます。

![列名](/images/visual_editor/components/action_table/column_name.png)

![列名の例](/images/visual_editor/components/action_table/column_name_example.png)

#### 列の種類 [](#列の種類)

表示する値をカスタマイズしたり、ビューやアクション実行画面へのリンクにするための設定です。
以下の中から選択します。

- 値の形式に合わせて表示
- 日時
- カスタムラベル
- アクション実行画面へのリンク
- ビューへのリンク
- リンク

##### 値の形式に合わせて表示 [](#値の形式に合わせて表示)

次のように、値に応じて自動で表示形式が決まります。

- 画像・動画と判別可能なURL：画像・動画として表示されます（詳細は「 [画像や動画の表示](/action/action_media_result/) 」をご覧ください）
- その他のURL：リンクテキストになります
- 画像・動画・PDFファイル：それぞれプレビューされます
- etc...

例えば、以下は `id` の列が通常のテキスト、 `url` の列がリンクテキストになる例です。

```
// アクションの実行結果
[
  { id: 1, url: "https://basemachina.example/users/1" },
  { id: 2, url: "https://basemachina.example/users/2" },
];
```

![値の形式に合わせて表示の例](/images/visual_editor/components/action_table/auto_column_example.png)

また、PDFの場合は次のようにプレビューが表示されます。

![PDFのプレビュー](/images/visual_editor/components/action_table/auto_column_pdf_preview.png)

###### 値 - 列から選択 [](#値---列から選択)

「値の形式に合わせて表示」では列の各行に表示する値を設定できます。

![値](/images/visual_editor/components/action_table/auto_column_value.png)

まず、「列から選択」では、デフォルトの列の値をそのまま使います。

![値 - 列から選択の例](/images/visual_editor/components/action_table/auto_column_value_key.png)

例えば、 `[ { "id": 1, "name": "ベース太郎" }, { "id": 2, "name": "ベース花子" } ]` という実行結果の場合は、 `name` を選択すると `ベース太郎` と `ベース花子` が表示されます。

###### 値 - 式で設定 [](#値---式で設定)

「式で設定」では、JavaScriptの式を使って値を設定できます。詳しくは [「式」](/view/visual_editor/expression/) をご覧ください。

なお、式では以下の値が使用できます。値の詳しい説明についてはドキュメントの各セクションをご覧ください。

- [`urlQueries`](/view/visual_editor/expression/#urlqueries)
- [`row`](/view/visual_editor/expression/#row)

###### 値 - 固定の値 [](#値---固定の値)

なんらかの固定の値を表示したい場合に利用できます。
すべての行で同じ値が表示されます。

###### スタイリング [](#スタイリング)

列の値に応じて見た目を変更するためのスタイリングルールを設定できます。
ルールは複数追加でき、それぞれに「適用する値」と見た目を設定します。
列の値が「適用する値」と完全一致する場合に、設定した見た目が適用されます。

現在はバッジに対応しており、バッジの色を選択できます。

![スタイリングの設定画面](/images/visual_editor/components/action_table/auto_column_styling.png)

![バッジの表示例](/images/visual_editor/components/action_table/auto_column_badge_example.png)

##### 日時 [](#日時)

このオプションを使うと、列の各行の日時の値を読みやすい形式で表示できます。
ISO8601形式またはタイムスタンプ（エポック秒）の日時の値を、指定した表示形式で表示します。

![「日時」の設定画面](/images/visual_editor/components/action_table/cell_customization_datetime.png)

###### 値 [](#値)

表示する日時の値を設定します。

対応する値の形式は以下の通りです。

- ISO8601形式の文字列（例： `"2001-02-03T04:05:06Z"` ）
- タイムスタンプ（エポック秒）の数値（例： `1580702700` ）

空文字、 `null` 、 `undefined` の場合、何も表示されません。

###### 表示形式 [](#表示形式)

表示形式は以下から選択できます。

| 形式 | 表示例 |
| --- | --- |
| 年/月/日 | 2001/02/03 |
| 年/月/日 時:分 | 2001/02/03 04:05 |
| 年/月/日 時:分:秒 | 2001/02/03 04:05:06 |

##### カスタムラベル [](#カスタムラベル)

このオプションを使うと、列の各行の値を任意のラベルに変換して表示できます。
例えば、データ上は `1` や `2` といった数値で管理されているステータスを、「有効」「無効」といったわかりやすいラベルに変換して表示するような使い方が可能です。

###### 値 [](#値-1)

変換対象となる値を設定します。値の入力方法は「値の形式に合わせて表示」の値と同じ仕様に従います。

###### 変換する値とラベル [](#変換する値とラベル)

「変換する値」と「ラベル」のペアを複数設定できます。
列の値が設定した「変換する値」と完全一致する場合に、対応する「ラベル」が表示されます。

###### バッジの色 [](#バッジの色)

各「変換する値」と「ラベル」のペアに対して、バッジの色を設定できます。
バッジの色を設定すると、ラベルが指定した色のバッジとして表示されます。

![カスタムラベルのバッジ色設定](/images/visual_editor/components/action_table/custom_label_badge_color.png)

![カスタムラベルのバッジ表示例](/images/visual_editor/components/action_table/custom_label_badge_example.png)

##### アクション実行画面へのリンク [](#アクション実行画面へのリンク)

このオプションを使うと、列の各行が選択したアクションの実行画面へのリンクになります。

![アクション実行画面へのリンク](/images/visual_editor/components/action_table/action_link_column.png)

利用ケースとしては、テーブルを使った一覧画面から、特定のデータを編集するアクションの実行画面を開くような使い方が可能になります。

###### リンクテキスト [](#リンクテキスト)

列に表示されるアクション実行画面へのリンクのテキストに関する設定です。「値の形式に合わせて表示」の値と同じ仕様に従います。

###### パラメーターの初期値 [](#パラメーターの初期値)

選択したアクションのパラメーターに初期値を設定すると、フォームの初期値が入力された状態で実行画面を開くことが可能になります。
これも入力する値に関しては「値の形式に合わせて表示」の値と同じ仕様に従います。

ただし、「式」で設定する場合はパラメーターの種類に応じた適切な値を設定する必要があります。
詳しくは「 [式](/view/visual_editor/expression/#%E5%BC%8F%E3%81%AE%E7%B5%90%E6%9E%9C%E3%81%AE%E5%9E%8B%E3%81%AB%E3%81%A4%E3%81%84%E3%81%A6) 」をご覧ください。

###### 移動時に自動でアクションを実行する [](#移動時に自動でアクションを実行する)

リンクをクリックし実行画面へ移動したときに、そのまま自動でアクションを実行するかどうかを設定できます。

###### 新しいタブで開く [](#新しいタブで開く)

リンクをクリックしたときに、実行画面を新しいタブで開くかどうかを設定できます。

##### ビューへのリンク [](#ビューへのリンク)

このオプションを使うと、列の各行が選択したビューへのリンクになります。

![ビューへのリンク](/images/visual_editor/components/action_table/view_link_column.png)

利用ケースとしては、テーブルを使った一覧画面から、特定のデータを表示する詳細画面としてのビューを開くような使い方が可能になります。

###### リンクテキスト [](#リンクテキスト-1)

列に表示されるビューへのリンクのテキストに関する設定です。「値の形式に合わせて表示」の値と同じ仕様に従います。

###### クエリパラメーター [](#クエリパラメーター)

ビューへのリンクに付与するクエリパラメーターを設定します。
クエリパラメーターは、複数の「名前」と「値」の組み合わせで設定します。

リンク先のビューに「 [クエリパラメーター設定](/view/visual_editor/query_parameter_setting/) 」を設定している場合は、そこで指定されたクエリパラメーターのみをここで設定します。
例えば、以下の例ではリンク先のビューで `user_id` というクエリパラメーターが設定されています。

![クエリパラメーター（リンク先のビューにクエリパラメーター設定がある場合）](/images/visual_editor/components/action_table/view_link_column_query_parameter_with_setting.png)

リンク先のビューにクエリパラメーター設定がない場合は、自由にクエリパラメーターを設定できます。

![クエリパラメーター（リンク先のビューにクエリパラメーター設定がない場合）](/images/visual_editor/components/action_table/view_link_column_query_parameter_without_setting.png)

どちらの場合も、クエリパラメーターの値の入力方法は「値の形式に合わせて表示」の値と同じ仕様に従います。

###### 新しいタブで開く [](#新しいタブで開く-1)

リンクをクリックしたときに、実行画面を新しいタブで開くかどうかを設定できます。

##### リンク [](#リンク)

「値の形式に合わせて表示」でもURLは自動でリンクになりますが、このオプションを使うとリンクテキストとリンク先URLをそれぞれ個別に設定できます。

###### リンクテキスト [](#リンクテキスト-2)

列に表示されるリンクのテキストに関する設定です。「値の形式に合わせて表示」の値と同じ仕様に従います。

###### URL [](#url)

リンク先のURLに関する設定です。「値の形式に合わせて表示」の値と同じ仕様に従います。

###### クエリパラメーター [](#クエリパラメーター-1)

リンクのURLに付与するクエリパラメーターを設定します。
クエリパラメーターは、複数の「名前」と「値」の組み合わせで設定します。

クエリパラメーターの値の入力方法は「値の形式に合わせて表示」の値と同じ仕様に従います。

###### 新しいタブで開く [](#新しいタブで開く-2)

リンクをクリックしたときに、リンク先を新しいタブで開くかどうかを設定できます。

## ページネーション設定 [](#ページネーション設定)

テーブルの1ページあたりの初期表示件数を設定できます。

### 初期表示件数 [](#初期表示件数)

テーブルを表示した際に、1ページに表示するデータの件数を設定します。
以下の中から選択できます。

- 10件（デフォルト）
- 25件
- 50件
- 100件

ユーザーはテーブル表示後にページネーションのUIから表示件数を変更できます。

## 各列の最大表示文字数 [](#各列の最大表示文字数)

設定した文字数を超えるテキストは省略されます。
省略されたテキストは末尾に「...」が表示され、展開ボタンをクリックすると全文を表示できます。

## ダウンロード [](#ダウンロード)

テーブルに表示されているデータはJSON形式またはCSV形式でダウンロードできます。

CSV形式の場合、以下のオプションを設定できます。

- BOMを付与する
- ヘッダーを含める
- 文字列の値を常にダブルクォーテーションで囲む

詳細については「 [CSV形式のオプション](/action/download_result/#csv%E5%BD%A2%E5%BC%8F%E3%81%AE%E3%82%AA%E3%83%97%E3%82%B7%E3%83%A7%E3%83%B3) 」をご覧ください。

![テーブルのダウンロードメニュー](/images/visual_editor/components/action_table/download.png)

[フォーム](/view/visual_editor/components/action_form/) [詳細テーブル](/view/visual_editor/components/action_detail_table/)
---
[ビュー](/view/)

[ビジュアルエディター](/view/visual_editor/)

[コンポーネント](/view/visual_editor/components/)

タブグループ

# タブグループ

タブグループは、複数のコンポーネントを複数のタブで切り替えて表示するためのコンポーネントです。複数の観点のデータを1つの画面に整理して表示したい場合に使用します。

![タブグループの表示例](/images/visual_editor/components/tab/example.png)

他のコンポーネントが1つのアクションの実行結果を表示するのに対して、タブグループは内部に他のコンポーネントを配置できる唯一のコンポーネントです。

## タブの中に配置できるコンポーネント [](#タブの中に配置できるコンポーネント)

各タブには、以下のコンポーネントを配置できます。

- [フォーム](/view/visual_editor/components/action_form/)
- [テーブル](/view/visual_editor/components/action_table/)
- [詳細テーブル](/view/visual_editor/components/action_detail_table/)

タブの中にさらにタブグループは配置できません。

## タブグループの設定 [](#タブグループの設定)

タブグループコンポーネントの設定画面では、「名前」「タイトル」に加えて、タブの一覧を管理できます。「名前」「タイトル」については「 [コンポーネント](/view/visual_editor/components/) 」の共通設定をご覧ください。

### タブ一覧の管理 [](#タブ一覧の管理)

「タブ一覧」では、タブ名の編集・追加・削除・並べ替えができます。

![タブ一覧の管理](/images/visual_editor/components/tab/tab_list_management.png)

- **タブ名の編集**: 各タブの名前を入力します。タブ名は画面上のタブの見出しとして表示されます。
- **タブの追加**: 一覧の下にある「タブを追加」ボタンでタブを追加します。タブは最大10個まで追加できます。
- **タブの削除**: 各タブの削除ボタンでタブを削除します。タブが1つだけの場合は削除できません。タブの中にコンポーネントがある状態で削除すると、中のコンポーネントも一緒に削除されます。
- **タブの並べ替え**: 各タブ行のハンドルをドラッグして、タブの表示順を入れ替えます。

## タブの中のコンポーネントを編集する [](#タブの中のコンポーネントを編集する)

タブの中のコンポーネントは、画面左側のコンポーネント一覧から追加・編集・削除します。

コンポーネント一覧でタブの見出しをクリックすると、編集対象のタブを切り替えられます。タブを選択した状態でコンポーネントを追加すると、そのタブの中に配置されます。

![コンポーネント一覧でのタブ切り替えと子コンポーネントの追加](/images/visual_editor/components/tab/tab_switching.png)

コンポーネントはドラッグアンドドロップで移動できます。タブの中とトップレベルの間や、タブ同士でも移動できます。

[詳細テーブル](/view/visual_editor/components/action_detail_table/) [式](/view/visual_editor/expression/)
---
[ビュー](/view/)

[ビジュアルエディター](/view/visual_editor/)

式

# 式

「式」を使うと、いくつかの設定に対して柔軟に値を設定できます。

- アクションのパラメーターの値で、 [クエリパラメーター](/view/visual_editor/query_parameter_setting/) の値を利用する
- フォームコンポーネントのアクションの初期値で、 [初期値用アクション](/view/visual_editor/components/action_form/#%E5%88%9D%E6%9C%9F%E5%80%A4%E7%94%A8%E3%82%A2%E3%82%AF%E3%82%B7%E3%83%A7%E3%83%B3) の実行結果を利用する
- テーブルコンポーネントの「 [列のカスタマイズ](/view/visual_editor/components/action_table/#%E5%88%97%E3%81%AE%E3%82%AB%E3%82%B9%E3%82%BF%E3%83%9E%E3%82%A4%E3%82%BA) 」でビューへのリンクに列の値を利用する
- 詳細テーブルコンポーネントの「 [項目のカスタマイズ](/view/visual_editor/components/action_detail_table/#%E9%A0%85%E7%9B%AE%E3%81%AE%E3%82%AB%E3%82%B9%E3%82%BF%E3%83%9E%E3%82%A4%E3%82%BA) 」でビューへのリンクに項目の値を利用する

## 式で使用できる値 [](#式で使用できる値)

「式」ではJavaScriptのコードを利用でき、利用箇所によってそれぞれ特殊な値を参照できます。
実際に使用できる値は、次のように画面上で閲覧可能になっています。

![式で使用できる値](/images/visual_editor/expression/inspector.png)

このセクションの残りの部分では、どのような値がどこで使えるのかをそれぞれ説明します。

### `urlQueries` [](#urlqueries)

`urlQueries` にはクエリパラメーターの値が格納されています。
利用できる箇所は以下のとおりです。

- テーブル／詳細テーブルの「コンポーネントの表示時に実行」で実行するアクションのパラメーターの値
- フォームコンポーネントのアクションのパラメーターの初期値、初期値用アクションのパラメーターの値
- テーブルの「 [列のカスタマイズ](/view/visual_editor/components/action_table/#%E5%88%97%E3%81%AE%E3%82%AB%E3%82%B9%E3%82%BF%E3%83%9E%E3%82%A4%E3%82%BA) 」
  - 列の値やリンクテキスト
  - ビューへのリンクを構成するクエリパラメーターの値
  - アクション実行画面へのリンクを構成するパラメーターの初期値
- 詳細テーブルの「 [項目のカスタマイズ](/view/visual_editor/components/action_detail_table/#%E9%A0%85%E7%9B%AE%E3%81%AE%E3%82%AB%E3%82%B9%E3%82%BF%E3%83%9E%E3%82%A4%E3%82%BA) 」
  - 項目の値やリンクテキスト
  - ビューへのリンクを構成するクエリパラメーターの値
  - アクション実行画面へのリンクを構成するパラメーターの初期値

「 [クエリパラメーター設定](/view/visual_editor/query_parameter_setting/) 」で設定したクエリパラメーターのみが `urlQueries` に格納されます。
たとえば、クエリパラメーター設定に `user_id` を設定しているとします。
これを詳細テーブルで呼び出すアクションのパラメーターに設定する場合は、パラメーターの「値を式で設定する」を有効にして次のように書きます。

![パラメーター名](/images/visual_editor/query_parameter_setting/usage.png)

### `row` [](#row)

`row` にはテーブルの行の値が格納されています。
利用できる箇所は以下のとおりです。

- テーブルの「 [列のカスタマイズ](/view/visual_editor/components/action_table/#%E5%88%97%E3%81%AE%E3%82%AB%E3%82%B9%E3%82%BF%E3%83%9E%E3%82%A4%E3%82%BA) 」
  - 列の値やリンクテキスト
  - ビューへのリンクを構成するクエリパラメーターの値
  - アクション実行画面へのリンクを構成するパラメーターの初期値

例えば、「姓」と「名」の2つの列から「名前」という列を作りたい場合は、 `row` 変数を使って `row['姓'] + row['名']` という式を設定することで実現可能です。

![row - 式の例](/images/visual_editor/components/action_table/auto_column_value_expression.png)

### `data` [](#data)

`data` には詳細テーブルのデータが格納されています。
利用できる箇所は以下のとおりです。

- 詳細テーブルの「 [項目のカスタマイズ](/view/visual_editor/components/action_detail_table/#%E9%A0%85%E7%9B%AE%E3%81%AE%E3%82%AB%E3%82%B9%E3%82%BF%E3%83%9E%E3%82%A4%E3%82%BA) 」
  - 項目の値やリンクテキスト
  - ビューへのリンクを構成するクエリパラメーターの値
  - アクション実行画面へのリンクを構成するパラメーターの初期値

詳細テーブルでは1つのオブジェクトのデータを表示するため、 `data` にはそのオブジェクトが格納されます。
例えば、「姓」と「名」の2つの項目から「名前」という項目を作りたい場合は、 `data` 変数を使って `data['姓'] + data['名']` という式を設定することで実現可能です。

![data - 式の例](/images/visual_editor/components/action_detail_table/auto_item_value_expression.png)

### `results` [](#results)

`results` は何らかのアクションの実行結果の値が格納されています。
利用できる箇所は以下のとおりです。

- フォームコンポーネントのアクションのパラメーターの初期値

#### フォームコンポーネントのアクションのパラメーターの初期値 [](#フォームコンポーネントのアクションのパラメーターの初期値)

`results` には初期値用アクションの実行結果が格納されます。
アクションの実行結果は複数になる場合があるので、 `results` は配列形式になっています。
例えば、初期値用アクションの1つ目の実行結果が `{ "id": "1","name": "ベース太郎" }` だったとします。
この中の `id` をフォームのアクションのパラメーターとして使うには、次のように `results[0].success.id` と書きます。

![フォームコンポーネントのアクションのパラメーターの初期値](/images/visual_editor/expression/initial_value_results.png)

### `vars` [](#vars)

`vars` には [変数・シークレット](/action/parameter/vars_secrets/) で設定した変数の値が格納されています。
変数は環境ごとに設定されるため、環境に応じて異なる値を入力したい場合に利用できます。

`vars` は式が使えるすべての箇所で利用可能です。

## 式の結果の型について [](#式の結果の型について)

アクションパラメーターの初期値や値に式を使う場合、結果の型をパラメーターの「 [種類](/action/parameter/action_parameter/#%E3%83%91%E3%83%A9%E3%83%A1%E3%83%BC%E3%82%BF%E3%83%BC%E3%81%AE%E7%A8%AE%E9%A1%9E) 」に一致させる必要があります。

例えば、フォームにおいてテキストのパラメーターに対して `number` の `1` を設定すると以下のようなエラーが表示されます。

![式の結果のエラー](/images/visual_editor/expression/result_type_error.png)

この場合、正しく `string` の `"1"` を設定する必要があります。

![正しい結果の型](/images/visual_editor/expression/correct_result_type.png)

種類と求められる結果の型の対応は次のとおりです。

| 種類 | 型 | 説明 |
| --- | --- | --- |
| テキスト | `string | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 |
| 数値 | `number | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 |
| 日付 | `Date | string | number | null | undefined` | `string` は `Date` 型に変換できる値、 `number` はUnixTimestamp (秒)を入力してください。 `null` や `undefined` の場合は未入力として扱われます。 |
| 真偽値 | `boolean | null | undefined` | `null` や `undefined` の場合は `false` として扱われます。 |
| JSON値 | `string | number | Date | null | undefined` | JSON値の種類ごとに型が異なります。 テキストなら `string | null | undefined` 、数値なら `number | null | undefined` 、日付なら `string | number | Date | null | undefined` を渡せます。 日付の場合 `string` は `Date` 型に変換できる値、 `number` はUnixTimestamp (秒)を入力してください。 `null` や `undefined` の場合は `null` として扱われます。 |
| SQL | `string | null | undefined` | `null` や `undefined` の場合は未入力として扱われます。 |
| 配列 | `Array | null | undefined` | 各要素の種類の型は、各種類の型と同じです。 `null` や `undefined` の場合は空配列として扱われます。 |
| タプル | `Array` | 各要素の種類の型は、各種類の型と同じです。 |

[タブグループ](/view/visual_editor/components/tab/) [結果の加工](/view/visual_editor/result_transformation/)
---
[ビュー](/view/)

[ビジュアルエディター](/view/visual_editor/)

ページ設定

# ページ設定

「ページ設定」を使うと、ビューにタイトルを設定できます。
タイトルを設定すると、ビューの最上部に見出しとして表示されます。

![タイトルが設定されたビューの表示例](/images/visual_editor/page_setting/example_with_title.png)

## 設定方法 [](#設定方法)

画面右上の「ページ設定」をクリックすると設定画面が開きます。

![ページ設定を開くボタン](/images/visual_editor/page_setting/open_button.png)

![ページ設定画面](/images/visual_editor/page_setting/modal.png)

### タイトル [](#タイトル)

ビューに表示するタイトルを設定します。
タイトルは任意で、設定しない場合は何も表示されません。

[結果の加工](/view/visual_editor/result_transformation/) [クエリパラメーター設定](/view/visual_editor/query_parameter_setting/)
---
[ビュー](/view/)

[ビジュアルエディター](/view/visual_editor/)

クエリパラメーター設定

# クエリパラメーター設定

「クエリパラメーター設定」を使うと、ビューへアクセスする際にURLのクエリパラメーターを変えることで、アクション実行時のパラメーターを変更できます。
例えば、以下は `user_id` というクエリパラメーターの値を変えることでアクション実行のパラメーターが変更している例です。

![クエリパラメーター設定の例1](/images/visual_editor/query_parameter_setting/example1.png)

![クエリパラメーター設定の例2](/images/visual_editor/query_parameter_setting/example2.png)

## 設定方法 [](#設定方法)

画面右上の「クエリパラメーター設定」をクリックすると設定画面が開きます。

![クエリパラメーター設定を開くボタン](/images/visual_editor/query_parameter_setting/open_button.png)

![クエリパラメーター設定画面](/images/visual_editor/query_parameter_setting/modal.png)

クエリパラメーターには項目が3つあります。

### パラメーター名 [](#パラメーター名)

クエリパラメーターの名前を設定します。
例えば、 `https://basemachina.basemachina.com/projects/xxx/environments/yyy/views/zzz?user_id=123` の `user_id` の部分がパラメーター名にあたります。
詳細テーブルなどの「アクション設定」にて、ここで設定した名前を用いて `urlQueries.user_id` のようにして値を取得できます。

![パラメーター名](/images/visual_editor/query_parameter_setting/usage.png)

上記のURLですと、 `urlQueries.user_id` の値は `'123'` になりますし、 `user_id=456` でアクセスした場合は `'456'` になります。

式でクエリパラメーターの値を使う方法については「 [式](/view/visual_editor/expression/) 」をご覧ください。

### 必須 [](#必須)

クエリパラメーターが必須かどうかを設定します。
必須にしたクエリパラメーターを欠いたURLでビューを開くと、次のようなエラーが表示されます。

![必須](/images/visual_editor/query_parameter_setting/required_param_error.png)

### 編集時の値 [](#編集時の値)

ビューの編集画面では「 [式](/view/visual_editor/expression/) 」でクエリパラメーターを用いる際、必ずここで設定した値が使われます。

## ビューの利用時 [](#ビューの利用時)

ビューの利用時には、ビューのURLにクエリパラメーターを付与した状態でアクセスします。
テーブルコンポーネントの「列のカスタマイズ」でビューへのリンクを作成するときにクエリパラメーターを付与できます。
詳しくは [「列のカスタマイズ」](/view/visual_editor/components/action_table/#%E5%88%97%E3%81%AE%E3%82%AB%E3%82%B9%E3%82%BF%E3%83%9E%E3%82%A4%E3%82%BA) をご覧ください。

## その他の仕様 [](#その他の仕様)

### 同一のパラメーターが複数ある場合 [](#同一のパラメーターが複数ある場合)

`user_id=1&user_id=2` のように同一のパラメーターが複数ある場合は、最初の値（ `user_id=1` ）が使われます。

[ページ設定](/view/visual_editor/page_setting/) [コードエディター](/view/code_editor/)
---
[ビュー](/view/)

[ビジュアルエディター](/view/visual_editor/)

結果の加工

# 結果の加工

以下のコンポーネントには、「結果の加工」というアクションの実行結果を加工する機能があります。

- [テーブル](/view/visual_editor/components/action_table/)
- [詳細テーブル](/view/visual_editor/components/action_detail_table/)

## ユースケース [](#ユースケース)

### アクションの結果が複数ある場合 [](#アクションの結果が複数ある場合)

アクションの種類によっては複数の結果が返ってくることがあります。
例えば、MySQLアクションではクエリを複数登録でき、それぞれのクエリに対応する実行結果が返ってきますが、
デフォルトでは結果がいくつかあっても必ず1つ目の結果が表示に利用されます。
そういったケースでも、「結果の加工」を使えばどの結果を表示するか選択できます。

### データの抽出 [](#データの抽出)

コンポーネントにはそれぞれ要求される実行結果の形式がありますが、アクションが必ずしもそれを満たした結果を返すとは限りません。
例えば、次のような配列のデータはそのままテーブルコンポーネントで表示可能です。

```
[
  { id: 1, name: "山田太郎" },
  { id: 2, name: "山田花子" },
];
```

しかしアクションが次のように上記のデータを `data` で包んで返す場合は、そのままでは表示できません。
このようなケースはHTTP APIアクションでしばしば見られます。

```
{
  "data": [
    { "id": 1, "name": "山田太郎"},
    { "id": 2, "name": "山田花子"},
  ]
}
```

そんな場合は、「結果の加工」で `data` を使うように指示することで表示が可能になります。

## 使い方 [](#使い方)

結果の加工はJavaScriptのコードで実装します。

![結果の加工](/images/visual_editor/result_transformation.png)

`export default` で結果を加工する関数を定義してください。
関数の戻り値がコンポーネントに表示されるデータとなります。
デフォルトでは次のようなコードが設定されています。これは「結果の加工」を使わない場合と同じ挙動のコードです。

```
export default (results, { vars }) => {
  return results[0].success;
};
```

### 引数 [](#引数)

定義した関数には、第一引数としてアクションの実行結果が渡されます。
先述したとおり、アクションは複数の結果を返すことがあります。
そのため、第一引数として渡される `results` は配列になっています。

第二引数は `vars` を含むオブジェクトです。
`vars` には [変数・シークレット](/action/parameter/vars_secrets/) で設定した変数の値が格納されています。
環境に応じた値を結果の加工で利用したい場合に使用できます。

また、実際に渡される引数の値は「引数の値」をクリックすることで閲覧できます。

![引数の値](/images/visual_editor/result_transformation_inspector.png)

### 例 [](#例)

例えば、2つ目の実行結果を使いたい場合は以下のように関数を定義してください。

```
export default (results, { vars }) => {
  return results[1].success; // results[0]ではなくresults[1]
};
```

また、実行結果が `{ data: [/* ... */] }` のように `data` で包まれている場合は、以下のように `data` を使うように関数を定義できます。

```
export default (results, { vars }) => {
  return results[0].success.data;
};
```

[式](/view/visual_editor/expression/) [ページ設定](/view/visual_editor/page_setting/)
---