google-ads

Google Ads

用于通过 Google Ads API（https://googleads.googleapis.com/v23/）操作 Google Ads 账户的工具。读取操作通过搜索端点使用 GAQL（Google Ads 查询语言）；写入操作通过各资源对应的 mutate 端点执行。共 13 个工具，涵盖账户导航、读取与报告，以及广告系列 / 预算 / 转化跟踪管理。Google Ads 将账户组织成层级结构：管理者（MCC）账户可以管理其下属的客户账户。大多数工具都需要操作账户的 customerId；如果通过管理者账户访问操作账户，还可以指定可选的 loginCustomerId（管理者账户）。

独立的非官方 Google Ads 连接器。与 Google Ads 无关联，未获其认可或赞助。“Google Ads”是其所有者的商标，此处仅用于标识本连接器所适用的服务。

适用场景

• 确定要操作的账户 — 列出连接可以访问的账户；如果通过管理者账户访问，则继续列出其下属的客户账户。
• 读取广告系列、广告组和广告 — 列出它们及其状态和预算，或运行任意 GAQL 查询，以获取结构化读取操作未涵盖的信息。
• 生成效果报告 — 选择资源、要衡量的指标和日期范围。
• 管理广告系列和预算 — 暂停、启用或移除广告系列；创建或调整每日预算。
• 设置转化跟踪 — 列出或创建转化操作（包括离线转化 UPLOAD_CLICKS 操作）。

设置

这是一个 agentskills.io 技能。

如果尚未将连接器安装为技能，请先运行 npx skills add zapier/connectors --skill google-ads 安装（或使用你所用运行环境自己的技能安装机制），然后继续操作。安装技能只会复制这些文件，不会安装依赖项。在运行 CLI、本地 MCP 服务或 zapier-sdk 身份验证命令之前，请先在此处运行一次 npm install --omit=dev。如果想在自己的项目中将已发布的软件包作为依赖项导入？运行 npm install 时已会解析所有依赖项 — 请参阅 references/use-as-sdk.md。

如果需要获取仓库源代码，以便浏览 references/、运行此连接器的测试或修改代码，请参阅 README.md，了解如何执行范围受限的 git clone。

连接器运行于 Node.js 22.18+。选择与你的运行方式相符的参考文档，并在进行其他操作前先加载：

你拥有……	加载
支持 MCP 的客户端 — 工具可能已加载（例如 mcp__google-ads__<tool>），或者你可以自行注册本地服务（或引导用户完成注册）	references/use-as-mcp.md
终端 / 子进程访问权限（可以运行 node）	references/use-as-cli.md
仅有自己的代码，并将此软件包作为依赖项导入	references/use-as-sdk.md
无法访问工具或终端，也无法导入此软件包 — 你需要编写自己的代码，直接调用 Google Ads API（例如，在代码执行沙盒中）	references/use-as-recipe.md

脚本

所有脚本都使用单一连接 google-ads。需要指定客户账号范围的脚本会接收操作账号的 customerId（仅包含数字），以及可选的 loginCustomerId（通过管理账号访问时使用的管理账号）。

脚本	脚本名称	连接	描述
scripts/listAccessibleCustomers.ts	listAccessibleCustomers	google-ads	列出该连接可直接访问的账号（账号解析的入口）。
scripts/listCustomerClients.ts	listCustomerClients	google-ads	列出管理账号下的客户端（操作）账号。
scripts/search.ts	search	google-ads	运行任意 GAQL 查询——完整的读取功能。
scripts/listSearchableFields.ts	listSearchableFields	google-ads	列出资源可选择、可筛选、可排序的字段（用于构造 search 查询）。
scripts/listCampaigns.ts	listCampaigns	google-ads	列出广告系列及其状态、渠道类型、预算和日期。
scripts/listAdGroups.ts	listAdGroups	google-ads	列出广告组，可选择限定在某个广告系列内。
scripts/listAds.ts	listAds	google-ads	列出广告，可选择限定在某个广告组内。
scripts/listConversionActions.ts	listConversionActions	google-ads	列出账号上配置的转化操作。
scripts/getReport.ts	getReport	google-ads	构建效果报告：资源 + 指标 + 日期范围内的细分数据。
scripts/setCampaignStatus.ts	setCampaignStatus	google-ads	暂停、启用或移除广告系列。
scripts/createCampaignBudget.ts	createCampaignBudget	google-ads	创建每日广告系列预算（金额以微单位表示）。
scripts/updateCampaignBudget.ts	updateCampaignBudget	google-ads	更新现有预算的金额、名称或投放方式。
scripts/createConversionAction.ts	createConversionAction	google-ads	创建转化操作（例如，用于离线跟踪的 UPLOAD_CLICKS）。

