自動ルールとスクリプトの SDK
自動一時停止ルールとユーザースクリプトのコード内で利用できるもののリファレンスです：ad オブジェクトのフィールド、一時停止と再開のための関数、広告を選ぶためのセレクター。すべてのフィールドの説明付きのキャプションは、ルールエディター内 — ad.* キーのリファレンス サイドパネル（名前と説明で検索）でも利用できます。
これは Server SDK です — 訪問者のブラウザで動作する Browser SDK とは異なり、Qubix サーバー上で実行されるコマンドです。Server SDK は同期的です：sql、ctx.fetch、state は await や Promise なしで直接値を返します。
ad オブジェクト
自動一時停止ルールでは、1 つの ad オブジェクトを受け取ります — これはチェックの対象となっている広告です。これを通じて、すべてのメトリクスと属性を読みます。利用可能なすべてのフィールドはスコープごとにグループ分けされています。
| グループ | フィールドの接頭辞 | 中身 |
|---|---|---|
| Ad | ad.spend_24h、ad.roas_24h、ad.primary_country、ad.effective_status… | 広告そのもののメトリクスと属性 |
| Creative | ad.creo_* | クリエイティブ別のメトリクス（このクリエイティブを使うすべての広告） |
| Geo | ad.geo_* | 国別のメトリクス |
| Offer | ad.offer_* | オファーのメトリクスとパラメーター（ペイアウト、キャップ） |
| Network | ad.network_* | ネットワーク別のメトリクス |
| Previous period | ad.prev_* | 前の期間の同じメトリクス（比較用） |
メトリクスの完全なリスト、時間枠（_1h…_total）、各接頭辞の意味は メトリクスと列 セクションにあります。
存在しないフィールド（ad.something_wrong）にアクセスすると、ルールは即座にエラーで中断します。名前はエディターのリファレンスと照合してください。
一時停止
スコープごとに 3 つの関数があります。広告、広告セット、キャンペーン。
| 関数 | アクション |
|---|---|
pauseAd(duration, reason?) | 現在の広告を一時停止 |
pauseAdset({ adsetId, duration, reason? }) | 広告セットを一時停止 |
pauseCampaign({ campaignId, duration, reason? }) | キャンペーンを一時停止 |
pauseAd では継続時間を文字列として渡すだけで十分です；広告セットとキャンペーンでは、明示的な adsetId / campaignId を持つオブジェクト形式が必須です。
継続時間（duration）：
| 値 | 意味 |
|---|---|
6h / 12h / 24h | N 時間の一時停止 |
next_day_target_geo | ターゲット国の時間での翌日の始まりまで |
next_day_ad_account | 広告アカウントの時間での翌日の始まりまで |
permanent | 永続的な一時停止 |
while_matches | ルールの条件が成立している間 |
reason はログに入る任意のコメントです。省略すると、ルール名が代入されます。
再開
| 関数 | アクション |
|---|---|
activateAd(reason?) | 現在の広告を再開 |
activateAdset({ adsetId, reason? }) | 広告セットを再開 |
activateCampaign({ campaignId, reason? }) | キャンペーンを再開 |
隣接する広告
ルールの中で、同じ広告セットやキャンペーンの他の広告を参照できます — たとえば、1 件の広告だけが落ち込んだ場合に広告セット全体を停止するなど。
| 関数 | 返すもの |
|---|---|
getAd(id) | ad_id による広告 |
getAdset() | 現在の広告の広告セット内のすべての広告 |
getCampaign() | 現在の広告のキャンペーン内のすべての広告 |
また、デバッグ出力のための console.log / console.warn / console.error と、skipNextRules() — この広告の残りのルールをスキップする — も利用できます。
QubixApp セレクター（スクリプト用）
ユーザースクリプトでは QubixApp オブジェクトが利用できます — 条件で広告、広告セット、キャンペーンを選択します。選択された各要素には、独自の統計と一時停止メソッドがあります。
| メソッド | 返す選択 |
|---|---|
QubixApp.ads() | 広告 |
QubixApp.adsets() | 広告セット |
QubixApp.campaigns() | キャンペーン |
選択メソッド（チェーン可能）：
| メソッド | 動作 |
|---|---|
.withCondition(sql) | 条件でフィルター |
.filter(fn) | 関数でフィルター |
.orderBy(field, dir) | ソート（'asc' / 'desc'） |
.withLimit(n) | 要素数を制限 |
.get() | 要素の配列を取得 |
.first() | 最初の要素を取得 |
要素メソッド：
| メソッド | アクション |
|---|---|
.pause({ duration, reason? }) | 一時停止 |
.activate({ reason? }) | 再開 |
.getStatsFor(period) | 時間枠のメトリクス（'1h'…'total'） |
.getAds() | 広告セット／キャンペーン内の広告 |
.getAdsets() | キャンペーン内の広告セット |
getStatsFor は、選択した時間枠のメトリクスのセットを返します：spend、revenue、clicks、regs、deps、installs、roas、cpd、cpc、click2reg、reg2dep、ctr、i2r、i2d、c2i。
スクリプトコンテキスト
スクリプトでは、追加で ctx オブジェクトが利用できます。
| フィールド／メソッド | 目的 |
|---|---|
ctx.state.get/set/delete/keys | 実行間の状態の保持 |
ctx.fetch(url, opts?) | HTTP リクエスト（ホストは許可リストにある必要があります、設定の JavaScript をご覧ください） |
ctx.now() | 現在時刻 |
ctx.script | 現在のスクリプトに関する情報 |
ctx オブジェクト（ctx.fetch を含む）はスクリプトにのみ存在します — 自動一時停止ルールの中では利用 できません。さらにスクリプトでも、ctx.fetch はサーバー上の実際の実行でのみ動作します：ブラウザでのテスト実行ではネットワーク呼び出しが無効なので、実際の実行で確認してください。
共有 state
プライベートな ctx.state に加えて、すべてのスクリプト、ルール、サイトハンドラから同時に参照できる共有ストア ctx.state.global があります。
| メソッド | アクション |
|---|---|
ctx.state.global.get(key) | 値を読み取る |
ctx.state.global.keys() | キーの一覧を取得する |
ctx.state.global.set(key, value) | 値を書き込む |
ctx.state.global.delete(key) | 値を削除する |
スクリプトやルールはいずれも共有ストアを読み取ることができます。書き込み（set / delete）は、管理者が所有するスクリプトまたはルールからのみ許可されます — それ以外の場合、書き込みはエラーになります。管理者が一度値を書き込み、他の全員が読み取る共有ルックアップテーブルとして便利に使えます。
ctx.fetch：デフォルトのタイムアウトは 10 秒（最大 30 秒）、レスポンスは最大 1 MB、1 回の実行あたり最大 20 リクエスト。sql：1 回のクエリで返される行数は最大数千行です — 正確な上限は管理者が設定で決定します。大量データを取得する場合は、クエリ内で集計してください。
正確な制限値は システム → JavaScript タブで設定します。
読み取り専用の sql
タグ付きテンプレート sql\SELECT …` は、オーナーの権限の範囲内で読み取り専用のデータクエリを実行します。これは **自動一時停止ルール（Britva）とユーザースクリプトの両方** で利用できます — 対応するシステム設定が有効になっている場合に限ります。ブラウザでのテスト実行では無効です（ctx.fetch と同様）ので、sql` を使うルールやスクリプトはサーバー上の実際の実行で確認してください。
クエリでアクセスできるテーブルと列の完全なリストは sql クエリ用テーブル にあります。