asc-apple-ads

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

asc Apple Ads

Use this skill when a task involves Apple Ads or

asc ads

当任务涉及Apple Ads或

asc ads

时使用此技能。

Ground Rules

基本规则

Run
```
asc ads --help
```
or the specific subgroup help before scripting a command.
Apple Ads auth is separate from App Store Connect auth.
```
asc auth login
```
does not configure
```
asc ads
```
.
Use JSON output for automation:
```
--output json
```
.
Most commands need an org ID. Prefer
```
--org
```
for one-off commands and
```
ASC_ADS_ORG_ID
```
for a scoped session.
Never guess payload fields. Use Apple Ads request JSON in a file and pass it with
```
--file
```
.
Do not mutate a live account until the user has named the org and approved the resource type. Prefer read-only checks first.

在编写命令脚本前，运行
```
asc ads --help
```
或特定子组的帮助命令。
Apple Ads认证与App Store Connect认证是相互独立的。
```
asc auth login
```
不会配置
```
asc ads
```
。
自动化场景下使用JSON输出：
```
--output json
```
。
大多数命令需要组织ID。一次性命令优先使用
```
--org
```
参数，限定范围的会话优先使用环境变量
```
ASC_ADS_ORG_ID
```
。
切勿猜测请求体字段。使用文件中的Apple Ads请求JSON，并通过
```
--file
```
参数传入。
在用户指定组织并确认资源类型之前，不要修改正式账户。优先执行只读检查。

Auth

认证

Stored profile:

bash

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" \
  --org "$ASC_ADS_ORG_ID" \
  --network

Environment auth:

bash

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_ORG_ID="123456"

Short-lived token auth:

bash

export ASC_ADS_ACCESS_TOKEN="ACCESS_TOKEN"
export ASC_ADS_ORG_ID="123456"

Useful checks:

bash

asc ads auth status --validate --output json
asc ads auth doctor --output json
asc ads me view --output json
asc ads acls --output json

存储配置文件：

bash

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" \
  --org "$ASC_ADS_ORG_ID" \
  --network

环境变量认证：

bash

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_ORG_ID="123456"

短期令牌认证：

bash

export ASC_ADS_ACCESS_TOKEN="ACCESS_TOKEN"
export ASC_ADS_ORG_ID="123456"

实用检查命令：

bash

asc ads auth status --validate --output json
asc ads auth doctor --output json
asc ads me view --output json
asc ads acls --output json

Org Resolution

组织ID解析

When the org ID is unknown:

bash

asc ads acls --output json

Use the returned org ID:

bash

asc ads campaigns --org "123456" --limit 10 --output json

Org precedence is

--org

ASC_ADS_ORG_ID

, stored profile

org_id

, then config

ads.org_id

当组织ID未知时：

bash

asc ads acls --output json

使用返回的组织ID：

bash

asc ads campaigns --org "123456" --limit 10 --output json

组织ID的优先级为：

--org

参数 > 环境变量

ASC_ADS_ORG_ID

> 存储配置文件中的

org_id

> 配置文件中的

ads.org_id

。

Read Workflows

只读工作流

Campaigns and ad groups:

bash

asc ads campaigns --org "123456" --limit 100 --output json
asc ads campaigns --org "123456" --paginate --output json
asc ads campaigns view --org "123456" --campaign 987654321 --output json
asc ads ad-groups list --org "123456" --campaign 987654321 --output json

Discovery:

bash

asc ads apps search --org "123456" --query "My App" --limit 10 --output json
asc ads product-pages list --org "123456" --adam-id 1234567890 --states VISIBLE --output json
asc ads creatives list --org "123456" --limit 100 --output json
asc ads geo search --org "123456" --query "San Francisco" --country-code US --limit 10 --output json

Reports:

bash

asc ads reports campaigns --org "123456" --file reporting-request.json --output json
asc ads reports keywords --org "123456" --campaign 987654321 --file reporting-request.json --output json

Reporting and find endpoints keep pagination in the JSON body.

广告系列与广告组：

bash

asc ads campaigns --org "123456" --limit 100 --output json
asc ads campaigns --org "123456" --paginate --output json
asc ads campaigns view --org "123456" --campaign 987654321 --output json
asc ads ad-groups list --org "123456" --campaign 987654321 --output json

