meta-ads-control

Meta Ads Control

Meta Marketing API を使用する際に、このスキルを使います。構造化された JSON 出力、ドライランによる保護、再試行、ページネーション、バッチ処理、非同期 Insights ジョブ、ターゲティング検索、アセットのアップロードに対応しているため、同梱スクリプトの使用を推奨します。

広告費や配信に手を加える前に

1. 対象範囲を確認します。

   python3 scripts/meta_ads.py accounts
   python3 scripts/meta_ads.py account
   

2. 対象の広告アカウント、通貨、タイムゾーン、書き込み可能なオブジェクトを確認します。
3. 広告費の発生、配信の変更、またはトラッキングの変更につながる操作では、次の手順に従います。
   • 簡潔な計画を用意します。
   • --dry-run を実行します。
   • 変更するオブジェクトとフィールドを正確に提示します。
   • ユーザーから明示的な承認を得ます。
   • その後、--confirm を付けて再実行します。
4. ユーザーがすぐに配信を開始するよう明示的に依頼した場合を除き、新しいキャンペーン、広告セット、広告のステータスは PAUSED にします。
5. 書き込み操作の後は、get、list、または request GET で読み取り直し、変更を検証します。

認証と環境

スクリプトは次の値を読み取ります。

• META_ACCESS_TOKEN — ライブ API 呼び出しに必須
• META_AD_ACCOUNT_ID — 省略可能なデフォルトアカウント。act_ の有無は問いません
• META_API_VERSION — デフォルトは v25.0
• META_GRAPH_BASE — デフォルトは https://graph.facebook.com

META_ACCESS_TOKEN が設定されていない場合は、推測したり API の応答を捏造したりせず、まずユーザーが設定できるよう支援します。

OpenClaw ユーザーは、スキル設定からこれらの値を注入できます。OpenClaw の注意事項を参照してください。

タスク別のクイックガイド

1) アカウントの監査または診断

質問への回答に必要な最小限の読み取りから始めます。

python3 scripts/meta_ads.py account --fields id,name,account_status,currency,timezone_name,amount_spent,spend_cap
python3 scripts/meta_ads.py list campaigns --fields id,name,objective,status,effective_status,daily_budget,lifetime_budget
python3 scripts/meta_ads.py list adsets --fields id,name,campaign_id,status,effective_status,daily_budget,lifetime_budget,optimization_goal,bid_strategy
python3 scripts/meta_ads.py list ads --fields id,name,adset_id,campaign_id,status,effective_status,creative

複数の小規模な読み取りを一度に行う必要がある場合は、batch を使います。まず最小限のフィールドセットを使います。

2) パフォーマンスレポート

insights を使います。対象レベルと期間を絞って開始します。対象期間が長い場合や、フィールド数が多い場合、または内訳を使う場合は、--async を使います。

python3 scripts/meta_ads.py insights act_123 --level campaign --date-preset last_7d
python3 scripts/meta_ads.py insights act_123 --level ad --fields ad_id,ad_name,spend,impressions,clicks,ctr,cpc,actions,action_values,purchase_roas --date-preset last_30d --async --fetch-all

ユーザーがコンバージョンまたは ROAS を求めている場合は、actions と action_values を含めます。ユーザーがデモグラフィック別または配置別の内訳を求めている場合は、--breakdowns を使います。アクションレベルの内訳を求めている場合は、actions を含めて --action-breakdowns を使います。

3) オブジェクトの一時停止、再開、またはアーカイブ

単一オブジェクトの変更には、set-status を優先して使います。

python3 scripts/meta_ads.py set-status 120000000000000 PAUSED --dry-run
python3 scripts/meta_ads.py set-status 120000000000000 PAUSED --confirm

一括操作では、JSON バッチファイルを作成し、承認を得てから batch を使います。

4) キャンペーン構成の作成または更新

次の順序で作成します。

1. キャンペーン
2. 広告セット
3. クリエイティブ
4. 広告

ネストされたパラメーターには、JSON ペイロードファイルを使います。assets/ のテンプレートから始めてください。

python3 scripts/meta_ads.py create campaign --params-file assets/campaign-create.json --dry-run
python3 scripts/meta_ads.py create campaign --params-file work/campaign.json --confirm

python3 scripts/meta_ads.py create adset --params-file work/adset.json --dry-run
python3 scripts/meta_ads.py create adset --params-file work/adset.json --confirm

python3 scripts/meta_ads.py create adcreative --params-file work/adcreative.json --dry-run
python3 scripts/meta_ads.py create adcreative --params-file work/adcreative.json --confirm

