サイトのバックエンド（動的ハンドラ）
アップロードしたウェブサイトは、静的ファイルに加えて本物のバックエンドを持てます。個々のアドレスに紐づく小さな JavaScript のハンドラです。各ハンドラはパスと HTTP メソッドに結び付けられ、訪問者がそのアドレスを開くと、Qubix がハンドラを実行し、ハンドラが組み立てたもの（ページ、JSON レスポンス、リダイレクト、ステータスコード）を返します。
ページが静的なコンテンツを表示するだけでなく、サーバー側で何かを行う必要があるときに使います。POST リクエストでリードを受け取る、特定のパスに対して生成した HTML を返す、リクエストに応じてリダイレクトを送る、といった用途です。通常の静的なホワイトページやランディングには不要です。Backend タブを空のままにしておけば、ウェブサイトは素のファイルとして配信されます。
Backend タブを開く
ウェブサイトのカードには上部に 3 つのタブがあります。ファイル、Backend、プレビュー です。アクティブなタブはアドレスバーに保存されるので、特定のタブへのリンクをそのままコピーできます。
- 「Websites」 セクションを開き、目的のウェブサイトをクリックします。
- Backend タブに切り替えます。
ウェブサイトにまだハンドラがない場合、一覧には 「+ new」 でテンプレートから 1 つ作成できる旨のヒントが表示されます。
Backend タブは、ページがサーバー側で何かを処理する必要があるときにのみ必要です。純粋に静的なページはハンドラなしで動作します。
ハンドラを作成する
- Backend タブで、ハンドラ一覧の上、左上にある 「+ new」 をクリックします。既製のテンプレートから新しいハンドラが作成され、エディタで開きます。
🎬 GIF: 「+ new」をクリックし、テンプレートのハンドラがエディタで開く様子
- エディタ上部のヘッダーフォームで、パス を設定します。これはハンドラが応答するアドレスです。フィールドはプレースホルダ付きのテンプレートを受け付けます（例:
/users/:id）。:name— パスのセグメントを 1 つキャプチャします（例:/users/:idの:idは/users/42にマッチします）。*— 複数のセグメントにわたって、パスの残り部分をキャプチャします。**— パスの残り部分にマッチしますが、キャプチャはしません。
- method を選択します。
GET、POST、PUT、DELETE、PATCH、HEAD、OPTIONS、または ANY（任意のメソッドに応答）です。 - enabled チェックボックスをオンのままにして、ハンドラが公開中のサイトで動作するようにします。オフにすると、ハンドラを保存したまま非アクティブにできます。
- 中央のエディタで、ハンドラのコードを記述します（後述の ハンドラのコード を参照）。
- 保存（または Cmd+S、Windows では Ctrl+S）をクリックします。
左側の一覧では、各ハンドラはメソッドとパスとして表示されます（メソッドが設定されていないハンドラは ANY と表示されます）。無効なものはそれと分かるように示されます。
複数のハンドラが同じアドレスに応答しうる場合、Qubix は最も具体的なものを選びます。完全一致のパスを持つハンドラは、プレースホルダやワイルドカードを持つものより優先されます。これにより、正確なハンドラと広範なキャッチオールを衝突させずに並べておけます。
ハンドラのコード
ハンドラは、リクエストオブジェクト（r と呼びます）を受け取る JavaScript 関数です。このオブジェクトはリクエスト（メソッド、パス、クエリやフォームの引数、ヘッダー、キャプチャされたパスセグメント）と、レスポンス（ヘッダーの設定、ボディ付きのステータスの返却、リダイレクト）を公開します。エディタが開始時に表示するテンプレートには、典型的な形がすでに示されています。
エディタは構文ハイライトとオートコンプリートを備えた本格的なコードエディタです。r. と入力し始めると、Qubix が利用可能なリクエストとレスポンスのフィールドを説明付きで提案するので、頭の中に覚えておく必要はありません。
ハンドラの内部では、Qubix の共有ツールセットも利用できます。読み取り専用のデータベースクエリ、外部サービスへのリクエスト、呼び出し間で保持される state です。これらは Scripts と同じように動作します。詳細はその記事を参照してください。外部へのリクエストは、管理者が許可リストに追加したアドレスに対してのみ許可されます。クエリでアクセスできるテーブルと列については sql クエリ用テーブル をご覧ください。
r オブジェクトのリファレンス
ハンドラがリクエストから読み取り、レスポンスを組み立てるために使うすべての情報です。
リクエストの読み取り：
| フィールド | 内容 |
|---|---|
r.method | リクエストの HTTP メソッド（GET、POST など） |
r.uri | ハンドラが応答したアドレス（例：/promo/123） |
r.rawUri | サービスプレフィックスを含む完全な外部アドレス |
r.args | アドレスとフォームのパラメーター（キー → 値） |
r.params | パステンプレートからキャプチャされた値（例：/users/:id の id） |
r.requestBuffer | 文字列としてのリクエストボディ |
r.headersIn | リクエストヘッダー |
r.remoteAddress | 訪問者の IP アドレス |
r.variables | クリックのコンテキスト：geo、click_id、sub1…sub5、lang |
r.session | 訪問者のセッション：get(key)、set(key, value)、delete(key) |
レスポンスの組み立て：
| フィールド／メソッド | アクション |
|---|---|
r.headersOut | レスポンスヘッダー（設定・削除が可能） |
r.return(status, body?, location?) | レスポンスを送信する；location はリダイレクト先のアドレス |
r.log(...)、r.warn(...)、r.error(...) | 実行ログに書き込む（テストランナーで確認できる） |
Crypto ヘルパー
ハンドラでは crypto ヘルパーも利用できます。
| メソッド | 動作 |
|---|---|
crypto.uuid() | ランダムな識別子を生成 |
crypto.hmac(algo, key, data) | key を使った data の HMAC を hex エンコードで返す；algo は 'sha256'、'sha1'、または 'md5' |
たとえば、fetch で外部サービスにデータを送信する前に署名する際に便利です。
ハンドラをテストする
各ハンドラには、エディタの右側に内蔵のテストランナーがあります。テストリクエストを送って、公開中のサイトに触れることなく、ハンドラが正確に何を返すかを確認できます。
- method を選択し、テストする パス を入力します（例:
/users/42）。 - （任意）リクエストの入力を埋めます。
- クエリ (JSON) — クエリパラメータを JSON オブジェクトとして指定します。
- ボディ (raw) — 生のリクエストボディです。
- geo と click_id — リクエスト変数としてハンドラに渡される値です。
- 実行 をクリックします。
結果は下に表示されます。
- レスポンスの status（緑 / 青 / 赤で色分け）と、実行にかかった時間。
- パラメータ — パステンプレートからキャプチャされた値。
- リダイレクト — ハンドラがリダイレクトを設定した場合の、その遷移先。
- レスポンスの ヘッダー と ボディ。
- コンソール — 実行中にハンドラがログ出力したすべての内容。
リクエストがハンドラの保存された state に到達したり、それを変更したりすると、パネルは セッション が変更されたことも示します。
クエリ (JSON) は有効な JSON でなければなりません。そうでない場合、テストは実行されずフィールドが強調表示されます。JSON を修正して、再度 実行 をクリックしてください。
サイトファイルを編集する
カードのもう半分は ファイル タブです。ウェブサイトの静的ファイル（HTML、CSS、JS、画像、フォント）が左側のツリーに、コードエディタが右側に表示されます。テキストファイルは構文ハイライト付きで開きます。保存 または Cmd+S（Windows では Ctrl+S）で保存します。画像、動画、音声、その他のファイルはプレビューまたはダウンロードが表示されます。ファイルをフォルダ間でドラッグしたり、自分のコンピュータから新しいファイルをドロップしたりできます。
ファイル タブの詳しい説明は Websites と ウェブサイトのアップロード にあります。
フィールドと挙動についてのメモ
パス — ハンドラが応答するアドレステンプレートです。:name（1 セグメント）、*（残り、キャプチャあり）、**（残り、キャプチャなし）をサポートします。キャプチャされたセグメントはハンドラから利用でき、テストランナーでは params として表示されます。
method — どの HTTP メソッドがハンドラを起動するか。ANY はすべてのメソッドに応答します。
enabled — ハンドラが公開中のサイトで動作するかどうか。無効なハンドラは保存されたままですがスキップされます。
「+ new」 — 内蔵テンプレートから、編集できる状態のハンドラを作成します。