进行首次 API 调用

在本指南中,我们将逐步引导您进行首次 API 调用。这将打开充分利用 AdWords API 的大门。

该视频以 Java 和 Eclipse 为例,但是您可以根据需要选择相应语言和客户端库,概念都是相似的。下文为支持的所有语言提供了说明。

流程概览

要设置 API 访问权限,您需要获取一些必需的身份验证凭据,创建一些测试帐号,然后将身份验证和帐号详细信息添加到客户端库的配置文件中。

配置文件设置完成后,您就可以对 API 进行调用了。

有六个主要步骤需要完成:

  1. 申请开发者令牌
  2. 创建测试帐号
  3. 获取客户端库
  4. 通过 OAuth2 设置身份验证
  5. 获取 OAuth2 刷新令牌并配置客户端
  6. 进行首次 API 调用

下面各节分别描述了每个步骤。

申请开发者令牌

Google 的开发者令牌可让您的应用连接到 AdWords API。要申请开发者令牌,请执行注册指南中的步骤(如果您还没有完成的话)。注册后,您会收到状态为“待审批”的开发者令牌。

您的待审批开发者令牌必须先获得批准,然后才能与“生产”AdWords 帐号配合使用。

创建测试帐号

执行以下步骤创建测试经理帐号、测试客户帐号和几个广告系列以填充测试客户帐号。

  1. 转到 AdWords 经理帐号页面,创建测试经理帐号
  2. 使用 AdWords 网页界面,在之前创建的测试经理帐号下创建测试客户帐号。当您以测试经理帐号登录 AdWords 时,您创建的所有客户帐号都将自动成为测试帐号。
  3. 使用 AdWords 网页界面,在测试客户帐号下创建几个测试广告系列。
  4. 记下新测试客户帐号的客户 ID 并保存:稍后您需要将其添加到配置文件中。客户帐号的客户 ID 如下所示。

对“测试”经理帐号发出请求时,请使用“生产”经理帐号的开发者令牌。即使该令牌尚未获得批准,对测试帐号依然有效,您刚刚创建的帐号也不例外。

获取客户端库

客户端库为您处理所有后端 API 调用,并提供适合搭配使用的对象,包括几乎每项常见 API 任务的代码示例。

如果您是一个有经验的开发者,您可能已经按照自己需要的方式设置了开发环境。如果没有,我们现在将逐步介绍针对客户端库的推荐设置。

根据您使用的语言点击下面的标签,然后按照说明操作。

Java

  1. 请参阅 GitHub 中 Java 客户端库 README 文件中的“Getting Started”部分,下载并安装适用于 Java 的 AdWords API 客户端库。
  2. 在执行 OAuth2 步骤之前返回此网页:我们将在下面的下一步中设置 OAuth2 凭据。

.NET

  1. 请参阅 .NET 客户端库 README 文件中的“Getting Started”部分,下载并安装适用于 C# 或 Visual Basic 的 AdWords API 客户端库。
  2. 在执行 OAuth2 步骤之前返回此网页:我们将在下面的下一步中设置 OAuth2 凭据。

Python

  1. 请参阅 Python 客户端库 README 文件中的“Getting Started”部分,下载并安装适用于 Python 的 AdWords API 客户端库。
  2. 在执行 OAuth2 步骤之前返回此网页:我们将在下面的下一步中设置 OAuth2 凭据。

PHP

  1. 请参阅 PHP 客户端库 README 文件中的“Getting Started”部分,下载并安装适用于 PHP 的 AdWords API 客户端库。
  2. 在执行 OAuth2 步骤之前返回此网页:我们将在下面的下一步中设置 OAuth2 凭据。

Perl

  1. 请参阅 Perl 客户端库 README 文件中的“Getting Started”部分,下载并安装适用于 Perl 的 AdWords API 客户端库。
  2. 在执行 OAuth2 步骤之前返回此网页:我们将在下面的下一步中设置 OAuth2 凭据。

Ruby

  1. 请参阅 Ruby 客户端库 README 文件中的“Getting Started”部分,下载并安装适用于 Ruby 的 AdWords API 客户端库。
  2. 在执行 OAuth2 步骤之前返回此网页:我们将在下面的下一步中设置 OAuth2 凭据。

设置 OAuth2 身份验证

您的应用需要访问用户数据,并代表您与其他 Google 服务联系。通过 OAuth2 进行身份验证可让您的应用代表您的帐号操作。

要使您的应用能够访问 API,您需要 OAuth2 客户端 ID客户端密钥

  1. 使用经理帐号凭据登录后,打开 Google API 控制台凭据页面
  2. 从项目下拉菜单中,选择新建项目,输入项目的名称,然后点击创建
  3. 选择创建凭据,然后选择 OAuth 客户端 ID
  4. 同意屏幕上,系统可能会提示您设置产品名称;若如此,请点击配置同意屏幕,提供要求的信息,然后点击保存以返回到凭据屏幕。
  5. 对于本教程,在应用类型下,选择其他。在提供的空间中输入名称。
  6. 点击创建。系统会显示 OAuth2 客户端 ID 和客户端密钥。复制并保存这些信息。您将在下一步中将它们添加到您的配置文件。

