Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

Google Ads API 入门指南

本指南详细介绍了注册、身份验证和首次调用 Google Ads API 的端到端流程。

1. 前提条件和账号层次结构

在与 Google Ads API 互动之前，您必须了解账号层次结构，并设置正确的顶级账号结构。

经理账号 (MCC)：Google Ads 经理账号（以前称为“我的客户中心”）是一种主要账号，用于查看和管理多个客户账号。您必须拥有经理账号才能申请 Google Ads API 开发者令牌。
客户账号：用于创建广告系列、广告组和广告以及配置结算信息的标准账号。

操作项：如果您没有经理账号，请前往 Google Ads 经理账号创建一个。

2. 获取开发者令牌

开发者令牌用于向 Google Ads API 唯一标识您的应用，并控制您的调用量访问权限层级。

申请步骤

登录您的 Google Ads 经理账号。
依次前往工具和设置 > 设置 > API 中心（或管理 > API 中心）。
填写开发者详细信息表单，并同意《API 服务条款》。
提交申请。

访问权限级别

待审批：新创建的令牌会立即获得“待审批”状态。您可以使用待处理令牌立即连接到测试账号，但它无法用于生产账号。
基本访问权限：获得批准后，每天最多可执行 15,000 项 API 操作。
标准访问权限：对于符合最低功能要求 (RMF) 的应用，每天的 API 操作次数不受限制。

3. 设置测试账号

针对生产账号进行开发和测试可能会导致不必要的广告支出和广告系列修改。强烈建议您针对测试账号执行所有活跃的开发工作。

创建测试经理账号

前往 Google Ads 测试经理账号创建页面。
使用尚未与您的正式版 Google Ads 经理账号相关联的 Google 账号登录。
输入一个描述性账号名称（例如 MyCompany Test MCC）。
选择主要用途：管理其他人的账号。
选择结算国家/地区、时区和币种。点击保存并继续。

创建测试客户账号

创建测试经理账号后，您必须创建至少一个子客户账号才能投放测试广告系列。

登录您新创建的 Test Manager 账号。
在左侧导航菜单中，点击账号，然后选择子账号设置（或效果）。
点击蓝色 +（加号）按钮，然后选择创建新账号。
选择 Google Ads 账号。
输入账号名称（例如 Test Client Account A）。
选择时区和币种，然后点击保存并继续。
记下此新客户账号的 10 位数客户 ID（例如，1234567890 不含连字符）。

测试账号的重要规则

开发者令牌使用情况：请勿通过测试经理账号申请开发者令牌。始终使用生产经理账号中的待审批或已获批的开发者令牌。
结算：测试账号不会投放实际的广告，因此您无需输入真实的结算信息。

4. Google Cloud 项目设置

所有 API 请求都必须使用启用了 Google Ads API 的 Google Cloud 项目进行身份验证。

启用 API 的步骤

前往 Google Cloud 控制台。
创建新项目或选择现有项目。
前往 API 和服务 > 库。
搜索 Google Ads API，然后点击启用。

定价和结算

无 API 费用：创建 Google Cloud 项目、启用 Google Ads API 和生成 OAuth 2.0 凭据是完全免费的。Google 不会针对调用或使用 Google Ads API 本身收取任何费用。
其他 Cloud 资源：只有当您主动使用其他超出免费层级限制的可结算 Google Cloud 服务（例如 Compute Engine、Cloud Run 或 BigQuery）来托管应用或存储广告数据时，才会产生 Google Cloud 费用。

5. OAuth 2.0 身份验证配置

Google Ads API 使用 OAuth 2.0 对请求进行身份验证和授权。

桌面应用流程的步骤

在您的 Google Cloud 项目中，依次前往 API 和服务 > OAuth 权限请求页面，然后配置权限请求页面。在应用处于“测试”状态时，将您的电子邮件地址添加到测试用户部分，以防止在授权期间出现访问错误。
前往 API 和服务 > 凭据。
依次点击创建凭据 > OAuth 客户端 ID。
选择桌面应用作为应用类型。
点击创建，然后将 OAuth 凭据文件下载为 client_secret.json（或复制您的 Client ID 和 Client Secret）。

生成刷新令牌

获得客户端 ID 和客户端密钥后，您必须生成刷新令牌。您可以使用 Google OAuth 2.0 Playground 或客户端库脚本来完成此操作。

方法 A：使用 Google OAuth 2.0 Playground

前往 Google OAuth 2.0 Playground。
点击右上角的齿轮图标 (OAuth 2.0 配置)。
勾选 Use your own OAuth credentials（使用您自己的 OAuth 凭据）对应的复选框。
输入您的 OAuth2 Client ID 和 Client Secret，然后点击关闭。
在左侧的第 1 步（选择和授权 API）中，在“输入您自己的范围”字段中输入 Google Ads API 范围： https://www.googleapis.com/auth/adwords
点击授权 API。系统提示时，请使用有权访问您的 Google Ads 经理账号（或测试账号）的 Google 账号登录。
在权限请求页面上点击继续。
在第 2 步（以授权代码交换令牌）中，点击蓝色以授权代码交换令牌按钮。
您的 Refresh token 和 Access token 将显示在回答面板中。复制并保存 Refresh token。

