google-ads-api-account-diagnostics

Google Ads API アカウント パフォーマンス診断スキル

このスキルでは、Google Ads MCP サーバーのツールを使って、よくあるアカウントのパフォーマンス問題を診断する方法を説明します。

ワークフロー

実行前のツール確認

診断タスクを始める前に、Google Ads MCP サーバーのツール（search、list_accessible_customers、get_resource_metadata。サーバーのプレフィックス付きで公開される場合があります。例：customers_list_accessible_customers）が実行環境で利用可能か確認します。

• MCP ツールが利用可能な場合：ライブ診断を進めます。まず有効なクライアントアカウントを特定するし、その後、search ツール（引数は customer_id と query）を使って GAQL を実行します。
• MCP ツールが利用できない場合：MCP ツールを利用できない場合の代替手順に従います。

有効なクライアントアカウントを特定する

ほとんどの診断タスクでは、特定の顧客アカウントに GAQL クエリを送信する必要があります。顧客 ID がユーザーから明示されていない場合は、まず list_accessible_customers（または customers_list_accessible_customers）ツールを呼び出し、アクセス可能な顧客のリソース名／ID を取得してください。

アクセス可能な顧客 ID のリストを取得したら、対象の顧客アカウントで search ツールを使って customer_client リソースにクエリを実行し、有効なクライアント顧客アカウントを見つけます。有効なクライアントアカウントのみを選択し、マネージャーアカウントは除外してください。

SELECT
  customer_client.id,
  customer_client.descriptive_name,
  customer_client.status,
  customer_client.manager
FROM customer_client
WHERE customer_client.status = 'ENABLED' AND customer_client.manager = FALSE

以降の診断クエリは、このリストから取得した有効なクライアント顧客 ID に対してのみ実行してください。無効化されたアカウントやマネージャーアカウントにクエリを実行すると API エラーが発生するため、実行しないでください。

MCP ツールを利用できない場合の代替手順

Google Ads MCP ツール（search、list_accessible_customers、get_resource_metadata。サーバーのプレフィックス付きで公開される場合があります。例：customers_list_accessible_customers）が実行環境に登録されていない場合：

1. ユーザーに伝える：ライブのアカウントパフォーマンス診断には Google Ads MCP サーバーが必要であることを伝えます。
2. セットアップガイドを案内する：ユーザーに、アシスタント環境で Google Ads MCP サーバーをインストールして設定するための手順として、google-ads-api-mcp-setup スキルを案内します。
3. GAQL テンプレート、注意事項、改善案を提示する：Google Ads Query Builder または API 連携を使って手動で実行できる、診断計画全体を作成して出力します。
   • ワークフローに必要な複数ステップの GAQL クエリをすべて提示します。これには、現行期間と前期間の比較（例：トラフィック、インプレッション シェア、コンバージョンの内訳、変更イベント）が含まれます。
   • 指標の変換と制約に関する注意点を説明します（通貨の場合は metrics.cost_micros / 1,000,000、インプレッション シェアは小数または "< 0.10" で報告されること、change_event は30日間の期間を対象とし metrics.* を含めずに LIMIT 10000 を指定すること、アップロードの健全性には successful_event_count / total_event_count と status を使うこと）。
   • 診断の各分岐で実施できる、具体的で実行可能な次の手順を示します（例：search_budget_lost_impression_share が高い場合はキャンペーン予算を引き上げ、search_rank_lost_impression_share が高い場合は広告の品質または入札単価を改善します）。
4. 許可されていないローカル調査を試みない：アカウントデータにアクセスするために、シェルコマンド、独自の Python スクリプト、ローカル SQL／データベースクエリ、または直接 RPC を実行する CLI ユーティリティを使わないでください。これらのコマンドには認証情報と API アクセスがなく、実行しても失敗します。

1. コンバージョン数とコンバージョン値の損失

コンバージョン数またはコンバージョン値が急に減少した場合は、次の手順で問題を診断します。

手順：

1. フィールドを確認する：リソース campaign または ad_group に対して get_resource_metadata を使用し、正しいフィールド名を確認します。

