APIをビルドしてデータベースをデプロイする

スキーマファイル（.sfn）を作成したら、次は設計を実際のサービスに変える番です。APIビルドを開くと、テーブルごとに登録・照会・修正・削除のAPIが準備され、それぞれのアドレスを誰が使用できるのかも、1つの画面で確認できます。

必要に応じて、自分で作成したクエリAPI、静的ファイルAPI、リアルタイムイベントも、同じサービスに接続できます。

始める前に

• 必要な権限：データベースの使用権限が付与されたユーザー
• 事前準備：先にスキーマファイル（.sfn）を作成しておく必要があります。

APIビルドを開く

スキーマ画面上部のAPIビルドタブを選択すると、テーブルごとに自動生成されたAPIの一覧を確認できます。

自動生成されるAPI

テーブルごとに、基本として次の5つのAPIが自動生成されます。必要に応じて、新しいAPIを自分で追加することもできます。

新しいAPIを追加 (Custom Endpoint)では、必要なクエリと応答の形式を決めたAPIを追加できます。静的ファイルAPIを追加を使用すると、ワークスペースのJSON、XML、HTML、画像、バイナリファイルを、ファイル形式に合わせて提供できます。

静的ファイルまたはフォルダをAPIで提供する

1. 静的ファイルAPIを追加を選択します。
2. 保存領域で、チームスペースまたは個人スペースを選択します。
3. 公開対象で単一ファイルまたはフォルダー一覧・ファイル閲覧を選択してから、ファイルを選択またはフォルダーを選択で、元になるファイルやフォルダを指定します。
4. フォルダを選択した場合は、許可する拡張子とサブフォルダーを含むを設定します。拡張子を空欄にすると、すべての形式が対象になります。
5. 応答方法で、内容をブラウザーに表示するか（ブラウザーで表示）、ファイルとして受け取るか（ダウンロード）を選択します。
6. エンドポイントの権限を確認してから、スキーマをデプロイします。

単一ファイルの場合は、設定したエンドポイントがファイルの内容を応答します。フォルダの場合は、ファイル一覧のJSONと、一覧の項目のidで内容を読み取るアドレスがあわせて作成されます。ファイル名を変更したり移動したりすると、パスをもとに作成されるidも変わるため、クライアントは一覧から受け取った最新のidまたはviewUrlを使用する必要があります。

機能エンドポイントでは、リアルタイムソケット、ファイル・画像のアップロード、AI応答のように、サービス全体で使用する機能の権限を設定します。

リアルタイムイベントとRESTのバンドルをインポートする

リアルタイムソケットのイベント定義では、イベントだけを作成することも、イベントに必要なテーブルとREST設定を含むJSONまたはYAMLのバンドルをインポートすることもできます。

1. AIの回答を貼り付けを選択し、バンドルを貼り付けます。自分で用意したバンドルも、同じ形式で貼り付けることができます。
2. 既存のイベントを維持する場合は名前で統合、現在のイベント全体を置き換える場合はすべて置き換えを選択します。
3. 適用プレビューで、追加・変更・削除されるイベントと、追加されるテーブル・カラム・RESTの数を確認します。
4. 既存のRESTと競合する項目や、形式が自動的に整理・除外された項目を確認します。既存のRESTを変更する必要がある場合にのみ、重複するREST設定を上書きを選択します。
5. サーバーの検査結果を確認し、エラーを修正してから適用を選択します。

インポートは、現在編集中のスキーマを変更します。実際のサービスには、配布するを完了してはじめて反映されます。インポート画面で適用した場合でも、デプロイの際にサーバーがイベントとRESTのルールをもう一度検査し、検査に通らなければデプロイされません。

カスタムエンドポイントでCRUD以外のAPIを作る

自動生成される5つのAPI（list/view/create/update/delete）では足りない場合は、新しいAPIを追加 (Custom Endpoint)を押すと、動作をさらに細かく定義できます。

操作種別

基本の5つのCRUD操作のほかに、操作種別のドロップダウンには次のような選択肢もあります。

対象範囲は、コレクション（テーブル全体や複数のレコードが対象。通常は:idのないパス）、単一項目（特定の1件のレコード）、コマンド（CRUDに当てはまらないカスタムの命令型エンドポイント）の中から選びます。

権限はREST APIと同じ3段階

カスタムエンドポイントには、自動生成されるAPIと同じ権限を設定できます。

会員 + 追加条件を選ぶと、レベル・所属チーム・管理者かどうか・本人（owner）の条件を組み合わせて適用できます。たとえば、「レベル2以上のみ」「営業チームの所属者のみ」といった条件を、REST APIの自動生成エンドポイントとまったく同じ方式で、カスタムエンドポイントにも設定できます。

SQLを直接記述する

処理の流れタブの基本クエリには、このエンドポイントが実行するSQLを直接記述するエディタがあります。自動生成されるAPIでは、基本クエリを手書きの SQLに切り替えると、同じエディタが開きます。

REST APIの一覧の処理カラムにも、このエンドポイントが直接記述したクエリを使用していることを示す表示（SQLバッジ）が出ます。自動生成されるAPIでは表現できない条件、たとえば「このメンバーが今日登録した行が3件以上なら拒否する」のような集計にもとづく条件は、このSQLエディタでしか作成できません。

SQLの検査とパラメータの確認

SQLを入力すると、ブラウザーが構文と現在のスキーマのテーブル・カラムを検査します。エラーや確認が必要な項目に行・列が表示されている場合、その項目を選択するとエディタ内の該当位置に移動します。デプロイ領域からもエラーのあるSQLを開けます。

