メインコンテンツまでスキップ

スクリプトの作成

スクリプトエディターは、コードを書き、実データでテストし、スケジュールを設定する作業スペースです。画面は 3 つの部分に分かれています：左に AI アシスタント、中央にコードエディターとコンソール、右に設定パネル（メタデータ、スケジュール、状態、実行履歴）。

スクリプトエディターの全体像 — 3 つの列

スクリプトを作成する方法​

  1. スクリプト セクションを開き、+ Script を作成 をクリックします。コードテンプレート付きのエディターが開きます。 コードテンプレート付きの新しいスクリプト
  2. 右パネルの メタデータ セクションで、スクリプトの 名前 と 説明 を入力します。
  3. 中央のエディターで main() 関数の本体を書きます — スクリプトが何をすべきか正確に（下記の QubixApp SDK セクションをご覧ください）。
  4. スケジュール セクションで、スクリプトが自動的に実行される頻度を設定します（スケジュール をご覧ください）。手動でのみ実行する場合は空のままにできます。
  5. エディターの下の 実行 ボタンをクリックして、実データでスクリプトをテストします — 結果はコンソールに表示されます（スクリプトのテスト をご覧ください）。
  6. 右上の アクティブ トグルをオンにして、保存 をクリックします。
ヒント

カーソルをボタンに移動させずに、エディターから直接キーボードショートカット Ctrl + S（macOS では Cmd + S）で保存できます。

AI アシスタント​

左の列は AI アシスタントとのチャットです。タスクを平易な言葉で説明すると（「ROAS が 0.5 未満で消化が $20 超の広告を停止」）、アシスタントが Qubix SDK に対応した完成コードを生成します。回答の下の Code に挿入 ボタンで、このコードをエディターに直接入れられます。

入力フィールドの下には既成のプロンプト例があります — いずれかをクリックすればすぐに始められます。

アシスタントは、コードからスクリプトの 名前 と 説明 を考え出すこともできます — メタデータ セクションのこれらのフィールドの隣にある AI アイコンをクリックしてください。

🎬 GIF：AI アシスタントへのリクエストと、コードのエディターへの挿入

QubixApp SDK​

スクリプトは main() 関数で、その中で QubixApp コマンドセットを通じて広告データを扱います。3 つのレベルが利用できます：

  • QubixApp.ads() — 広告、
  • QubixApp.adsets() — 広告セット、
  • QubixApp.campaigns() — キャンペーン。

それぞれが、フィルターしたり反復したりできる選択を返します。選択には次のメソッドがあります：

  • .withCondition('...') — メトリクスの条件で選択（たとえば 'spend_24h > 10 AND roas_24h < 0.5'）；
  • .orderBy('field', 'desc') — ソート；
  • .withLimit(n) — 件数を制限；
  • .get() — 要素の配列を取得；
  • .first() — 最初の要素を取得。

各広告、広告セット、キャンペーンにはアクションがあります：

  • .pause({ duration: '24h', reason: '...' }) — 指定した期間一時停止；
  • .activate({ reason: '...' }) — 再びオンにする；
  • .getStatsFor('24h') — 期間のメトリクスを取得。

基本例：直近 1 日で消化が $10 超かつ ROAS が 0.5 未満の広告を一時停止する。

pause-low-roas.jsJavaScript
function main() {
  const ads = QubixApp.ads()
    .withCondition('spend_24h > 10 AND roas_24h < 0.5')
    .get()

  for (const ad of ads) {
    console.log('pausing', ad.name, 'roas24h=', ad.roas_24h)
    ad.pause({ duration: '24h', reason: 'low roas' })
  }
}

さらに多くの既成スニペットは スクリプトの例 セクションにあります。

ヒント

エディターではオートコンプリートが動作します：ad. または QubixApp. と入力し始めると — Qubix が利用可能なフィールドとメソッドを説明付きで提案します。これでメトリクスの一覧を頭に入れておく必要がありません。

データベースクエリ​