方法 B：使用客户端库脚本（Python 示例）

官方 Python 客户端库提供了一个内置的辅助脚本来生成凭据。或者，您也可以从 Google Cloud 控制台下载 client_secret.json，然后运行以下独立 Python 脚本：

安装所需的 OAuth 库：

pip install google-auth-oauthlib

在 client_secret.json 所在的目录中创建名为 generate_refresh_token.py 的脚本并运行该脚本：

from google_auth_oauthlib.flow import InstalledAppFlow

CLIENT_SECRETS_FILE = "client_secret.json"
SCOPES = ["https://www.googleapis.com/auth/adwords"]

def main():
    flow = InstalledAppFlow.from_client_secrets_file(
        CLIENT_SECRETS_FILE, SCOPES
    )
    credentials = flow.run_local_server(port=0)
    
    print("\nAuthorization Successful!\n")
    print(f"Refresh Token: {credentials.refresh_token}")

if __name__ == "__main__":
    main()

6. 客户端库和凭据设置

Google 提供官方支持的客户端库，用于处理身份验证、序列化以及与 gRPC 端点的通信。

支持的语言

Python： pip install google-ads
Java：可通过 Maven 或 Gradle 获取
PHP： composer require googleads/google-ads-php
.NET： Install-Package Google.Ads.GoogleAds
Ruby： gem install google-ads-googleads
Perl： cpanm Google::Ads::GoogleAds::Client

配置文件 (`google-ads.yaml`)

创建一个包含凭据的配置文件。默认情况下，客户端库的初始化方法（例如 GoogleAdsClient.load_from_storage()）会在以下两个位置自动搜索 google-ads.yaml：

运行脚本的当前工作目录。
您的用户主目录（在 Linux/macOS 上为 ~，在 Windows 上为 %HOMEPATH%）。

如果您将文件存储在自定义位置，则可以明确将路径传递给初始化方法（例如，load_from_storage("path/to/google-ads.yaml")）。

developer_token: "INSERT_YOUR_DEVELOPER_TOKEN_HERE"
client_id: "INSERT_YOUR_OAUTH2_CLIENT_ID_HERE"
client_secret: "INSERT_YOUR_OAUTH2_CLIENT_SECRET_HERE"
refresh_token: "INSERT_YOUR_OAUTH2_REFRESH_TOKEN_HERE"
login_customer_id: "INSERT_YOUR_MANAGER_ACCOUNT_ID_HERE"

7. 进行首次 API 调用

如需验证您的初始配置，请运行快速入门脚本，从您的测试账号中提取现有广告系列。

Python 脚本示例 (`quickstart.py`)

import sys
from google.ads.googleads.client import GoogleAdsClient
from google.ads.googleads.errors import GoogleAdsException

def main(client, customer_id):
    ga_service = client.get_service("GoogleAdsService")
    query = """
        SELECT
          campaign.id,
          campaign.name
        FROM campaign
        ORDER BY campaign.id
    """
    
    # Issues a search request
    stream = ga_service.search_stream(customer_id=customer_id, query=query)
    for batch in stream:
        for row in batch.results:
            print(
                f"Campaign with ID {row.campaign.id} and name "
                f"'{row.campaign.name}' was found."
            )

if __name__ == "__main__":
    # Initialize client from google-ads.yaml
    # By default, load_from_storage() searches for 'google-ads.yaml' in the
    # current working directory or the user's home directory (~). You can
    # also pass an explicit path: load_from_storage("path/to/google-ads.yaml")
    try:
        googleads_client = GoogleAdsClient.load_from_storage()
        # Replace with your test client account ID (without hyphens) from
        # Section 3, NOT your manager account ID (which belongs in
        # google-ads.yaml).
        test_customer_id = "1234567890" 
        main(googleads_client, test_customer_id)
    except GoogleAdsException as ex:
        print(
            f"Request failed with status {ex.error.code().name} and "
            f"includes the following errors:"
        )
        for error in ex.failure.errors:
            print(f"\tError with message '{error.message}'.")
            if error.location:
                for field_path_element in error.location.field_path_elements:
                    print(f"\t\tOn field: {field_path_element.field_name}")
        sys.exit(1)

8. 最佳实践和资源

日志记录：在客户端库中启用详细日志记录，以捕获请求和响应 ID (request-id)，这对于向 Google 请求支持至关重要。
错误处理：为 GoogleAdsException 实现强大的错误处理机制，专门用于管理速率限制 (RESOURCE_TEMPORARILY_EXHAUSTED)。
官方文档： Google Ads API 开发者文档
客户端库和代码示例： GitHub Google Ads 代码库

简介

快速入门

Google Ads API 入门指南 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。