English 中文TürkçeРусскийFrançaisTiếng ViệtEspañol日本語

从 CLI 管理 Ads Manager

Adapty CLI 可以通过 adapty asa 主题从终端管理你的 Ads Manager 账户。它涵盖广告系列、广告组、关键词、广告、产品页面、自动化规则、数据图表和竞品研究。

将浏览器操作中耗时的工作交给它来处理：让 AI 代理实时访问广告效果数据、从文件中批量添加数百个关键词，以及跨多个推广活动执行相同的配置。其他情况下，使用看板会更快。

Warning

CLI 无法删除任何内容。推广活动、广告和自动化规则可以在终端中创建、更新和暂停，但只能在看板中删除。

开始之前

Ads Manager 命令与 CLI 其他功能共用同一套安装和登录方式。如果尚未完成配置，请参照快速入门指南中的第 1 步和第 2 步进行操作。

前提条件

每条 adapty asa 命令还需满足以下两个条件：

  • 已连接 Apple Ads 账户：使用 adapty asa connect 连接，或按照 Adapty Ads Manager 入门指南 中的说明在看板中完成连接。
  • 有效的 Ads Manager 订阅：若无订阅，每条命令都会返回 402 ads_manager_subscription_required 错误。

以下命令可同时查看上述两项状态：

adapty asa whoami

与其他 CLI 命令的区别

  • 没有 --app 标志：操作范围是你的 Token 所属公司。--app 仅在部分 list 命令中作为过滤条件存在。
  • 写操作直接触达 Apple：每个会修改账户的命令都会打印请求体，并在发送前要求你确认。没有预发布步骤。
  • 读操作代价低，写操作代价高：可以随意执行 list 命令和 --dry-run。其他所有操作都应视为不可逆。

要在脚本中跳过确认提示，请传入 --yes。在 --json 模式下或管道中，写入命令会拒绝执行而非等待一个永远不会到来的输入，因此在这些情况下必须使用 --yes。

查找所需 ID

每条命令都需要 UUID，而每个 UUID 都来自对应的 list 命令。按层级逐步获取：

adapty asa orgs list
adapty asa campaigns list --campaign-group <campaign-group-id>
adapty asa ad-groups list --campaign <campaign-id>

每次查询都应配合过滤条件来缩小范围。过滤条件收窄的是查询本身，而非仅限于输出结果，因此带范围的查询开销很小，而不带范围的查询则会翻遍整个账户的数据。不加 --ad-group 直接运行 adapty asa keywords list 是本主题中读取范围最广的操作。

这些列表仅返回元数据。性能数据请通过 asa metrics 获取。

批量添加关键词

逐个添加关键词是离开看板的主要原因。将每个关键词单独放在文本文件的一行中：

adapty asa keywords add --ad-group <ad-group-id> --from-file keywords.txt --bid 1.20 --match-type EXACT

关键词以每次最多 100 个的批量方式提交。如果列表较大，请拆分为多次调用。

可能出现两种失败情况，且两者的表现不同。ID 无效会在调用 Apple 之前导致整批请求失败，因此没有任何内容会被应用。Apple 也可能拒绝单个关键词——其余关键词仍会正常添加，每条拒绝都会附带说明原因。请以摘要行为准，而非单纯依赖退出码。

先发送少量关键词并确认结果，再发送完整文件。

创建最大转化量广告系列

使用 MAX_CONVERSIONS 出价策略的广告系列只有在拥有自动广告组后才会投放，因此需要同时创建两者：

adapty asa campaigns create --org <campaign-group-id> --name "Max Conv" --adam-id 123456 --country US --daily-budget 50 --bidding-strategy MAX_CONVERSIONS
adapty asa ad-groups create --campaign <campaign-id> --name "Automated Max Conv" --automated

在该广告组存在之前，广告系列的 serving_status 会报告为 NOT_RUNNING，且 serving_state_reasons 中包含 AUTOMATED_KEYWORDS_REQUIRED_AD_GROUP_MISSING；campaigns create 会同时打印出原因以及解决该问题的命令。

--automated 才能满足该要求——带有 --automated-keywords 的普通广告组不行。Apple 会自动调度并运行该自动广告组，因此无需设置 --start-time，--default-bid 为可选项，且该广告组始终保持启用状态：如需停止消耗，请暂停广告系列。

对于广告系列，请将 --target-cpa 设置为低于 --daily-budget。

为信用额度设置开票选项

Apple 要求组织中每个按信用额度计费的广告系列都必须填写开票选项。adapty asa orgs list 会显示每个组织的 payment_model——若值为 LOC，则以下五个 --invoice-* 标志适用：

adapty asa campaigns create --org <campaign-group-id> --name "LOC push" --adam-id 123456 --country US --daily-budget 50 --invoice-advertiser "Acme Inc" --invoice-order-number PO-42 --invoice-contact-name "Jane Doe" --invoice-contact-email jane@acme.com --invoice-billing-email billing@acme.com

一次调用中必须同时传入全部五个参数——缺少任何一个，请求在到达 Apple 之前就会被拒绝。若缺失这些参数，广告系列虽会创建成功，但会报告 serving_status: NOT_RUNNING，并附带 MISSING_BO_OR_INVOICING_FIELDS。

在 adapty asa campaigns update 中使用同样的五个参数，可为已存在的广告系列设置发票选项。这五个参数会整体替换已存储的配置，因此即使只需修改其中一个，也必须同时传入全部五个。