调用脚本前，请先了解其输入约定——切勿猜测字段名称、大小写或类型。 对脚本运行 --help（./scripts/<name>.ts --help 或 node cli.js run <name> --help）；它会以 JSON Schema 格式显示 inputSchema，并列出连接标志和解析器。猜测载荷只会导致 ZodError，白白浪费一次往返。

歧义处理与拒绝

• 金额单位为微单位。 预算、出价和报告中的费用指标（*_micros）均为货币金额的 1,000,000 倍（例如，$50.00 → 50000000）。唯一例外是转化操作的默认值，该值使用普通货币单位。不要将 cost_micros 为 5,000,000 的费用报告为“$5,000,000”。
• 根据 ID 操作，而不是名称。 写入操作（setCampaignStatus、updateCampaignBudget）需要 ID。先通过 listCampaigns / search 将名称解析为 ID；如果两个广告系列名称相同，请使用可区分的字段（ID、状态、渠道类型）列出，并在操作前确认要处理哪一个——绝不要擅自选择。
• 不支持的操作——应拒绝，不要用其他操作替代。 此连接器不会上传离线转化，也不会向 Customer Match 受众添加成员（Google 会将新的 API 集成引导至单独的 Data Manager API），也不会创建完整的广告系列或管理关键字／定向／广告创意。如果收到此类请求，请说明不支持，而不是用其他工具替代并声称已成功。createConversionAction 会设置转化_操作_，不会上传转化。

身份验证

每种形态都通过一个连接选择器传递身份验证信息，而不是密钥——格式为 [<resolver>:]<value> 字符串。每个连接器都接受 zapier:<connection-id>（由 Zapier 管理的身份验证——通过 Zapier 的身份验证、重试和治理层路由）；有些连接器还接受一个或多个直接令牌解析器（名称和数量因连接器而异）——请查看此连接器自身的解析器，不要想当然。<resolver>: 前缀为可选；裸值会交给第一个接收它的解析器——UUID 格式的裸值总会匹配 zapier:。每个脚本都会声明所需的连接以及各自接受的解析器。传递连接的具体语法（以及如何查看此连接器的解析器列表）因形态而异——请参阅上文已加载的参考文档。

想先检查已配置的内容？不要通过输出环境变量值来检查——env 或 env | grep <name> 会连同名称一起打印值，如果已设置，就会将有效凭据泄露到对话记录中。只检查名称（env | cut -d= -f1 | grep -i <name>），或直接测试已知名称（[ -n "$VAR_NAME" ]）。

还没有连接？选择一种方式——并按照对应参考文档中的流程获取连接；绝不要直接询问用户连接 ID 或令牌，仿佛他们早已记住这些信息：

	加载
直接传递凭据	references/use-without-zapier.md
通过 Zapier 连接进行路由	references/use-with-zapier.md

输出格式

每个脚本都会返回一个 { data, meta } 信封：

• data — 脚本的结果（其形状由 outputSchema 声明；有关如何检查脚本的确切形状，请参阅上方加载的参考文档）。
• meta.outputDataValidation — 验证 data 的结果：
  • { skipped: false, droppedPaths: null } — 已验证，未移除任何内容。
  • { skipped: false, droppedPaths: [...], instruction } — 已验证，但这些路径已从 data 中剥除：脚本从 API 返回、但 outputSchema 未声明的字段。如果需要这些字段，请跳过输出验证后重新运行。
  • { skipped: true } — 已绕过验证；data 是未经检查的脚本原始输出。

读取已剥除的字段 / skipOutputDataValidation。 要接收未经验证的原始结果，请选择退出输出验证（具体语法因形状而异，请参阅上方加载的参考文档）。输入验证永远不会跳过。

精简结果 / filterOutputData。 要将大型结果缩减为所需字段，请传入一个对 data 进行后处理的 jq 表达式（具体语法因形状而异）。jq 只会针对 data 运行，不会针对 { data, meta } 信封运行，因此表达式应以 data 为根（运行脚本的 --help，或形状对应的命令，查看其输出架构）。转换后的值会替换 data，meta 保持不变，且结果不会再次根据输出架构进行验证。

参考文档

在处理相关内容前，加载匹配的参考文件：

参考文档	涵盖内容	在以下情况下加载
references/google-ads-api-gotchas.md	身份验证标头、账户层级、GAQL、微单位、变更语义、错误、速率限制、转化跟踪、版本管理。	在编写 GAQL 查询、处理金额字段（微单位）、设置广告系列状态或解读 Google Ads API 错误之前。