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 工具运行 GAQL（参数为 customer_id 和 query）。
• 如果缺少 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-api-mcp-setup 技能中的设置说明，以便在其助手环境中安装并配置 Google Ads MCP 服务。
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. 切勿尝试未经授权的本地探查：不要运行 shell 命令、自定义 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 资源时：
     • 必须指定小于或等于 10000 的 LIMIT 子句。
     • 必须按日期筛选（change_event.change_date_time），且日期范围须在过去 30 天内。
     • 不能选择效果指标（例如，不支持 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 字段以诊断失败原因。