获取 OAuth2 刷新令牌并配置您的客户端

由于 OAuth2 访问权限会在限定时间后过期,因此使用 OAuth2 刷新令牌来自动更新 OAuth2 访问权限。

点击您所用编程语言的标签,然后按照说明生成 OAuth2 刷新令牌,并为您的客户端设置配置文件。

Java

  1. 按照 GitHub 中的这些说明获取 OAuth2 刷新令牌并配置客户端库。
  2. 完成后返回此页面。完成这些步骤后,您的 ads.properties 文件应该具有进行测试 API 调用所需的全部信息,并且应包含类似于以下内容的值:
[...]
api.adwords.developerToken=123axxxxxxxxxxxxxxxxxx
api.adwords.clientId=xxxxxxxxxx.apps.googleusercontent.com
api.adwords.clientSecret=zZxxxxxTxxxxxxxxxxx
api.adwords.clientCustomerId=123-456-7890
api.adwords.refreshToken=1/dyOIp7ki-xxxxxxxxxxxxxxxxxxxxxxxx
api.adwords.userAgent=Company_Name
[...]

.NET

  1. 按照 GitHub 中的这些说明获取 OAuth2 刷新令牌并配置客户端库。
  2. 完成后返回此页面。完成这些步骤后,您的 app.config 文件应该具有进行测试 API 调用所需的全部信息,并且应包含类似于以下内容的值:
<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <configSections>
    <section name="AdWordsApi"
        type="System.Configuration.DictionarySectionHandler"/>
  </configSections>
  <AdWordsApi>
    <!-- Settings specific to AdWords API.-->
    <add key="UserAgent" value="My AdWords API application"/>
    <add key="DeveloperToken" value="xxxxxxxxxxxxxxxxxxxxxx"/>
    <add key="ClientCustomerId" value="123-456-7890"/>

    <!-- OAuth2 configuration -->
    <add key="AuthorizationMethod" value="OAuth2" />
    <add key="OAuth2ClientId" value="xxxxxxxxxx.apps.googleusercontent.com" />
    <add key="OAuth2ClientSecret" value="zZxxxxxTxxxxxxxxxxx" />
    <add key="OAuth2Mode" value="APPLICATION" />
    <add key="OAuth2RefreshToken" value="1/dyOIp7ki-xxxxxxxxxxxxxxxxxxxxx" />
  </AdWordsApi>
</configuration>

Python

  1. 按照 GitHub 中的这些说明获取 OAuth2 刷新令牌并配置客户端库。
  2. 完成后返回此页面。完成这些步骤后,您的 googleads.yaml 配置文件应该具有进行测试 API 调用所需的全部信息,并且应包含类似于以下内容的值:
adwords:
  developer_token: 123axxxxxxxxxxxxxxxxxx
  user_agent: Company_Name
  client_customer_id: 123-456-7890
  client_id: xxxxxxxxxx.apps.googleusercontent.com
  client_secret: zZxxxxxTxxxxxxxxxxx
  refresh_token: 1/dyOIp7ki-xxxxxxxxxxxxxxxxxxxxxxxx
[...]

PHP

  1. 按照 GitHub 中的这些说明获取 OAuth2 刷新令牌并配置客户端库。
  2. 完成后返回此页面。完成这些步骤后,您的 auth.ini 配置文件应该具有进行测试 API 调用所需的全部信息,并且应包含类似于以下内容的值:
[...]
developerToken = 123axxxxxxxxxxxxxxxxxx
userAgent = Company_Name
clientCustomerId = 123-456-7890
client_id = xxxxxxxxxx.apps.googleusercontent.com
client_secret = zZxxxxxTxxxxxxxxxxx
refresh_token = 1/dyOIp7ki-xxxxxxxxxxxxxxxxxxxxxxxx
[...]

Perl

  1. 按照 GitHub 中的这些说明获取 OAuth2 刷新令牌并配置客户端库。
  2. 完成后返回此页面。完成这些步骤后,您的 adwords.properties 配置文件应该具有进行测试 API 调用所需的全部信息,并且应包含类似于以下内容的值:
[...]
userAgent = Company_Name
developerToken=123axxxxxxxxxxxxxxxxxx
clientId=123-456-7890
oAuth2ClientId=xxxxxxxxxx.apps.googleusercontent.com
oAuth2ClientSecret=zZxxxxxTxxxxxxxxxxx
oAuth2RefreshToken=1/dyOIp7ki-xxxxxxxxxxxxxxxxxxxxxxxx
[...]

Ruby

  1. 按照 GitHub 中的这些说明获取 OAuth2 刷新令牌并配置客户端库。
  2. 完成后返回此页面。完成这些步骤后,您的 adwords_api.yml 配置文件应该具有进行测试 API 调用所需的全部信息,并且应包含类似于以下内容的值:
