Adapty 开发者 CLI 的 Ads Manager 命令
本文列出了 Adapty CLI 中所有 Ads Manager 命令，包括其参数、标志及可接受的值。Ads Manager 命令位于 adapty asa 主题下。
有关前提条件、安全写入实践及基于任务的示例，请参阅通过 CLI 管理 Ads Manager。
这些命令需要已连接的 Apple Ads 账户以及有效的 Ads Manager 订阅。运行 adapty asa whoami 可同时查看两者的状态。其余 CLI 命令请参阅命令参考。
全局标志
这些标志适用于所有 Ads Manager 命令。
| 标志 | 描述 |
|---|---|
--json | 以 JSON 格式输出，而非格式化文本 |
--help | 显示命令帮助 |
所有 list 命令还支持分页标志：
| 标志 | 默认值 | 描述 |
|---|---|---|
--page | 1 | 页码 |
--page-size | 100 | 每页条目数（最大：1000） |
Ads Manager 的每页数据量大于 CLI 其他部分。建议使用单次大页请求，而非多次小页循环。
所有会修改账户的命令均支持以下标志：
| 标志 | 描述 |
|---|---|
--yes, -y | 不询问确认直接应用。当输出被管道传输或使用 --json 时必须指定 |
--idempotency-key | 为本次写入操作指定固定键。在 24 小时内使用相同键和请求体重复调用时，将返回已存储的结果，而不会再次应用变更 |
Ads Manager 命令不接受 --app 标志。操作范围为您的令牌所属的公司。--app 仅在部分 list 命令中作为过滤参数存在。
列表筛选
筛选器作用于查询本身，而非当前显示的页面。未设置筛选条件的 keywords list 会遍历账户中的所有关键词，因此请将每次读取的范围限定在所需层级。
| 过滤器 | 接受方 |
|---|---|
--campaign-group | campaigns, ad-groups, keywords, negative-keywords, search-terms, ads, creatives, product-pages |
--app | campaigns, ad-groups, keywords, negative-keywords, search-terms, creatives, product-pages |
--campaign | ad-groups, keywords, negative-keywords, search-terms, ads |
--ad-group | keywords, negative-keywords, search-terms, ads |
--status | campaigns, ad-groups, ads（ENABLED 或 PAUSED），keywords（ACTIVE 或 PAUSED） |
--search | campaigns, ad-groups, keywords, negative-keywords, search-terms, ads。对名称进行不区分大小写的子字符串匹配 |
adapty asa apps list、orgs list、automations list 和 automations runs 不支持任何过滤条件，仅接受分页标志。
--campaign-group、--app、--campaign 和 --ad-group 接受对应 list 命令输出的 UUID，且每个选项均可重复使用：
adapty asa keywords list --ad-group <ad-group-id> --ad-group <other-ad-group-id>如果传入的 ID 属于其他公司，则不会匹配任何结果，接口会返回空页，而非报错。
账户
adapty asa whoami
显示公司信息、Ads Manager 访问权限的授予方式，以及 Apple Ads 是否已连接。
adapty asa whoami首先运行此命令。它会报告其他所有命令的两个前提条件是否已满足。
adapty asa connect
将 Apple Ads 账户关联到 Adapty。
adapty asa connect该命令会打印一个 Apple 授权链接，并等待 Apple 报告账户已成功连接。
| 参数 | 默认值 | 说明 |
|---|---|---|
--wait / --no-wait | --wait | 等待 Apple Ads 报告连接成功。--no-wait 表示立即返回 |
--timeout | 300 | 等待浏览器操作步骤的超时秒数 |
adapty asa orgs list
列出您公司可用的广告系列组（Apple Ads 组织）。
adapty asa orgs list每行包含两个标识符，二者不可互换：
| 字段 | 用途 |
|---|---|
internal_id | campaigns create 的 --org 参数所接受的 UUID，也是列表筛选器中 --campaign-group 所接受的值 |
org_id | Apple 的数字组织 ID，两个参数均不接受此值 |
--org 仅在 campaigns create 中存在，任何列表命令均不接受该参数。
支持分页参数。
adapty asa apps list
列出在 Apple Ads 中推广的应用。
adapty asa apps list每行包含两个标识符，它们不可互换：
| 字段 | 用途 |
|---|---|
internal_id | 作为列表过滤器中 --app 参数接受的 UUID |
adam_id | Apple 的数字 App Store ID，由 campaigns create 和 product-pages sync 上的 --adam-id 参数使用 |
接受分页标志。
营销活动
adapty asa campaigns list
列出广告系列。仅返回元数据——如需查看效果数据，请使用 asa metrics。
adapty asa campaigns list --app <app-id> --status PAUSED支持分页标志以及 --campaign-group、--app、--search 和 --status 列表过滤器。
adapty asa campaigns get
获取特定广告系列的详细信息。
adapty asa campaigns get <campaign-id>| 参数 | 描述 |
|---|---|
campaign-id | 广告系列 ID（UUID） |
adapty asa campaigns create
创建一个广告活动。
adapty asa campaigns create --org <campaign-group-id> --name "Winter push" --adam-id 123456 --country US --daily-budget 50| 标志 | 必填 | 描述 |
|---|---|---|
--org | 是 | 推广活动组 ID（UUID）。参见 orgs list |
--name | 是 | 推广活动名称 |
--adam-id | 是 | App Store 应用 ID（adam_id） |
--country | 是 | 国家或地区代码。重复使用可指定多个：--country US --country CA |
--daily-budget | 是 | 每日预算，填写纯数字金额，例如 50 或 12.50 |
--budget | 否 | 总预算 |
--target-cpa | 否 | 目标每次获客成本 |
--currency | 否 | 本次调用金额所用的货币代码。默认值：USD |
--bidding-strategy | 否 | MANUAL_CPT 或 MAX_CONVERSIONS。Apple 默认为 MANUAL_CPT |
--ad-channel-type | 否 | SEARCH 或 DISPLAY。默认值：SEARCH |
--billing-event | 否 | TAPS 或 IMPRESSIONS。默认值：TAPS |
--supply-source | 否 | 供应来源，可重复使用。默认值：APPSTORE_SEARCH_RESULTS |
--status | 否 | 初始状态：ENABLED 或 PAUSED |
adapty asa campaigns update
更新已有的广告活动。
adapty asa campaigns update <campaign-id> --daily-budget 80 --status PAUSED| 参数 | 描述 |
|---|---|
campaign-id | 广告活动 ID（UUID） |
| 标志 | 描述 |
|---|---|
--name | 新广告活动名称 |
--status | ENABLED 或 PAUSED |
--country | 替换国家/地区列表。可重复使用以指定多个国家/地区 |
--daily-budget | 新的每日预算 |
--budget | 新的总生命周期预算 |
--target-cpa | 新的目标每次转化费用 |
--bidding-strategy | MANUAL_CPT 或 MAX_CONVERSIONS |
--currency | 本次调用中金额所使用的货币代码。默认值：USD |
至少需要提供一个标志。
广告组
adapty asa ad-groups list
列出广告组。仅返回元数据——如需查看效果数据，请使用 asa metrics。
adapty asa ad-groups list --campaign <campaign-id>支持分页标志以及 --campaign-group、--app、--campaign、--search 和 --status 列表筛选器。
adapty asa ad-groups get
获取特定广告组的详细信息。
adapty asa ad-groups get <ad-group-id>| 参数 | 描述 |
|---|---|
ad-group-id | 广告组 ID（UUID） |
adapty asa ad-groups create
在广告系列中创建广告组。
adapty asa ad-groups create --campaign <campaign-id> --name "Brand terms" --default-bid 1.20| 参数 | 是否必填 | 说明 |
|---|---|---|
--campaign | 是 | 广告系列 ID（UUID） |
--name | 是 | 广告组名称 |
--default-bid | 是 | 默认出价金额，例如 1.20 |
--cpa-goal | 否 | 目标单次转化成本 |
--pricing-model | 否 | CPC 或 CPM。Apple 要求每个广告组必须指定其中一种。默认值：CPC |
--start-time | 否 | 排期开始时间（YYYY-MM-DD），默认为今天 |
--end-time | 否 | 排期结束时间（YYYY-MM-DD） |
--automated-keywords / --no-automated-keywords | 否 | 允许 Apple 自动添加关键词 |
--currency | 否 | 本次调用所用的货币代码。默认值：USD |
--status | 否 | 初始状态：ENABLED 或 PAUSED |
adapty asa ad-groups update
更新现有广告组。
adapty asa ad-groups update <ad-group-id> --default-bid 1.50 --status PAUSED| 参数 | 描述 |
|---|---|
ad-group-id | 广告组 ID（UUID） |
| 参数 | 描述 |
|---|---|
--name | 新广告组名称 |
--status | ENABLED 或 PAUSED |
--default-bid | 新默认出价 |
--cpa-goal | 新的每次转化费用目标 |
--start-time | 排期开始时间（YYYY-MM-DD） |
--end-time | 排期结束时间（YYYY-MM-DD） |
--automated-keywords / --no-automated-keywords | 允许 Apple 自动添加关键词 |
--currency | 本次调用金额所用货币代码，默认值：USD |
至少需要传入一个参数。父级推广活动由服务器解析，无需手动传入。
关键词
关键词命令每次调用最多批量处理 100 条。看板端的等效操作请参阅管理关键词。
adapty asa keywords list
列出定向关键词。仅返回元数据——如需读取效果数据，请使用 asa metrics。
adapty asa keywords list --ad-group <ad-group-id> --status ACTIVE支持分页标志以及 --campaign-group、--app、--campaign、--ad-group、--search 和 --status 列表筛选条件。建议通过 --ad-group 进行筛选——不添加筛选条件时，此操作的读取范围最广。
adapty asa keywords add
向广告组添加定向关键词。
adapty asa keywords add --ad-group <ad-group-id> --text "running shoes" --text "trail shoes" --bid 1.20从文件中读取关键词，每行一个：
adapty asa keywords add --ad-group <ad-group-id> --from-file keywords.txt| 参数 | 是否必填 | 说明 |
|---|---|---|
--ad-group | 是 | 广告组 ID（UUID），系统会据此解析对应的广告系列 |
--text | 是，除非使用 --from-file | 关键词文本，可重复多次以添加多个关键词 |
--from-file | 否 | 包含关键词的文件，每行一个，与 --text 参数合并使用 |
--bid | 否 | 每个关键词的出价金额 |
--match-type | 否 | BROAD 或 EXACT，默认值：BROAD |
--currency | 否 | 本次调用中金额所使用的货币代码，默认值：USD |
--status | 否 | ACTIVE 或 PAUSED，默认值：ACTIVE |
一个无效 ID 会导致整批请求在调用 Apple 之前全部失败。Apple 仍可能拒绝单个关键词，每次拒绝都会附带相应原因。
adapty asa keywords update
更改一个或多个关键词的出价、状态、文本或匹配类型。
adapty asa keywords update <keyword-id> <keyword-id> --bid 2.00 --status PAUSED| 参数 | 说明 |
|---|---|
keyword-id | 关键词 ID（UUID）。可传入多个作为额外参数 |
| 标志 | 说明 |
|---|---|
--bid | 新出价 |
--status | ACTIVE 或 PAUSED |
--match-type | BROAD 或 EXACT |
--text | 新关键词文本，仅对单个关键词有意义 |
--currency | 本次调用金额所用的货币代码，默认值：USD |
一次更改适用于所传入的每个 ID。
否定关键词
adapty asa negative-keywords list
列出否定关键词。ad_group_id 为空的行属于广告系列级别。
adapty asa negative-keywords list --campaign <campaign-id>| Flag | Description |
|---|---|
--campaign-level-only | 仅保留广告系列级别的行 |
接受分页标志以及 --campaign-group、--app、--campaign、--ad-group 和 --search 列表过滤器。
adapty asa negative-keywords add
向广告组或广告系列添加否定关键词。
adapty asa negative-keywords add --ad-group <ad-group-id> --text free或者将其应用于广告系列中的每个广告组：
adapty asa negative-keywords add --campaign <campaign-id> --all-ad-groups --text free| 参数 | 是否必填 | 说明 |
|---|---|---|
--ad-group | --ad-group 或 --campaign 二选一 | 广告组 ID（UUID），系统会从中解析出对应的广告系列 |
--campaign | --ad-group 或 --campaign 二选一 | 广告系列 ID（UUID） |
--text | 是 | 关键词文本，可重复使用以指定多个关键词 |
--all-ad-groups | 否 | 应用于该广告系列的所有广告组，而非广告系列本身。需配合 --campaign 使用 |
--match-type | 否 | BROAD（广泛匹配）或 EXACT（精确匹配），默认值：EXACT |
--status | 否 | ACTIVE（启用）或 PAUSED（暂停），默认值：ACTIVE |
--ad-group 和 --campaign 互斥，二者只能传其一。
搜索词
adapty asa search-terms list
列出触发广告的搜索词，用于发现新的关键词和新的否定关键词。
adapty asa search-terms list --ad-group <ad-group-id> --date-from 2026-07-01 --date-to 2026-07-31| 参数 | 默认值 | 说明 |
|---|---|---|
--date-from | 今天 | 报告周期开始日期（YYYY-MM-DD） |
--date-to | 今天 | 报告周期结束日期（YYYY-MM-DD） |
支持分页参数以及 --campaign-group、--app、--campaign、--ad-group 和 --search 列表过滤器。
该命令与 asa metrics 共享分析资源池。请参阅错误。
广告
adapty asa ads list
列出广告。serving_state_reasons 字段说明广告未投放的原因。
adapty asa ads list --ad-group <ad-group-id>支持分页标志以及 --campaign-group、--campaign、--ad-group、--search 和 --status 列表过滤器。此列表没有 --app 过滤器，因为广告隶属于广告组。
adapty asa ads get
获取特定广告的详细信息。
adapty asa ads get <ad-id>| 参数 | 说明 |
|---|---|
ad-id | 广告 ID（UUID） |
adapty asa ads create
在广告组中创建广告。
adapty asa ads create --ad-group <ad-group-id> --creative-id 4321 --name "Summer ad"| 标志 | 是否必填 | 描述 |
|---|---|---|
--ad-group | 是 | 广告组 ID（UUID）。广告系列将从中解析 |
--creative-id | 是 | Apple 素材 ID。参见 creatives list |
--name | 是 | 广告名称 |
--status | 否 | 初始状态：ENABLED 或 PAUSED |
adapty asa ads update
更新现有广告。
adapty asa ads update <ad-id> --status PAUSED| 参数 | 描述 |
|---|---|
ad-id | 广告 ID（UUID） |
| 标志 | 描述 |
|---|---|
--name | 新广告名称 |
--status | ENABLED 或 PAUSED |
至少需要一个标志。创意素材和所属广告组在创建时已固定，不可更改。
创意素材
adapty asa creatives list
列出可用于新广告的创意素材。
adapty asa creatives list --app <app-id>此处返回的 creative_id 即为 ads create 的 --creative-id 参数值。
支持分页标志以及 --campaign-group 和 --app 列表过滤器。
产品页面
adapty asa product-pages list
列出应用可用的自定义产品页面。
adapty asa product-pages list --app <app-id>支持分页标志以及 --campaign-group 和 --app 列表筛选器。
adapty asa product-pages sync
从 App Store Connect 刷新自定义产品页面。
adapty asa product-pages sync --adam-id 123456| 标志 | 描述 |
|---|---|
--adam-id | 限制仅刷新一个应用。省略则覆盖所有应用 |
刷新操作会进入队列而非立即执行，命令成功后返回 Sync queued.。如果相同的刷新已在进行中，则返回 Already running; nothing new was queued.。
自动化
CLI 会存储你提供的规则 JSON，而不会自行构建规则。请参阅自动化了解各规则类型的作用，以及运行自动化规则了解如何生成规则文件。
adapty asa automations list
列出自动化规则。status 字段中，1 表示启用，0 表示已停止。
adapty asa automations list接受分页标志。
adapty asa automations get
获取特定自动化规则，包括其条件和操作。
adapty asa automations get <automation-id>| Argument | Description |
|---|---|
automation-id | 自动化规则 ID（UUID） |
adapty asa automations create
从 JSON 规则文件创建自动化规则。
adapty asa automations create --file rule.json| 参数 | 描述 |
|---|---|
--file | 包含规则内容的 JSON 文件，或使用 - 从标准输入读取 |
--run-now | 规则存储完成后立即将首次运行加入队列 |
--file 为必填项。
adapty asa automations update
修改自动化规则：停止、重命名或替换规则的部分内容。
adapty asa automations update <automation-id> --stop| 参数 | 描述 |
|---|---|
automation-id | 自动化规则 ID（UUID） |
| 标志 | 描述 |
|---|---|
--start | 激活规则 |
--stop | 停止规则并清除其下次运行时间 |
--name | 新规则名称 |
--file | 包含待修改部分的 JSON 文件，或使用 - 从标准输入读取 |
--start 和 --stop 互斥，不可同时使用。通过此方式传入的文件不得包含 internal_id。
adapty asa automations run
在计划之外，立即执行一次自动化规则。
adapty asa automations run <automation-id> --dry-run| 参数 | 说明 |
|---|---|
automation-id | 自动化规则 ID（UUID） |
| 标志 | 说明 |
|---|---|
--dry-run | 评估规则并记录结果，但不在 Apple Ads 中做任何变更 |
执行任务会进入队列，命令将输出一个运行 ID。可通过 automations runs 查看执行结果。
adapty asa automations runs
列出某条自动化规则的历史运行记录，包括试运行记录。
adapty asa automations runs <automation-id>| 参数 | 描述 |
|---|---|
automation-id | 自动化规则 ID（UUID） |
支持分页标志。
数据图表
adapty asa metrics
查询指定日期范围内任意账户层级的数据图表。
adapty asa metrics --entity campaign --date-from 2026-07-01 --date-to 2026-07-31| 参数 | 是否必填 | 描述 |
|---|---|---|
--entity | 是 | 报告对象：campaign、ad-group、keyword 或 ad |
--date-from | 是 | 时间段起始日期（YYYY-MM-DD） |
--date-to | 是 | 时间段结束日期（YYYY-MM-DD） |
--metric | 否 | 数据图表名称，可重复使用。省略则返回所有数据图表 |
--group-by | 否 | 按 country、day、week、month、quarter 或 year 对行进行分组，可重复使用 |
--by-days | 否 | 同期群数据图表的续订周期（天数），可重复使用，每次调用最多 16 个。省略则使用看板默认值 |
--order-by | 否 | 用于排序的数据图表或字段 |
--order-by-day | 否 | 按指定续订周期的同期群数据图表排名，必须是 --by-days 中的某个值 |
--order | 否 | asc 或 desc，默认值：desc |
接受分页标志。此命令不支持列表过滤器——请通过实体级别和时间段来缩小报告范围，然后将结果行与有范围限制的 list 命令返回的 ID 进行匹配。
每一行代表一个实体，由服务器汇总后按 --order-by 排序。因此，查询前 N 名只需一次调用——设置 --order-by 和 --page-size N，而无需逐页翻阅结果再手动累加：
adapty asa metrics --entity campaign --date-from 2026-07-01 --date-to 2026-07-31 --order-by spend --page-size 5--metric 接受 Ads Manager 所追踪的数据图表名称，使用看板命名规范——例如 spend、taps 或 gross_roas。完整列表及每项数据图表的计算方式，请参见数据图表。若传入不存在的名称，请求将失败，错误信息中会列出所有有效名称。
报告周期的长度受最粗粒度的 --group-by 值限制。如需覆盖更长的时间范围，应将分组粒度调粗，而不是将请求拆分为多次调用：
最粗粒度的 --group-by | 最大时间范围 |
|---|---|
day 或不分组 | 90 天 |
week | 180 天 |
month 及更粗粒度 | 365 天 |
没有 ltv 数据图表。生命周期价值是一个同期群指标，通过续订窗口读取，因此需要用 --by-days 来获取第 7 天或第 90 天的值：
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 天 ROAS 排名的最佳广告活动。
adapty asa metrics overview
Query totals for a period, bucketed by a unit of time.
adapty asa metrics overview --entity campaign --date-from 2026-07-01 --date-to 2026-07-31 --period-unit week| 参数 | 是否必填 | 描述 |
|---|---|---|
--entity | 是 | 报告维度：campaign、ad-group、keyword 或 ad |
--date-from | 是 | 时间段起始日期（YYYY-MM-DD） |
--date-to | 是 | 时间段结束日期（YYYY-MM-DD） |
--period-unit | 否 | 统计粒度：day、week、month、quarter 或 year。默认值：day |
--metric | 否 | 数据图表名称，可重复使用。省略则返回所有数据图表 |
--by-days | 否 | 同期群数据图表的续订窗口天数，可重复使用。每次调用最多 16 个 |
此命令返回整个实体级别的汇总数据以及按时间段的序列数据，因此只需一次调用即可回答”总体花费或收入了多少”。它没有排序标志，也不支持分页。
在此命令中，--metric 仅接受同期群根指标——revenue、roas 和 arpu——不接受其 gross_、proceeds_ 或 net_ 变体。
报告周期的长度受 --period-unit 限制：
--period-unit | 最大周期 |
|---|---|
day | 90 天 |
week | 180 天 |
month 及更粗粒度 | 365 天 |
竞品对比
adapty asa competitors summary
汇总一组 App Store 应用所竞价的 Apple Ads 关键词。返回的竞争对手数据与看板中的 Market Intelligence 相同。
adapty asa competitors summary --app-ids 1668337467,6503873027| 标志 | 必填 | 描述 |
|---|---|---|
--app-ids | 是 | Apple App Store ID（adam_id），以逗号分隔，支持 1 到 5 个值 |
报告周期和国家集合在服务端固定——取最近一个完整月份，覆盖所有国家。该命令不支持周期、国家或分页参数。
该命令会输出三个部分：分析汇总数据、按表现排名的顶部应用，以及竞争最激烈的词条。添加 --json 可获取完整结果，其中还会按国家细分每个应用的词条数据。
对于一组应用的首次调用，数据准备期间可能需要数十秒。后续对相同应用的调用将更快返回。
错误
| 状态码 | 错误码 | 含义 |
|---|---|---|
402 | ads_manager_subscription_required | 该公司没有有效的 Ads Manager 订阅 |
404 | — | 实体不存在，或属于其他公司 |
409 | cli_idempotency_in_progress | 使用相同幂等键的写入操作仍在进行中 |
422 | cli_idempotency_key_reuse | 相同的幂等键被用于不同的请求体 |
429 | cli_analytics_busy | 分析池繁忙，等待时间见 Retry-After 响应头 |
429 | cli_cooldown_active | 过多被拒请求导致令牌进入冷却期 |
数据图表与搜索词列表共用同一个分析预算，每家公司每分钟最多调用 5 次，任意 10 秒内最多调用 2 次。若在 5 分钟内累计出现 20 次被拒绝的请求，将触发逐级递增的冷却机制：依次为 5 分钟、30 分钟和 3 小时。在冷却期间重试不会延长等待时间，但解决问题的正确方式是修正失败的请求，而非反复重试。
CLI 会自动处理短暂等待。若收到非冷却触发的 429 响应，且 Retry-After 不超过 60 秒，命令会等待相应时长后重试一次，并将等待信息输出至标准错误流。