English 中文TürkçeРусскийFrançaisTiếng ViệtEspañol日本語

CLIからAds Managerを管理する

Adapty CLIでは、adapty asaトピックの下で、ターミナルからAds Managerアカウントを管理できます。キャンペーン、広告グループ、キーワード、広告、プロダクトページ、自動化ルール、指標、競合調査などに対応しています。

ブラウザでは時間がかかる作業に活用しましょう。たとえば、AIエージェントに広告パフォーマンスへのライブアクセスを提供したり、ファイルから数百件のキーワードを追加したり、複数のキャンペーンに同じ設定を適用したりする場合です。それ以外の作業は、ダッシュボードの方が速いです。

Warning

CLIでは削除操作はできません。キャンペーン、広告、自動化ルールはターミナルから作成・更新・一時停止できますが、削除はダッシュボードからのみ可能です。

始める前に

Ads Manager のコマンドは、CLI の他の機能と同じインストール・ログイン手順を使用します。まだ設定していない場合は、クイックスタートガイドのステップ 1 と 2 を参照してください。

前提条件

すべての adapty asa コマンドには、さらに次の2つの条件が必要です：

  • Apple Ads アカウントの接続: adapty asa connect を使うか、Adapty Ads Manager を始めるで説明されているダッシュボードから接続してください。
  • 有効な Ads Manager サブスクリプション: これがない場合、すべてのコマンドが 402 ads_manager_subscription_required で失敗します。

次のコマンドで両方を確認できます：

adapty asa whoami

CLIの他の部分との違い

  • --app フラグはありません: スコープはトークンが属する会社です。--app は一部の list コマンドにフィルターとしてのみ存在します。
  • 書き込みはAppleに直接届きます: アカウントを変更するコマンドはリクエスト本文を表示し、送信前に確認を求めます。ステージング手順はありません。
  • 読み取りは低コスト、書き込みは高コスト: list コマンドと --dry-run は自由に使用できます。それ以外はすべて不可逆的なものとして扱ってください。

確認プロンプトをスクリプト内でスキップするには、--yes を渡してください。--json モードまたはパイプ経由では、書き込みコマンドは応答を無限に待つ代わりに拒否するため、--yes が必要です。

必要なIDを確認する

各コマンドはUUIDを必要とし、すべてのUUIDはlistコマンドから取得します。階層に沿って順番に実行してください。

adapty asa orgs list
adapty asa campaigns list --campaign-group <campaign-group-id>
adapty asa ad-groups list --campaign <campaign-id>

各読み取りにはフィルターを指定してスコープを絞ってください。フィルターは表示されるページではなくクエリ自体を絞り込むため、スコープを指定した読み取りはコストが低く、指定しない場合はアカウント全体をページングします。--ad-groupを指定しないadapty asa keywords listは、このトピックの中で最も広範な読み取りです。

これらのリストはメタデータのみを返します。パフォーマンスの数値は asa metrics から取得できます。

キーワードを一括追加する

キーワードを1件ずつ追加するのは、ダッシュボードを離れる主な理由です。テキストファイルに1行1キーワードで記述してください：

adapty asa keywords add --ad-group <ad-group-id> --from-file keywords.txt --bid 1.20 --match-type EXACT

キーワードは1回の呼び出しにつき最大100件のバッチとして適用されます。リストがそれ以上の場合は、複数回に分けて呼び出してください。

失敗には2種類あり、挙動が異なります。IDが無効な場合はAppleへのリクエスト前にバッチ全体が失敗し、何も適用されません。Appleが個々のキーワードを拒否した場合は、残りは追加され、各拒否の理由が報告されます。終了コードだけでなく、サマリー行を必ず確認してください。

まず少数のキーワードで試し、結果を確認してからファイル全体を送信してください。

MAX_CONVERSIONSキャンペーンを作成する

MAX_CONVERSIONSで入札するキャンペーンは、自動化された広告グループを所有して初めて配信されるため、両方を一緒に作成します：

adapty asa campaigns create --org <campaign-group-id> --name "Max Conv" --adam-id 123456 --country US --daily-budget 50 --bidding-strategy MAX_CONVERSIONS
adapty asa ad-groups create --campaign <campaign-id> --name "Automated Max Conv" --automated

そのアドグループが作成されるまで、キャンペーンは serving_status: NOT_RUNNING を報告し、serving_state_reasons に AUTOMATED_KEYWORDS_REQUIRED_AD_GROUP_MISSING が含まれます。また、campaigns create はその理由と解決するためのコマンドの両方を出力します。

要件を満たすのは --automated です。--automated-keywords を指定した通常のアドグループでは条件を満たしません。Apple が自動アドグループのスケジュールと運用を行うため、--start-time は不要で、--default-bid は任意項目です。またアドグループは有効な状態を維持します。支出を止めるには、キャンペーンを一時停止してください。

キャンペーンでは、--target-cpa を --daily-budget より低く設定してください。

クレジットライン請求の請求書オプションを設定する

Apple は、クレジットライン（line of credit）で請求する組織のすべてのキャンペーンに請求書オプションを必須としています。adapty asa orgs list は各組織の payment_model を表示し、LOC の場合は 5 つの --invoice-* フラグが適用されます。

adapty asa campaigns create --org <campaign-group-id> --name "LOC push" --adam-id 123456 --country US --daily-budget 50 --invoice-advertiser "Acme Inc" --invoice-order-number PO-42 --invoice-contact-name "Jane Doe" --invoice-contact-email jane@acme.com --invoice-billing-email billing@acme.com

5つすべてを1回の呼び出しで渡してください。一部のみを渡した場合、リクエストはAppleに届く前に拒否されます。これらがないと、キャンペーンは作成されますが、MISSING_BO_OR_INVOICING_FIELDS とともに serving_status: NOT_RUNNING が返されます。