[...]
:oauth2_client_id: xxxxxxxxxx.apps.googleusercontent.com
:oauth2_client_secret: zZxxxxxTxxxxxxxxxxx
:refresh_token: 1/dyOIp7ki-xxxxxxxxxxxxxxxxxxxxxxxx
:developer_token: 123axxxxxxxxxxxxxxxxxx
:client_customer_id: 123-456-7890
:user_agent: Company_Name
[...]

进行首次 API 调用

现在您的环境和配置文件都已设置完毕,是时候进行首次 API 调用了:

Java

  1. 在 IDE 中,打开 GetCampaigns.java 并加以执行。
  2. 控制台应输出上文中您添加到测试帐号的测试广告系列的列表。

.NET

  1. 在 IDE 中,打开 GetCampaigns.csGetCampaigns.vb 并加以执行。
  2. 控制台应输出上文中您添加到测试帐号的测试广告系列的列表。

Python

  1. 在 IDE 中,打开 get_campaigns.py 并加以执行。
  2. 控制台应输出上文中您添加到测试帐号的测试广告系列的列表。

PHP

  1. 在 IDE 中,打开 GetCampaigns.php 并加以执行。
  2. 控制台应输出上文中您添加到测试帐号的测试广告系列的列表。

Perl

  1. 在 IDE 中,打开 get_campaigns.pl 并加以执行。
  2. 控制台应输出上文中您添加到测试帐号的测试广告系列的列表。

Ruby

  1. 在命令行上,键入以下命令以执行 get_campaigns.rb
    ruby get_campaigns.rb
  2. 控制台应输出上文中您添加到测试帐号的测试广告系列的列表。

恭喜,您已经进行了首次 AdWords API 调用。

我们在本节中已经介绍了很多基础知识。在下一节中,我们将回顾并详细介绍我们在这一部分中使用的一些配置要素。

查看配置要素

在上一节中,我们帮助您完成了首次 API 调用的设置。

在本节中,我们将回顾并详细介绍我们用于对 AdWords API 进行调用的应用配置要素。

测试帐号与生产帐号

在上一节中,您创建了测试经理帐号和测试客户帐号。

要对 API 进行实验,测试帐号是一种很有用的方式,因为它们不会影响您的已上线广告或导致向您的帐号收费。它们也非常适合试用 AdWords 网页界面,而且不会造成什么后果。

登录 AdWords 网页界面后,亮红色测试帐号标签会提醒您,您所使用的是测试帐号:

由于测试帐号不投放任何实际广告,因此在报告或 API 调用中,展示次数或费用数据通常都是零。

有关测试帐号、生产帐号和设置帐号层级结构的详细信息,请参阅管理帐号

配置要素

由于我们使用的是客户端库,因此我们不会介绍有关 API 调用方式的后端细节。但是如果您想详细了解使这些调用正常操作的 SOAP、OAuth2 和其他管道,请参阅 API 调用结构

即使使用客户端库,也有一些您一定会用到的要素:我们已经在上文一总进行了设置,不过现在让我们回顾和稍微详细解释一下。

开发者令牌

开发者令牌会让 AdWords API 识别您的应用。只有经过批准的令牌才能连接到生产 AdWords 帐号的 API;待处理令牌只能连接到测试帐号。一旦您的令牌获得批准,您就可以将同一令牌用于针对所有 AdWords 帐号的请求,即使它们未关联到与此开发者令牌相关联的经理帐号,也是如此。

有关详细信息,请参阅管理帐号

OAuth2 客户端 ID 和客户端密钥

这些信息将您的客户端应用与 Google Developers Console 中项目对应,并用于 OAuth2 身份验证,以便允许您的应用代表您的帐号进行操作。

有关详细信息,请参阅 OAuth2 身份验证

OAuth2 访问令牌和刷新令牌

您的应用必须先获取授予 API 访问权限的 OAuth2 访问令牌,才可以使用 API 访问非公开数据。

如果您使用的是客户端库,则系统会自动为您处理 OAuth2 访问令牌。否则,请参阅 API 调用结构指南中的 API 调用示例,了解有关如何生成访问令牌的详细信息。

OAuth2 访问令牌会在限定时间后过期。因此,客户端库使用 OAuth2 刷新令牌来自动重新生成 OAuth2 访问令牌。

在上面的步骤中,您通过客户端库中的实用工具创建了刷新令牌

有关将 OAuth2 与 Google API 配合使用的详细信息,请参阅 OAuth2 身份验证OAuth2 身份平台文档。

客户帐号的客户 ID

客户帐号的客户 ID 是您要通过 API 管理的 AdWords 客户帐号的帐号编号,通常其格式为 123-456-7890

可以选择将客户帐号的客户 ID 留在配置文件之外,并采用编程方式进行设置。在您的开发者令牌获得批准后,您所使用的客户帐号的客户 ID 可以来自生产帐号,而不再是测试帐号。

有关详细信息,请参阅代码示例和用例

后续步骤

现在您了解了首个 API 应用的所有要素。在下一篇指南代码示例和用例中,我们将介绍客户端库和代码示例如何帮助您开始自定义报告并实现自动化。

发送以下问题的反馈:

此网页
AdWords API
AdWords API
需要帮助?请访问我们的支持页面