一次性创建完整广告系列结构

campaigns bulk-create 可替代循环调用 campaigns create 和 ad-groups create 的脚本。它将完整的广告系列结构——包括广告系列、广告组、关键词、否定关键词和广告——作为一个操作一次性提交：

adapty asa campaigns bulk-create --file structure.json

输入内容是描述该结构的 JSON——字段说明请参阅结构格式。JSON 是 AI 智能体的天然选择：它生成结构后直接通过管道传入：

cat structure.json | adapty asa campaigns bulk-create --file -

原生的 Apple Ads 批量模板 也可以作为输入——服务器会将 Campaign_And_Adgroup_Template.xlsx 或关键词 .csv 转换为结构体。--org-id 接受 adapty asa orgs list 返回的数字型 org_id。如需在创建前预览转换结果，请添加 --preview：

adapty asa campaigns bulk-create --from-file Campaign_And_Adgroup_Template.xlsx --org-id 1234567 --preview

转换问题会附带所在的工作表、行和列信息一并报告。当打印出的结构看起来正确时，去掉 --preview 即可提交。

--preview 的输出也是获取起始结构文件的最快方式：保存后编辑，再通过 --file 提交——与 automations get 提供规则模板的方式相同。

整个结构在创建前会经过完整验证，验证失败时会列出所有无效节点。验证通过后，对象将在服务器上依次创建，命令会实时报告进度。最终结果为 success、partial 或 failed——partial 结果会列出每个未成功创建的对象及 Apple 返回的错误信息。

对于规模较大的结构，可传入 --no-wait 立即获取操作 ID，稍后再查询进度：

adapty asa campaigns bulk-status <operation-id>

从代理程序和脚本中查询数据图表

asa metrics 可对账户任意层级的数据按日期范围进行报告。添加 --json 参数后，AI 代理程序或脚本可直接使用输出结果：

adapty asa metrics --entity campaign --date-from 2026-07-01 --date-to 2026-07-31 --metric spend --metric roas --json

--metric 接受 Ads Manager 所追踪的指标名称。完整列表请参阅数据图表。

同期群数据图表的工作方式与其他数据图表不同。不存在 ltv 指标，因为生命周期价值是按续订窗口而非按日期读取的。请改为指定窗口：

adapty asa metrics --entity campaign --date-from 2026-07-01 --date-to 2026-07-31 --metric roas --by-days 7 --by-days 90 --order-by-day 90

这将返回按第 90 天 ROAS 排名的广告系列。单次调用最多可容纳 16 个窗口。

每行代表一个实体，已在服务器端完成聚合和排序。因此，“按消耗金额排名前五的广告系列”这类问题只需一次调用，无需遍历每一页：

adapty asa metrics --entity campaign --date-from 2026-07-01 --date-to 2026-07-31 --order-by spend --page-size 5

数据图表和搜索词列表共享同一个分析预算：每分钟 5 次调用，任意 10 秒内最多 2 次。尽量一次性提出精确的问题，而不是反复轮询。报告周期也受分组粒度的限制——按天最多 90 天，按周最多 180 天，按月最多 365 天——如需扩大报告范围，请通过粗化 --group-by 来实现，而不是拆分成更多次调用。

查看竞品关键词

一条命令即可返回竞争对手应用所投放的关键词，每次最多支持五个 App Store 应用：

adapty asa competitors summary --app-ids 1668337467,6503873027 --json

时间周期和国家/地区由服务端固定——取最近一个完整月份，覆盖所有国家/地区——因此该命令除应用 ID 外无其他参数。首次查询某组应用时，可能需要数十秒才能返回结果。

使用此功能可按计划将竞品关键词数据拉取到报告中。如需筛选结果、对比不同国家/地区的数据，或将找到的关键词直接添加到推广活动，请使用看板中的 Market Intelligence。

运行自动化规则

CLI 不会构建自动化规则——它只存储你提供的 JSON。获取有效规则文件最快的方式是在看板中创建一条规则，然后将其读取出来：

adapty asa automations get <automation-id> --json > rule.json

编辑该文件，并将其作为新规则的模板：

adapty asa automations create --file rule.json

向 automations update 传入文件时，请先删除 internal_id 字段——如果该字段存在，更新操作将被拒绝。

在正式让规则修改出价之前，先进行测试：

adapty asa automations run <automation-id> --dry-run

模拟运行会评估所有条件，并记录规则将执行的操作，但不会对 Apple Ads 做任何实际修改。运行任务会进入队列而非立即执行，因此该命令会输出一个运行 ID，执行结果可在 adapty asa automations runs 中查看。

安全地重复运行脚本

每次写入操作都会携带一个幂等性密钥。CLI 在每次调用时自动生成一个，并在网络错误后重试一次，因此传输过程中失败的请求不会被重复执行。

在脚本中，可以自行固定密钥，从而安全地重复运行整个流水线：

adapty asa campaigns create --org <campaign-group-id> --name "Winter push" --adam-id 123456 --country US --daily-budget 50 --idempotency-key winter-push-2026 --yes

在 24 小时内重复执行相同命令，系统会返回已存储的结果并打印 Already applied earlier，而不会创建第二个活动。使用相同键名但请求体不同的情况会返回 422 错误，从而捕获那些因脚本错误而重复使用键名的情况。

后续步骤