2. パフォーマンスをクエリする：search を使用してパフォーマンスデータを取得します。

   • リソース：campaign または ad_group
   • フィールド：campaign.name、metrics.conversions、metrics.conversions_value、metrics.cost_micros を含めます。
   • セグメント：損失の要因を特定するには、segments.date、segments.device、segments.conversion_action などのセグメントを含めます。
   • 条件：減少した期間を前の期間と比較します（例：segments.date >= '{start_date}'）。
   • 注意点：metrics.cost_micros を標準通貨額にするには、1,000,000 で割る必要があります。
   • 注意点（コンバージョン アクションのセグメント化）：GAQL では、segments.conversion_action でセグメント化する場合、metrics.cost_micros を選択できません。コンバージョン アクションの内訳は、metrics.cost_micros を含めずに別途クエリしてください。

   GAQL クエリの例：

   1. 日付とデバイス別にパフォーマンスと費用をクエリする場合：

   SELECT
     campaign.name,
     metrics.conversions,
     metrics.conversions_value,
     metrics.cost_micros,
     segments.date,
     segments.device
   FROM campaign
   WHERE segments.date >= '{start_date}' AND segments.date <= '{end_date}'
   

   2. コンバージョン アクション別の内訳をクエリする場合（metrics.cost_micros なし）：

   SELECT
     campaign.name,
     metrics.conversions,
     metrics.conversions_value,
     segments.date,
     segments.conversion_action
   FROM campaign
   WHERE segments.date >= '{start_date}' AND segments.date <= '{end_date}'
   

3. 分析する：損失が特定のデバイス（例：モバイルとデスクトップ）または特定のコンバージョン アクションに限られているかを確認します。

4. アップロードを確認する：オフライン インポートを使用している場合は、offline_conversion_upload_conversion_action_summary をクエリして、アップロード パイプラインの状態を確認します。クエリ結果が空の場合は、アカウントにオフライン アップロードが存在しないことを報告して、次に進みます。

   GAQL クエリの例： 顧客アカウント {customer_id} のアップロード パイプラインの状態を確認する場合：

   SELECT
     offline_conversion_upload_conversion_action_summary.conversion_action_name,
     offline_conversion_upload_conversion_action_summary.successful_event_count,
     offline_conversion_upload_conversion_action_summary.total_event_count,
     offline_conversion_upload_conversion_action_summary.status
   FROM offline_conversion_upload_conversion_action_summary
   

2. 失われた機会（インプレッション シェア）

広告ランク、入札単価、または予算が原因で失われた機会を特定するには、インプレッション シェアの指標を分析します。

手順：

1. インプレッション シェアをクエリする：search を使用してインプレッション シェアの指標を取得します。

   • リソース：campaign
   • フィールド：campaign.name、metrics.search_impression_share、metrics.search_rank_lost_impression_share、metrics.search_budget_lost_impression_share を含めます。
   • 注意点：API から返されるインプレッション シェアの値は、小数（例：0.35 = 35%）または書式設定された文字列（例："< 0.10"）です。

   GAQL クエリの例： 顧客アカウント {customer_id} の {start_date} から {end_date} までのインプレッション シェアの指標をクエリする場合：

   SELECT
     campaign.name,
     metrics.search_impression_share,
     metrics.search_rank_lost_impression_share,
     metrics.search_budget_lost_impression_share
   FROM campaign
   WHERE segments.date >= '{start_date}' AND segments.date <= '{end_date}'
   

2. 分析する：

   • search_budget_lost_impression_share の値が高い場合、予算不足により機会を失っていることを示します。
   • search_rank_lost_impression_share の値が高い場合、広告ランクの低さ（入札単価または品質の問題）により機会を失っていることを示します。

3. リード獲得数が少ない場合の診断

ユーザーから「ここ数日、リード獲得数が少ないのはなぜですか？」と尋ねられた場合は、次の手順で体系的に対応してください。

手順：

1. 減少の確認：直近数日とそれ以前の期間について、日付別にコンバージョンをクエリします。

