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 はこれを拒否します。
• リソース、レポート、アップロード、raw コマンドは情報を損なわない JSON を出力します。テーブル形式や Markdown 形式を求める代わりに、jq で必要な項目を抽出してください。

認証してアカウントを固定する

プロファイルで 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 の順序になります。

読み取り専用から始める

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

次に、簡単なアプリ検索で選択したアカウントを確認します。

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

アプリ検索には、--query、--cpids、--return-owned-apps のうち少なくとも 1 つが必要です。ストアフロントには、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 を使用します。現在の asc は認証前に拒否するため、v5 の Selector フィールドである conditions や複数形の values を流用しないでください。

直接の v1 ツリーには、広告アカウントと広告主リソースのほか、アプリの適格性、ロケール、プロダクトページ、却下理由、ブランド、ビジネスカテゴリ、所在地、ロケーショングループ、クリエイティブ、アセット、地域ターゲティング、共有予算、アプリとブランドのレポート、インサイト、提案、レコメンデーション、変更履歴も含まれます。raw 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 と、演算子が 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 や広告グループ 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 はリクエストのコンテキストを選択するもので、JSON に adAccountId を追加するものではありません。この一時停止状態の形式をベースにし、選択したアカウントから読み取った値ですべてのプレースホルダーを置き換え、アカウント固有の要件がないか、現在の 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 なしで実行できます。status が省略されている場合、または一時停止以外のステータスの場合は、--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 の一括キーワードファイルでは、v5 の生配列形式ではなく、KeywordCreateBulkRequest などのラッパーオブジェクトを使用します：

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 から一度に 1 コマンドずつ移行する

既存の v5 ペイロードは、各スクリプトにレビュー済みの v1 ボディとレスポンスパーサーを用意するまで、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 ...

v5 の 7 つのリーフコマンドには、1 つのコマンドで置き換えられる v1 のコマンドがありません。該当するのは、プロダクトページの国、プロダクトページのデバイス、ターゲティングキーワードの一括削除、2 種類の除外キーワードの一括削除、インプレッションシェアレポートの一覧表示と表示です。geo search、insights impression-share、単一リソースの削除が、これらの契約を維持するとみなさないでください。

ライブテストを適切に完了する

• まず ACL の検出を行い、アプリを 1 件だけ検索します。
• 破棄可能なキャンペーンのテストには、一意のタイムスタンプ付きの名前と明示的な PAUSED ステータスを使用します。
• 作成したすべての ID を JSON 出力から保存します。
• 支出を伴うリソースは、ほかの項目を確認する前に一時停止します。
• 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 の「見つかりません」という応答をクリーンアップ完了の証拠として扱い、まだ存在する、または削除できなかったキャンペーンがあれば報告します。