ベースマキナとは # ベースマキナとは ![ベースマキナとは](/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/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) をご覧ください。 - **アクション**: 実行するアクションを選択します。 - **パラメーター**: 選択したアクションにパラメーターがある場合、実行時の値を設定します。 1. 「保存」を選択して定期実行の作成は完了です。 定期実行は、現在選択中の環境に対して設定されます。アクションは定期実行の設定者として実行されます。 ## スケジュールの設定形式 [](#スケジュールの設定形式) 画面上の入力フォームからスケジュールを設定します。実行日と実行時刻の組み合わせで指定します。 ### 実行日 [](#実行日) | 指定方法 | 説明 | 例 | | --- | --- | --- | | 曜日で指定 | 特定の曜日に実行する | 毎週月曜日と金曜日 | | 日にちで指定 | 毎月特定の日に実行する | 毎月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. 「再試行」を選択します。 実行が失敗した場合や、結果を再度取得したい場合に活用できます。 [予約実行](/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 | 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) をご参照ください。 ## 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 | ### 便利な使い方 [](#便利な使い方) 「バケット名」と「オブジェクト名（オブジェクトキー）」では、アクションのパラメーターのほかに、 [変数・シークレット](/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 | 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で動作確認済み）で必要なリソースを作成します。 `` 、 `` 、 `` を環境に合わせて置き換えてください。 既存のバケットを使用する場合は `google_storage_bucket` の定義を削除し、 `google_storage_bucket_iam_member` の `bucket` を既存バケット名に変更してください。 ``` provider "google" { project = "" } data "google_project" "project" {} # GCS バケット（既存バケットを使う場合は不要） resource "google_storage_bucket" "bucket" { name = "" location = "asia-northeast1" uniform_bucket_level_access = true } # ベースマキナが権限借用するサービスアカウント resource "google_service_account" "sa" { account_id = "" display_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//locations/global/workloadIdentityPools//providers/` | `projects/123456789/locations/global/workloadIdentityPools/basemachina/providers/basemachina` | | サービスアカウント | `@.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 | ### 便利な使い方 [](#便利な使い方) 「バケット名」と「オブジェクト名（オブジェクトキー）」では、アクションのパラメーターのほかに、 [変数・シークレット](/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ファイルのパス }}"' ``` [HTTP API](/action/datasources/httpapi_integration/) [Google スプレッドシート](/action/datasources/googlespreadsheet_integration/) --- [アクション](/action/) データソース別の設定 HTTP API # HTTP API ## HTTP API のデータソースに接続する [](#http-api-のデータソースに接続する) 1. 右上のメニューから「データソース」を選択する 2. 「データソースの追加」をクリックする 3. データソースの種類の中から「 HTTP API 」を選択する ![データソースの選択](/images/httpapi_integration/select.png) 4. データソースへの接続に必要な情報を入力して保存する ![データソースの接続設定](/images/httpapi_integration/connection.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/httpapi_integration/common_header.png) ### 認証設定 [](#認証設定) HTTP APIアクションでは、認証形式としてBasic認証と、認証用アクションのいずれかを選択できます。 #### 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/) と共通しているので、アクションの実行ページで事前に動作内容を確認できます。 ## HTTP API をアクションで利用する [](#http-api-をアクションで利用する) 1. 右上のメニューから「アクション」を選択する 2. 「アクションの追加」をクリックする 3. アクション名やパラメーターを設定する ![データソースの選択](/images/httpapi_integration/basic_action.png) 1. リクエスト方法を登録する APIに対してのリクエスト内容を入力してください。 ![HTTP APIアクション](/images/httpapi_integration/httpapi_setting.png) 上記の例はURLのパスパラメーターとして値を利用しています。 他にもヘッダーやクエリパラメーター、リクエストボディの中に3で指定したパラメーターを渡すことができます。 ![パラメーターの入力された、HTTP APIヘッダー、クエリパラメーター、リクエストタイプとリクエストボディ](/images/httpapi_integration/applied_parameters.png) HTTP APIアクションにおけるアクションパラメーターの入力は基本的に単純置換となります。 そのため、複数行入力を有効にしたテキスト型パラメーターをJSONのリクエストボディに埋め込むと、改行がそのまま送信されます。 例えば、次のように文字列中に改行を含むJSONが生成されてエラーとなります。 ``` { "detail": "行1 行2" } ``` 複数行の文字列を扱う場合は、テキスト型パラメーターの設定画面で「改行文字を指定する」を有効にし改行文字を `\\n` に設定するか、 [JSON値](/action/parameter/json_parameter/) （種類：テキスト）を利用してください。 リクエストボディでオブジェクトの配列を送信したい場合は、JavaScriptアクションと組み合わせて実現できます。詳しくは [アクションに関する質問](/faq/action_questions/) を参照してください。 ### ファイルを送信する [](#ファイルを送信する) ファイルを送信する場合は、リクエストタイプに `binary` または `form-data` を選択して、表示される入力欄に [ファイルパラメーター](/action/parameter/file_parameter/) を指定してください。 ![リクエストタイプにform-dataを選択して、ファイルパラメーターを指定する](/images/httpapi_integration/form_data.png) リクエストタイプを `form-data` に設定した場合、HTTPリクエスト自体のContent-Typeは `multipart/form-data` となります。 ただし、multipart/form-data内のファイルパラメーターのContent-Typeは、現在はファイルの内容に関わらず `application/octet-stream` となります。 ### GraphQL を利用する [](#graphql-を利用する) HTTP APIのアクションでは、GraphQLサーバーとの通信に使いやすくするため、リクエストタイプに `GraphQL` を用意しています。 ![リクエストタイプ GraphQL](/images/httpapi_integration/graphql.png) `GraphQL` を選択すると、QueryとVariablesを入力するフィールドがそれぞれ表示されます。 GraphQLサーバーへのリクエストは、上記フィールドへの設定内容をもとにJSON形式で送信されます。 Query、Variablesのいずれも、他のリクエストタイプと同様に、パラメーターを渡すことができます。 上記の例では、Variablesの `id` キーに、 `"{{ id }}"` としてパラメーターを渡しています。 ### 200系以外のレスポンスステータスコードを実行エラーとして扱う [](#200系以外のレスポンスステータスコードを実行エラーとして扱う) 「200系以外のレスポンスステータスコードを実行エラーとして扱う」を有効にすると、アクション実行時にHTTPのレスポンスステータスコードが200系以外だった場合に、実行エラーとして扱います。 実行エラーの場合、レスポンスの内容が `results[0].failure` に格納されます。 [Firestore](/action/datasources/firestore_integration/) [gRPC](/action/datasources/grpc_integration/) --- [アクション](/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` はWeb APIの一部のプロパティにのみ対応しております。 未対応のプロパティやメソッドは今後随時対応する予定です。 | `{ 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/) [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` | ### 戻り値 [](#戻り値) 戻り値はありません。 [createActionJob](/action/datasources/javascript_action/builtin_functions/create_action_job/) [型定義ファイルのダウンロード](/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アクションは現在一部のお客さまに限定して公開しています。近日中に一般公開を予定しています。 [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` | 対応 | | `NUMBER` `DECIMAL` `NUMERIC` `INT` `INTEGER` `BIGINT` `SMALLINT` `TINYINT` `BYTEINT` | `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. 確認画面で「削除」を選択します。 通知方法を削除すると、その通知方法を使用しているアクションの通知設定が無効になります。 ## 次のステップ [](#次のステップ) 通知方法を追加したら、 [アクションの通知設定](/action/notification/action_notification/) で各アクションに通知を設定できます。 [Slack連携](/action/notification/slack_integration/) [アクションの通知設定](/action/notification/action_notification/) --- [アクション](/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) - [`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/) [通知方法の管理](/action/notification/notification_methods/) --- [アクション](/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 ### フォーマットなし [](#フォーマットなし) 配列の形式のまま送信されます。 **フォーマットなし** は以下のデータソースでのみ利用できます。 - [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が実行されます。 ## 最小要素数 [](#最小要素数) 入力できる最小要素数を設定できます。 ## 最大要素数 [](#最大要素数) 入力できる最大要素数を設定できます。 [真偽値](/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. 「追加」ボタンを選択して、レビュー設定の作成画面に移動します。 ![レビュー設定の設定画面](/images/review_setting/setting_form.png) レビュー設定では以下の項目を設定します。 - 名前 - 各環境の設定 - レビューを有効化する - 承認できるユーザー・グループ - 自身のレビュー依頼を承認可能にする - 自身のレビュー依頼を自動承認する - 承認者もアクションを実行可能にする - レビュー依頼のデフォルト設定 ### 名前 [](#名前) レビュー設定の名前です。 --- 以下は各環境ごとに設定する項目です。 ### レビューを有効化する [](#レビューを有効化する) その環境でレビューを有効化するかどうかを設定します。 有効化すると以下の項目が設定できるようになります。 #### 承認できるユーザー・グループ [](#承認できるユーザーグループ) レビュアーのユーザー・グループを設定します。 グループを設定する場合は、そのグループのうち最低何人の承認が必要なのかも設定できます。 #### 自身のレビュー依頼を承認可能にする [](#自身のレビュー依頼を承認可能にする) レビュー依頼者が自分自身のレビュー依頼を承認できるかどうかを設定します。 「自身のレビュー依頼を承認可能にする」が無効の場合、レビュー依頼者は自分のレビュー依頼を承認できません。レビュアーとして設定された他のユーザーのみが承認できます。 #### 自身のレビュー依頼を自動承認する [](#自身のレビュー依頼を自動承認する) レビュー依頼作成時、自分自身がレビュアーの場合に自動で承認するかどうかを設定します。 この設定は「自身のレビュー依頼を承認可能にする」が有効な場合にのみ設定できます。 #### 承認者もアクションを実行可能にする [](#承認者もアクションを実行可能にする) レビュー依頼の承認後に、承認者もアクションを実行可能にするかどうかを設定します。 「承認者もアクションを実行可能にする」が無効な場合、アクションを実行できるのはレビュー依頼を作成したユーザーのみです。 「承認者もアクションを実行可能にする」が有効な場合でも、承認者がアクションの実行権限を持っていない場合はアクションを実行できません。 #### レビュー依頼のデフォルト設定 [](#レビュー依頼のデフォルト設定) レビュー依頼を作成する際に、入力フォームに自動で入力されるデフォルト値を設定できます。 ##### レビュー依頼の説明 [](#レビュー依頼の説明) レビュー依頼作成時に「説明」欄に自動入力される文章を設定します。 ##### レビュー期限を設定しない [](#レビュー期限を設定しない) 有効にすると、レビュー依頼作成時に「有効期限を設定しない」がデフォルトで有効になります。 レビュー依頼作成時にこの設定を変更して、有効期限を設定できます。 ## アクションのレビュー設定 [](#アクションのレビュー設定) アクションの編集画面の「レビュー設定」のタブで、アクションにレビュー設定を紐づけられます。 レビューが有効化されている環境で、アクションの実行権限を持ったユーザーがアクション実行画面に移動すると、アクションの実行フォームの代わりにレビュー依頼フォームが表示されます。 レビューが有効化されている環境では、レビューが承認されてからでなければアクションを実行できません。 ![レビュー依頼のフォーム](/images/review/review_request_form.png) なお、実行権限を持たないユーザーはレビューを依頼できません。 実行権限の設定とレビューの設定の対応関係は、以下のとおりです。 | | 誰でも実行できる | 実行権限を設定する | | --- | --- | --- | | レビュー無効 | すべての人が即実行できる | 実行権限のある人は即実行できる。実行権限のない人は何もできない | | レビュー有効 | 誰でもレビュー依頼が行なえる | 実行権限のある人はレビュー依頼ができる。実行権限のない人は何もできない | ## 確認と実行 [](#確認と実行) 自分に依頼されたレビュー、または自分が他の人に依頼したレビューの履歴は専用の画面で確認できます。 画面上部のメニューからレビュー依頼のアイコンをクリックして、レビューの一覧画面に移動してください。 レビュー依頼ごとの詳細画面に行くとレビューを出した人や確認状況を見ることができます。 ![レビュー依頼のアイコン](/images/review/nav_icon.png) 詳細画面では依頼時点で入力されたパラメーターの値の情報などを確認したうえで、承認・却下、そして承認後の実行などを行なえます。 ![レビュー依頼の詳細画面](/images/review/review_history.png) ### 承認・却下 [](#承認却下) レビュー依頼をされたユーザーは、画面右上のボタンから承認または却下をコメント付きで行なえます。 また承認済みのレビュー依頼の却下も可能です。 レビューを依頼したユーザーは、それらのコメントを後から確認することで、なぜレビューが承認・却下されたのかを知ることができます。 ![レビュー依頼の承認と却下](/images/review/approval_form.png) ### 承認後の実行 [](#承認後の実行) レビュー依頼が承認されると「承認者もアクションを実行可能にする」が有効な場合はレビュー依頼の作成者と承認者が、無効な場合はレビュー依頼の作成者のみが、アクションを実行できます。 ![レビュー依頼の承認後の実行](/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` のどちらかのみを指定した場合は、画像の縦横比率を維持したまま表示されます。 ## 詳細なインターフェース [](#詳細なインターフェース) ``` 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 ; const user = data?.results[0].success; return ( {user.name} {user.email} {user.createdAt}登録 ); }; 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` を通じて行なわれます。シェルスクリプトジョブからは `34.84.42.41` を通じて行なわれます。 データソースを登録する際には、この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) すべてのプロジェクトには、初めから"初期環境"と言う名前の環境が存在していますが、この環境を編集して名前を変えることも可能です。 使わなくなった環境は、無効化できます。 無効化された環境は、環境切り替えのメニューに表示されなくなります。 ただし、無効化された設定は削除されず、同じ画面上で再び有効化できます。 ## 環境の切り替え方法 [](#環境の切り替え方法) メニューバーに表示されている環境名をクリックすると、切り替え可能な環境の一覧が表示されます。 ここから、使用したい環境を選択してください。 選択すると、メニューバーの背景色が環境に合わせて変化します。 ![環境を切り替える](/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/) をご覧ください。 [IPアドレス制限](/admin/security/ip_restriction/) [開発環境](/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) のページから請求できます。 ログの保持期間は最大で1年間です。「ダウンロードリンクを請求する」をクリックすると請求したお客さまのメールアドレス宛に、監査ログが記録された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 | アクションの実行、作成、更新、削除 | アクションの識別子 | | review\_id | レビュー依頼の作成、承認、却下 | レビュー依頼のID | | review\_description | レビュー依頼の作成、承認、却下 | レビュー依頼の詳細 | | review\_expires\_in | レビュー依頼の作成、承認、却下 | レビュー依頼の有効期限 | | review\_created\_at | レビュー依頼の作成、承認、却下 | レビュー依頼の作成日時 | | review\_setting | レビュー設定の作成、更新、レビュー依頼の作成、アクションの作成、更新 | レビュー設定のID,名前 | | notification\_settings | アクションの作成、更新 | 通知設定（成功時・エラー時の通知方法ID、メンション対象ユーザーIDの配列） | | review\_setting\_id | レビュー設定の削除 | レビュー設定のID | | environment\_review\_setting | レビュー設定の作成、更新 | 環境のID,環境の名前,承認できるユーザーの配列,承認できるグループの配列,自身のレビュー依頼を承認可能にするか,自身のレビュー依頼を自動承認するか,承認者もアクションを実行可能にするか | | datasource-id | データソースの作成、更新、削除 | データソースのID | | datasource-name | データソースの作成、更新、削除 | データソースの名前 | | datasource-class | データソースの作成、更新、削除 | データソースの種類 | | view-id | ビューの作成、更新、削除 | ビューのID | | view-display\_id | ビューの作成、更新、削除 | ビューの識別子 | | view-name | ビューの作成、更新、削除 | ビューの名前 | | project\_users | プロジェクトユーザーの作成、削除 | プロジェクトユーザーのID,名前,メールアドレスの配列 | | user\_group\_assignments | プロジェクトユーザーのグループの更新 | プロジェクトユーザーのID,名前,メールアドレスとグループのID,名前,ロールの配列の配列 | | target\_user-id | ユーザーの更新 | ユーザーのID | | target\_user-name | ユーザーの更新 | ユーザーの名前 | | target\_user-email | ユーザーの更新 | ユーザーのメールアドレス | | is\_tenant\_admin | ユーザーの更新 | ユーザーが企業アカウントの管理者かどうか | | target\_users | ユーザーの作成、削除、環境別利用制限の更新 | ユーザーのID,名前,メールアドレスの配列 | | target\_user\_group-id | グループの作成、更新、削除 | グループのID | | target\_user\_group-name | グループの作成、更新、削除 | グループの名前 | | target\_user\_group-admin\_roles | グループの作成、更新、削除 | グループのロールの配列 | | target\_users | ユーザーの作成、削除、環境別利用制限の更新 | ユーザーのID,名前,メールアドレスの配列 | | target\_user\_groups | 環境別利用制限の更新 | グループのID,名前,ロールの配列の配列 | | target\_environment-id | 環境別利用制限の更新 | 環境のID | | target\_environment-name | 環境別利用制限の更新 | 環境の名前 | | target\_environment-access\_control\_enabled | 環境別利用制限の更新 | 環境の利用制限が有効かどうか | | slack\_workspace-workspace\_name | Slack連携、Slack連携解除 | Slackワークスペースの名前 | | notification\_method-id | 通知方法の作成、更新、削除 | 通知方法のID | | notification\_method-name | 通知方法の作成、更新、削除 | 通知方法の名前 | | environment\_slack\_notification\_methods | 通知方法の作成、更新 | 環境ごとの通知設定の配列 | | action\_cron\_job-id | 定期実行の作成、一時停止、再開、無効化、スケジュール更新、名前更新、アクション更新、再実行 | 定期実行のID | | action\_cron\_job-name | 定期実行の作成、一時停止、再開、無効化、スケジュール更新、名前更新、アクション更新、再実行 | 定期実行の名前 | | action\_cron\_job-schedule | 定期実行の作成、スケジュール更新 | 定期実行のスケジュール（cron式） | | action\_cron\_job-scheduled\_at | 定期実行の再実行 | 再実行対象のスケジュール日時 | | 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>, `bmrn` struct, `action` struct, `tenant_id` string, `client_ip` string, `context_id` string, `user` struct, `project` struct, `environment` struct ) 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, ``` ### プロジェクト内のすべての操作で共通 [](#プロジェクト内のすべての操作で共通) ``` `project` struct ``` ### 環境内のすべての操作で共通 [](#環境内のすべての操作で共通) ``` `environment` struct ``` ### `execute_action` [](#execute_action) ``` `arguments` array>, `bmrn` struct, `action` struct, ``` ### `create_review_request` [](#create_review_request) ``` `arguments` array>, `action` struct, `review_setting` struct, `review_request` struct, ``` ### `approve_review_request`, `reject_review_request` [](#approve_review_requestreject_review_request) ``` `action` struct, `review_request` struct, `status` string, ``` ### `execute_action_with_review_request` [](#execute_action_with_review_request) ``` `arguments` array>, `action` struct, `review_request` struct, ``` ### `create_datasource`, `update_datasource`, `delete_datasource` [](#create_datasourceupdate_datasourcedelete_datasource) ``` `datasource` struct, ``` ### `create_action`, `update_action` [](#create_actionupdate_action) ``` `bmrn` struct, `action` struct, `review_setting` struct, `notification_settings` struct>,on_error:struct>>, ``` ### `delete_action` [](#delete_action) ``` `bmrn` struct, `action` struct, ``` ### `create_view`, `update_view`, `delete_view` [](#create_viewupdate_viewdelete_view) ``` `view` struct, ``` ### `create_users`, `delete_users` [](#create_usersdelete_users) ``` `target_users` array>, ``` ### `update_user` [](#update_user) ``` `target_user` struct, `is_tenant_admin` boolean, ``` ### `create_project_users`, `delete_project_users` [](#create_project_usersdelete_project_users) ``` `project_users` array>, ``` ### `create_user_group`, `update_user_group`, `delete_user_group` [](#create_user_groupupdate_user_groupdelete_user_group) ``` `target_user_group` struct>, ``` ### `assign_users_to_user_group` [](#assign_users_to_user_group) ``` `users` array>, `user_group` array>>, ``` ### `update_user_group_assignments` [](#update_user_group_assignments) ``` `user_group_assignments` array,user_groups:array>>>>, ``` ### `create_review_setting`, `update_review_setting` [](#create_review_settingupdate_review_setting) ``` `review_setting` struct, `environment_review_settings` array,self_approval_enabled:boolean,approver_execution_enabled:boolean,user_approval_conditions:array>>,user_group_approval_conditions:array,required_count:integer>>>>, ``` ### `delete_review_setting` [](#delete_review_setting) ``` `review_setting_id` string, ``` ### `update_environment_access_control` [](#update_environment_access_control) ``` `target_environment` struct, `target_users` array>, `target_user_groups` array>>, ``` ### `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) の列の定義のみです。 ### `connect_slack`, `disconnect_slack` [](#connect_slack-disconnect_slack) ``` `slack_workspace` struct, ``` ### `create_slack_notification_method`, `update_slack_notification_method` [](#create_slack_notification_method-update_slack_notification_method) ``` `notification_method` struct, `environment_slack_notification_methods` array,channel_id:string>>, ``` ### `delete_notification_method` [](#delete_notification_method) ``` `notification_method` struct, ``` ### `create_action_cron_job` [](#create_action_cron_job) ``` `action_cron_job` struct, `action_cron_job_schedule` string, `action` struct, ``` ### `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, ``` ### `update_action_cron_job_schedule` [](#update_action_cron_job_schedule) ``` `action_cron_job` struct, `action_cron_job_schedule` string, ``` ### `update_action_cron_job_action` [](#update_action_cron_job_action) ``` `action_cron_job` struct, `action` struct, ``` ### `rerun_scheduled_action_cron_job` [](#rerun_scheduled_action_cron_job) ``` `action_cron_job` struct, `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/) --- 管理設定 セキュリティ・監査 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アドレスからのみアクセスできます。 [SAML SSO](/admin/security/saml/) [環境とは](/admin/environment/what_is_environment/) --- 管理設定 セキュリティ・監査 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/) [IPアドレス制限](/admin/security/ip_restriction/) --- 管理設定 組織やユーザーの設定 グループ # グループ 「グループ」はプロジェクトユーザーをグルーピングして管理する機能です。 プロジェクトユーザーにグループを設定すると、以下ができるようになります。 - グループ単位でアクションの実行権限や承認条件などを設定する。 - グループに「開発者」などのロールを設定して、アクションや環境の設定ができるユーザーを制限する。 ## グループ管理のページへ移動する [](#グループ管理のページへ移動する) 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/code_management/upcoming_features/) [企業アカウントの管理者権限](/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/) --- 非推奨の機能 環境別のアクション表示・非表示設定 # 環境別アクションの表示・非表示設定 ⚠️ この機能は廃止いたしました（ただし、一部のお客さまには継続してご提供しております）。 代わりに [アクションの有効化設定](/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, 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/code_editor/download_dts_file/) [コード管理とは](/preview/code_management/) --- 開発中の機能 コード管理 コード管理とは # コード管理とは ⚠️ この機能は現在開発中であり、まだ公開されていません。記載内容は今後変更される可能性があります。 コード管理は、ベースマキナのアクションの設定をTypeScriptのコードとしてGitリポジトリで管理できる機能です。 設定内容をコードとして管理することで、以下のメリットがあります。 - **コードレビュー**: 設定変更をPull Requestでレビューできる - **差分検出**: 設定変更の差分をCI上で自動検出し、PRにコメントとして表示できる - **環境別の反映**: 開発環境から検証環境、本番環境へ段階的に反映できる - **型安全な設定**: TypeScriptの型システムにより、設定ミスをコードの記述時に検出できる - **変更履歴**: Gitの履歴で設定変更の経緯を追跡できる ## 対応する管理対象 [](#対応する管理対象) 現在、以下のアクション種別のコード管理に対応しています。 - gRPCアクション - JavaScriptアクション 今後、対応するアクション種別は拡大予定です。 ## 全体像 [](#全体像) コード管理では、以下のツールを使用します。 | ツール | 説明 | | --- | --- | | `@basemachina/sdk/oac` | アクションの設定をTypeScriptで記述するためのSDK（ `defineConfig` / `defineAction` ） | | `@basemachina/cli` | 設定の差分検出や反映を行なうCLIツール（ `bm` コマンド） | 設定はTypeScriptファイル（ `basemachina.config.ts` ）に記述し、CLIコマンド [`bm sync`](/preview/code_management/cli/sync/) で設定の差分検出や環境間の同期を行ないます。GitHub Actionsと組み合わせることで、PRのマージをトリガーに自動で設定を反映できます。 ## 始めるには [](#始めるには) 1. [始め方](/preview/code_management/getting_started/) に従ってプロジェクトをダウンロードし、リポジトリをセットアップする 1. [設定ファイル](/preview/code_management/configuration/) を編集してアクションを定義する 1. [CLIコマンド](/preview/code_management/cli/sync/) で差分を確認し、反映する 1. [CI/CDの設定](/preview/code_management/ci_cd/) でGitHub Actionsを構成する 1. [運用例](/preview/code_management/examples/two_branch/) を参考に開発・運用を行なう [ナビゲーション](/navigation/) [始め方](/preview/code_management/getting_started/) --- 開発中の機能 コード管理 CI/CDの設定 # CI/CDの設定 GitHub Actionsを使って、PRの作成やマージをトリガーに設定の差分検出や反映を自動化できます。 ## 概要 [](#概要) CI/CDでは、 [`bm sync`](/preview/code_management/cli/sync/) コマンドをGitHub Actionsから実行することで、以下のような自動化が可能です。 - **PR作成時**: `bm sync --dry` で差分を検出し、PRにコメントする - **PRマージ時**: `bm sync` で設定を開発環境に反映する - **環境同期時**: `bm sync <環境ID>` で環境間のバージョンと有効化設定を同期する ブランチ構成や環境の対応は、プロジェクトの運用に合わせて自由に設定できます。具体的な設定例は [運用例](/preview/code_management/examples/two_branch/) をご参照ください。 ## 認証 [](#認証) `bm sync` はベースマキナに対して認証する必要があります。CI/CDでは、CI/CDが発行するOIDC ID Tokenを使用してサービスアカウントとして認証します。 ### 前提 [](#前提) 1. [始め方](/preview/code_management/getting_started/) で **OIDC信頼ポリシー** が設定済みであること 1. OIDC信頼ポリシーの `Issuer` / `Audience` / `Bound Claims` が、CI/CDの発行するID Tokenと整合していること ### 環境変数 [](#環境変数) `bm sync` は、以下のいずれかの方法で認証情報を読み取ります。 | 方法 | 用途 | | --- | --- | | 環境変数 `BM_OIDC_TOKEN` | CI/CDでの実行。CI/CDが発行するOIDC ID Tokenを設定する | | `~/.basemachina/credentials.json` | ローカルでの実行。 `bm login` コマンドで自動的に保存される | `BM_OIDC_TOKEN` が設定されている場合は、 `BM_OIDC_TOKEN` のトークンが優先されます。 ## セットアップ [](#セットアップ) ### GitHub Actionsの設定ファイル [](#github-actionsの設定ファイル) GitHub Actionsのワークフローでは、OIDC ID Tokenを発行するために `id-token: write` のパーミッションが必要です。取得したID Tokenを環境変数 `BM_OIDC_TOKEN` に設定し、 `bm sync` を実行します。 ``` name: Sync to dev on: pull_request: branches: [main] push: branches: [main] permissions: id-token: write # OIDC ID Token の発行に必須 contents: read pull-requests: write # PRコメントの投稿に必要（PR作成時のみ） jobs: sync: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 20 - run: npm ci - name: Fetch OIDC ID Token id: oidc uses: actions/github-script@v7 with: script: | const token = await core.getIDToken("https://basemachina.com") core.setSecret(token) core.setOutput("token", token) - name: Dry run if: github.event_name == 'pull_request' run: npx bm sync --dry env: BM_OIDC_TOKEN: ${{ steps.oidc.outputs.token }} - name: Sync if: github.event_name == 'push' run: npx bm sync env: BM_OIDC_TOKEN: ${{ steps.oidc.outputs.token }} ``` `core.getIDToken("https://basemachina.com")` の引数は、OIDC信頼ポリシーで設定した `Audience` と一致している必要があります。一致しない場合、 `bm sync` が認証エラーになります。 ## 動作の流れ [](#動作の流れ) ### PR作成時の差分検出 [](#pr作成時の差分検出) 1. PRが作成されると、CIが自動で `bm sync --dry` を実行します。 1. 設定ファイルとベースマキナ上の設定の差分が検出されます。 1. 差分の内容がPRにコメントとして投稿されます（PRコメントに貼り付ける処理はワークフロー側で実装します）。 これにより、マージ前に設定変更の影響を確認できます。 開発環境への反映時、 `bm sync` は実行環境を自動で検出し、GitHub ActionsおよびGitLab CI上ではPRコメントに貼り付けやすいMarkdown形式（ `
` タグで折り畳み可能）で出力します。オプションによる切り替えは不要です。 ### PRマージ時の反映 [](#prマージ時の反映) 1. PRがマージされると、CDが自動で `bm sync` を実行します。 1. 設定の差分がベースマキナの開発環境に反映されます。 ### 環境への同期 [](#環境への同期) 環境への同期用のブランチにマージすると、 `bm sync <環境ID>` が実行され、環境間のバージョンと有効化設定の同期が行なわれます。 [bm sync](/preview/code_management/cli/sync/) [基本（2ブランチ運用）](/preview/code_management/examples/two_branch/) --- 開発中の機能 コード管理 CLIコマンド bm sync # bm sync 設定ファイルの内容をベースマキナの環境に同期するコマンドです。同期先の環境IDの有無で挙動が変わります。 - **環境ID未指定**: 設定ファイルの内容を **開発環境** に反映します（設定ファイルとベースマキナ上の設定の差分検出・反映） - **環境ID指定**: 指定した環境に、他環境の [バージョンと有効化設定](/action/enablement_settings/) を同期します いずれの場合も、実行前に設定内容のバリデーションが行なわれます。 ``` # 開発環境に反映する（ドライラン） bm sync --dry # 開発環境に反映する bm sync # 設定ファイルから削除されたアクションを開発環境で無効化して反映する bm sync --with-disable # 開発環境の状態を検証環境に同期する bm sync <検証環境のID> # 検証環境の状態を本番環境に同期する bm sync <本番環境のID> --from <検証環境のID> # 同期内容をドライランで確認する bm sync --dry <環境ID> ``` ## オプション [](#オプション) | オプション | デフォルト値 | 説明 | | --- | --- | --- | | 第1引数 | （省略可） | 同期先の環境ID。省略した場合は開発環境への反映になる | | `--config ` | `basemachina.config.ts` | 設定ファイルのパス | | `--from ` | 開発環境のID | 同期元の環境ID。同期先の環境IDを指定したときのみ使用可 | | `--dry` | （反映する） | 変更を適用せずに実行結果を確認する | | `--with-disable` | （無効化しない） | 設定ファイルに存在しないアクションを開発環境で無効化する。同期先の環境ID未指定時のみ使用可 | `--from` は同期先の環境IDを指定したときのみ、 `--with-disable` は同期先の環境IDを指定しないとき（開発環境への反映）のみ使用できます。それ以外の組み合わせで指定するとエラーになります。 ## 開発環境への反映（環境ID未指定） [](#開発環境への反映環境id未指定) 同期先の環境IDを指定しないと、設定ファイルの内容を開発環境に反映します。 ### 差分検出の仕組み [](#差分検出の仕組み) 設定ファイルとベースマキナ上の設定を、アクションの識別子で突きあわせて比較します。 | 設定ファイル | ベースマキナ上の設定 | 結果 | | --- | --- | --- | | 存在する | 存在する（有効） | 内容に差分がある場合は **更新** | | 存在する | 存在する（開発環境で無効） | **再有効化** （内容に差分がある場合は併せて **更新** ） | | 存在する | 存在しない | **作成** | | 存在しない | 存在する | 何もしない（ `--with-disable` 指定時は **開発環境で無効化** ） | 設定ファイルに含まれないアクションは、デフォルトでは変更されません。 `--with-disable` オプションを指定した場合のみ、設定ファイルに存在しないアクションが開発環境で無効化されます。 ### 管理方法による挙動の違い [](#管理方法による挙動の違い) ベースマキナのアクションは、最後に作成・更新した場所によって「コード管理」と「Web管理」のいずれかに分類されます。 `bm sync` はこの管理方法に応じて挙動を切り替えます。 | ベースマキナ上の管理方法 | 設定ファイルに同じ識別子のアクションが存在する場合 | 設定ファイルに存在しない場合（ `--with-disable` 指定時） | | --- | --- | --- | | コード管理 | 内容の差分に応じて **作成・更新** 。差分がなければ変更なし | 開発環境で **無効化** | | Web管理 | 管理方法を「コード管理」に **移行** （内容に差分があればあわせて更新） | **無効化対象外** （引き続きWebで管理される） | Webで作成・更新されたアクションを設定ファイルに含めて `bm sync` を実行すると、そのアクションの管理方法がコード管理に切り替わります。設定ファイルに含めていないWeb管理のアクションは、 `--with-disable` を指定しても無効化されません。 ### 開発環境での無効化と再有効化 [](#開発環境での無効化と再有効化) `--with-disable` による無効化は、 [アクションの有効化設定](/action/enablement_settings/) の開発環境の設定を「無効」に変更する操作です。アクション自体は削除されず、識別子も保持されます。 一度無効化されたアクションを設定ファイルに戻して再度 `bm sync` を実行すると、開発環境で自動的に再有効化されます。これにより、 `git revert` や設定ファイルの巻き戻しで無効化を取り消せます。 他の環境（検証環境・本番環境など）の有効化設定は、 `--with-disable` では変更されません。ほかの環境へ状態を伝播させるには、同期先の環境IDを指定した `bm sync` を使用します。 ### 差分の出力内容 [](#差分の出力内容) 開発環境への反映時は、以下のサマリーを出力します。ヘッダーは `--dry` 指定時が `push すると以下の変更が適用されます` 、反映時は `push が完了しました` となります。 ``` push が完了しました ■ コード管理のアクション 作成: N 件 更新: N 件 再有効化: N 件 開発環境で無効化: N 件 変更なし: N 件 ■ Web 管理のアクション コード管理に移行（設定変更なし）: N 件 コード管理に移行（設定変更あり）: N 件 無効化対象外（引き続き Web で管理）: N 件 ``` 「Web 管理のアクション」ブロックは、該当するアクションが1件もない場合は表示されません。 各ブロックの件数に対応するアクションの詳細（作成内容、差分、対象アクションの一覧）は、サマリーの下に続けて表示されます。 `--with-disable` を指定していない状態で無効化対象が存在する場合、サマリーの「開発環境で無効化」行には「 `--with-disable` が指定されていないため適用されません」の注記が付きます。 ## 他の環境への同期（環境ID指定） [](#他の環境への同期環境id指定) 同期先の環境IDを指定すると、同期元環境のバージョンと有効化設定で同期先環境を上書きします。検証環境や本番環境への同期に使用します。 同期元環境は `--from` で指定するか、省略した場合は開発環境になります。 ### 同期対象 [](#同期対象) バージョンと有効化設定は同時に同期されます。 | 同期元の設定 | 同期先の設定 | 動作 | | --- | --- | --- | | 有効 | 有効 | バージョンを同期 | | 有効 | 無効 | **有効化** ＋バージョンを同期 | | 無効 | 有効 | **無効化** ＋バージョンを同期 | | 無効 | 無効 | バージョンを同期 | | 任意 | 未設定 | 同期元の状態で新規作成 | | 未設定 | 任意 | 同期しない | 同期元の有効化設定が無効の場合でも、バージョンは同期先にコピーされます。これにより、後から同期先を有効化した際に、同期元と同じバージョンで動作することが保証されます。 ### バージョン指定との関係 [](#バージョン指定との関係) アクションのバージョンには「特定のバージョン」と「常に最新」の2通りの指定方法があります。 `bm sync` は同期元のバージョン指定をそのまま同期先にコピーします。 - 同期元が「特定のバージョン」の場合、同期先も同じ特定のバージョンに設定されます - 同期元が「常に最新」の場合、同期先も「常に最新」に設定されます ### 開発環境への同期は禁止 [](#開発環境への同期は禁止) 開発環境は「設定ファイルからの反映」によって変更される起点であり、他の環境から同期する対象にはなりません。 `bm sync` の同期先に開発環境のIDを指定するとエラーになります。 ### 実行結果の出力 [](#実行結果の出力) 他の環境への同期時は「同期が完了しました」、ドライラン時は「同期内容を確認します (--dry)」というヘッダーで、同期内容をセクション別に分類したサマリーが出力されます。変化の種類に応じて「バージョン変更」「有効化」「無効化」の3つのセクションに分類されます。 ``` 同期が完了しました 同期元環境: <同期元環境の名前> 同期先環境: <同期先環境の名前> バージョン変更 (N件): <アクション名> (<識別子>): <同期前のバージョン> → <同期後のバージョン> 有効化 (N件): <アクション名> (<識別子>): 無効 → 有効 無効化 (N件): <アクション名> (<識別子>): 有効 → 無効 ``` - 同期元と同期先の有効化設定が同じ（両方有効、または両方無効）場合は **バージョン変更** に分類されます。 - 同期元のみ有効の場合は **有効化** 、同期先のみ有効の場合は **無効化** に分類されます。 - 同期対象がない場合は、本文に `変更はありません` と表示されます。 - ドライラン時は末尾に「※ `--dry` 指定のため変更は適用されていません」の注記が出力されます。 - 「常に最新」が指定されたアクションは、同期元のバージョン表記が `常に最新` と表示されます。 ### エラーケース [](#エラーケース) 他の環境への同期では、以下のケースがエラーとして扱われます。 | エラー条件 | 出力メッセージの例 | | --- | --- | | 同期元環境が見つからない | `同期元環境「<環境ID>」が見つかりません` | | 同期先環境が見つからない | `同期先環境「<環境ID>」が見つかりません` | | `--from` 未指定かつ開発環境が設定されていない | ``同期元環境が指定されていません。`--from` で指定するか、プロジェクトに開発環境を設定してください`` | | 同期元と同期先が同じ環境 | `同期元環境と同期先環境に同じ環境は指定できません` | | 同期元環境が無効化されている | `同期元環境「<環境ID>」は無効化されています` | | 同期先環境が無効化されている | `同期先環境「<環境ID>」は無効化されています` | | 同期先に開発環境を指定 | ``開発環境への同期はサポートされていません。環境IDを指定せずに `bm sync` を使用してください`` | ## 実行環境の自動検出 [](#実行環境の自動検出) 開発環境への反映時は、実行環境（GitHub Actions、GitLab CI、ローカル端末など）を自動検出し、出力形式を切り替えます。GitHub ActionsおよびGitLab CI上では、作成アクションの詳細を `
` タグで折り畳んでPRコメントに貼り付けやすい形式で出力します。その他の環境ではプレーンテキストで出力されます。 出力形式を明示的に切り替えるオプションはありません。 [readFile](/preview/code_management/sdk/read_file/) [CI/CDの設定](/preview/code_management/ci_cd/) --- 開発中の機能 コード管理 設定ファイル # 設定ファイル コード管理では、TypeScriptで設定を記述します。SDK（ `@basemachina/sdk/oac` ）が提供する関数を使うことで、型安全に設定を定義できます。 現在のコード管理では、gRPCアクションとJavaScriptアクションのみを設定ファイルで管理できます。ビューの設定は管理対象外ですが、ビュー内のコードは [コード取得設定](/preview/code_management/examples/view_code_fetch/) との組み合わせで同じリポジトリに同居させられます。 ## ダウンロードされるファイル [](#ダウンロードされるファイル) [始め方](/preview/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アクション用の型拡張 └── src/ └── actions/ # アクション定義 ├── get-users.ts ├── list-users.ts └── js-action-codes/ # JavaScriptアクションのコード（JSアクションがある場合） └── get-user.js ``` - アクション定義は `src/actions/` 配下に、アクションの識別子ごとに1ファイルずつ配置されます。 - JavaScriptアクションのコードは `src/actions/js-action-codes/` 配下に、アクションの識別子ごとに `.js` ファイルとして出力されます。 - GitHub Actionsのワークフローファイルは含まれません。CI/CDの設定は、 [CI/CDの設定](/preview/code_management/ci_cd/) を参考に手動で追加してください。 ファイル構造に厳密な規約はありません。設定ファイルに書き出したあとは、機能別のディレクトリに整理し直したり、モノレポの一部として既存リポジトリに同居させたりできます。 ## SDK関数 [](#sdk関数) 設定ファイルでは、 `@basemachina/sdk/oac` から以下のSDK関数をインポートして使用します。 - [`defineConfig`](/preview/code_management/sdk/define_config/) - プロジェクト全体の設定を定義する - [`defineAction`](/preview/code_management/sdk/define_action/) - アクションを定義する - [`readFile`](/preview/code_management/sdk/read_file/) - 外部ファイルの内容を読み込む ``` import { defineConfig, defineAction, 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` の型定義も利用できます。 [始め方](/preview/code_management/getting_started/) [defineConfig](/preview/code_management/sdk/define_config/) --- 開発中の機能 コード管理 運用例 3ブランチ運用 # 3ブランチ運用 `main` 、 `stg` 、 `prd` の3つのブランチで、開発環境・検証環境・本番環境を管理する運用例です。 本番環境への同期前に検証環境での動作確認を挟むため、より安全な運用フローを実現できます。 ## ブランチと環境の対応 [](#ブランチと環境の対応) | ブランチ | ベースマキナの環境 | 説明 | | --- | --- | --- | | `main` | 開発環境 | 日常的な開発を行なうブランチ | | `stg` | 検証環境 | 本番環境への同期前に動作を検証するブランチ | | `prd` | 本番環境 | 本番環境用のブランチ | ## 開発環境への変更 [](#開発環境への変更) ### 1. featureブランチで開発 [](#1-featureブランチで開発) `main` から `feature/xxx` ブランチを作成し、アクションやビューの設定を編集してPRを作成します。 ### 2. CIで差分を確認 [](#2-ciで差分を確認) PRが作成されると、CIで `bm sync --dry` が実行され、設定の差分がPRにコメントされます。 ### 3. マージして開発環境に反映 [](#3-マージして開発環境に反映) PRをマージすると、CDで `bm sync` が実行され、アクションの変更がベースマキナの開発環境に反映されます。新しいバージョンが作成され、開発環境では常に最新バージョンが使用されるため即時反映されます。設定ファイルから削除されたアクションは、 `--with-disable` 指定時のみ開発環境で無効化されます。 ビューのコードを同じリポジトリで管理している場合は、ワークフローにビューのビルド・アップロード処理を追加します。詳細は [コード取得設定との連携](/preview/code_management/examples/view_code_fetch/) をご参照ください。レビュー設定やデータソースなど、コード管理対象外の設定は引き続きベースマキナの画面から設定してください。 ## 検証環境への変更 [](#検証環境への変更) 開発環境で確認が取れたら、検証環境に同期します。 ### 1. PRの作成 [](#1-prの作成) `stg` ブランチに `main` をマージするPRを作成します。 ### 2. マージして検証環境に同期 [](#2-マージして検証環境に同期) PRをマージすると、CDで `bm sync <検証環境のID>` が実行され、検証環境の **すべて** のアクションのバージョンと有効化設定が開発環境の状態に合わせて同期されます。 ビューのコードも同じリポジトリで管理している場合は、同じワークフローで検証環境用のストレージへのアップロードも行なえます。 ## 本番環境への変更 [](#本番環境への変更) 検証環境で確認が取れたら、本番環境に同期します。 ### 1. PRの作成 [](#1-prの作成-1) `prd` ブランチに `stg` をマージするPRを作成します。 ### 2. マージして本番環境に同期 [](#2-マージして本番環境に同期) PRをマージすると、CDで `bm sync <本番環境のID> --from <検証環境のID>` が実行され、本番環境の **すべて** のアクションのバージョンと有効化設定が検証環境の状態に合わせて同期されます。 ビューのコードも同じリポジトリで管理している場合は、同じワークフローで本番環境用のストレージへのアップロードも行なえます。 ## コード管理した設定のWeb上での変更 [](#コード管理した設定のweb上での変更) コード管理している設定は、引き続きWeb上（ベースマキナの管理画面）からも変更できます。 Web上で変更すると、そのアクションの管理方法は一時的に「Web管理」に戻ります。次回の `bm sync` で、設定ファイルに差分があれば「コード管理に移行（設定変更あり）」として設定を上書きし、差分がなければ「コード管理に移行（設定変更なし）」として管理方法だけを戻します。 コード管理を開始した後は、設定の変更はコードで行なうことを推奨します。 ⚠️ Web上での変更時には、コード管理されている設定であることを示す警告が表示されます。 ## CI/CDの設定例 [](#cicdの設定例) | トリガー | 対象ブランチ | 実行内容 | 説明 | | --- | --- | --- | --- | | PR作成時 | `main` | `bm sync --dry` | 設定の差分をPRにコメント | | PRマージ時 | `main` | `bm sync` | 設定の差分を開発環境に反映 | | PRマージ時 | `stg` | `bm sync ` | 開発環境のバージョンを検証環境に同期 | | PR作成時 | `prd` | `bm sync --dry ` | 本番環境への同期の差分をPRにコメント | | PRマージ時 | `prd` | `bm sync --from ` | 検証環境のバージョンを本番環境に同期 | ### GitHub Actionsの設定ファイル例 [](#github-actionsの設定ファイル例) 以下は `.github/workflows/` に配置するワークフローファイルの例です。認証の詳細は [CI/CDの設定](/preview/code_management/ci_cd/) をご参照ください。 #### 開発環境への反映（ `.github/workflows/sync-dev.yml` ） [](#開発環境への反映githubworkflowssync-devyml) ``` name: Sync to dev on: pull_request: branches: [main] push: branches: [main] permissions: id-token: write contents: read pull-requests: write jobs: sync: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 20 - run: npm ci - name: Fetch OIDC ID Token id: oidc uses: actions/github-script@v7 with: script: | const token = await core.getIDToken("https://basemachina.com") core.setSecret(token) core.setOutput("token", token) - name: Dry run if: github.event_name == 'pull_request' run: npx bm sync --dry env: BM_OIDC_TOKEN: ${{ steps.oidc.outputs.token }} - name: Sync if: github.event_name == 'push' run: npx bm sync env: BM_OIDC_TOKEN: ${{ steps.oidc.outputs.token }} ``` #### 検証環境への同期（ `.github/workflows/sync-stg.yml` ） [](#検証環境への同期githubworkflowssync-stgyml) ``` name: Sync to stg on: push: branches: [stg] permissions: id-token: write contents: read jobs: sync: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 20 - run: npm ci - name: Fetch OIDC ID Token id: oidc uses: actions/github-script@v7 with: script: | const token = await core.getIDToken("https://basemachina.com") core.setSecret(token) core.setOutput("token", token) - name: Sync run: npx bm sync env: BM_OIDC_TOKEN: ${{ steps.oidc.outputs.token }} ``` #### 本番環境への同期（ `.github/workflows/sync-prd.yml` ） [](#本番環境への同期githubworkflowssync-prdyml) ``` name: Sync to prd on: pull_request: branches: [prd] push: branches: [prd] permissions: id-token: write contents: read pull-requests: write jobs: sync: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 20 - run: npm ci - name: Fetch OIDC ID Token id: oidc uses: actions/github-script@v7 with: script: | const token = await core.getIDToken("https://basemachina.com") core.setSecret(token) core.setOutput("token", token) - name: Dry run if: github.event_name == 'pull_request' run: npx bm sync --dry --from env: BM_OIDC_TOKEN: ${{ steps.oidc.outputs.token }} - name: Sync if: github.event_name == 'push' run: npx bm sync --from env: BM_OIDC_TOKEN: ${{ steps.oidc.outputs.token }} ``` [基本（2ブランチ運用）](/preview/code_management/examples/two_branch/) [コード取得設定との連携](/preview/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にコメントされます。 ### 3. マージして開発環境に反映 [](#3-マージして開発環境に反映) PRをマージすると、CDで `bm sync` が実行され、アクションの変更がベースマキナの開発環境に反映されます。新しいバージョンが作成され、開発環境では常に最新バージョンが使用されるため即時反映されます。設定ファイルから削除されたアクションは、 `--with-disable` 指定時のみ開発環境で無効化されます。 ビューのコードを同じリポジトリで管理している場合は、ワークフローにビューのビルド・アップロード処理を追加します。詳細は [コード取得設定との連携](/preview/code_management/examples/view_code_fetch/) をご参照ください。レビュー設定やデータソースなど、コード管理対象外の設定は引き続きベースマキナの画面から設定してください。 ## 本番環境への変更 [](#本番環境への変更) 開発環境で確認が取れたら、本番環境に同期します。 ### 1. PRの作成 [](#1-prの作成) `prd` ブランチに `main` をマージするPRを作成します。 ### 2. マージして本番環境に同期 [](#2-マージして本番環境に同期) PRをマージすると、CDで `bm sync <本番環境のID>` が実行され、本番環境の **すべて** のアクションのバージョンと有効化設定が開発環境の状態に合わせて同期されます。 ビューのコードも同じリポジトリで管理している場合は、同じワークフローで本番環境用のストレージへのアップロードも行なえます。詳細は [コード取得設定との連携](/preview/code_management/examples/view_code_fetch/) をご参照ください。 ## コード管理した設定のWeb上での変更 [](#コード管理した設定のweb上での変更) コード管理している設定は、引き続きWeb上（ベースマキナの管理画面）からも変更できます。 Web上で変更すると、そのアクションの管理方法は一時的に「Web管理」に戻ります。次回の `bm sync` で、設定ファイルに差分があれば「コード管理に移行（設定変更あり）」として設定を上書きし、差分がなければ「コード管理に移行（設定変更なし）」として管理方法だけを戻します。 コード管理を開始した後は、設定の変更はコードで行なうことを推奨します。 ⚠️ Web上での変更時には、コード管理されている設定であることを示す警告が表示されます。 ## CI/CDの設定例 [](#cicdの設定例) | トリガー | 対象ブランチ | 実行内容 | 説明 | | --- | --- | --- | --- | | PR作成時 | `main` | `bm sync --dry` | 設定の差分をPRにコメント | | PRマージ時 | `main` | `bm sync` | 設定の差分を開発環境に反映 | | PR作成時 | `prd` | `bm sync --dry ` | 本番への同期の差分をコメント | | PRマージ時 | `prd` | `bm sync ` | 開発環境のバージョンを本番に同期 | ### GitHub Actionsの設定ファイル例 [](#github-actionsの設定ファイル例) 以下は `.github/workflows/` に配置するワークフローファイルの例です。認証の詳細は [CI/CDの設定](/preview/code_management/ci_cd/) をご参照ください。 #### 開発環境への反映（ `.github/workflows/sync-dev.yml` ） [](#開発環境への反映githubworkflowssync-devyml) ``` name: Sync to dev on: pull_request: branches: [main] push: branches: [main] permissions: id-token: write contents: read pull-requests: write jobs: sync: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 20 - run: npm ci - name: Fetch OIDC ID Token id: oidc uses: actions/github-script@v7 with: script: | const token = await core.getIDToken("https://basemachina.com") core.setSecret(token) core.setOutput("token", token) - name: Dry run if: github.event_name == 'pull_request' run: npx bm sync --dry env: BM_OIDC_TOKEN: ${{ steps.oidc.outputs.token }} - name: Sync if: github.event_name == 'push' run: npx bm sync env: BM_OIDC_TOKEN: ${{ steps.oidc.outputs.token }} ``` #### 本番環境への同期（ `.github/workflows/sync-prd.yml` ） [](#本番環境への同期githubworkflowssync-prdyml) ``` name: Sync to prd on: pull_request: branches: [prd] push: branches: [prd] permissions: id-token: write contents: read pull-requests: write jobs: sync: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 20 - run: npm ci - name: Fetch OIDC ID Token id: oidc uses: actions/github-script@v7 with: script: | const token = await core.getIDToken("https://basemachina.com") core.setSecret(token) core.setOutput("token", token) - name: Dry run if: github.event_name == 'pull_request' run: npx bm sync --dry env: BM_OIDC_TOKEN: ${{ steps.oidc.outputs.token }} - name: Sync if: github.event_name == 'push' run: npx bm sync env: BM_OIDC_TOKEN: ${{ steps.oidc.outputs.token }} ``` [CI/CDの設定](/preview/code_management/ci_cd/) [3ブランチ運用](/preview/code_management/examples/three_branch/) --- 開発中の機能 コード管理 運用例 コード取得設定との連携 # コード取得設定との連携 コード管理のリポジトリでビュー（コードエディター）のコードも一緒に管理し、 [コード取得設定](/view/code_editor/git_management/) と組み合わせて運用する例です。 アクションとビューの変更を同じPRでレビューできるため、関連する変更をまとめて管理できます。 ## リポジトリ構造の例 [](#リポジトリ構造の例) ``` my-project/ ├── basemachina.config.ts ├── actions/ │ ├── get-users.ts │ └── fetch-view-code.ts # ビューのコードを取得するアクション └── views/ └── user-list/ └── index.tsx # ビューのコード ``` ## 仕組み [](#仕組み) ビューのコード管理は、以下の流れで動作します。 1. リポジトリ内の `views/` ディレクトリにビューのコードを配置する 1. CI/CDで、ビューのコードをビルドしてストレージ（GCSやS3など）にアップロードする 1. ベースマキナのビューで [コード取得設定](/view/code_editor/git_management/) を有効化し、ストレージからコードを取得するアクションを指定する 1. ビューを表示するたびに、ストレージから最新のコードが読み込まれる ## GitHub Actionsの設定ファイル例 [](#github-actionsの設定ファイル例) 以下は、ビューのコードをビルドしてGCSにアップロードするワークフローの例です。アクションの反映（ `bm sync` ）と合わせて実行します。 #### 開発環境への反映（ `.github/workflows/sync-dev.yml` ） [](#開発環境への反映githubworkflowssync-devyml) ``` name: Sync to dev on: pull_request: branches: [main] push: branches: [main] permissions: id-token: write contents: read pull-requests: write jobs: sync: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 20 - run: npm ci - name: Fetch OIDC ID Token id: oidc uses: actions/github-script@v7 with: script: | const token = await core.getIDToken("https://basemachina.com") core.setSecret(token) core.setOutput("token", token) # アクションの差分検出・反映 - name: Dry run if: github.event_name == 'pull_request' run: npx bm sync --dry env: BM_OIDC_TOKEN: ${{ steps.oidc.outputs.token }} - name: Sync if: github.event_name == 'push' run: npx bm sync env: BM_OIDC_TOKEN: ${{ steps.oidc.outputs.token }} # ビューのビルド・アップロード - 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の切り替え」をご参照ください。 [3ブランチ運用](/preview/code_management/examples/three_branch/) [トラブルシューティング](/preview/code_management/troubleshooting/) --- 開発中の機能 コード管理 始め方 # 始め方 コード管理を始めるための手順を説明します。 ## 前提条件 [](#前提条件) - [開発環境](/admin/environment/development_environment/) が設定済みであること - 企業アカウントの管理者の権限を持っていること ## 1. コード管理の開始とOIDC信頼ポリシーの設定 [](#1-コード管理の開始とoidc信頼ポリシーの設定) コード管理でのCLIやCI/CDからの認証は、 **OIDC信頼ポリシー** を使用します。OIDC信頼ポリシーは、GitHub Actionsなどの外部サービスが発行したOIDC ID Tokenを、ベースマキナのサービスアカウントと紐づけるためのポリシーです。 1. 右上のメニューから「設定」を選択します。 1. サイドバーのメニューから「開発設定」を選択します。 1. 「コード管理」セクションの「コード管理を開始する」ボタンをクリックします。これにより、コード管理用のサービスアカウントがプロジェクトに自動作成されます。 1. サービスアカウント作成後に表示される「OIDC信頼ポリシー」のフォームから、「ポリシーを追加」→「GitHub Actions」または「カスタム」を選択して、ポリシーを追加します。 「コード管理を開始する」ボタンは企業アカウントの管理者のみが操作できます。 サービスアカウントはプロジェクト管理者の権限を持ち、アクションの作成・更新などの操作が可能です。サービスアカウントはベースマキナの画面上のユーザー一覧には表示されず、課金の対象にもなりません。 ### OIDC信頼ポリシーの設定項目 [](#oidc信頼ポリシーの設定項目) | 項目 | 説明 | | --- | --- | | `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」を選択すると、 `Issuer` などがあらかじめ入力された状態でポリシーを追加できます。 `Bound Claims` には、例えば `key: sub` 、 `pattern: repo:/:ref:refs/heads/main` のように、受け付けるブランチ・リポジトリの条件を指定します。 ## 2. プロジェクトのダウンロード [](#2-プロジェクトのダウンロード) 「開発設定」画面の「コード管理」セクション上部にある「設定のダウンロード」ボタンをクリックすると、プロジェクトの設定ファイル一式（ `oac-project.zip` ）をダウンロードできます。 ダウンロードされるファイルの構成は、 [設定ファイル](/preview/code_management/configuration/) をご参照ください。 ダウンロードの対象はgRPCアクションとJavaScriptアクションのうち、識別子が設定されているものです。識別子が未設定のアクションはダウンロードされないため、同じ画面にある「識別子の一括設定」から事前に識別子を設定してください。 ## 3. リポジトリの作成とセットアップ [](#3-リポジトリの作成とセットアップ) ダウンロードしたファイルをGitリポジトリとして管理します。 ``` # リポジトリを作成 git init git remote add origin <リモートリポジトリのURL> # 依存関係をインストール npm install # 初回コミットとプッシュ git add . git commit -m "Initial commit" git push -u origin main ``` ## 4. CI/CDからの認証の準備 [](#4-cicdからの認証の準備) CI/CDからCLIを実行する際は、CI/CDが発行したOIDC ID Tokenを環境変数 `BM_OIDC_TOKEN` に設定します。 GitHub Actionsの場合は、ワークフローで `id-token: write` のパーミッションを付与します。 `actions/github-script` などから `core.getIDToken()` で取得したトークンを `BM_OIDC_TOKEN` に設定します。 具体的なワークフローの書き方は、 [CI/CDの設定](/preview/code_management/ci_cd/) と [運用例](/preview/code_management/examples/two_branch/) をご参照ください。 ローカルからCLIを実行する場合は、 `bm login` でブラウザログインするとトークンが `~/.basemachina/credentials.json` に保存されます。以降はそのトークンが自動で利用されるため、 `BM_OIDC_TOKEN` の設定は不要です。 ## 5. 初回の反映 [](#5-初回の反映) セットアップが完了したら、PRを作成してコード管理を開始します。 1. PRを作成すると、CIで `bm sync --dry` が実行され、設定の差分がPRにコメントされます。 1. 初回は各アクションの管理方法が「Web管理」から「コード管理」に移行する差分が表示されます。 1. PRをマージすると、 `bm sync` が実行されて管理方法が更新されます。 初回の反映では、管理方法の変更のみが行なわれます。アクションの設定内容自体は変更されません。ダウンロード後に画面上で設定を変更した場合は、差分として検出されます。 これで、以降はコード管理の運用に沿って開発を進められます。詳しくは [運用例](/preview/code_management/examples/two_branch/) をご参照ください。 [コード管理とは](/preview/code_management/) [設定ファイル](/preview/code_management/configuration/) --- 開発中の機能 コード管理 SDK defineAction # defineAction アクションを定義する関数です。 `class` フィールドで種別を指定し、種別に応じたフィールドを設定します。 `class` によって設定できるフィールドが型で絞り込まれるため、存在しないフィールドを指定するとTypeScriptのコンパイルエラーになります。 以下の設定項目はコード管理の対象外です。これらはベースマキナの管理画面から設定してください。 - 結果の加工（加工スクリプト、ページネーション） - 環境ごとの有効/無効 - 環境ごとのバージョン ## 共通フィールド [](#共通フィールド) すべてのアクション種別で使用できるフィールドです。 | フィールド | 型 | 必須 | 説明 | | --- | --- | --- | --- | | `id` | `string` | はい | アクションの識別子。1〜128文字で、使用できる文字は英数字・アンダースコア・ハイフン（ `^[a-zA-Z0-9_-]+$` ） | | `name` | `string` | はい | アクション名。1〜128文字 | | `description` | `string` | いいえ | 説明。最大1000文字 | | `preferJobExecution` | `boolean` | いいえ | ジョブ実行を優先的に表示するか | | `jobDetailVisibility` | `"EXECUTOR_ONLY" | "PUBLIC"` | いいえ | ジョブ詳細の公開範囲 | | `reviewSettingId` | `string` | いいえ | レビュー設定の識別子 | | `notificationSettings` | `NotificationSettingsConfig` | いいえ | 通知設定 | | `permissions` | `[PermissionTarget, ...]` （非空） | いいえ | 実行権限の対象。指定する場合は1件以上必要 | ### permissions [](#permissions) `permissions` は実行を許可する対象の配列です。指定しない場合はプロジェクト内の全ユーザーに実行が許可されます。 ``` permissions: [ { type: "user", id: "<ユーザーID>" }, { type: "userGroup", id: "<ユーザーグループID>" }, { type: "javascriptAction", id: "" }, ]; ``` | `type` | 説明 | | --- | --- | | `"user"` | 特定のユーザーに実行を許可 | | `"userGroup"` | 特定のユーザーグループに属するユーザーに実行を許可 | | `"javascriptAction"` | JavaScriptアクションの判定結果に従って実行を許可 | ### notificationSettings [](#notificationsettings) アクションの成功時・失敗時に通知するための設定です。 ``` notificationSettings: { onSuccess: { notificationMethodId: "<通知方法の識別子>", mentionTargetUserIds: ["<ユーザーID>"], message: "ユーザー作成が成功しました", }, onError: { notificationMethodId: "<通知方法の識別子>", message: "ユーザー作成に失敗しました", }, }; ``` | フィールド | 型 | 必須 | 説明 | | --- | --- | --- | --- | | `onSuccess.notificationMethodId` | `string` | はい | 通知方法の識別子 | | `onSuccess.mentionTargetUserIds` | `string[]` | いいえ | メンション対象ユーザー | | `onSuccess.message` | `string` | いいえ | 通知メッセージ | | `onError.notificationMethodId` | `string` | はい | 通知方法の識別子 | | `onError.mentionTargetUserIds` | `string[]` | いいえ | メンション対象ユーザー | | `onError.message` | `string` | いいえ | 通知メッセージ | `onSuccess` と `onError` はどちらも省略可能で、必要な方だけ指定できます。 ## gRPCアクション [](#grpcアクション) ``` import { defineAction } from "@basemachina/sdk/oac"; export const fetchOrders = defineAction({ id: "fetch-orders", name: "注文一覧取得", class: "grpc", dataSource: "orders-service", fullyQualifiedMethodName: "orders.OrderService/ListOrders", parameters: [{ type: "TEXT", name: "customerId", required: true }], }); ``` | フィールド | 型 | 必須 | 説明 | | --- | --- | --- | --- | | `class` | `"grpc"` | はい | gRPCアクションを指定 | | `dataSource` | `string` | はい | データソースの識別子 | | `fullyQualifiedMethodName` | `string` | はい | gRPCメソッドの完全修飾名 | | `headers` | `{ name: string; value: string }[]` | いいえ | リクエストヘッダー | | `body` | `{ payload: string }` | いいえ | リクエストボディ | | `parameters` | `ParameterConfig[]` | いいえ | パラメーター定義（下記参照） | ## JavaScriptアクション [](#javascriptアクション) ``` import { defineAction, readFile } from "@basemachina/sdk/oac"; export const createUser = defineAction({ id: "create-user", name: "ユーザー作成", class: "javascript", code: readFile("./js-action-codes/create-user.ts"), parameters: [ { type: "TEXT", name: "email", required: true }, { type: "NUMBER", name: "age", required: true }, ], }); ``` | フィールド | 型 | 必須 | 説明 | | --- | --- | --- | --- | | `class` | `"javascript"` | はい | JavaScriptアクションを指定 | | `code` | `string` | はい | JavaScriptコードまたは `readFile()` の戻り値 | | `parameters` | `ParameterConfig[]` | いいえ | パラメーター定義（下記参照） | ## パラメーター定義 [](#パラメーター定義) `parameters` には、アクションの入力パラメーターを `type` フィールドで種別を分けて配列で指定します。gRPCアクションとJavaScriptアクションで、使用できるパラメーター種別と `formatType` が一部異なります。 すべての種別に共通で、 `name` は1〜128文字、 `description` は最大400文字までです。 | パラメーター種別 | gRPC | JavaScript | | --- | --- | --- | | `TEXT` | 使用可 | 使用可 | | `NUMBER` | 使用可 | 使用可 | | `DATE` | 使用可 | 使用可 | | `BOOL` | 使用可 | 使用可 | | `SYSTEM_VALUE` | 使用可 | 使用可 | | `JSON` | 使用可 | 使用不可 | | `FILE` | 使用不可 | 使用可 | | `ARRAY` | 使用可 | 使用可 | | `TUPLE` | 使用可 | 使用可 | ### TEXTパラメーター [](#textパラメーター) ``` { type: "TEXT", name: "email", required: true, defaultValue: "example@example.com", minLength: 1, maxLength: 255, multiline: false, regexValidation: "^[\\w.+-]+@[\\w-]+\\.[\\w.]+$", regexErrorMessage: "メールアドレスの形式で入力してください", } ``` | フィールド | 型 | 必須 | 説明 | | --- | --- | --- | --- | | `type` | `"TEXT"` | はい | テキストパラメーターを指定 | | `name` | `string` | はい | パラメーター名 | | `description` | `string` | いいえ | 説明 | | `required` | `boolean` | いいえ | 必須かどうか | | `defaultValue` | `string` | いいえ | デフォルト値 | | `minLength` | `number` | いいえ | 最小文字数 | | `maxLength` | `number` | いいえ | 最大文字数 | | `multiline` | `boolean` | いいえ | 複数行入力を許可するか | | `newlineCharacters` | `string` | いいえ | `multiline: true` の場合の改行コード | | `regexValidation` | `string` | いいえ | 入力値のバリデーション正規表現（ `multiline: false` のみ） | | `regexErrorMessage` | `string` | いいえ | バリデーションエラー時のメッセージ | | `selectOptions` | `{ label: string; value: string }[]` | いいえ | 選択肢（ `multiline: false` のみ） | | `masterDataFetchSettingId` | `string` | いいえ | マスターデータ取得設定の識別子（ `multiline: false` のみ） | `selectOptions` と `masterDataFetchSettingId` は排他関係にあり、どちらか一方のみ指定できます。 ### NUMBERパラメーター [](#numberパラメーター) ``` { type: "NUMBER", name: "age", required: true, min: 0, max: 150, } ``` | フィールド | 型 | 必須 | 説明 | | --- | --- | --- | --- | | `type` | `"NUMBER"` | はい | 数値パラメーターを指定 | | `name` | `string` | はい | パラメーター名 | | `description` | `string` | いいえ | 説明 | | `required` | `boolean` | いいえ | 必須かどうか | | `defaultValue` | `number` | いいえ | デフォルト値 | | `min` | `number` | いいえ | 最小値 | | `max` | `number` | いいえ | 最大値 | | `selectOptions` | `{ label: string; value: number }[]` | いいえ | 選択肢 | | `masterDataFetchSettingId` | `string` | いいえ | マスターデータ取得設定の識別子 | ### DATEパラメーター [](#dateパラメーター) ``` // ISO文字列で扱う場合 { type: "DATE", name: "targetDate", required: true, includeTime: false, format: "YYYY-MM-DD", defaultValue: "2025-01-01", } // Unixタイムスタンプで扱う場合 { type: "DATE", name: "targetDate", required: true, includeTime: true, useUnixTimestamp: true, defaultValue: 1735689600, } ``` | フィールド | 型 | 必須 | 説明 | | --- | --- | --- | --- | | `type` | `"DATE"` | はい | 日付パラメーターを指定 | | `name` | `string` | はい | パラメーター名 | | `description` | `string` | いいえ | 説明 | | `required` | `boolean` | いいえ | 必須かどうか | | `includeTime` | `boolean` | いいえ | 時刻を含めるか | | `useUnixTimestamp` | `boolean` | いいえ | Unixタイムスタンプで扱うか。 `true` の場合 `format` は指定不可 | | `format` | `string` | いいえ | 日付フォーマット（ `useUnixTimestamp: false` の場合のみ） | | `defaultValue` | `string | number` | いいえ | デフォルト値（ `useUnixTimestamp: true` の場合は `number` ） | ### BOOLパラメーター [](#boolパラメーター) ``` // JavaScriptアクションの例（真偽値で扱う） { type: "BOOL", name: "isActive", formatType: "RAW", defaultValue: true, } // JavaScriptアクションの例（文字列で扱う） { type: "BOOL", name: "isActive", formatType: "STRING", trueValue: "1", falseValue: "0", } // gRPCアクションの例（BOOLは文字列形式のみ、formatType指定不要） { type: "BOOL", name: "isActive", trueValue: "true", falseValue: "false", } ``` | フィールド | 型 | 必須 | 説明 | | --- | --- | --- | --- | | `type` | `"BOOL"` | はい | 真偽値パラメーターを指定 | | `name` | `string` | はい | パラメーター名 | | `description` | `string` | いいえ | 説明 | | `defaultValue` | `boolean` | いいえ | デフォルト値 | | `formatType` | `"RAW" | "STRING"` | JavaScriptで必須、gRPCでは不要 | 値の扱い方。 `"RAW"` は真偽値、 `"STRING"` は `trueValue` / `falseValue` の文字列 | | `trueValue` | `string` | `formatType: "STRING"` で必須 | `true` のときに送信する文字列 | | `falseValue` | `string` | `formatType: "STRING"` で必須 | `false` のときに送信する文字列 | gRPCアクションの `BOOL` は常に文字列形式で扱われるため、 `formatType` の指定は不要で `trueValue` / `falseValue` が必須です。 ### FILEパラメーター（JavaScriptアクションのみ） [](#fileパラメーターjavascriptアクションのみ) ``` { type: "FILE", name: "uploadFile", required: true, maxBytes: 10485760, } ``` | フィールド | 型 | 必須 | 説明 | | --- | --- | --- | --- | | `type` | `"FILE"` | はい | ファイルパラメーターを指定 | | `name` | `string` | はい | パラメーター名 | | `description` | `string` | いいえ | 説明 | | `required` | `boolean` | いいえ | 必須かどうか | | `maxBytes` | `number` | いいえ | 最大バイト数 | ### JSONパラメーター（gRPCアクションのみ） [](#jsonパラメーターgrpcアクションのみ) ``` { type: "JSON", name: "statusFilter", valueType: "TEXT", selectOptions: [ { label: "有効", value: "ACTIVE" }, { label: "無効", value: "INACTIVE" }, ], } ``` | フィールド | 型 | 必須 | 説明 | | --- | --- | --- | --- | | `type` | `"JSON"` | はい | JSONパラメーターを指定 | | `name` | `string` | はい | パラメーター名 | | `description` | `string` | いいえ | 説明 | | `valueType` | `"TEXT" | "NUMBER" | "DATE"` | はい | JSONとして送信する値の型 | `valueType` に応じて、 `TEXT` / `NUMBER` / `DATE` パラメーターと同様のフィールドが追加で指定できます（ `required` を除く）。 ### SYSTEM\_VALUEパラメーター [](#system_valueパラメーター) ログイン中のユーザーIDなど、システムが提供する値を自動的に埋め込むパラメーターです。 ``` { type: "SYSTEM_VALUE", name: "currentUserId", required: true, } ``` | フィールド | 型 | 必須 | 説明 | | --- | --- | --- | --- | | `type` | `"SYSTEM_VALUE"` | はい | システム値パラメーターを指定 | | `name` | `string` | はい | パラメーター名 | | `description` | `string` | いいえ | 説明 | | `required` | `boolean` | いいえ | 必須かどうか | ### ARRAYパラメーター [](#arrayパラメーター) 複数要素を配列として入力するパラメーターです。 `childElement` で要素の型を、 `formatType` で送信時の形式を指定します。 ``` { type: "ARRAY", name: "targetIds", formatType: "JSON", childElement: { type: "NUMBER" }, } ``` | フィールド | 型 | 必須 | 説明 | | --- | --- | --- | --- | | `type` | `"ARRAY"` | はい | 配列パラメーターを指定 | | `name` | `string` | はい | パラメーター名 | | `description` | `string` | いいえ | 説明 | | `formatType` | `"RAW" | "JSON" | "SEPARATOR"` | はい | 送信時の形式 | | `childElement` | `ElementConfig` | はい | 要素の型（ `TEXT` / `NUMBER` / `DATE` / `ARRAY` / `TUPLE` ） | | `minItems` | `number` | いいえ | 最小要素数 | | `maxItems` | `number` | いいえ | 最大要素数 | | `delimiter` | `string` | `formatType: "SEPARATOR"` のみ | 区切り文字 | | `quoteCharacter` | `string` | `formatType: "SEPARATOR"` のみ | 引用符 | gRPCアクションでは `formatType: "RAW"` は使用できません。 ### TUPLEパラメーター [](#tupleパラメーター) 複数のフィールドを1つのパラメーターとしてまとめるタプル型のパラメーターです。 ``` { type: "TUPLE", name: "filter", formatType: "JSON", tupleElements: [ { label: "開始日", childElement: { type: "DATE" } }, { label: "終了日", childElement: { type: "DATE" } }, ], } ``` | フィールド | 型 | 必須 | 説明 | | --- | --- | --- | --- | | `type` | `"TUPLE"` | はい | タプルパラメーターを指定 | | `name` | `string` | はい | パラメーター名 | | `description` | `string` | いいえ | 説明 | | `formatType` | `"RAW" | "JSON"` | はい | 送信時の形式 | | `tupleElements` | `{ label?: string; childElement: TupleChildElementConfig }[]` | いいえ | 各要素の定義 | `tupleElements` の `childElement` には `TEXT` / `NUMBER` / `DATE` / `BOOL` が指定できます。gRPCアクションでは `formatType` に `"JSON"` のみが指定可能です。 [defineConfig](/preview/code_management/sdk/define_config/) [readFile](/preview/code_management/sdk/read_file/) --- 開発中の機能 コード管理 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"; export default defineConfig({ project: { id: "your-project-id", }, actions: [getUsers, listUsers], }); ``` ## プロパティ [](#プロパティ) | プロパティ | 型 | 必須 | 説明 | | --- | --- | --- | --- | | `project.id` | `string` | はい | プロジェクトのID | | `actions` | `ActionConfig[]` | はい | アクション定義の配列 | [設定ファイル](/preview/code_management/configuration/) [defineAction](/preview/code_management/sdk/define_action/) --- 開発中の機能 コード管理 SDK readFile # readFile 外部ファイルの内容を読み込む関数です。JavaScriptアクションのコードを別ファイルで管理できます。 ## 使用例 [](#使用例) ``` import { defineAction, readFile } from "@basemachina/sdk/oac"; // JavaScriptアクションのコードを読み込む export const createUser = defineAction({ id: "create-user", name: "ユーザー作成", class: "javascript", code: readFile("./js-action-codes/create-user.ts"), }); ``` ## 引数 [](#引数) | 引数 | 型 | 説明 | | --- | --- | --- | | `relativePath` | `string` | 呼び出し元ファイルからの相対パス | ## TypeScriptファイルの自動トランスパイル [](#typescriptファイルの自動トランスパイル) 拡張子が `.ts` / `.tsx` / `.mts` / `.cts` のファイルを指定した場合は、自動的にJavaScriptにトランスパイルされます。 これにより、JavaScriptアクションのコードをTypeScriptで記述できます。 [defineAction](/preview/code_management/sdk/define_action/) [bm sync](/preview/code_management/cli/sync/) --- 開発中の機能 コード管理 トラブルシューティング # トラブルシューティング コード管理の運用中によく発生する困りごとと、その対処方法をまとめます。 本ページでは「現状の対応方法」と並べて、 [今後追加予定の機能](/preview/code_management/upcoming_features/) （ `bm rollback` 、 `bm hotfix` 、 `draftActions` ）を使った将来の対応方法も紹介します。将来の対応方法は構想段階のため、仕様は変更される可能性があります。各ケースごとに、該当する「現状の対応方法」「将来の対応方法」またはその両方を記載します。 ## バージョンを戻したい [](#バージョンを戻したい) ### 1つのアクションを以前のバージョンに戻したい [](#1つのアクションを以前のバージョンに戻したい) **状況**: 本番環境に同期した特定のアクションに不具合があり、そのアクションだけを以前のバージョンに戻したい。 #### 対応方法 [](#対応方法) アクション単位のバージョン巻き戻しはWeb UIからのみ行なえます（CLIには該当コマンドがありません）。 1. 本番環境のアクション一覧から、対象のアクションのバージョン/有効化設定画面を開く 1. 戻したい特定のバージョンを選択して保存する [今後追加予定の `bm rollback`](/preview/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` ）](/preview/code_management/upcoming_features/) で、同期単位の一括ロールバックを実行します。 ### 環境ごとに異なるバージョンで動かしたい [](#環境ごとに異なるバージョンで動かしたい) **状況**: 開発環境では新しいバージョンで開発を続けつつ、本番環境だけは以前のバージョンに戻して動かしたい。 #### 現状の対応方法 [](#現状の対応方法-1) 本番環境のWeb UIで対象のアクションを以前のバージョンに切り替えます。ただし、次回の `bm sync <環境ID>` で開発環境のバージョンが再度反映されてしまうため、本番環境への同期のタイミングを制御する必要があります。 #### 将来の対応方法 [](#将来の対応方法-1) [`bm rollback`](/preview/code_management/upcoming_features/) で本番環境のみを以前の同期時点に戻すか、 [`bm hotfix`](/preview/code_management/upcoming_features/) で本番環境専用のバージョンを作成します。 ### 環境間でバージョンを揃え直したい [](#環境間でバージョンを揃え直したい) **状況**: 何らかの理由で検証環境と本番環境のバージョンがずれてしまったため、揃え直したい。 #### 対応方法 [](#対応方法-1) `bm sync` で同期元の環境を明示的に指定して再同期します。 ``` # 検証環境のバージョンを本番環境に揃える bm sync <本番環境のID> --from <検証環境のID> ``` 詳細は [`bm sync` の他の環境への同期](/preview/code_management/cli/sync/) をご参照ください。 ## 特定の環境だけ修正したい [](#特定の環境だけ修正したい) ### 本番環境でのみ緊急修正を入れたい [](#本番環境でのみ緊急修正を入れたい) **状況**: 本番環境でのみ発生するバグが見つかり、開発環境を経由せずに本番環境だけを直接修正したい。 #### 現状の対応方法 [](#現状の対応方法-2) 現状の `bm sync` では、開発環境を経由しないと本番環境のアクションを修正できません。やむを得ずWeb UIでアクションを直接修正する場合は、新しいバージョンを作成したうえで、本番環境のバージョン/有効化設定画面から作成したバージョンを紐づけます。その後、変更内容を設定ファイルにも反映する必要があります。 #### 将来の対応方法 [](#将来の対応方法-2) `bm hotfix` コマンドで、本番環境のアクションを直接修正します。想定する運用フローは [hotfix（ `bm hotfix` ）](/preview/code_management/upcoming_features/) をご参照ください。 ## 設定ファイルとWeb UIの整合性 [](#設定ファイルとweb-uiの整合性) ### Web UIで変更した内容をコード管理に戻したい [](#web-uiで変更した内容をコード管理に戻したい) **状況**: Web UIから誤って変更してしまったアクションを、設定ファイルの内容に戻したい。 #### 対応方法 [](#対応方法-2) 設定ファイルを変更せずに `bm sync` を実行します。Web UIで変更されたアクションは、次回の `bm sync` で「コード管理に移行（設定変更あり）」として設定ファイルの内容に上書きされます。 詳細は [`bm sync` の管理方法による挙動の違い](/preview/code_management/cli/sync/) をご参照ください。 ### Web UIで変更した内容を設定ファイルに取り込みたい [](#web-uiで変更した内容を設定ファイルに取り込みたい) **状況**: Web UIで意図的に変更した内容を、設定ファイルにも反映してコード管理に戻したい。 #### 対応方法 [](#対応方法-3) 現状、Web UIから設定ファイルへの自動的な書き戻しは提供されていません。以下のいずれかの方法を使って手動で取り込みます。 - [始め方](/preview/code_management/getting_started/) の「プロジェクトのダウンロード」と同じ手順で「設定のダウンロード」から再ダウンロードし、変更されたアクションのファイルだけ差し替える - Web UIで変更内容を確認し、対応する設定ファイルを手動で更新する 更新後、 `bm sync --dry` で差分が出ないことを確認してから運用に戻します。 ### 設定ファイルから誤ってアクションを削除した [](#設定ファイルから誤ってアクションを削除した) **状況**: 設定ファイルから誤ってアクションの定義を削除してしまいました。 `bm sync` はまだ実行していない、または `--with-disable` を指定していません。 #### 対応方法 [](#対応方法-4) 設定ファイルからアクションを削除しただけでは、 `--with-disable` を指定しない限り環境上のアクションは変更されません。 `git revert` または手動で設定ファイルを元に戻し、再度 `bm sync` を実行してください。 `--with-disable` を指定して開発環境で無効化してしまった場合も、設定ファイルにアクションを戻して `bm sync` を実行すれば、開発環境で **自動的に再有効化** されます。 詳細は [開発環境での無効化と再有効化](/preview/code_management/cli/sync/) をご参照ください。 ### 設定ファイルから削除したアクションを環境からも削除したい [](#設定ファイルから削除したアクションを環境からも削除したい) **状況**: 不要になったアクションを設定ファイルから削除したので、環境上でも無効化したい。 #### 対応方法 [](#対応方法-5) `--with-disable` オプションを指定して `bm sync` を実行することで、開発環境上のアクションを無効化できます。 ``` bm sync --with-disable ``` 検証環境・本番環境への伝播は、その後の `bm sync <環境ID>` で行ないます。 `--with-disable` はアクションを削除するのではなく、有効化設定を「無効」に変更する操作です。アクションのデータと識別子は保持されるため、設定ファイルに戻して `bm sync` を実行すれば再有効化できます。 ## 誤った同期への対処 [](#誤った同期への対処) ### 反映したくない変更が本番ブランチにマージされた [](#反映したくない変更が本番ブランチにマージされた) **状況**: レビューが不十分なPRや、まだ本番環境に反映したくない変更が、誤って本番環境用のブランチにマージされてしまいました。 #### 対応方法 [](#対応方法-6) 現状は、本番環境のWeb UIから、マージ内容に含まれる各アクションを手作業で以前のバージョンに戻します。前述の「 [直前の同期全体を取り消したい](/preview/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`](/preview/code_management/upcoming_features/) による同期単位のロールバックでも対応できる予定です。 ### 本番に反映したくないアクションを分離したい [](#本番に反映したくないアクションを分離したい) **状況**: 開発中・実験中のアクションが `bm sync <環境ID>` で他の環境にも反映されてしまうのを防ぎたい。 #### 現状の対応方法 [](#現状の対応方法-3) [アクションの有効化設定](/action/enablement_settings/) で、対象アクションを開発環境でのみ有効、他の環境では無効に設定します。 ⚠️ 環境ごとの有効/無効はコード管理の対象外です（ [`defineAction` の注記](/preview/code_management/sdk/define_action/) をご参照ください）。設定ファイルでは指定できないため、Web UIの環境別の設定画面から個別に切り替えてください。 #### 将来の対応方法 [](#将来の対応方法-3) 設定ファイルで、対象アクションを `actions` ではなく `draftActions` フィールドに移動します。 `draftActions` に入れたアクションは `bm sync` で開発環境にのみ反映され、 `bm sync <環境ID>` の対象外となります。 詳細は [開発環境限定のアクション（ `draftActions` ）](/preview/code_management/upcoming_features/) をご参照ください。 ## ビュー（コード取得設定）との組み合わせ [](#ビューコード取得設定との組み合わせ) [コード取得設定](/view/code_editor/git_management/) を使ってビューも同じリポジトリで管理している場合の対処方法です。 ### アクションのロールバックに合わせてビューも戻したい [](#アクションのロールバックに合わせてビューも戻したい) **状況**: アクションを以前のバージョンに戻したが、ビュー（コード取得設定で読み込んでいるコード）が新しいままで動作しない。 #### 対応方法 [](#対応方法-7) ビューはアクションのバージョン履歴とは独立して、ストレージ上のファイルとして管理されています。アクションのロールバックと合わせてビューも戻すには、本番環境用のブランチ（ `prd` ブランチなど）でビューのコードを修正してマージしてください。 ⚠️ 通常のCI構成（ [2ブランチ運用](/preview/code_management/examples/two_branch/) や [3ブランチ運用](/preview/code_management/examples/three_branch/) の例）では、本番ブランチへのマージをトリガーに `bm sync <環境ID>` が自動実行されます。その結果、同期元環境の現在のバージョンが再度反映され、 **Web UIで戻したアクションが最新バージョンに戻ってしまいます** 。 これを防ぐには、CIの設定に以下のような調整を加える必要があります。 - アクションの `bm sync <環境ID>` は、検証環境ブランチからのマージ経由でのみ実行するようにし、本番ブランチ直接のpushでは走らせない - ビューのビルド・アップロードは、ビューのコードに変更があるときにだけ実行するようにする これにより、本番ブランチでビューだけを修正してマージしても、アクションの再同期は走らずビューだけが差し戻されます。 [コード取得設定との連携](/preview/code_management/examples/view_code_fetch/) [今後追加予定の機能](/preview/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ブランチでビューのコードも修正してマージします。 ## 開発環境限定のアクション（ `draftActions` ） [](#開発環境限定のアクションdraftactions) 開発途中のアクションや実験的なアクションを、開発環境では使いつつも、検証環境・本番環境にはまだ反映したくない場合があります。このような「本番に流したくないアクション」を明示的に分離するため、 `defineConfig` に `draftActions` フィールドを追加する予定です。 ``` import { defineConfig } from "@basemachina/sdk"; import { stableAction } from "./actions/stable-action"; import { experimentalAction } from "./actions/experimental-action"; export default defineConfig({ project: { id: "your-project-id" }, actions: [stableAction], draftActions: [experimentalAction], }); ``` 想定する挙動は以下の通りです。 | フィールド | `bm sync` （開発環境への反映） | `bm sync <環境ID>` （他環境への同期） | | --- | --- | --- | | `actions` | 反映される | 反映される | | `draftActions` | 反映される | 対象外（同期されない） | これにより、「開発環境でのみ動作確認したいアクション」を設定ファイル上で明示的に管理できるようにすることを検討しています。 #### 既存環境に存在するアクションを `draftActions` に移した場合 [](#既存環境に存在するアクションをdraftactionsに移した場合) すでに検証環境や本番環境に反映済みのアクションを、設定ファイルで `actions` から `draftActions` に移動する運用も想定されます。この場合の挙動は以下のいずれかを検討しています。 - `bm sync <環境ID>` の対象外となり、既存環境では **無変更のまま残る** - `bm sync <環境ID>` 時に、他環境では **自動的に無効化** される 仕様は今後検討予定です。 [トラブルシューティング](/preview/code_management/troubleshooting/) [企業アカウントのユーザー管理](/admin/user_management/tenant_add_new_user/) --- スタートガイド # スタートガイドとは スタートガイドは、ベースマキナにはじめて触れるお客さまへ主要な機能を体系的に説明するコンテンツです。 順番に従ってお読みいただくことで機能をまんべんなく知っていただき、セットアップの助けになることを目的としています。 ## スタートガイドの目次 [](#スタートガイドの目次) - [サンプルのアクションを実行する](/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 }} } ] } ] } ``` [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プラットフォームへの接続](/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": "翻訳時の注意点や特記事項（あれば）" } ``` [コンテンツの審査自動化](/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. コメント（全体的な所感や注意点を簡潔に記載） 審査結果を日本語で出力してください。 `; ``` [サポート対応時のユーザーサマリ生成](/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 (