asc-apple-ads

asc Apple Ads

通过 asc ads 执行 Apple Ads 工作。Apple Ads 凭证与 App Store Connect 凭证分开；asc auth login 不会配置 Ads。

先选择 API

• 直接使用 asc ads <resource> ... 命令时，会调用 Apple Ads Platform API v1，并使用广告账户 ID。
• 已弃用的 Campaign Management API v5 命令位于 asc ads v5 ... 下，并使用组织 ID。Apple 将于 2027 年 1 月 26 日停用 v5。
• 切勿用组织 ID 替代广告账户 ID。CLI 会将二者分开处理。
• 创建请求文件前，先对准确的叶级命令运行 --help。Platform v1 与 v5 的负载和响应封装格式不同；CLI 不会进行转换。
• 在非交互式管道中，传入 --file -，从标准输入读取 JSON 请求正文；如果标准输入连接到终端，CLI 会拒绝此参数。
• 资源、报告、上传和原始命令会输出无损 JSON。请使用 jq 提取所需内容，而不是要求输出表格或 Markdown。

进行身份验证并固定账户

如果某个配置文件必须同时支持 v1 和旧版 v5，请存储这两种上下文：

asc ads auth login \
  --name "Marketing" \
  --client-id "$ASC_ADS_CLIENT_ID" \
  --team-id "$ASC_ADS_TEAM_ID" \
  --key-id "$ASC_ADS_KEY_ID" \
  --private-key "$ASC_ADS_PRIVATE_KEY_PATH" \
  --ad-account "987654" \
  --org "123456" \
  --network

对于 CI，请设置 Ads 专用变量，并绕过主机密钥链：

export ASC_ADS_CLIENT_ID="SEARCHADS_CLIENT_ID"
export ASC_ADS_TEAM_ID="SEARCHADS_TEAM_ID"
export ASC_ADS_KEY_ID="KEY_ID"
export ASC_ADS_PRIVATE_KEY_PATH="$HOME/.asc/apple-ads-private-key.pem"
export ASC_ADS_AD_ACCOUNT_ID="987654"
export ASC_ADS_BYPASS_KEYCHAIN=1

ASC_ADS_PRIVATE_KEY 和 ASC_ADS_PRIVATE_KEY_B64 也可用。如果另一个受信任进程已生成短时效令牌，请设置 ASC_ADS_ACCESS_TOKEN；作用域为 v1 的调用仍需要广告账户 ID。

检查身份验证状态，但不要打印令牌：

asc ads auth status --validate --output json
asc ads auth discover --ads-profile "Marketing" --output json
asc ads auth doctor --output json

发现操作会调用 Platform v1 的 GET /v1/me 和 GET /v1/acls。对照每个 ACL 的广告账户 ID、名称、组织 ID 和角色；切勿自动选择第一个结果。进行任何变更前，先打印选定的账户；如果有多个配置文件或账户可用，再同时传入 --ads-profile "Marketing" 和 --ad-account "987654"。

对于具名配置文件，该配置文件的 ad_account_id 和 org_id 独立生效；它们不会继承其他配置文件或根配置中的上下文。v1 上下文的优先级依次为 --ad-account、ASC_ADS_AD_ACCOUNT_ID、所选配置文件，然后是无配置文件时的根配置。旧版 v5 使用对应的 --org 和 ASC_ADS_ORG_ID 链。

从只读操作开始

身份和 ACL 调用不需要广告账户上下文：

asc ads me view --ads-profile "Marketing" --output json
asc ads acls list --ads-profile "Marketing" --output json
asc ads orgs view --ads-profile "Marketing" --org-id "123456" --output json

然后通过简单的 App 搜索确认选定账户：

asc ads apps search \
  --ads-profile "Marketing" \
  --ad-account "987654" \
  --query "Example" \
  --limit 1 \
  --output json

App 搜索至少需要 --query、--cpids 或 --return-owned-apps 中的一个。店面使用以逗号分隔的 ISO alpha-2 代码。只有在需要所有搜索结果时才添加 --paginate。

使用各资源的 find 命令查看清单。大多数 v1 查询会在 JSON 对象中设置筛选条件、排序和分页。下级资源筛选条件示例如下：

{
  "filters": [
    {"field": "campaignId", "operator": "EQUALS", "value": ["campaign-id"]}
  ],
  "pagination": {"offset": 0, "pageSize": 100, "fetchTotalCount": true}
}

asc ads campaigns find --ads-profile "Marketing" --ad-account "987654" --output json
asc ads ad-groups find --ads-profile "Marketing" --ad-account "987654" --file query.json --output json
asc ads ads find --ads-profile "Marketing" --ad-account "987654" --file query.json --output json