この検査では、実際のデータベースでクエリを実行しません。データベース固有の関数、アクセス権限、実データによる結果は、デプロイ後にAPIを呼び出して確認してください。

パラメータの一覧には、SQLで使用している:name形式のパラメーターが表示されます。:id、:user_id、:nick、:nowはサーバーが設定する予約値です。そのほかの値は、読み取りリクエストではクエリ文字列、書き込みリクエストでは入力処理後の本文から取得します。値がなければNULLになります。

処理の流れでリクエストの処理を変える

SQLを直接書かなくても、処理の流れタブであらかじめ用意されている関数を順番に追加することで、リクエストを処理する流れを変えられます。関数は、入力処理・DB 処理・出力処理の3つの段階に分かれています。

権限の設定

APIごとに、アクセス権限を個別に設定できます。ここでいう会員とは、ワークスペースのメンバーアカウントそのものを指します。別のログイン・認証システムを新たに作る必要はなく、すでにワークスペースにあるメンバー・レベル・チームの仕組みが、そのままAPIの権限に連動しています。

デプロイする

次の手順に従って、デプロイの情報を入力します。

1. データベース識別子：デプロイ先のサーバーで使用するDBの論理名を、英字で入力します。
2. ストレージエンジンモード：SQLite3、PostgreSQL、MySQL、MariaDBの中から選択します。外部DBの場合は、host、port、DB名、ユーザー、パスワードを追加で入力します。MySQLとMariaDBは、InnoDBベースの構成を使用します。
3. 基本設定と詳細設定で、次の項目を確認します。

APIの一覧の下にあるデプロイ領域で配布するを選択すると、設定が展開されます。デプロイ領域は編集画面の最下部に固定されているため、APIの一覧をスクロールしても表示されたままです。最初の選択だけではデプロイされません。設定を確認してから配布するをもう一度選択すると、データベースとAPIが準備されます。クライアント配布パスを指定した場合は、APIを試せるサンプル画面もあわせて作成されます。画面を変更する方法は、フロントエンドのサンプルを確認するに続きます。

APIの呼び出し例

デプロイされたAPIは、次のような形式で呼び出します。（テーブル名がuser_profileの場合の例）

GET  /api/web/{dbName}/user_profile/list
GET  /api/web/{dbName}/user_profile/view/{id}
POST /api/web/{dbName}/user_profile/create
PUT  /api/web/{dbName}/user_profile/update/{id}
DELETE /api/web/{dbName}/user_profile/delete/{id}

登録（POST）リクエストの例：

POST /api/web/{dbName}/user_profile/create
Content-Type: application/json

{
  "email": "user@example.com",
  "is_active": true
}

エラー応答の読み方

リクエストが失敗した場合は、HTTPステータスとcodeまたはerrorCodeをあわせて確認してください。エラーコードは言語が変わっても同じであるため、ログインの要求や再試行といった動作はコードで判断し、messageは画面への表示に使用します。

WebSpaceの標準のエラー案内は、韓国語・英語・日本語・中国語（簡体字）・ドイツ語に対応しています。ログインしたメンバーの言語設定を優先して使用し、設定がない場合や対応していない言語の場合は、リクエストのAccept-Languageを参照します。どちらも一致しない場合は、英語で案内します。外部APIとの連携では、表示される文言そのものを比較しないでください。

たとえば、ログインが必要なリクエストは、次の情報を返します。

{
  "code": "WEBSPACE_LOGIN_REQUIRED",
  "errorCode": "WEBSPACE_LOGIN_REQUIRED",
  "message": "ログインが必要です。"
}

これは、エラー応答で確認する主なフィールドです。応答全体の形式は、REST API、静的ファイル、管理APIごとに異なる場合があります。

• 入力値の検証の応答は、従来の形式であるok: falseとerrorsの一覧を使用します。HTTP 200であってもokを確認し、各項目のfield・code・messageで問題を案内してください。
• WebSocketのエラーは、type: "error"メッセージのdataの中で確認します。従来の分類用のkeyは維持され、code・errorCodeでエラーの原因を区別します。
• サーバーの実際のファイルパス、SQL、内部エラーの原文は、ユーザーに返しません。運用担当者がサーバーログを確認する必要があるエラーの場合は、発生時刻、リクエストのパス、HTTPステータス、エラーコードをあわせて伝えてください。

デプロイと上書き

既存のデータがあるスキーマを上書きする操作は、サーバーのデプロイポリシーに従います。組織のポリシーに応じて、禁止することも、管理者または指定されたデプロイ担当者だけが実行できるように制限することもできます。構造を変更する前に、影響を受けるカラムとAPI、バックアップと復旧の手順を確認してください。

注意事項

• APIは、SetFNのログインセッションにもとづいて認証されます。認証されていないリクエストは拒否されます。（ただし、権限を誰でもに設定したAPIは例外です。）
• スキーマの構造を変更すると、APIのエンドポイントもあわせて更新されるため、既存の連携コードとの互換性を確認してください。
• SQLite3のデータはそのサーバーのWebSpaceストレージに、外部エンジンのデータは管理者が設定したDBに保存されます。
• 一覧のフィルター・並べ替え・ページサイズは、サーバーが許可しているクエリの範囲内で使用します。
• 外部サイトから呼び出す場合は、管理者が設定した許可OriginとCSPの設定もあわせて確認してください。

関連ドキュメント

• スキーマファイル（.sfn）を作成する
• リアルタイム五目並べゲームを作る
• フロントエンドのサンプルを確認する
• パフォーマンスとスケーリング
• WebSpace管理を始める