同じ5つのフラグを adapty asa campaigns update で使用すると、既存のキャンペーンの請求オプションを設定できます。これらは保存済みのセットをまるごと置き換えるため、1つだけ変更する場合でも5つすべてを渡してください。

1回の操作でキャンペーン構造を作成する

campaigns bulk-create は、campaigns create と ad-groups create をループするスクリプトを置き換えるコマンドです。キャンペーン、広告グループ、キーワード、除外キーワード、広告を含むキャンペーン構造全体を1回の操作で送信できます：

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

入力はJSON形式で構造を記述します — フィールドの詳細は構造フォーマットを参照してください。JSONはAIエージェントにとって最適な形式です。AIが構造を生成してパイプで渡せます：

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

ネイティブの Apple Ads バルクテンプレート も入力として使用できます — サーバーが Campaign_And_Adgroup_Template.xlsx または キーワード .csv を構造に変換します。--org-id には adapty asa orgs list から取得した数値の org_id を指定します。作成前に変換内容を確認したい場合は --preview を追加します:

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

変換の問題はシート、行、列とともに報告されます。出力された構造が正しければ、--preview を外して送信してください。

--preview の出力は、開始用の構造ファイルを素早く入手する方法でもあります。出力を保存して編集し、--file で送信してください — automations get がルールテンプレートを提供するのと同じ方法です。

構造全体が作成前に検証され、拒否された場合はすべての無効なノードが一覧表示されます。受け入れられると、オブジェクトがサーバー上に作成され、コマンドが進捗状況を報告します。最終レポートは success、partial、または failed のいずれかです。partial の結果には、作成されなかった各オブジェクトと Apple のエラーが一覧表示されます。

大規模な構造の場合は、--no-wait を渡すことで操作IDをすぐに取得し、後で進捗状況を確認できます：

adapty asa campaigns bulk-status <operation-id>

エージェントやスクリプトから指標を取得する

asa metrics は、アカウントの任意のレベルで日付範囲を指定して指標をレポートします。AIエージェントやスクリプトで結果を直接利用するには、--json を追加してください：

adapty asa metrics --entity campaign --date-from 2026-07-01 --date-to 2026-07-31 --metric spend --metric roas --json

--metric には、Ads Manager が追跡する指標名を指定します。全一覧は指標を参照してください。

コホート指標は他の指標とは動作が異なります。ltv 指標は存在しません。ライフタイムバリューは日付ではなくリニューアルウィンドウで読み取られるためです。代わりにウィンドウを指定してください：

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

これにより、day-90 ROAS 順にランク付けされたキャンペーンが返されます。1 回の呼び出しで最大 16 個のウィンドウを指定できます。

各行は 1 つのエンティティを表し、サーバー側で集計・ソート済みです。「支出上位 5 件のキャンペーン」を調べる場合も、全ページをスキャンする必要はなく、1 回の呼び出しで完結します：

adapty asa metrics --entity campaign --date-from 2026-07-01 --date-to 2026-07-31 --order-by spend --page-size 5

指標と検索語リストは、1社あたり1つのアナリティクス予算を共有します：1分間に5回、10秒以内に最大2回のコール制限があります。ポーリングせず、必要な質問を1回で絞り込みましょう。レポート期間もグループ化の粒度によって上限が決まります — 日次で90日、週次で180日、月次で365日 — レポートの期間を広げるには、複数のコールに分割するのではなく、--group-by を粗く設定してください。

競合アプリのキーワードを確認する

1回のコマンドで、App Storeの最大5つのアプリが入札しているキーワードを取得できます：

adapty asa competitors summary --app-ids 1668337467,6503873027 --json

期間と対象国はサーバー側で固定されており（直近の完全な月、全国対象）、フラグはアプリIDのみです。アプリのセットに対する初回の呼び出しは、数十秒かかる場合があります。

スケジュールに従って競合他社のキーワードデータをレポートに取り込む際に使用します。結果をフィルタリングしたり、国ごとに比較したり、見つかったキーワードをキャンペーンに直接追加したりするには、ダッシュボードの Market Intelligence を使用してください。

自動化ルールを実行する

CLI は自動化ルールをビルドしません — 渡した JSON をそのまま保存します。有効なルールファイルを最短で取得するには、ダッシュボードでルールを 1 つ作成してから読み返します:

adapty asa automations get <automation-id> --json > rule.json

そのファイルを編集して、新しいルールのテンプレートとして使用します:

adapty asa automations create --file rule.json

automations update にファイルを渡す場合は、事前に internal_id フィールドを削除してください — このフィールドが含まれていると更新が拒否されます。

ルールを適用する前にテストする:

adapty asa automations run <automation-id> --dry-run

ドライランは条件を評価し、Apple Ads に触れることなくルールが何をするかをログに記録します。実行はすぐに実行されるのではなくキューに追加されるため、コマンドは実行 ID を表示し、結果は adapty asa automations runs に表示されます。

スクリプトを安全に再実行する

すべての書き込みにはべき等性キーが付与されます。CLIは呼び出しごとにキーを生成し、ネットワークエラー後に1回リトライするため、途中で失敗したリクエストが二重に適用されることはありません。

スクリプトでは、パイプライン全体を再実行できるよう、キーを自分で固定してください:

adapty asa campaigns create --org <campaign-group-id> --name "Winter push" --adam-id 123456 --country US --daily-budget 50 --idempotency-key winter-push-2026 --yes

Re-running the same command within 24 hours returns the stored result and prints Already applied earlier instead of creating a second campaign. The same key with a different body fails with 422, which catches an edited script that reuses a key by mistake.

次のステップ