Google Ads CLI スキル (google-ads-cli)

このスキルは、オートメーションとエージェント パイプラインで google-ads-cli を確実に操作するようにエージェントを訓練します。

1) ツールの識別

• パッケージ: google-ads-cli
• バイナリ: google-ads-cli
• ローカル開発エントリ: npm run dev -- <command>

2) 機能

CLI は以下をサポートしています:

• セットアップと認証情報/プロファイル管理
• OAuth 認証
• アカウント一覧表示
• キャンペーンと広告グループの検査
• キーワード プランナー アイデア生成
• 地域ターゲット ロケーション検索
• GAQL クエリ実行

3) 前提条件と準備状態の確認

プリフライト チェック:

1. Node >= 18
2. セットアップ完了 (setup)
3. 認証済みプロファイル (auth)
4. 必要なアカウント コンテキストが存在する (顧客 ID/ログイン顧客 ID)

準備状態確認コマンド:

google-ads-cli --version
google-ads-cli --help
google-ads-cli config
google-ads-cli profiles --list

4) 初回ワークフロー

4.1 セットアップ

google-ads-cli setup

以下を入力します:

• OAuth クライアント ID
• OAuth クライアント シークレット
• デベロッパー トークン
• 顧客 ID (ハイフンなし)
• MCC 使用の場合はオプションのログイン顧客 ID

4.2 認証

google-ads-cli auth

必要に応じてプロファイル固有の認証を使用します:

google-ads-cli auth --profile my-profile

4.3 アクセスの確認

google-ads-cli accounts
google-ads-cli campaigns --limit 5

5) エージェント向けコマンド リファレンス

認証/設定:

• setup
• auth
• logout
• profiles --list
• profiles --switch
• config

アカウント:

• accounts [--json]

キャンペーン/広告グループ:

• campaigns [-l <limit>] [--json]
• campaign <id> [--json]
• ad-groups -c <campaign-id> [-l <limit>] [--json]

キーワード計画:

• keyword-ideas [keywords...] [--url <url>] [--language <code>] [--location <codes...>] [--limit <n>] [--json]
• locations <search> [-l <limit>] [--json]

レポート:

• query <gaql> [-f <file>] [--json]

プロファイル スコープは、ほとんどのコマンドで -p, --profile を介して利用できます。

6) 高信頼度オートメーション実行本

6.1 キャンペーン スナップショット

google-ads-cli campaigns --limit 25 --json

6.2 キャンペーンを詳細表示してから広告グループを表示

google-ads-cli campaign 1234567890 --json
google-ads-cli ad-groups --campaign-id 1234567890 --limit 50 --json

6.3 キーワード アイデア パイプライン

google-ads-cli keyword-ideas "seo tools" "content marketing" --location 2840 --limit 100 --json

6.4 GAQL レポート

google-ads-cli query "SELECT campaign.id, campaign.name, metrics.clicks FROM campaign WHERE segments.date DURING LAST_30_DAYS LIMIT 50" --json

またはファイルから:

google-ads-cli query "" --file ./report.gaql --json

7) エージェント運用標準

1. マシン解析と決定論的な出力のために --json を優先します。
2. 費用のかかるクエリの前に認証を検証します。
3. マルチ アカウント環境ではプロファイル/アカウント コンテキストを明示的に保ちます。
4. 必須オプション (--campaign-id、GAQL 文字列/ファイル) を検証します。
5. 変更の仮定は避けます: このCLI は主に読み取り/レポート指向です。

8) 構造化出力ガイダンス

エージェント パイプラインの場合、以下をキャプチャします:

• コマンド
• 使用されたプロファイル
• 顧客コンテキスト
• 結果数
• 返されたキー ID
• 修復方法を含むエラー

テーブルを解析する場合、テーブル出力をスクレイピングするのではなく、--json を指定して再実行することを優先します。

9) 失敗処理パターン

認証されていない

google-ads-cli auth

認証情報/プロファイルが見つからない

google-ads-cli setup
google-ads-cli profiles --list

デベロッパー トークンの制限

トークンがテスト モードの場合、操作を所有/管理アカウントに制限し、制限を報告します。

顧客/アカウントの不一致

セットアップを再実行するか、目的のプロファイルを使用します:

google-ads-cli config --profile my-profile

OAuth コールバックの問題 (ポート競合)

ローカル プロセスの競合を確認して、認証フローを再試行します。

10) マルチプロファイルのベストプラクティス

• クライアント/アカウント境界ごとに 1 つのプロファイル。
• オートメーション ジョブで明示的な --profile を使用します。
• 実行前にアクティブなプロファイルを検証します (config、profiles --list)。

11) 最小限のエージェント コマンド パック

読み取り専用ヘルスチェック:

google-ads-cli config
google-ads-cli accounts --json
google-ads-cli campaigns --limit 5 --json

キーワード リサーチ パック:

google-ads-cli locations "United States" --json
google-ads-cli keyword-ideas "b2b saas crm" --location 2840 --limit 75 --json

GAQL レポート パック:

google-ads-cli query "SELECT campaign.id, campaign.name, metrics.impressions, metrics.clicks FROM campaign WHERE segments.date DURING LAST_7_DAYS LIMIT 25" --json

12) セキュリティの基本

• クライアント シークレット、リフレッシュ トークン、または生の認証情報ファイルは決して出力しません。
• ローカル設定/シークレットをコミットしません。
• OAuth データはオペレーターのマシンにローカルに保ちます。
• 最小権限アクセスと目的の顧客 ID のみを使用します。