本文列出了 Adapty CLI 中每个 广告管理器 命令，包括其参数、标志和可接受的值。广告管理器命令位于 adapty asa 主题下。

这些命令需要已连接的 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 命令中作为筛选条件存在。市场细分命令是个例外：在这些命令中，--app 指定的是该市场细分所属的 Adapty 应用。

列表筛选

筛选器作用于查询本身，而非当前显示的页面。未设置筛选条件的 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，由 campaigns bulk-create 中的 --org-id 使用。--org 和 --campaign-group 不接受此值

--org 仅在 campaigns create 中可用，list 命令不接受该参数。

每行还包含一个 payment_model 字段。当其值为 LOC 时，表示该组织按信用额度计费，其中的每个推广活动都需要使用 --invoice-* 标志。

支持分页标志。

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	否	目标每次转化费用，必须低于 --daily-budget
--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
--invoice-advertiser	信用额度	发票选项：广告主名称
--invoice-order-number	信用额度	发票选项：订单编号
--invoice-contact-name	信用额度	发票选项：采购方联系人姓名
--invoice-contact-email	信用额度	发票选项：采购方联系人邮箱
--invoice-billing-email	信用额度	发票选项：账单联系人邮箱

一个 payment_model 为 LOC 的组织按信用额度计费，Apple 要求为其每个广告系列设置开票选项。请在一次调用中传入全部五个 --invoice-* 标志——部分传入会在请求发送前被拒绝。详见为信用额度设置开票选项。

响应中包含 serving_status 和 serving_state_reasons。创建成功的广告系列不一定会立即投放：MAX_CONVERSIONS 广告系列需要等待自动广告组，而信用额度广告系列则需要等待其发票选项配置完成。两种情况下，命令均会打印出原因说明及解决该问题所需执行的命令。

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
--invoice-advertiser	发票选项：广告主名称
--invoice-order-number	发票选项：订单编号
--invoice-contact-name	发票选项：采购方联系人姓名
--invoice-contact-email	发票选项：采购方联系人邮箱
--invoice-billing-email	发票选项：账单联系人邮箱

至少需要一个标志。

--invoice-* 这五个标志作为一组使用，会整体替换已存储的 Invoicing Options，因此即使只修改其中一项，也需要同时传入全部五个标志。如果传入的标志不完整，请求在发送前就会被拒绝。

adapty asa campaigns bulk-create

通过单次操作创建完整的广告活动结构——包含广告活动及其嵌套的广告组、关键词、否定关键词和广告。

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

也可以直接转换原生 Apple Ads 批量模板，无需手动编写 JSON：

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

标志	默认值	描述
--file	—	包含广告系列结构的 JSON 文件，或使用 - 从标准输入读取
--from-file	—	要在服务器上转换的 Apple Ads 批量模板：Campaign_And_Adgroup_Template.xlsx 或关键词 .csv
--org-id	—	Apple 的数字组织 ID（org_id）。参见 orgs list。与 --from-file 一起使用时必填
--preview	—	与 --from-file 配合使用：打印转换后的结构并停止，不会创建任何内容
--wait / --no-wait	--wait	轮询操作直至完成。--no-wait 会打印操作 ID 并返回
--poll-interval	5	轮询进度的间隔秒数
--timeout	900	等待操作完成的最长秒数

恰好需要 --file 和 --from-file 其中之一。

该结构在顶层命名活动组，并在其中嵌套所有其他内容：

{
  "campaign_group_id": 555777,
  "campaigns": [
    {
      "payload": {
        "name": "US Search",
        "adam_id": 123456,
        "countries_or_regions": ["US"],
        "daily_budget_amount": { "amount": "100", "currency": "USD" },
        "status": "ENABLED",
        "ad_channel_type": "SEARCH",
        "billing_event": "TAPS",
        "supply_sources": ["APPSTORE_SEARCH_RESULTS"]
      },
      "ad_groups": [
        {
          "payload": { "name": "Brand", "start_time": "2026-08-01T00:00:00Z", "status": "ENABLED" },
          "keywords": [{ "text": "meditation app", "match_type": "BROAD" }]
        }
      ]
    }
  ]
}