python3 scripts/meta_ads.py create ad --params-file work/ad.json --dry-run
python3 scripts/meta_ads.py create ad --params-file work/ad.json --confirm

アセットがローカルファイルの場合は、先に upload でアップロードします。

5) ターゲティングの確認

ターゲティング ID を決して推測しないでください。まずターゲティング検索で解決します。

python3 scripts/meta_ads.py targeting-search --type adinterest --q "running"
python3 scripts/meta_ads.py targeting-search --type adgeolocation --q "Munich"

次に、返された ID と記述子を広告セットの targeting 仕様に指定します。

6) 未対応またはニッチなエンドポイント

低レベルの request サブコマンドを使います。

python3 scripts/meta_ads.py request GET /act_123/reachestimate --set targeting_spec=@work/targeting.json
python3 scripts/meta_ads.py request GET /120000000000000/previews --set ad_format=DESKTOP_FEED_STANDARD

ネストされた値には、多数のインライン --set を使うより、--params-file または @file.json の値を優先します。

スクリプトリファレンス

メインエントリーポイント

python3 scripts/meta_ads.py --help

特に便利なサブコマンド

• accounts — トークンからアクセス可能な広告アカウントを一覧表示します
• account — デフォルトまたは指定したアカウントを読み取ります
• list — キャンペーン、adset、広告、クリエイティブ、オーディエンス、アセット、ピクセルなどを一覧表示します
• get — ノードまたはノードエッジを読み取ります
• create — キャンペーン、adset、adcreative、広告、customaudience、またはサポートされている任意のアカウントエッジを作成します
• update — ID を指定してノードを更新します
• set-status — status の便利なラッパーです
• insights — 同期または非同期のレポートを実行します
• targeting-search — ターゲティング記述子を解決します
• upload — adimages または advideos にアップロードします
• batch — Graph のバッチリクエストを送信します
• request — 任意の Graph パスに使える低レベルの汎用コマンドです

優れたエージェントの動作ルール

• 書き込む前に読み取ります。
• 質問に答えるために必要な最小限のフィールドセットを使用します。
• ネストされたデータには、JSON ペイロードファイルを優先します。
• ユーザーがすべてのページを本当に必要としている場合にのみ、--fetch-all を使用します。
• Insights の負荷の高いジョブには、--async を使用します。
• 613 または 80004 のレート制限エラーが繰り返し発生した場合は一時停止し、対象範囲を縮小するか、再試行までの時間を延ばします。
• 破壊的な削除操作より、PAUSED または ARCHIVED を優先します。
• 金額が関係する場合は、生の API 単位と人間が読みやすい単位の両方で報告します。予算は通常、通貨の最小単位で指定します。
• 予算を書き込む前に、アカウントの通貨とタイムゾーンを確認します。
• 変更を行った後は、必ず追加の読み取りで現在の状態を確認します。
• リクエストが住宅、雇用、信用、社会問題、選挙、政治に関わる場合は、作業を進める前にAPI ガイドで特別カテゴリに関する注意事項を確認します。

例

直近 7 日間のアカウント概要

python3 scripts/meta_ads.py batch --batch-file assets/batch-read-example.json
python3 scripts/meta_ads.py insights act_123 --level campaign --date-preset last_7d --fields campaign_id,campaign_name,spend,impressions,clicks,ctr,cpc,actions,action_values,purchase_roas

予算を安全に増やす

1. 現在の広告セットを確認します。
2. 新しい予算を指定した更新ペイロードを準備します。
3. ドライランを実行します。
4. 確認を求めます。
5. 適用して確認します。

python3 scripts/meta_ads.py get 120000000000000 --fields id,name,status,effective_status,daily_budget,lifetime_budget
python3 scripts/meta_ads.py update 120000000000000 --params-file work/adset-budget.json --dry-run
python3 scripts/meta_ads.py update 120000000000000 --params-file work/adset-budget.json --confirm
python3 scripts/meta_ads.py get 120000000000000 --fields id,name,daily_budget,lifetime_budget,updated_time

画像をアップロードしてリンク広告を作成する

python3 scripts/meta_ads.py upload adimages --file creative.jpg --confirm
# Put the returned image_hash into work/adcreative.json
python3 scripts/meta_ads.py create adcreative --params-file work/adcreative.json --confirm
python3 scripts/meta_ads.py create ad --params-file work/ad.json --confirm

参考資料

• API ガイド
• フィールドセットとレポートのデフォルト設定
• ワークフローガイド
• トラブルシューティング
• OpenClaw のメモ
• assets/ 内のアセットテンプレート
• evals/evals.json 内の評価例