企业官网建设流程全解析

Google Ads API 账户性能诊断实战：用 GAQL 与 MCP 工具定位转化损失、低潜客流量与错失展示份额

【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills

本篇技术指南以 skills 仓库中的 google-ads-api-account-diagnostics Agent Skill 为核心，系统讲解如何借助 Google Ads MCP Server 的search等工具，通过 GAQL（Google Ads Query Language）查询对账户级性能问题做结构化排查。你将掌握四套可直接落地的诊断工作流——转化与转化价值损失、错失展示份额（Impression Share）、低潜客流量、离线转化上传管道故障——以及cost_micros单位换算、change_event查询约束等关键陷阱，能够在出现"突然掉量""近几天潜客变少"等诉求时快速给出有数据依据的结论。

Skill 定位与适用边界

google-ads-api-account-diagnostics是一个面向 Agent（LLM 助手）的编排型 Skill，它不直接封装代码，而是把 Google Ads API 上"账户级性能诊断"这件事标准化为一组可复用的工作流与 GAQL 模板。其 frontmatter 中声明的能力边界非常清晰：

• 适用场景：诊断转化损失（value 或 volume）、潜客流量/量级偏低、因广告评级（ad rank）、出价或预算导致的错失展示份额；排查性能突然下滑、分析广告系列展示份额指标、调查潜客流量偏低、查找出价与预算约束。
• 不适用场景：新建广告系列、直接上传转化事件，以及 Google Mobile Ads SDK 集成类问题（后者应使用gma-android-integrate等专用 Skill）。

这一边界设计意味着：当用户的问题属于"已有账户跑得好好的，为什么这几天数据掉了"，才进入本 Skill 的诊断范围；而"我要开一个新广告系列"属于另一条完全不同的操作链路，不应误用诊断型 Skill。

前置工作流一：识别活跃客户账户

几乎所有诊断任务都需要把 GAQL 查询发送到某个具体的客户账户（customer account）上。Skill 给出的强制约束是：

如果用户没有明确提供 customer ID，必须先调用list_accessible_customers（或customers_list_accessible_customers）工具，获取当前认证用户有权限访问的客户资源名/ID 列表。

拿到可访问的客户 ID 列表后，再对这些账户逐一查询customer_client资源，筛选出"启用中的、非经理账户（manager account）"的客户账户：

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

这一步的筛选逻辑有两个原因：

1. 避免 API 报错：对已停用（deactivated/canceled）账户或经理账户执行查询会直接产生 API 错误。所有后续诊断查询只允许针对上面筛选出的启用客户账户 ID 发起。
2. 数据语义正确：只有真实投放的客户账户才有 campaign、ad_group 层面的性能数据；经理账户只是层级容器，查询它没有意义。

前置工作流二：只通过 MCP 工具查询，不要写自定义脚本

这是本 Skill 反复强调的一条硬性规定：

获取信息与执行查询时，必须直接调用 MCP Server 上的search工具（传入customer_id、query等参数）。不要编写或执行自定义 Python 脚本，也不要使用 Google Ads 客户端库直接查询 API——在评估沙箱（evaluation sandbox）环境中，它们会因认证失败而不可用。

结合仓库中配套的 google-ads-api-mcp-setup 文档可以确认，官方 Google Ads MCP Server 暴露的工具恰好覆盖了诊断所需的全部能力：

该 MCP Server 目前是严格只读的——它不能修改出价、暂停广告系列或创建广告资产。这与诊断型 Skill 的定位完全吻合：诊断只需要读数据，不需要写操作。

工作流 1：转化与转化价值损失诊断

当转化数（conversions）或转化价值（conversion value）突然下滑时，按以下步骤定位。

1. 先发现字段，再构造查询

调用get_resource_metadata（resource 传campaign或ad_group），确认当前 API 版本下可用的准确字段名。这一步能避免因字段名拼写错误导致整条 GAQL 失败。

2. 查询性能数据

用search拉取性能数据，字段选择要点：

• Resource：campaign或ad_group
• Fields：至少包含campaign.name、metrics.conversions、metrics.conversions_value、metrics.cost_micros
• Segments：用segments.date、segments.device、segments.conversion_action对损失进行切分定位
• Conditions：用下滑周期对比上一个正常周期（例如segments.date >= '{start_date}'）

完整示例（对客户账户{customer_id}查询{start_date}至{end_date}的性能数据）：

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

Gotcha：metrics.cost_micros的单位是微美元（百万分之一美元），必须除以 1,000,000 才能得到常规货币金额。

3. 分析损失范围

对比下滑期与基期数据，判断损失是否集中在特定设备（如移动端 vs 桌面端）或特定转化动作（conversion action）上。这一步把"整体转化下滑"收敛为"某设备/某转化动作下滑"，为后续追因缩小范围。