campaign_group_id 接受 Apple 的数字组织 ID；如需传入 UUID，请改用 campaign_group_internal_id。包含 payload 的节点会被创建。仅通过 id 引用现有实体的节点为锚点——可用锚点向已有广告系列添加广告组，同时添加 update_payload 可在同一操作中修改该实体。每个广告系列嵌套 ad_groups，每个广告组嵌套 keywords、negative_keywords 和 ads。广告系列还可直接接受 negative_keywords，用于设置广告系列级别的否定关键词。

整个结构在创建任何内容之前都会经过验证，拒绝时会列出每个无效节点。使用 --from-file 时，转换问题会附带所在的工作表、行和列信息；转换警告不会中止提交，但转换错误会终止操作。发送前，命令会汇报结构中包含多少个广告系列、广告组、关键词、否定关键词和广告，并要求确认。

命令随后会轮询操作进度并持续打印，直到出现以下三种最终状态之一：

状态	含义
success	所有对象均已创建
partial	部分对象未能创建，每条失败信息均附有 Apple 的错误提示
failed	操作失败，命令以非零状态退出

如果操作在 --timeout 秒内未完成，命令将返回并打印稍后运行的 bulk-status 调用。

adapty asa campaigns bulk-status

显示单个批量操作的进度：状态、对象计数以及每个对象的日志。

adapty asa campaigns bulk-status <operation-id>

参数	描述
operation-id	由 campaigns bulk-create 输出的操作 ID（UUID）

status 字段的值为 pending、running、success、partial 或 failed。counts 块报告在总数中已应用、失败和待处理的对象数量。

支持分页标志。

广告组

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	未设置 --automated 时必填	默认出价，填写纯数字金额，例如 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 自动添加关键词
--automated	否	创建 MAX_CONVERSIONS 广告系列所需的自动化广告组
--currency	否	本次调用中金额所用的货币代码。默认值：USD
--status	否	初始状态：ENABLED 或 PAUSED

--automated 选项会将广告组纳入自动关键词管理，因此不能与 --automated-keywords 同时使用。Apple 会自动安排该广告组并保持启用状态，所以 --start-time 和 --status PAUSED 均不被支持——如需暂停，请暂停广告系列本身。请参阅创建 Max Conversions 广告系列。

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 recommend

获取某个应用的现成关键词池。这些关键词池与你在看板中设置广告系列时 Ads Manager 所使用的相同。

adapty asa keywords recommend --adam-id <adam-id> --type generic --country US

参数	是否必填	说明
--adam-id	是	应用的 Apple App Store ID（adam_id），可从 asa apps list 获取
--type	是	brand、generic 或 competitor
--country	否	两位 ISO 国家代码，可重复使用以指定多个国家。默认值：关键词池中的所有国家

--type 标志用于选择资源池：

类型	关键词
brand	您应用的品牌词汇、拼写变体，以及包含品牌的自然流量词。输出结果还会列出品牌词汇本身
generic	您的应用及其主要自然竞争对手共同排名的非品牌词汇，已去除所有已知品牌词。relevance_tier: top_organic 标记您的应用已在自然搜索前 10 名中排名的词汇
competitor	在 AI Growth Advisor 中为该应用选定的各竞争对手的品牌词汇，每个竞争对手对应一个词库。在选择竞争对手之前为空

每个关键词都包含其所在国家/地区、热度、评分和自然搜索排名中位数。这些关键词没有预设出价或匹配类型，请自行决定，然后通过 asa keywords add 添加关键词。

在使用关键词池中的关键词之前，请先检查其 status：

状态	含义
ready	关键词池已构建完成
building	关键词池仍在构建中，请约一分钟后重试
empty	关键词池已构建完成，但没有关键词
failed	构建失败，请稍后重试

