自动规则与脚本 SDK
本参考说明在自动暂停规则与用户脚本的代码内部可以使用哪些内容：ad 对象的字段、暂停与恢复的函数，以及用于挑选广告的选择器。所有带说明的字段标题也可直接在规则编辑器中查看——位于 ad.* 键参考 侧边面板（可按名称与说明搜索）。
这是 Server SDK——运行在 Qubix 服务器上的命令，与运行在访客浏览器中的 Browser SDK 不同。Server SDK 是同步的：sql、ctx.fetch 和 state 直接返回值——无需 await 或 Promise。
ad 对象
在自动暂停规则中，您会收到一个 ad 对象——即当前正在检查的那条广告。您通过它读取所有指标与属性。所有可用字段都按作用域分组。
| 分组 | 字段前缀 | 包含内容 |
|---|---|---|
| 广告 | ad.spend_24h、ad.roas_24h、ad.primary_country、ad.effective_status… | 广告本身的指标与属性 |
| 素材 | ad.creo_* | 按素材统计的指标（使用该素材的所有广告） |
| 地区 | ad.geo_* | 按国家/地区统计的指标 |
| Offer | ad.offer_* | offer 的指标与参数（payout、cap） |
| 网络 | ad.network_* | 按网络统计的指标 |
| 上一周期 | ad.prev_* | 上一周期的相同指标（用于对比） |
完整的指标列表、时间窗口（_1h…_total）以及各前缀的含义，请参见 指标与列 一节。
访问不存在的字段（ad.something_wrong）会立即以错误中止规则。请对照编辑器中的参考核对字段名。
暂停
共三个函数——按作用域划分。广告、广告组与广告系列。
| 函数 | 操作 |
|---|---|
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? }) | 恢复广告系列 |
相邻广告
在规则内部，您可以查看同一广告组或广告系列中的其他广告——例如，当只有一条广告下滑时停掉整个广告组。
| 函数 | 返回 |
|---|---|
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 也仅在服务器上的真实运行中有效：在浏览器测试运行中网络调用被禁用，因此请通过真实运行来验证。
共享状态
除私有的 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，每次运行最多 20 个请求。sql：单次查询最多返回数千行——管理员在设置中配置具体上限。对于大批量查询，请直接在查询中进行聚合。
具体限制值在 系统 → JavaScript 标签页中配置。
只读 sql
带标签的模板 sql\SELECT …`会在所有者的权限范围内执行一次只读数据查询。它在**自动暂停规则（Britva）与用户脚本中均可使用**——前提是相应的系统设置已启用。在浏览器测试运行中它被禁用（与ctx.fetch一样），因此请通过服务器上的真实运行来验证使用sql` 的规则或脚本。
查询可访问的完整表和列列表，请参阅 sql 查询可用的表。