你有没有想过,让 AI 助手直接帮你查广告数据、分析搜索表现、甚至批量操作关键词?

让 AI 助手接管你的 Google Ads 和 GSC：API 接入完整教程

你有没有想过，让 AI 助手直接帮你查广告数据、分析搜索表现、甚至批量操作关键词？

不是那种”把截图发给 ChatGPT 让它分析”的半吊子方案，而是 AI 直接通过 API 读取你的 Google Ads 和 Google Search Console 数据，实时查询、实时分析、实时操作。

本教程将手把手教你完成两套 API 的接入配置，全程大约 30 分钟。配好之后，你的 AI 助手就能做到下面这些事情。

—

配好之后能做什么？真实用例

Google Ads API 用例

日常数据查询 — 告别手动导出

– “过去 7 天各广告系列的花费、转化和 ROAS 是多少？”

– “哪些搜索词花了钱但没有转化？”

– “美国和英国市场的 CPA 对比如何？”

– AI 直接查 API 返回结构化数据，不用你登录后台导 CSV 再分析

自动生成周报

– AI 拉取本周/上周数据 → 计算环比变化 → 生成带表格的完整分析报告

– 包含系列诊断、地区分析、搜索词质量、预算使用率

– 一份人工要做 2-3 小时的周报，AI 10 分钟搞定

批量操作 — 效率提升 10 倍

– “帮我把这 50 个搜索词加为否定关键词”

– “把这个系列的出价策略从 Maximize Clicks 改为 tROAS 70%”

– “创建一个新的广告系列，定向西班牙语国家”

– 不用在 Google Ads 后台一个个点，告诉 AI 你要做什么，它直接通过 API 执行

诊断与优化建议

– AI 能拉取完整的广告系列数据、搜索词报告、地区表现，然后给出数据驱动的优化建议

– 发现自竞价（两个系列抢同一批用户）、发现预算浪费、发现高效词未被充分利用

GSC API 用例

搜索表现分析

– “过去 30 天哪些页面的点击量增长最快？”

– “哪些关键词排名在 5-15 位，有机会优化到首页？”

– “和上个月相比，自然搜索流量有什么变化？”

收录与索引管理

– 批量提交新页面到 Google 索引

– 检查某个 URL 的收录状态

– 提交和管理 Sitemap

SEO + SEM 联动

– 发现 SEO 流量好的词，考虑是否在 Google Ads 中出价

– 发现 Google Ads 效果好的词，优化对应的 SEO 页面

– 全面掌控搜索可见性

—

API 访问等级详解（重要！）

在开始配置之前，你需要了解 Google Ads API 的三个访问等级。这决定了你能做什么、做多少。

三个等级对比

Test Account（测试账户）— 默认起步级别

– 申请后立即获得，无需审核

– 只能访问测试账户（Test Accounts），不能访问生产账户

– 每日请求限制：15,000 次

– 适用场景：开发调试、验证配置是否正确

– 限制：不能查询真实广告数据

Basic Access（基础访问）— 大多数用户的选择

– 需要提交申请表，通常 2-5 个工作日审批

– 可以访问生产账户（真实广告数据）

– 每日请求限制：15,000 次

– 可以执行读取和写入操作（查询数据 + 修改广告）

– 适用场景：内部工具、AI 助手集成、自动化报告

– 大多数中小型广告主用这个等级就够了

Standard Access（标准访问）— 大型工具/代理商

– 需要更严格的审核，可能需要 7-14 个工作日

– 无每日请求限制（理论上无限）

– 必须通过 Google 的合规审查（包括 OAuth 验证）

– 适用场景：SaaS 工具、广告代理公司、管理大量客户账户

– 对于大多数自用场景来说没必要申请

如何从 Test Account 升级

升级到 Basic Access：

1. 登录 Google Ads 管理账户 → 工具与设置 → API 中心

2. 点击「Apply for Basic Access」

3. 填写申请表：

  – 描述你的 API 使用场景（例如：”Internal reporting tool for analyzing ad performance and automating bid management”）

  – 说明你代表的公司

  – 描述你会使用哪些 API 功能

4. 提交后等待 Google 审核（通常 2-5 个工作日）

5. 审核通过后，你的开发者令牌自动升级

升级到 Standard Access：

1. 先拥有 Basic Access

2. 在 API 中心申请 Standard Access

3. 需要额外通过 OAuth 验证（Google 会审查你的应用名称、隐私政策等）

4. 审核更严格，需要证明你的工具为多个客户服务

实用建议： 如果你只是给自己的广告账户做分析和优化，Basic Access 完全够用。15,000 次/天的配额对于 AI 助手场景绑绑有余 — 一次完整的周报分析大约消耗 20-50 次请求。

—

第一部分：Google Ads API 配置

Google Ads API 使用 OAuth 2.0 用户授权模式，需要以下四个凭证：

– client_id（OAuth 客户端 ID）

– client_secret（OAuth 客户端密钥）

– developer_token（开发者令牌）

– refresh_token（用户授权令牌）

步骤 1：获取开发者令牌（Developer Token）

开发者令牌是调用 Google Ads API 的入场券，需要在 Google Ads MCC（管理账户）后台申请。

什么是 MCC？ MCC（My Client Center）是 Google Ads 的管理账户，可以统一管理多个广告账户。如果你只有一个广告账户，也需要先创建一个 MCC 来申请开发者令牌。

操作步骤：

1. 登录 Google Ads 管理账户：https://ads.google.com

2. 点击右上角「工具与设置」→「设置」→「API 中心」

3. 如果没有开发者令牌，点击「申请访问权限」

4. 填写公司信息和 API 用途说明

5. 提交后立即获得一个 Test Account 级别的令牌

6. 按需申请升级到 Basic Access（见上文「API 访问等级详解」）

注意： 开发者令牌只需申请一次，团队成员可以共用同一个令牌。令牌绑定的是 MCC 账户，不是个人。

步骤 2：创建 OAuth 客户端凭证

OAuth 客户端凭证用于用户授权流程，需要在 Google Cloud Console 创建。

操作步骤：

1. 打开 Google Cloud Console：https://console.cloud.google.com

2. 创建一个新项目（或选择已有项目）

3. 配置 OAuth 同意屏幕：

  – 左侧菜单 →「APIs & Services」→「OAuth consent screen」

  – User Type 选「External」→ 点击「Create」

  – 填写应用名称（随意，例如 “Google Ads Tool”）

  – 填写用户支持邮箱和开发者邮箱（填你自己的邮箱）

  – 其他字段可以跳过 → 点击「Save and Continue」

  – Scopes 页面直接跳过 → Test users 页面添加你自己的 Gmail → 完成

4. 创建 OAuth 客户端：

  – 左侧菜单 →「APIs & Services」→「Credentials」

  – 点击「+ CREATE CREDENTIALS」→「OAuth client ID」

  – 应用类型选「Web application」

  – 名称随意填写

  – 在「Authorized redirect URIs」中添加：http://localhost

  – 点击「Create」

  – 弹出窗口会显示 Client ID 和 Client Secret，复制保存下来

5. 启用 Google Ads API：

  – 左侧菜单 →「APIs & Services」→「Library」

  – 搜索「Google Ads API」

  – 点击进入 → 点击「Enable」

⚠️ 注意： Redirect URI 必须填 http://localhost。旧版的 urn:ietf:wg:oauth:2.0:oob 已被 Google 在 2022 年废弃，不再可用。

步骤 3：获取 Refresh Token（用户授权）

这是最关键的一步。Refresh Token 代表你的 Google 账号对 API 的授权。

3.1 拼接授权链接

将下面链接中的 YOUR_CLIENT_ID 替换为步骤 2 获得的 Client ID：

https://accounts.google.com/o/oauth2/v2/auth?client_id=YOUR_CLIENT_ID&redirect_uri=http://localhost&scope=https://www.googleapis.com/auth/adwords&response_type=code&access_type=offline&prompt=consent

3.2 浏览器授权

1. 将完整链接粘贴到浏览器地址栏，回车

2. 选择你的 Google 账号登录（必须是有权访问 Google Ads 的账号）

3. 点击「Allow」授权

4. 浏览器会跳转到类似这样的地址：http://localhost/?code=4/0AXXXX…&scope=…

5. 页面打不开是正常的！ 不要慌，这是预期行为

6. 从浏览器地址栏复制完整的 URL

3.3 用授权码换取 Refresh Token

运行以下 Python 代码（替换三个占位符）：

import requests

response = requests.post(“https://oauth2.googleapis.com/token”, data={

    “code”: “从URL中提取的code值”,

    “client_id”: “你的CLIENT_ID”,

    “client_secret”: “你的CLIENT_SECRET”,

    “redirect_uri”: “http://localhost”,

    “grant_type”: “authorization_code”

})

result = response.json()

print(“Refresh Token:”, result.get(“refresh_token”))

# 复制保存这个 refresh_token

💡 简化方式： 如果你已经配置好了 AI 助手，直接把浏览器地址栏的完整 URL 发给它，它会自动帮你提取 code 并换取 refresh_token。

步骤 4：编写凭证文件

将所有凭证信息写入 YAML 配置文件。

文件路径： ~/.google-ads.yaml

client_id: “你的CLIENT_ID.apps.googleusercontent.com”

client_secret: “你的CLIENT_SECRET”

customer_id: “你的MCC账户ID”

developer_token: “你的开发者令牌”

login_customer_id: “你的MCC账户ID”

refresh_token: “你的REFRESH_TOKEN”

use_proto_plus: true

字段说明：

– client_id / client_secret：步骤 2 获得的 OAuth 凭证

– customer_id / login_customer_id：MCC 管理账户 ID（10 位数字，不含横线）

– developer_token：步骤 1 获得的开发者令牌

– refresh_token：步骤 3 获得的用户授权令牌

– use_proto_plus：Python 客户端库设置，固定为 true

步骤 5：安装依赖并验证

pip install google-ads

验证连接：

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage(“~/.google-ads.yaml”)

service = client.get_service(“GoogleAdsService”)

# 查询 MCC 下的子账户列表

query = “””

    SELECT

        customer_client.id,

        customer_client.descriptive_name

    FROM customer_client

    WHERE customer_client.manager = FALSE

“””

response = service.search_stream(

    customer_id=”你的MCC账户ID”,

    query=query

)

for batch in response:

    for row in batch.results:

        print(f”账户: {row.customer_client.descriptive_name} (ID: {row.customer_client.id})”)

能正常输出子账户列表就说明配置成功了 🎉

Google Ads API 常见问题

Q: 报错 invalid_grant: Token has been expired or revoked

A: Refresh Token 过期了。重新执行步骤 3 获取新 Token。常见原因：OAuth 同意屏幕在 Testing 状态超过 7 天、用户改了密码、或手动撤销了授权。

Q: 报错 DEVELOPER_TOKEN_NOT_APPROVED

A: 开发者令牌还在 Test Account 状态，只能访问测试账户。需要申请升级到 Basic Access 才能查询真实数据。

Q: 查询返回空结果

A: 最常见的原因是用了 MCC ID 去查数据。MCC 本身没有广告数据，必须用子账户 ID。通过上面的验证代码先拿到子账户列表，再用子账户 ID 查询。

Q: 报错 RESOURCE_EXHAUSTED / 日配额耗尽

A: Test Account 和 Basic Access 每日限制 15,000 次请求。正常数据查询很难超限，但批量操作（添加大量关键词、受众群体）容易触发。配额在美国太平洋时间午夜重置。

—

第二部分：GSC API 配置

Google Search Console API 使用 Service Account（服务账号）模式，不需要用户交互授权，配置比 Google Ads 简单很多。

步骤 1：创建 Service Account

1. 打开 Google Cloud Console：https://console.cloud.google.com

2. 选择项目（建议和 Google Ads API 用同一个项目）

3. 左侧菜单 →「IAM & Admin」→「Service Accounts」

4. 点击「+ CREATE SERVICE ACCOUNT」

5. 填写名称（例如 gsc-api）和描述

6. 点击「Create and Continue」

7. 角色页面直接跳过 → 点击「Done」

步骤 2：下载 JSON 密钥

1. 在 Service Accounts 列表中，点击刚创建的账号

2. 切换到「Keys」标签页

3. 点击「Add Key」→「Create new key」→ 选择「JSON」

4. 点击「Create」→ 浏览器自动下载 JSON 文件

5. 将文件保存到安全位置（例如 ~/.gsc/gsc-key.json）

密钥文件长这样（脱敏示例）：

{

  “type”: “service_account”,

  “project_id”: “your-project-id”,

  “private_key_id”: “abc123…”,

  “private_key”: “—–BEGIN PRIVATE KEY—–\n…\n—–END PRIVATE KEY—–\n”,

  “client_email”: “gsc-api@your-project-id.iam.gserviceaccount.com”,

  “client_id”: “123456789012345678”,

  “auth_uri”: “https://accounts.google.com/o/oauth2/auth”,

  “token_uri”: “https://oauth2.googleapis.com/token”

}

⚠️ 安全提醒： 这个 JSON 文件包含私钥，相当于密码。不要上传到 GitHub、不要发到群里、不要分享给不需要的人。

步骤 3：启用 Search Console API

1. Google Cloud Console →「APIs & Services」→「Library」

2. 搜索「Google Search Console API」

3. 点击「Enable」启用

步骤 4：在 GSC 中授权 Service Account

这一步最容易被忽略！ 创建了 Service Account 不等于它能访问你的数据。你需要在 GSC 后台手动给它添加权限。

1. 打开 Google Search Console：https://search.google.com/search-console

2. 选择你的站点

3. 左侧菜单 →「设置」→「用户和权限」

4. 点击「添加用户」

5. 邮箱填入 Service Account 的邮箱（就是密钥文件里 client_email 的值，格式为 xxx@your-project.iam.gserviceaccount.com）

6. 权限选择「受限」（Restricted，只读）或「完整」（Full，可管理）

7. 点击「添加」

注意： 每个站点要单独添加。如果你有多个站点需要分析，要逐个操作。

步骤 5：验证连接

from google.oauth2 import service_account

from googleapiclient.discovery import build

credentials = service_account.Credentials.from_service_account_file(

    ‘~/.gsc/gsc-key.json’,

    scopes=[‘https://www.googleapis.com/auth/webmasters.readonly’]

)

service = build(‘searchconsole’, ‘v1’, credentials=credentials)

# 列出有权限的站点

sites = service.sites().list().execute()

for site in sites.get(‘siteEntry’, []):

    print(f”站点: {site[‘siteUrl’]}”)

能列出站点就说明配置成功了。

GSC API 常见问题

Q: 返回 403 Forbidden

A: Service Account 没有站点权限。检查是否在 GSC 后台的「用户和权限」中添加了 SA 邮箱。

Q: 站点格式不匹配

A: GSC 站点有两种格式，API 请求中的格式必须与 GSC 中完全一致：

– 网域资源：sc-domain:example.com（推荐，覆盖所有子域名）

– 网址前缀：https://example.com/（仅覆盖该前缀）

Q: 数据有 2-3 天延迟

A: 这是 Google 的正常行为，不是配置问题。GSC 数据处理需要时间。

—

配置完成后的实战示例

示例 1：一句话查广告数据

对 AI 说：”过去 7 天花费 Top 5 的广告系列表现如何？”

AI 自动执行：

1. 调用 Google Ads API 查询 campaign 维度数据

2. 按花费排序，取 Top 5

3. 计算 CTR、CPA、ROAS 等指标

4. 返回格式化的分析报告

整个过程 10 秒钟，不需要登录后台、不需要导出数据。

示例 2：搜索词挖矿

对 AI 说：”帮我找出过去 30 天花了钱但没有转化的搜索词。”

AI 自动执行：

1. 查询 search_term_view 维度数据

2. 筛选 cost > 0 AND conversions = 0

3. 按花费降序排列

4. 输出浪费金额 + 建议添加的否定关键词列表

5. 你确认后，AI 直接通过 API 批量添加否定词

示例 3：SEO + SEM 联动分析

对 AI 说：”fliphtml5.com 在自然搜索和付费搜索中表现最好的关键词分别是哪些？有没有重叠？”

AI 自动执行：

1. 通过 GSC API 拉取自然搜索 Top 关键词

2. 通过 Google Ads API 拉取付费搜索 Top 关键词

3. 交叉比对，找出重叠词和各自独有的词

4. 给出策略建议（哪些词可以减少付费投入靠 SEO、哪些词 SEO 排不上去需要加大广告）

示例 4：自动化周报

对 AI 说：”帮我生成本周的 Google Ads 周报。”

AI 自动执行：

1. 拉取本周和上周的全维度数据（系列、广告组、地区、搜索词、日趋势）

2. 计算环比变化，标注异常波动

3. 分析每个广告系列的表现，给出诊断

4. 生成包含 10+ 个数据表格的完整报告

5. 写入云文档，分享给团队

—

总结

Google Ads API： OAuth 授权模式，需要在 GCP 创建凭证 + 用户交互授权获取 Refresh Token，适合管理自己的广告账户。

GSC API： Service Account 模式，创建密钥文件 + 在 GSC 后台添加权限即可，无需用户交互，配置更简单。

两套 API 配好之后，你的 AI 助手就从一个只能看截图聊天的工具，变成了一个能直接操作你广告账户的专业分析师。查数据、出报告、改出价、加否定词、诊断问题 — 全部一句话搞定。

30 分钟的配置时间，换来的是每周节省数小时的手动操作。这笔账怎么算都划算。

—

最后更新：2026-04-30