第一次为某个应用调用 brand 或 generic 时，系统会在请求期间构建数据池，这可能需要数十秒。该命令每家公司每分钟限额 10 次调用，且每家公司同一时间只能运行一个 brand 或 generic 构建任务。如果在此期间发起第二次构建，将返回 429 cli_analytics_busy，并附带 Retry-After: 5。

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 列表过滤器。

除了效果数据指标外，每个搜索词行还包含 Apple 对该词的洞察信息：

字段	值
impression_share_all, impression_share_first	任意广告位或首位广告位的展示份额
impression_midpoint_all, impression_midpoint_first	以单一百分比表示的展示份额
rank_all, rank_first	您的应用在任意广告位或首位广告位中针对该词的排名（与其他应用相比）
search_popularity	搜索热度，范围 1 到 5

当 Apple 没有该字段的数据时，其值为 null。有关 Apple 如何定义这些值，请参阅 Insights。

此命令与 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.。

市场细分

这些命令根据 Apple Ads 广告系列、广告组或关键词创建 Adapty 市场细分，与 Ads Manager 中的 Create segment from… 功能一致。将市场细分用作版位和 A/B 测试中的目标受众，可以向来自特定广告系列的用户展示不同的付费墙。

每个市场细分都包含一个归因过滤条件，针对你所选实体的 Apple ID。CLI 会自动查找这些 ID，因此你需要传入 list 命令输出的 UUID。

与其他 adapty asa 命令不同，这些命令使用 --app：即该市场细分所属的 Adapty 应用 ID，可通过 adapty apps list 获取。它们不支持 --idempotency-key。如需创建包含其他筛选条件（如国家或安装日期）的市场细分，请使用 adapty segments create。

adapty asa segments create

从广告系列、广告组或关键词创建市场细分。

adapty asa segments create --app <app-id> --campaign <campaign-id>
adapty asa segments create --app <app-id> --ad-group <ad-group-id> --keyword <keyword-id> --keyword <other-keyword-id>

参数	必填	说明
--app	是	Adapty 应用 ID（UUID）
--campaign	选填其一	广告系列 ID（UUID）。可重复使用
--ad-group	选填其一	广告组 ID（UUID）。可重复使用。与 --keyword 同时使用时，只能传入一个：即包含相关关键词的广告组
--keyword	选填其一	关键词 ID（UUID）。可重复使用。需要同时指定一个 --ad-group
--title	否	市场细分标题。默认使用 Ads Manager 格式，例如 [ASA] Campaign: <name>
--description	否	市场细分描述。默认使用 Ads Manager 格式

每个细分市场只能由同一类实体构成。同时传入 --campaign 和 --ad-group，或者 --campaign 与 --keyword 一起使用，会在发送任何请求之前以退出码 2 报错。同一类型的多个实体会生成一个细分市场，匹配其中任意一个实体的用户。

除非有特殊需求，保持默认标题即可。Ads Manager 通过 [ASA] 前缀识别其细分市场，asa segments list 只会列出带有此前缀的细分市场。

响应包含完整的片段，包括 id 和 filters。profile_count 初始值为 0，Adapty 会在市场细分创建完成后重新计算该值。

adapty asa segments update

替换现有市场细分的广告系列、广告组或关键词。

adapty asa segments update <segment-id> --app <app-id> --campaign <campaign-id> --campaign <other-campaign-id>

参数	说明
segment-id	市场细分 ID（UUID），来自 asa segments list 或 adapty segments list

接受与 asa segments create 相同的标志。市场细分的筛选条件将替换为你传入的实体，标题和描述保持不变，除非你传入 --title 或 --description。

adapty asa segments list

列出从 Apple Ads 实体创建的市场细分——即标题以 [ASA] 开头的市场细分。

adapty asa segments list --app <app-id> --campaign <campaign-id>

标志	是否必填	描述
--app	是	Adapty 应用 ID（UUID）
--campaign	否	仅保留从此推广活动构建的市场细分（UUID）
--ad-group	否	仅保留从此广告组构建的市场细分（UUID）

传入 --campaign 或 --ad-group，二者不可同时使用。为避免为同一广告系列重复创建市场细分，请在执行 asa segments create 之前先运行此命令：若结果为空，说明该广告系列尚未关联任何市场细分。