在 campaigns find 中省略 --file 会请求默认的第一页。要控制或获取全部结果，请在查询文件中使用 pagination.offset、pageSize 和 fetchTotalCount，读取响应中的分页信息，并逐步增加偏移量，直至获取完整结果。此命令没有 --paginate 标志。Platform 筛选条件使用单数形式的 value；不要照搬 v5 Selector 字段（如 conditions 或复数形式的 values），当前版本的 asc 会在身份验证前拒绝这些字段。

直接的 v1 命令树还涵盖广告账户和广告主资源；App 资格、地区设置、产品页面和拒绝原因；品牌、业务类别、地点、地点组、创意和素材；地理定位和共享预算；App 与品牌报告；洞察、建议、推荐和变更历史。请先查找准确的叶级命令，不要退回到原始 HTTP：

asc ads change-history --help
asc ads suggestions --help
asc ads rejection-reasons --help
asc ads reports brands --help

关键词查询需要选择器文件。定向关键词要求有 id、adGroupId 或 campaignId 筛选条件。否定关键词要求有 id 或 adGroupId 筛选条件；广告系列级否定关键词需要同时使用 campaignId 和 operator 为 IS_NULL 的 adGroupId 筛选条件。

asc ads targeting-keywords find --ads-profile "Marketing" --ad-account "987654" --file keyword-query.json --output json
asc ads negative-keywords find --ads-profile "Marketing" --ad-account "987654" --file negative-keyword-query.json --output json

报告与优化

V1 报告需要针对端点的请求体。日期位于 timeRange 下，分页控件使用 offset 和 pageSize，广告系列或广告组 ID 应放在 filters 中：

{
  "pagination": {"offset": 0, "pageSize": 20},
  "filters": [
    {"field": "campaignId", "operator": "EQUALS", "value": ["campaign-id"]}
  ],
  "groupBy": ["countryOrRegion"],
  "timeRange": {
    "start": "2026-08-01",
    "end": "2026-08-14",
    "timeZone": "ORTZ",
    "granularity": "DAILY"
  }
}

asc ads reports apps campaigns \
  --ads-profile "Marketing" \
  --ad-account "987654" \
  --file report.json \
  --output json

报告命令不接受 --paginate；请在请求体中更改分页设置。查看叶子命令的帮助信息，因为不同的报告实体接受不同的 groupBy 和选项值。

推荐和建议也使用针对端点的请求体。应用或忽略推荐可能会改变支出，因此需要 --confirm：

asc ads recommendations daily-budgets find --ads-profile "Marketing" --ad-account "987654" --file query.json
asc ads recommendations daily-budgets apply --ads-profile "Marketing" --ad-account "987654" --file recommendations.json --confirm

谨慎执行变更

在用户批准广告帐户、资源类型和目标 ID，并审核请求载荷之前，不要执行变更。将请求 JSON 保存在文件中；不要根据相关的 v5 架构臆造字段。

创建广告系列可能会开始产生支出。CampaignCreate 需要 adAccountId、billingEvent、dailyBudget、name、promotedObjectId、promotedObjectType 和 targeting。CLI 会原样发送文件：--ad-account 用于选择请求上下文，但不会将 adAccountId 注入 JSON。请从此暂停状态的格式开始，将每个占位符替换为从所选帐户读取的值，并再次检查当前 Apple v1 架构，确认是否有特定于帐户的要求：

{
  "name": "ASC agent validation 2026-08-15T00:00:00Z",
  "status": "PAUSED",
  "adAccountId": 987654,
  "promotedObjectType": "APPSTORE_APP",
  "promotedObjectId": "123456789",
  "billingEvent": "TAPS",
  "dailyBudget": {"value": {"amount": "1", "currency": "USD"}},
  "startTime": "2030-01-01T00:00:00.000",
  "endTime": "2030-01-02T00:00:00.000",
  "targeting": {"countryOrRegion": {"include": ["US"]}},
  "bidStrategy": {"bidStrategyType": "MANUAL_CPT", "bidStrategyGoal": "TAP"}
}

包含明确顶层 "status":"PAUSED" 的请求载荷无需 --confirm 即可运行；如果省略状态或状态不是暂停，则需要确认。

asc ads campaigns create --ads-profile "Marketing" --ad-account "987654" --file paused-campaign.json
asc ads campaigns pause --ads-profile "Marketing" --ad-account "987654" --campaign "campaign-id"
asc ads campaigns resume --ads-profile "Marketing" --ad-account "987654" --campaign "campaign-id" --confirm