资源发现：

bash

asc ads apps search --org "123456" --query "My App" --limit 10 --output json
asc ads product-pages list --org "123456" --adam-id 1234567890 --states VISIBLE --output json
asc ads creatives list --org "123456" --limit 100 --output json
asc ads geo search --org "123456" --query "San Francisco" --country-code US --limit 10 --output json

报告：

bash

asc ads reports campaigns --org "123456" --file reporting-request.json --output json
asc ads reports keywords --org "123456" --campaign 987654321 --file reporting-request.json --output json

报告和查询接口的分页信息会保留在JSON响应体中。

Mutating Workflows

修改类工作流

Create and update commands take Apple Ads JSON files:

bash

asc ads campaigns create --org "123456" --file campaign.json --output json
asc ads campaigns update --org "123456" --campaign 987654321 --file campaign-update.json --output json
asc ads ad-groups create --org "123456" --campaign 987654321 --file ad-group.json --output json

Bulk endpoints often require arrays:

bash

asc ads targeting-keywords create-bulk \
  --org "123456" \
  --campaign 987654321 \
  --ad-group 123456789 \
  --file keywords.json \
  --output json

Delete commands require

--confirm

bash

asc ads targeting-keywords delete-bulk \
  --org "123456" \
  --campaign 987654321 \
  --ad-group 123456789 \
  --file keyword-ids.json \
  --confirm \
  --output json

asc ads campaigns delete --org "123456" --campaign 987654321 --confirm

For live tests, create paused resources with names such as

ASC CLI Live Test <timestamp>

. Clean up only the parent campaign or ad group created for that test. Apple may reject direct deletion for default product page creative ads, but deleting the test parent campaign or ad group can clean up the test resource.

创建和更新命令需要传入Apple Ads JSON文件：

bash

asc ads campaigns create --org "123456" --file campaign.json --output json
asc ads campaigns update --org "123456" --campaign 987654321 --file campaign-update.json --output json
asc ads ad-groups create --org "123456" --campaign 987654321 --file ad-group.json --output json

批量接口通常需要传入数组：

bash

asc ads targeting-keywords create-bulk \
  --org "123456" \
  --campaign 987654321 \
  --ad-group 123456789 \
  --file keywords.json \
  --output json

删除命令需要

--confirm

参数：

bash

asc ads targeting-keywords delete-bulk \
  --org "123456" \
  --campaign 987654321 \
  --ad-group 123456789 \
  --file keyword-ids.json \
  --confirm \
  --output json

asc ads campaigns delete --org "123456" --campaign 987654321 --confirm

进行实时测试时，创建名称类似

ASC CLI Live Test <timestamp>

的暂停状态资源。仅清理为该测试创建的父广告系列或广告组。对于默认产品页面创意广告，Apple可能会拒绝直接删除，但删除测试用的父广告系列或广告组可以清理测试资源。

Raw API

原始API

Use raw requests when Apple adds a field before the first-class command surface changes:

bash

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

Raw requests accept only Apple Ads v5 paths or

https://api.searchads.apple.com/api/v5/...

URLs.

DELETE

still requires

--confirm

当Apple在正式命令支持之前新增字段时，可以使用原始请求：

bash

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

原始请求仅支持Apple Ads v5路径或

https://api.searchads.apple.com/api/v5/...

格式的URL。

DELETE

请求仍需要

--confirm

参数。

Live Test Checklist

实时测试检查清单

Start with

asc ads me view --output json

and

asc ads acls --output json

Print the target org ID before mutations.
Create paused or future-dated resources.
Use a unique test name.
Save created IDs from JSON output.
Delete only the test parent campaign or ad group created during the run.
Run a final campaigns find/list query to confirm cleanup.

先运行

asc ads me view --output json

和

asc ads acls --output json

。

在执行修改操作前，打印目标组织ID。
创建暂停状态或未来生效的资源。
使用唯一的测试名称。
从JSON输出中保存创建的资源ID。
仅删除本次运行中创建的测试用父广告系列或广告组。
最后运行广告系列查询/列表命令，确认清理完成。