该命令最多读取应用的前 100 个市场细分。

自动化

CLI 会存储您提供的规则 JSON，但有一个例外：Add as keyword 操作的设置来自命令行参数。有关每种规则类型的功能，请参阅自动化；有关如何生成规则文件，请参阅运行自动化规则。

添加为关键词操作的命令标志

automations create 和 automations update 共享一组命令标志，用于为 add-as-keyword-to 操作设置 actions[0].params——对应搜索词规则中的 Add as keyword，以及关键词规则中的 Add as keyword to…。传入其中任意标志都会替换整个 params 对象，因此该操作无需手动编写 JSON。

标志	JSON 字段	描述
--target-ad-group	targets.internal_ids	接收关键词的广告组（UUID），可重复。没有目标广告组的规则不会执行任何操作
--match-type	match_type	BROAD 或 EXACT
--cpt-bid-type	cpt_bid.type	新关键词出价的来源：ad_group_default_bid、set_to、search_term_current_cpt 或 keyword_current_bid
--cpt-bid	cpt_bid.value	使用 set_to 时，为出价本身。使用 search_term_current_cpt 或 keyword_current_bid 时，为所复制出价的百分比加价。不与 ad_group_default_bid 一起使用
--negate	negate	同时将搜索词添加为否定关键词，添加到其所属的 ad-group 或 campaign 中。--no-negate 则不保留任何否定关键词。仅适用于搜索词规则
--skip-enable-duplicates	skip_enable_duplicate_keywords	跳过目标广告组中已存在的关键词，而不是将其启用。仅适用于搜索词规则
--pause-original	pause_in_original_ad_group	在源广告组中暂停该关键词。仅适用于关键词规则

--cpt-bid-type 和 --match-type 没有默认值，因此当规则文件本身不包含 params 时，这两个参数均为必填项。

以下四个标志取决于规则的 operate_with 字段：--negate、--no-negate 和 --skip-enable-duplicates 属于 search-term 规则，--pause-original 属于 targeting-keyword 规则。若使用了不属于当前规则类型的标志，命令将以退出码 2 失败，并列出适用的标志。

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 为必填项，且文件中必须恰好包含一个 action：API 每条规则只保留一个 action 和一个 condition。

同时支持 add-as-keyword action 标志，用于填充或覆盖 actions[0].params：

adapty asa automations create --file rule.json --target-ad-group <ad-group-id> --match-type EXACT --cpt-bid-type search_term_current_cpt --negate ad-group

adapty asa automations update

更改自动化规则：停止、重命名或替换规则的某些部分。

adapty asa automations update <automation-id> --stop

参数	说明
automation-id	自动化规则 ID（UUID）

标志	说明
--start	激活规则
--stop	停止规则并清除下次运行时间
--name	新规则名称
--file	包含待修改部分的 JSON 文件，或 - 表示从标准输入读取

--start 与 --stop 互斥。此处传入的文件不得包含 internal_id。

同样接受 add-as-keyword 操作标志。传入其中一个会使调用变为读-改-写操作：CLI 读取规则，重新构建 actions[0].params，然后将整个 actions 列表发送回去，因为 API 会替换 actions 而非合并。如果在读取和写入之间通过看板进行了编辑，这些更改将被覆盖。

带有操作标志的更新也会修复那些存储的 params 携带其他操作结构的规则。params 会从头重建，因此只有符合 add-as-keyword-to 结构的存储键会被保留，其余所有内容都必须来自标志。

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	是	数据图表名称，可重复使用
--app	否	仅报告指定应用，可重复使用
--campaign	否	仅报告指定推广活动，可重复使用
--ad-group	否	仅报告指定广告组，可重复使用
--group-by	否	按 country、day、week、month、quarter 或 year 分组，可重复使用
--by-days	否	同期群数据图表的续订窗口（天数），可重复使用，每次调用最多 16 个。省略则使用看板默认值
--order-by	否	排序依据的数据图表或字段
--order-by-day	否	按指定续订窗口的同期群数据图表排名，必须是 --by-days 中的某个值
--order	否	asc 或 desc，默认值：desc