4. 检查离线上传管道

如果账户使用了离线导入（offline imports），需要查询offline_conversion_upload_conversion_action_summary验证上传管道健康度：

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

Gotcha：如果该查询返回空结果，说明账户中不存在任何离线上传配置——直接如实报告"该账户没有离线上传数据"并继续后续诊断即可，不要陷入重试循环。

工作流 2：错失机会（展示份额）诊断

当需要判断"机会丢失是源于广告评级、出价还是预算"时，展示份额（Impression Share）指标是关键抓手。

查询展示份额指标

对campaign资源查询以下字段：

• metrics.search_impression_share：搜索网络实际获得的展示份额
• metrics.search_rank_lost_impression_share：因广告评级不足（出价或质量）错失的展示份额
• metrics.search_budget_lost_impression_share：因预算不足错失的展示份额

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}'

Gotcha：API 返回的展示份额数值有两种形态——小数（如0.35表示 35%）或格式化字符串（如"< 0.10"）。解读结果时务必注意，不要在两种形态之间混淆单位。

分析逻辑

• search_budget_lost_impression_share偏高→ 机会丢失源于预算受限，需要提升预算或优化支出结构。
• search_rank_lost_impression_share偏高→ 机会丢失源于广告评级偏低，通常与出价（bid）或广告质量（quality）问题相关。

工作流 3：低潜客流量诊断

当用户问"为什么最近几天我的潜客流量这么低"时，按下面的系统化思路排查，而不是凭直觉猜原因。

第一步：确认下滑是否真实

按日期分段查询最近几天的转化数据，并与上一周期对比，先确认下滑在统计上是否成立。

第二步：二分定位——流量问题还是转化率问题

把"潜客减少"拆成两个可独立验证的分支：

1. 流量（Traffic）是否下降：检查点击量（clicks）、展示量（impressions）是否同步下滑。
2. 转化率（Conversion Rate）是否下降：检查conversions / clicks是否下滑。

第三步：按分支追因

• 流量下降：回到工作流 2 检查展示份额指标，判断是预算/评级问题，还是整体搜索量（search volume）本身在下降。
• 转化率下降：按segments.device或segments.conversion_action做细分下钻，定位是哪个具体区域在失效。

第四步：检查变更事件

查询change_event资源，确认下滑开始的时间点附近是否发生过出价、预算或定向（targeting）方面的变更。

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

change_event查询的三条硬性约束（Gotcha）：

1. 必须指定LIMIT子句，且取值必须小于等于 10000；
2. 必须按日期过滤（change_event.change_date_time），且只能在过去 30 天内查询；
3. 不能选择性能指标——metrics.*字段不被支持，只能选择change_event属性及允许的资源字段。

违反任意一条都会导致查询失败，这也是构造该查询前必须检查的部分。

工作流 4：离线上传管道诊断

当某个特定转化动作（如 store-purchase）的离线转化上传不再显示或持续失败时，按以下步骤诊断。

第一步：检索客户账户

若未提供{customer_id}，先调用list_accessible_customers获取可访问客户 ID，再查询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

第二步：验证管道健康度

对活跃客户账户查询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：上传状态

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

第三步：分析结果

• 空结果即停止：如果查询返回空结果（说明账户没有配置或没有活跃的离线转化上传），立即终止诊断流程，直接向用户报告"可访问账户中不存在离线转化上传数据或摘要"，而不是反复重试或试图生成自定义脚本来强行取数。
• 有结果则比对成功率：用successful_event_count与total_event_count的比值计算上传成功率，再结合status字段定位失败原因（例如某个转化动作整体失败、部分失败或已暂停）。

关键陷阱（Gotcha）速查表

与其他 Skill 的协同使用

本 Skill 依赖 MCP Server 作为数据通道，因此在首次接入时，需要先完成 google-ads-api-mcp-setup 中描述的安装与配置流程：它要求 Python 3.12+ 与pipx，通过pipx install google-ads-mcp安装，并将GOOGLE_ADS_DEVELOPER_TOKEN、GOOGLE_ADS_CLIENT_ID、GOOGLE_ADS_CLIENT_SECRET、GOOGLE_ADS_REFRESH_TOKEN等认证变量配置到 MCP 客户端的mcpServers配置块中；若处于经理账户层级，还需配置GOOGLE_ADS_LOGIN_CUSTOMER_ID。

如果你的目标是诊断已有账户的性能问题，且 MCP Server 尚未就绪，也可以参考 google-ads-api-quickstart 了解凭据获取与 GAQL 的基础用法——但请记住，本 Skill 明确要求诊断类查询必须经由 MCP 的search工具执行，而非自行编写客户端库脚本。

【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills