跳到主要内容

编写脚本

脚本编辑器是您编写代码、在实时数据上测试代码并设置计划任务的工作区。屏幕分为三部分：左侧是 AI 助手，中间是代码编辑器和控制台，右侧是设置面板（元数据、计划任务、状态、运行历史）。

脚本编辑器整体视图 — 三栏布局

如何创建脚本​

  1. 打开 脚本 板块并点击 + 创建 script。编辑器随即打开并带有一个代码模板。 带有代码模板的新建脚本
  2. 在右侧面板的 元数据 区域，填写脚本的 名称 和 描述。
  3. 在中央编辑器中，编写 main() 函数的主体——即脚本应当执行的具体内容（参见下方的 QubixApp SDK 区域）。
  4. 在 计划 区域，设置脚本自动运行的频率（参见 计划任务）。如果您只打算手动运行，可以将其留空。
  5. 点击编辑器下方的 Run 按钮，在实时数据上测试脚本——结果会显示在控制台中（参见 测试脚本）。
  6. 打开右上角的 运行中 开关并点击 保存。
提示

您可以直接在编辑器中使用键盘快捷键 Ctrl + S（在 macOS 上为 Cmd + S）保存，无需将光标移动到按钮上。

AI 助手​

左栏是与 AI 助手的对话。用平实的语言描述任务（"停掉 ROAS 低于 0.5 且花费超过 20 美元的广告"），助手便会针对 Qubix SDK 生成现成的代码。回答下方的 插入到 Code 按钮可将这段代码直接放入编辑器。

输入框下方有现成的示例提示词——点击其中任意一个即可快速上手。

助手还能根据脚本的代码为其拟定 名称 和 描述——点击 元数据 区域中这些字段旁边的 AI 图标即可。

🎬 GIF: 向 AI 助手发起请求并将代码插入编辑器

QubixApp SDK​

脚本就是一个 main() 函数，您在其中通过 QubixApp 命令集来处理广告数据。共有三个层级可供使用：

  • 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') — 获取某一时段的指标。

基础示例：暂停过去一天内花费超过 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. 以 cron 格式输入计划任务（例如，*/5 * * * * — 每 5 分钟一次）并点击 +。
  2. 在该行下方，Qubix 会立即以平实的语言显示一段解释——请核对您与系统的理解是否一致。
  3. 为避免记忆 cron 语法，请点击该行中的 AI 图标，用文字描述计划任务（"每天上午 9 点"）——Qubix 便会填入现成的表达式。

带有 cron 解释的 Schedule 区域

备注

如果未设置任何计划任务，脚本将不会自动运行——只能通过 Run 按钮运行。要让自动运行生效，运行中 开关必须处于开启状态。

使用 "Run" 按钮测试脚本​

代码编辑器下方有一个控制台和一个 ▶ Run 按钮。它会在实时数据上执行当前编辑器中的代码——这是一种无需等待计划任务即可测试逻辑的安全方式。脚本通过 console.log 输出的一切内容都会显示在控制台中，并附带运行时间、状态和耗时。

显示运行结果的控制台

注意

Run 按钮会执行真实操作。如果代码中包含 pause() 或 activate()，广告将会被实际暂停或开启。要在不产生后果的情况下测试逻辑，请先注释掉包含操作的行，只保留 console.log。

Run 按钮在脚本首次保存后才可用。

运行历史​

右侧面板中的 运行记录 区域保存着所有执行的历史记录：时间、状态（成功、错误、超时）、耗时以及已执行的操作数量。点击某一行可展开该次运行的完整控制台输出——这有助于弄清脚本为何出现异常行为。

接下来​

脚本示例

应对常见任务的现成方案。

Britva 自动规则

当按条件逐条暂停/恢复广告就已足够时。

On this page