接受分页标志。在列表过滤器中，它仅支持 --app、--campaign 和 --ad-group；没有 --search 和 --status。如需按其他条件缩小报告范围，请将行与限定范围的 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。完整列表及各指标的计算方式，请参阅数据指标。如果指标名称不存在，命令会报错并列出所有有效名称。

使用 --entity keyword 时，--metric 还支持仅适用于关键词的数据图表。Apple 会分别针对任意广告位置和首个广告位置上报展示份额与排名，因此每项均有两个版本：_all 和 _first。各项的具体定义请参阅 Insights。

数据图表	值
impression_midpoint_all, impression_midpoint_first	报告周期内的展示份额，以百分比表示
rank_all, rank_first	你的应用针对该关键词相对于其他应用的排名。取最新值，不受 --date-from 和 --date-to 限制
search_popularity	搜索热度，范围 1 到 5

若某关键词没有报告数据，这些数据图表的返回值均为 0。自 CLI 0.9.2 起，这些名称取代了原有的 rank 和 impression_midpoint。

每个数据图表都在分页之前跨整个实体层级进行计算，因此请只请求你实际读取的列，而不是获取全部字段。subscribers 和 paid_subscribers 统计每个实体的唯一用户画像数量，其开销约为普通花费和安装量调用的 17 倍，arppu 和 arpas 由它们派生，同样如此。在任意 --entity 下，这四个字段名需要配合 --campaign 或 --ad-group 来缩小调用范围：

adapty asa metrics --entity keyword --date-from 2026-07-01 --date-to 2026-07-31 --metric arpas --campaign <campaign-id>

如果缺少上述两个过滤条件中的任意一个，调用将失败并返回 422 cli_metric_scope_too_wide。缩小范围是加速任何数据图表调用的最低成本方式，因为开销取决于聚合的实体数量，而非页面大小。

报告周期的最大长度受最细 --group-by 值的限制。如需覆盖更长的时间范围，请将分组粒度调粗，而不是将请求拆分为多次调用：

最细 --group-by	最大周期
day	28 天
无周期分组	90 天
week	180 天
month 及更粗粒度	365 天

因此，day 粒度最多覆盖四周。如需更长的时间段，请使用 week 粒度查询，一次调用最多可覆盖半年。

每页的明细行数上限为 5000 行，一行表示一个实体 × 国家 × 时间段的组合。若页面超出上限，将返回 422 cli_response_too_large 错误。解决方法包括：粗化分组粒度、缩短日期范围，或降低 --page-size 的值。当按 day 分组时，错误信息会直接给出适合的页大小，请直接使用该数值重试，而不是自行估算。metrics overview 不返回按实体拆分的明细，因此该上限对其不适用。

没有 ltv 这个数据图表。生命周期价值是同期群数据图表，在续费窗口读取，因此要获取第 7 天或第 90 天的值，需要使用 --by-days：

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 可获取完整结果，其中还会按国家细分每个应用的词条数据。

对于一组应用的首次调用，数据准备期间可能需要数十秒。后续对相同应用的调用将更快返回。

变更历史

变更历史直接从 Apple Ads API 实时获取。Adapty 不会存储这些数据，Apple 保留期限为 6 个月。它涵盖组织内的所有变更，包括直接在 Apple Ads 中进行的变更、由 Apple 客服操作的变更，以及通过其他 API 工具所做的变更。

adapty asa change-history list

列出某个 Apple Ads 组织中的变更历史，按时间倒序排列。

adapty asa change-history list --campaign-group <campaign-group-id> --date-from 2026-10-01 --entity-type Campaign --event-type UPDATE