2. 原因の切り分け：

   • トラフィック（クリック数、インプレッション数）が減少したかどうかを確認します。
   • コンバージョン率（コンバージョン数／クリック数）が低下したかどうかを確認します。

   GAQL クエリの例（トラフィックとコンバージョンの傾向）： キャンペーンごとに日付でセグメント化して、トラフィックとコンバージョン率の指標をクエリするには、次のようにします。

   SELECT
     campaign.id,
     campaign.name,
     segments.date,
     metrics.impressions,
     metrics.clicks,
     metrics.ctr,
     metrics.conversions,
     metrics.conversions_from_interactions_rate
   FROM campaign
   WHERE segments.date >= '{start_date}' AND segments.date <= '{end_date}'
   ORDER BY segments.date DESC
   

3. トラフィックが減少した場合：インプレッション シェアの指標（ワークフロー 2 を参照）を確認して、予算または広告ランクの問題なのか、検索ボリューム全般が減少したのかを確認します。

4. コンバージョン率が低下した場合：segments.device または segments.conversion_action で内訳を確認し、特定の箇所で問題が発生していないかを調べます。

5. 変更内容の確認：change_event リソースをクエリして、減少が始まった頃に入札単価、予算、ターゲティングに変更が加えられていないかを確認します。

   • 注意点（change_event の制約）：change_event リソースへのクエリには、次の制約があります。
     • LIMIT 句を指定する必要があり、その値は 10000 以下でなければなりません。
     • 過去 30 日以内の日付（change_event.change_date_time）でフィルタリングする必要があります。
     • パフォーマンス指標（例：metrics.*）は選択できません。選択できるのは、change_event の属性と許可されたリソースフィールドのみです。

   GAQL クエリの例： {customer_id} の顧客アカウントについて、{start_date} から {end_date} までの変更イベントをクエリするには、次のようにします。

   SELECT
     change_event.change_date_time,
     change_event.change_resource_name,
     change_event.resource_change_operation,
     change_event.changed_fields
   FROM change_event
   WHERE change_event.change_date_time >= '{start_date}' AND change_event.change_date_time <= '{end_date}'
   LIMIT 10000
   

4. オフラインアップロードパイプラインの診断

特定のアクション（例：store-purchase）のオフラインコンバージョンアップロードが表示されなくなった場合や失敗した場合は、以下の手順で問題を診断します。

手順：

1. クライアントアカウントの取得：{customer_id} が指定されていない場合は、アクティブなクライアントアカウントの特定に従って、アクティブなクライアントの顧客アカウントを取得します。

2. パイプラインの健全性を確認：アクティブなクライアントアカウントに対して offline_conversion_upload_conversion_action_summary をクエリします。

   • フィールド：offline_conversion_upload_conversion_action_summary.conversion_action_name、offline_conversion_upload_conversion_action_summary.successful_event_count、offline_conversion_upload_conversion_action_summary.total_event_count、および offline_conversion_upload_conversion_action_summary.status を含めます。

   GAQL クエリの例：

   SELECT
     offline_conversion_upload_conversion_action_summary.conversion_action_name,
     offline_conversion_upload_conversion_action_summary.successful_event_count,
     offline_conversion_upload_conversion_action_summary.total_event_count,
     offline_conversion_upload_conversion_action_summary.status
   FROM offline_conversion_upload_conversion_action_summary
   

3. 分析：

   • 注意点：offline_conversion_upload_conversion_action_summary へのクエリで結果が返されない、または空の場合（顧客アカウントにオフラインコンバージョンアップロードが設定されていないか、有効になっていないことを示します）は、ただちに診断ワークフローを中止します。再試行したり、カスタムスクリプトの生成を試みたりせず、アクセス可能なアカウントにオフラインコンバージョンアップロードのデータやサマリーが存在しないことをユーザーに直接報告します。
   • 結果が返された場合は、successful_event_count と total_event_count を比較してアップロードの成功率を確認します。status フィールドを確認して失敗の原因を診断します。