2026/9/13 19:53:54
FEATURED · 精选文章 
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等工具通过 GAQLGoogle Ads Query Language查询对账户级性能问题做结构化排查。你将掌握四套可直接落地的诊断工作流——转化与转化价值损失、错失展示份额Impression Share、低潜客流量、离线转化上传管道故障——以及cost_micros单位换算、change_event查询约束等关键陷阱能够在出现突然掉量近几天潜客变少等诉求时快速给出有数据依据的结论。Skill 定位与适用边界google-ads-api-account-diagnostics是一个面向 AgentLLM 助手的编排型 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这一步的筛选逻辑有两个原因避免 API 报错对已停用deactivated/canceled账户或经理账户执行查询会直接产生 API 错误。所有后续诊断查询只允许针对上面筛选出的启用客户账户 ID 发起。数据语义正确只有真实投放的客户账户才有 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 工具用途关键参数list_accessible_customers返回认证用户可访问的 Google Ads 客户 ID 与账户名新会话或不知道目标客户 ID 时首先调用无需参数get_resource_metadata返回某个 API 资源如campaign、ad_group、customer的结构元数据用于构造 GAQL 前确认字段、指标、细分段的准确名称resource必填字符串如campaignsearch执行一条 GAQL 查询获取资源指标、属性、细分段与状态customer_id必填10 位纯数字客户 ID、query必填合法 GAQL 字符串该 MCP Server 目前是严格只读的——它不能修改出价、暂停广告系列或创建广告资产。这与诊断型 Skill 的定位完全吻合诊断只需要读数据不需要写操作。工作流 1转化与转化价值损失诊断当转化数conversions或转化价值conversion value突然下滑时按以下步骤定位。1. 先发现字段再构造查询调用get_resource_metadataresource 传campaign或ad_group确认当前 API 版本下可用的准确字段名。这一步能避免因字段名拼写错误导致整条 GAQL 失败。2. 查询性能数据用search拉取性能数据字段选择要点Resourcecampaign或ad_groupFields至少包含campaign.name、metrics.conversions、metrics.conversions_value、metrics.cost_microsSegments用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}Gotchametrics.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_summaryGotcha如果该查询返回空结果说明账户中不存在任何离线上传配置——直接如实报告该账户没有离线上传数据并继续后续诊断即可不要陷入重试循环。工作流 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}GotchaAPI 返回的展示份额数值有两种形态——小数如0.35表示 35%或格式化字符串如 0.10。解读结果时务必注意不要在两种形态之间混淆单位。分析逻辑search_budget_lost_impression_share偏高→ 机会丢失源于预算受限需要提升预算或优化支出结构。search_rank_lost_impression_share偏高→ 机会丢失源于广告评级偏低通常与出价bid或广告质量quality问题相关。工作流 3低潜客流量诊断当用户问为什么最近几天我的潜客流量这么低时按下面的系统化思路排查而不是凭直觉猜原因。第一步确认下滑是否真实按日期分段查询最近几天的转化数据并与上一周期对比先确认下滑在统计上是否成立。第二步二分定位——流量问题还是转化率问题把潜客减少拆成两个可独立验证的分支流量Traffic是否下降检查点击量clicks、展示量impressions是否同步下滑。转化率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 10000change_event查询的三条硬性约束Gotcha必须指定LIMIT子句且取值必须小于等于 10000必须按日期过滤change_event.change_date_time且只能在过去 30 天内查询不能选择性能指标——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速查表陷阱说明metrics.cost_micros单位返回值为微美元需除以 1,000,000 才是常规货币金额Impression Share 返回值形态可能是小数0.3535%也可能是格式化字符串 0.10change_eventLIMIT 限制必须带LIMIT子句且值 ≤ 10000change_event时间窗口只能查询过去 30 天内的变更change_event字段限制不支持选择metrics.*性能指标查询已停用/经理账户会导致 API 错误必须先过滤出 ENABLED 且非 manager 的客户账户离线上传摘要为空说明无离线上传配置直接如实报告不要重试或写自定义脚本在沙箱内使用客户端库认证会失败必须直接调用 MCP 的search工具与其他 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Google Ads API 账户性能诊断实战：用 GAQL 与 MCP 工具定位转化损失、低潜客流量与错失展示份额
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等工具通过 GAQLGoogle Ads Query Language查询对账户级性能问题做结构化排查。你将掌握四套可直接落地的诊断工作流——转化与转化价值损失、错失展示份额Impression Share、低潜客流量、离线转化上传管道故障——以及cost_micros单位换算、change_event查询约束等关键陷阱能够在出现突然掉量近几天潜客变少等诉求时快速给出有数据依据的结论。Skill 定位与适用边界google-ads-api-account-diagnostics是一个面向 AgentLLM 助手的编排型 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这一步的筛选逻辑有两个原因避免 API 报错对已停用deactivated/canceled账户或经理账户执行查询会直接产生 API 错误。所有后续诊断查询只允许针对上面筛选出的启用客户账户 ID 发起。数据语义正确只有真实投放的客户账户才有 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 工具用途关键参数list_accessible_customers返回认证用户可访问的 Google Ads 客户 ID 与账户名新会话或不知道目标客户 ID 时首先调用无需参数get_resource_metadata返回某个 API 资源如campaign、ad_group、customer的结构元数据用于构造 GAQL 前确认字段、指标、细分段的准确名称resource必填字符串如campaignsearch执行一条 GAQL 查询获取资源指标、属性、细分段与状态customer_id必填10 位纯数字客户 ID、query必填合法 GAQL 字符串该 MCP Server 目前是严格只读的——它不能修改出价、暂停广告系列或创建广告资产。这与诊断型 Skill 的定位完全吻合诊断只需要读数据不需要写操作。工作流 1转化与转化价值损失诊断当转化数conversions或转化价值conversion value突然下滑时按以下步骤定位。1. 先发现字段再构造查询调用get_resource_metadataresource 传campaign或ad_group确认当前 API 版本下可用的准确字段名。这一步能避免因字段名拼写错误导致整条 GAQL 失败。2. 查询性能数据用search拉取性能数据字段选择要点Resourcecampaign或ad_groupFields至少包含campaign.name、metrics.conversions、metrics.conversions_value、metrics.cost_microsSegments用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}Gotchametrics.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_summaryGotcha如果该查询返回空结果说明账户中不存在任何离线上传配置——直接如实报告该账户没有离线上传数据并继续后续诊断即可不要陷入重试循环。工作流 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}GotchaAPI 返回的展示份额数值有两种形态——小数如0.35表示 35%或格式化字符串如 0.10。解读结果时务必注意不要在两种形态之间混淆单位。分析逻辑search_budget_lost_impression_share偏高→ 机会丢失源于预算受限需要提升预算或优化支出结构。search_rank_lost_impression_share偏高→ 机会丢失源于广告评级偏低通常与出价bid或广告质量quality问题相关。工作流 3低潜客流量诊断当用户问为什么最近几天我的潜客流量这么低时按下面的系统化思路排查而不是凭直觉猜原因。第一步确认下滑是否真实按日期分段查询最近几天的转化数据并与上一周期对比先确认下滑在统计上是否成立。第二步二分定位——流量问题还是转化率问题把潜客减少拆成两个可独立验证的分支流量Traffic是否下降检查点击量clicks、展示量impressions是否同步下滑。转化率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 10000change_event查询的三条硬性约束Gotcha必须指定LIMIT子句且取值必须小于等于 10000必须按日期过滤change_event.change_date_time且只能在过去 30 天内查询不能选择性能指标——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速查表陷阱说明metrics.cost_micros单位返回值为微美元需除以 1,000,000 才是常规货币金额Impression Share 返回值形态可能是小数0.3535%也可能是格式化字符串 0.10change_eventLIMIT 限制必须带LIMIT子句且值 ≤ 10000change_event时间窗口只能查询过去 30 天内的变更change_event字段限制不支持选择metrics.*性能指标查询已停用/经理账户会导致 API 错误必须先过滤出 ENABLED 且非 manager 的客户账户离线上传摘要为空说明无离线上传配置直接如实报告不要重试或写自定义脚本在沙箱内使用客户端库认证会失败必须直接调用 MCP 的search工具与其他 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