QubixApp を通じて利用できる現在の広告のほかに、スクリプトは sql コマンドで Qubix のデータベースから直接データを読めます。これは、タグ付きテンプレートとして書く読み取り専用クエリです：

JavaScript
const rows = sql`
  SELECT country, sum(spend) AS spend
    FROM hourly_insights
   WHERE date >= ${'2026-06-01'}
   GROUP BY country`
for (const row of rows) console.log(row.country, row.spend)

クエリは行の配列を返します；各行は、キーが列名であるオブジェクトです。${…} で渡す値は安全なパラメーターとして送られます — 手でエスケープする必要はなく、SQL インジェクションは不可能です。クエリは 読み取り専用 です：スクリプトはデータを読めますが、何も変更できません。クエリが到達できる範囲は、あなたの役割が見ることを許可されているデータに限られます。

実行間の状態​

スクリプトは ctx.state を通じて実行間で値を記憶できます — これはスクリプトの個人的なメモリです：

  • ctx.state.set('key', value) — 保存；
  • ctx.state.get('key') — 読み取り；
  • ctx.state.delete('key') — 削除。

たとえば、これによってどの広告がすでに処理されたかを記憶し、再び触れないようにできます。メモリの現在の内容は、右パネルの 状態 セクションで確認でき — そこから個々のエントリを手動で削除することもできます。

外部サービスへのリクエスト​

ctx.fetch(url, opts) コマンドは外部に HTTP リクエストを行います — たとえば、メッセンジャーに通知を送ったり、他人の API を呼んだりするためです。

注意

外向きのリクエストは、許可リストにあるアドレスにのみ許可されます。管理者は システム → JavaScript タブで設定します。リストが空の場合、外向きのリクエストは無効です。リストにないアドレスに到達しようとすると、スクリプトはコンソールに分かりやすいヒントを表示します。

スケジュール​

右パネルの スケジュール セクションで、スクリプトが自動的に実行されるタイミングを設定します。スケジュールは複数設定できます — たとえば 1 時間に 1 回、加えて特定の時刻に。

  1. cron 形式でスケジュールを入力し（たとえば */5 * * * * — 5 分ごと）、+ をクリックします。
  2. その行の下に、Qubix がすぐに平易な言葉での説明を表示します — お互いの理解が正しいか確認してください。
  3. cron 構文を思い出さずに済むよう、行の AI アイコンをクリックして、スケジュールを言葉で説明してください（「毎日午前 9 時」）— Qubix が完成した式を入力します。

cron の説明付きの«スケジュール»セクション

注記

スケジュールが設定されていない場合、スクリプトは自ら実行されません — 実行 ボタンからのみです。自動実行が動作するには、アクティブ トグルがオンになっている必要があります。

「実行」ボタンでのスクリプトのテスト​

コードエディターの下にはコンソールと ▶ 実行 ボタンがあります。これは 現在エディターにあるコード を実データで実行します — スケジュールを待たずにロジックをテストする安全な方法です。スクリプトが console.log で出力するすべてが、実行時刻、ステータス、所要時間とともにコンソールに表示されます。

実行結果付きのコンソール

注意

実行 ボタンは実際のアクションを実行します。コードに pause() や activate() が含まれている場合、広告は実際に一時停止されたりオンにされたりします。影響なしにロジックをテストするには、まずアクションの行をコメントアウトし、console.log だけを残してください。

実行 ボタンは、スクリプトを初めて保存した後に利用可能になります。

実行履歴​

右パネルの 実行 セクションは、すべての実行の履歴を保持します：時刻、ステータス（成功、エラー、タイムアウト）、所要時間、実行されたアクションの数。行をクリックすると、その実行の完全なコンソール出力が展開されます — スクリプトが予期せず動作した理由を突き止めるのに便利です。

次のステップ​

スクリプトの例

よくあるタスク向けの既成シナリオ。

Britva 自動ルール

条件による広告ごとの一時停止／復帰で十分なとき。

On this page