标志	是否必填	说明
--campaign-group	是	要读取的组织（来自 orgs list 的 UUID）。每次调用只能指定一个组织。如需读取多个，请对每个组织分别执行该命令
--date-from	否	时间段起始日期（YYYY-MM-DD）。默认值：7 天前
--date-to	否	时间段结束日期（YYYY-MM-DD）。默认值：今天。时间段最长不超过 14 天
--entity-type	否	Campaign、AdGroup、Keyword、NegativeKeyword、Ad、Creative、LocationGroup、Org 或 AdAccount。可重复指定。默认值：除 Org 和 AdAccount 之外的所有类型。Org 和 AdAccount 不能与其他类型混合使用
--event-type	否	CREATE、UPDATE 或 DELETE。可重复指定
--user-type	否	操作人类型：CUSTOMER（在 Apple Ads 中操作）、CUSTOMER_API（通过 Apple Ads API 操作）或 APPLE_SUPPORT。可重复指定
--campaign、--ad-group、--entity-id	否	广告系列、广告组或被修改实体的 Apple 数字 ID。可重复指定
--user	否	执行变更操作的人员的 Apple 用户 ID。可重复指定
--txn	否	Apple 交易 ID。可重复指定
--fields	否	将每条变更展开为每个已更改字段一行，并显示其新旧值

每一行代表一次操作记录：操作者（modified_by、user_type）、操作时间（event_time）以及所变更的实体。每个实体都包含一个 detail_id，可用于 change-history get。

使用 --fields 时，页面大小默认为 10，更大的 --page-size 会被拒绝。若某页需要超过 20 次查找，则操作失败：请缩小过滤条件，或去掉 --fields，改用 change-history get 逐条读取变更记录。

支持分页标志。--page × --page-size 不能超过 1000。

adapty asa change-history get

显示某一实体在某一事务中的字段级变更详情。

adapty asa change-history get Campaign.444555666.TXN_ID --campaign-group <campaign-group-id>

参数	说明
detail-id	来自 change-history list 的 detail_id，格式为 EntityType.entityId.txnId

标志	是否必填	说明
--campaign-group	是	该变更所属的组织。从列表行中的 campaign_group_id 获取

响应中列出了每个变更字段的 old_values 和 new_values，以及 entity_metadata 中的实体元数据。如果 Apple 没有对应记录的 detail_id，则返回 404。

错误

状态码	代码	含义
402	ads_manager_subscription_required	该公司没有有效的 Ads Manager 订阅
403	cli_ad_account_unreadable	change-history 无法读取该组织：Apple Ads 令牌已被撤销、组织不再关联，或 Apple 拒绝了访问
404	—	该实体不存在，或属于其他公司
409	cli_idempotency_in_progress	使用相同幂等键的写入操作仍在运行中
422	cli_idempotency_key_reuse	相同的幂等键被用于不同的请求体
422	cli_metric_scope_too_wide	请求了用户画像计数类数据图表，但未指定 --campaign 或 --ad-group
422	cli_response_too_large	metrics 分页结果超过 5000 行明细数据
429	cli_analytics_busy	分析池繁忙，或该公司的另一个关键词池构建仍在运行中。等待时间见 Retry-After 响应头
429	cli_cooldown_active	过多的被拒请求导致令牌进入冷却期
429	cli_upstream_rate_limited	Apple 对 change-history 请求进行了限流。Apple 返回的等待时间见 Retry-After 响应头
504	cli_read_timeout	change-history 请求耗时超过 50 秒。请缩小时间范围或过滤条件

数据图表与搜索词列表共享同一个分析预算（每家公司）：每分钟 5 次调用，且任意 10 秒内不超过 2 次。change-history 有独立的预算：每分钟 30 次调用，任意 10 秒内不超过 5 次，且每家公司同一时间只能发起 1 个请求。若在 5 分钟内有 20 个请求被拒绝，将触发逐步升级的冷却机制：依次冷却 5 分钟、30 分钟、3 小时。在冷却期间重试不会延长冷却时间，但真正的解决办法是修正出错的请求，而不是反复重试。

CLI 会自动处理短暂的等待。当遇到非冷却期的 429 错误时，如果 Retry-After 不超过 60 秒，命令会等待相应时间后重试一次，并在标准错误输出中报告等待情况。