如果广告系列更新可能更改预算、定向、出价、投放、日期或状态，则需要 --confirm。仅更新名称，或同时更新名称和 PAUSED 状态，则不需要确认。删除、批量创建或更新、应用或忽略推荐、预算订单写入，以及其他存在操作风险的变更，都需要在认证或访问网络之前确认。

创建广告组和批量写入关键词，都是始终需要确认的投放或定向变更示例。V1 批量关键词文件使用 KeywordCreateBulkRequest 等包装对象，而不是 v5 的原始数组格式：

asc ads ad-groups create --ads-profile "Marketing" --ad-account "987654" --file ad-group.json --confirm
asc ads targeting-keywords create-bulk --ads-profile "Marketing" --ad-account "987654" --file keywords.json --confirm
asc ads targeting-keywords delete --ads-profile "Marketing" --ad-account "987654" --keyword "keyword-id" --confirm

共享预算使用 budget-orders 命令组。创建、更新和删除操作不依赖上下文，但需要确认；查看和查找操作可选择提供广告帐户上下文。

asc ads budget-orders create --ads-profile "Marketing" --file shared-budget.json --confirm
asc ads budget-orders update --ads-profile "Marketing" --budget-order "budget-id" --file update.json --confirm
asc ads budget-orders delete --ads-profile "Marketing" --budget-order "budget-id" --confirm

创建广告帐户也需要 --confirm，因为帐户系列无法更改，而且 Apple 没有提供删除端点。包含 delegations 的广告帐户更新需要确认，因为它会替换整个列表。

品牌素材请使用专用的多部分命令。持续轮询，直到 Apple 完成处理：

asc ads assets upload --ads-profile "Marketing" --file ./brand.png --brand "BRAND_ID" --ad-account "987654"
asc ads assets view --ads-profile "Marketing" --asset "ASSET_UUID" --ad-account "987654"

仅当 eligibility.status 为 ELIGIBLE 时才使用素材；如果状态为 LIMITED，请检查 allowedGroups。不要附加状态为 PENDING 或 INELIGIBLE 的素材。

原始请求

日常操作请使用一等命令。原始 v1 请求仅接受 v1/... 路径或 https://api.ads.apple.com/v1/... URL：

asc ads api request \
  --method POST \
  --path v1/campaigns/query \
  --ads-profile "Marketing" \
  --ad-account "987654" \
  --file query.json \
  --output json

未知变更默认拒绝执行；已知的高风险变更需要 --confirm。原始命令会拒绝多部分素材上传；请使用 asc ads assets upload。

明确指定旧版调用：

asc ads v5 api request \
  --method POST \
  --path v5/campaigns/find \
  --ads-profile "Marketing" \
  --org "123456" \
  --file selector.json \
  --output json

一次迁移一个命令，从 v5 迁移

在每个脚本都有经过审核的 v1 请求体和响应解析器之前，请将现有 v5 请求载荷保留在 asc ads v5 下。常见迁移方式：

已弃用的 v5	Platform API v1
asc ads v5 campaigns list	asc ads campaigns find
asc ads v5 apps localized-details	asc ads apps locales find
asc ads v5 product-pages list	asc ads product-pages find
asc ads v5 reports campaigns	asc ads reports apps campaigns
asc ads v5 campaigns pause / resume	asc ads campaigns pause / resume
v5 广告系列或广告组否定关键词	asc ads negative-keywords ...，在请求体中指定范围

有 7 个 v5 叶子命令没有可通过单个 v1 命令替代的方案：商品页面国家/地区、商品页面设备、定向关键词批量删除、两个否定关键词批量删除命令，以及展示份额报告列表和查看命令。不要假定 geo search、insights impression-share 或单资源删除能够保留这些命令的契约。

干净地完成实时测试

• 从 ACL 发现和仅返回一个结果的应用搜索开始。
• 为一次性广告系列测试使用唯一的时间戳名称，并明确设置 PAUSED 状态。
• 保存 JSON 输出中的每个已创建 ID。
• 在检查其他内容之前，先暂停会产生费用的资源。
• 使用 asc ads campaigns view --ads-profile "Marketing" --ad-account "987654" --campaign "campaign-id" --output json 重新读取测试广告系列。
• 仅删除测试创建的广告系列：asc ads campaigns delete --ads-profile "Marketing" --ad-account "987654" --campaign "campaign-id" --confirm；不要删除预先存在的父级广告系列。
• 再次运行相同的 campaigns view。将 Apple 返回的未找到响应视为清理成功的证明；报告任何仍然存在或无法删除的广告系列。