代码结构

在此之前,我们已经引导您完成进行首次 API 调用所需的设置,并回顾了调用 API 所需的配置要素

在本指南中,我们将了解典型 AdWords API 代码示例的结构。

然后,我们将研究一些常见用例,说明如何使用这些代码示例将几乎任何 API 功能集成到您的应用中。

API 代码示例剖析

随客户端库提供的代码示例涵盖了所有最常见的 API 函数。它们会自动处理大多数后端任务,并大大简化 AdWords API 应用的开发工作。

让我们来了解一下 AdWords API 代码示例的典型结构。点击下面的语言标签:

Java

在 IDE 中,打开我们在前一个指南中使用的示例文件:GetCampaigns.java

在 GetCampaigns.java 中,您会注意到 main 中执行以下操作的一些样板代码:

  • 生成凭据
  • 创建 AdWords 会话
  • AdWords 服务实例化

研究客户端库中的代码示例的过程中,您将会熟悉这些内容。

您可能需要 GetCampaigns 示例中的另一行:回想一下,在前一个指南中,我们在 ads.properties 文件中设置了客户帐号的客户 ID。

但是,如果您在经理帐号下有很多客户帐号,该怎么办?在这种情况下,您可以从 ads.properties 文件中移除客户帐号的客户 ID,并通过 AdWords 会话对象采用编程方式进行设置。构建对象后,调用 setClientCustomerID 即可动态设置。

// Construct an AdWordsSession.
AdWordsSession session = new AdWordsSession.Builder()
    .fromFile()
    .withOAuth2Credential(oAuth2Credential)
    .build();

session.setClientCustomerID("123-456-7890");

AdWordsServices adWordsServices = new AdWordsServices();

runExample(adWordsServices, session);

C#

在 IDE 中,打开我们在前一个指南中使用的示例文件:GetCampaigns.cs

您将在 main 中看到一些引用 AdWordsUser 的样板代码:
public static void Main(string[] args) {
    GetCampaigns codeExample = new GetCampaigns();
    Console.WriteLine(codeExample.Description);
    try {
      codeExample.Run(new AdWordsUser());
    }
}

C# 库中最重要的类是 AdsUser 类。AdsUser 类通常会封装一个广告帐号,本例中为 AdWords 帐号。

AdsWordsUser 类允许您使用在应用的 app.config 文件中指定的设置,创建可用于进行 API 调用的预配置服务类。

// Create a new AdWordsUser with the App.config settings.
AdWordsUser user = new AdWordsUser();

但是,如果您在经理帐号下有很多客户帐号,该怎么办?在这种情况下,您可以使用 AdsUser 对象的 Config 属性对其进行编程设置,以便在运行时配置该用户:

// Create a default AdWordsUser instance. If any configuration
// is available in App.config, those will be used.
AdWordsUser user = new AdWordsUser();

// Override a specific setting at runtime.
AdWordsAppConfig config = (AdWordsAppConfig) user.Config;
user.Config.clientCustomerId = "123-456-7890";

另一个选择是使用接受 AdWordsAppConfig 实例的构造函数,例如:

// Create a config object with the values in App.config.
AdWordsAppConfig config = new AdWordsAppConfig();

// Override any specific setting you wish to change.
user.Config.clientCustomerId = "123-456-7890";

AdWordsUser user = new AdWordsUser(config);

Python

在 IDE 中,打开我们在前一个指南中使用的示例文件:get_campaigns.py

在此示例中,注释表示 LoadFromStorage 方法从 googleads.yaml 文件中提取凭据和属性。回想一下,在前一个指南中,我们在 googleads.yaml 中设置了客户帐号的客户 ID。LoadFromStorage 方法默认在主目录中查找具有此名称的文件,但您可以提供具有正确 yaml 内容的任何文件的路径:

使用默认位置 - 您的主目录:

adwords_client = adwords.AdWordsClient.LoadFromStorage()

传递文件的位置:

adwords_client = adwords.AdWordsClient.LoadFromStorage('C:\My\Directory\googleads.yaml')

但是,如果您在经理帐号下有很多客户帐号,该怎么办?在这种情况下,您可以使用以下代码在运行时以编程方式设置客户帐号的客户 ID:

adwords_client = AdWordsClient.LoadFromStorage()
adwords_client.SetClientCustomerId('123-456-7890')

PHP

在 IDE 中,打开示例文件 GetCampaigns.php

该示例首先生成一个 OAuth 令牌:

// Generate a refreshable OAuth2 credential for authentication.
$oAuth2Credential = (new OAuth2TokenBuilder())
    ->fromFile()
    ->build();

然后,它使用该令牌构建执行 runExample() 函数的 API 会话:

// Construct an API session configured from a properties file and the OAuth2
// credentials above.
$session = (new AdWordsSessionBuilder())
    ->fromFile()
    ->withOAuth2Credential($oAuth2Credential)
    ->build();
self::runExample(new AdWordsServices(), $session);

runExample() 是本示例中的主要函数;它通过使用 CampaignService 中的选择器来提取广告系列 ID 和名称。

Perl

在 IDE 中,打开我们在前一个指南中使用的示例文件:get_campaigns.pl

在此示例中,您会注意到从配置文件 adwords.properties 获取凭据信息的一些代码。

# Get AdWords Client, credentials will be read from ~/adwords.properties.
my $client = Google::Ads::AdWords::Client->new({version => "v201710"});

回想一下,在前一个指南中,我们在 adwords.properties 文件中设置了客户帐号的客户 ID。

但是,如果您在经理帐号下有很多客户帐号,该怎么办?在这种情况下,您可以从 adwords.properties 中移除客户帐号的客户 ID,并通过调用 set_client_id 进行编程设置:

# Get AdWords Client, credentials will be read from ~/adwords.properties.
my $client = Google::Ads::AdWords::Client->new({version => "v201710"});
$client->set_client_id("123-456-7890");

Ruby

打开我们在前一个指南中使用的示例文件:get_campaigns.rb

在示例中,您会注意到 main 中用于从 adwords_api.yml 配置文件中提取凭据信息的一些样板代码。

  # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
  # when called without parameters.
  adwords = AdwordsApi::Api.new

您可能需要示例中的另一行:回想一下,在前一个指南中,我们在 adwords_api.yml 配置文件中设置了客户帐号的客户 ID。

但是,如果您在经理帐号下有很多客户帐号,该怎么办?在这种情况下,您可以从 adwords_api.yml 文件中移除客户帐号的客户 ID,并通过 AdWords 会话对象进行编程设置。构建对象后,调用 adwords.config.set 即可动态设置。

# Set a new CID value
adwords.config.set("authentication.client_customer_id", "123-456-7890")

访问代码示例

您可以在我们的客户端库和示例页上浏览所有 AdWords API 代码示例。这些示例涵盖了 API 功能的所有主要方面,包括:

  • 帐号管理
  • 广告系列管理
  • 错误处理
  • 优化
  • 报告
  • 定位

您已了解了典型 AdWords API 代码示例的结构,我们接下来将介绍一些用例,演示如何将代码示例用于几乎任何 API 函数。

API 的两大块功能是报告和自动化,让我们从报告开始。

将代码示例用于报告

我们将从下载条件效果报告的代码示例开始:

Java

转到 IDE 并打开 DownloadCriteriaReport.java

您将在 main 中看到我们之前见过的样板代码:

public static void main(String[] args) throws Exception {
    // Generate a refreshable OAuth2 credential.
    Credential oAuth2Credential = new OfflineCredentials.Builder()
        .forApi(Api.ADWORDS)
        .fromFile()
        .build()
        .generateCredential();

    // Construct an AdWordsSession.
    AdWordsSession session = new AdWordsSession.Builder()
        .fromFile()
        .withOAuth2Credential(oAuth2Credential)
        .build();

不过,RunExample 才是这个类中包含一些有趣代码的方法。我们在这里创建定义所需报告的对象层级结构:

// Create report definition.
    ReportDefinition reportDefinition = new ReportDefinition();
    reportDefinition.setReportName("Criteria performance report #" + System.currentTimeMillis());
    reportDefinition.setDateRangeType(ReportDefinitionDateRangeType.YESTERDAY);
    reportDefinition.setReportType(ReportDefinitionReportType.CRITERIA_PERFORMANCE_REPORT);
    reportDefinition.setDownloadFormat(DownloadFormat.CSV);

然后将它传递给 ReportDownloader 的实例:

 ReportDownloadResponse response =
          new ReportDownloader(session).downloadReport(reportDefinition);
      response.saveToFile(reportFile);

下面我们运行 DownloadCriteriaReport.java

IDE 控制台将列出已下载文件的位置。

您会注意到,该示例代码指定了一个报告类型,在本例中为条件效果报告

reportDefinition.setReportType(ReportDefinitionReportType.CRITERIA_PERFORMANCE_REPORT);

示例还指定要为报告提取的一些字段。

Selector selector = new Selector();
    selector.getFields().addAll(Lists.newArrayList("CampaignId",
        "AdGroupId",
        "Id",
        "CriteriaType",
        "Criteria",
        "FinalUrls",
        "Impressions",
        "Clicks",
        "Cost"));

C#

转到 IDE 并打开 DownloadCriteriaReport.cs

您将看到我们已在上一个示例中见过的样板代码,它通过从 app.config 文件中提取值来进行身份验证:

public static void Main(string[] args) {
  GetCampaigns codeExample = new GetCampaigns();
  Console.WriteLine(codeExample.Description);
  try {
    codeExample.Run(new AdWordsUser());
  }
}

不过,此示例中代码的有趣之处在于创建定义所需报告的对象层级结构:

public void Run(AdWordsUser user, string fileName) {
  ReportDefinition definition = new ReportDefinition() {
    reportName = "Last 7 days CRITERIA_PERFORMANCE_REPORT",
        reportType = ReportDefinitionReportType.CRITERIA_PERFORMANCE_REPORT,
        downloadFormat = DownloadFormat.GZIPPED_CSV,
        dateRangeType = ReportDefinitionDateRangeType.LAST_7_DAYS,
  }
}

下面我们运行 DownloadCriteriaReport.cs.

控制台将列出已下载文件的位置。

您会注意到,该示例代码指定了一个报告类型,在本例中为条件效果报告

reportType = ReportDefinitionReportType.CRITERIA_PERFORMANCE_REPORT,

示例还指定要为报告提取的一些字段。

selector = new Selector() {
  fields = new string[] {"CampaignId", "AdGroupId", "Id", "CriteriaType", "Criteria",
      "FinalUrls", "Clicks", "Impressions", "Cost"},
      predicates = new Predicate[] {
        Predicate.In("Status", new string[] {"ENABLED", "PAUSED"})
      }
}

Python

转到 IDE 并打开 download_criteria_report_with_selector.py

您将看到我们已在上一个示例中见过的样板代码,它通过从 googleads.yaml 配置文件中提取值来进行身份验证:

adwords_client = adwords.AdWordsClient.LoadFromStorage()
  main(adwords_client)

不过,此示例中代码的有趣之处在于定义所需报告的对象层级结构:

# Create report definition.
report = {
    'reportName': 'Last 7 days CRITERIA_PERFORMANCE_REPORT',
    'dateRangeType': 'LAST_7_DAYS',
    'reportType': 'CRITERIA_PERFORMANCE_REPORT',
    'downloadFormat': 'CSV',
    'selector': {
        'fields': ['CampaignId', 'AdGroupId', 'Id', 'CriteriaType',
                   'Criteria', 'FinalUrls', 'Impressions', 'Clicks', 'Cost']
    }
}

然后将它传递给 ReportDownloader 的实例:

report_downloader.DownloadReport(
    report, sys.stdout, skip_report_header=False, skip_column_header=False,
    skip_report_summary=False)

下面我们运行 download_criteria_report_with_selector.py

您的控制台将列出已下载文件的位置。

您会注意到,该示例代码指定了一个报告类型,在本例中为条件效果报告

该示例还在“selector”部分指定了为报告提取的一些字段,例如“CampaignId”、“AdGroupId”,等等。

PHP

转到 IDE 并打开 DownloadCriteriaReportWithSelector.php

该示例包含用于身份验证和构建 AdWords 会话的标准代码。它在构造选择器并定义报告的主函数 runExample() 中:

// Create selector.
$selector = new Selector();
$selector->setFields(['CampaignId', 'AdGroupId', 'Id', 'Criteria',
    'CriteriaType', 'Impressions', 'Clicks', 'Cost']);

// Create report definition.
$reportDefinition = new ReportDefinition();
$reportDefinition->setSelector($selector);
$reportDefinition->setReportName(
    'Criteria performance report #' . uniqid());
$reportDefinition->setDateRangeType(
    ReportDefinitionDateRangeType::LAST_7_DAYS);
$reportDefinition->setReportType(
    ReportDefinitionReportType::CRITERIA_PERFORMANCE_REPORT);
$reportDefinition->setDownloadFormat(DownloadFormat::CSV);

请注意,该示例将报告类型指定为 CRITERIA_PERFORMANCE_REPORT,并指定了要为报告提取的字段。

然后将报告定义传递给报告下载工具:

// Download report.
$reportDownloader = new ReportDownloader($session);
$reportDownloadResult =
    $reportDownloader->downloadReport($reportDefinition);
$reportDownloadResult->saveToFile($filePath);
printf("Report with name '%s' was downloaded to '%s'.\n",
    $reportDefinition->getReportName(), $filePath);

运行 DownloadCriteriaReportWithSelector.php,控制台将列出已下载文件的位置。

Perl

转到 IDE 并打开 download_criteria_report_with_selector.pl

您将看到我们已在上一个示例中见过的样板代码,它通过从 adwords.properties 配置文件中提取值来进行身份验证:

# Get AdWords Client, credentials will be read from ~/adwords.properties.
my $client = Google::Ads::AdWords::Client->new({version => "v201710"});

不过,此示例中代码的有趣之处在于创建选择器和定义所需报告的报告定义:

my $report_definition = Google::Ads::AdWords::Reports::ReportDefinition->new({
      reportName     => "Last 7 days CRITERIA_PERFORMANCE_REPORT #" . $today,
      dateRangeType  => "LAST_7_DAYS",
      reportType     => "CRITERIA_PERFORMANCE_REPORT",
      downloadFormat => "CSV",
      selector       => $selector
});

然后将它传递给 ReportDownloader 的实例:

# Download the report using the appropriate method on ReportDownloadHandler.
my $result;
if ($output_file) {
  $result = $report_handler->save($output_file);
} else {
  $result = $report_handler->get_as_string();
}

下面我们运行 download_criteria_report_with_selector.pl

控制台将列出已下载文件的位置。

您会注意到,该示例代码指定了一个报告类型,在本例中为条件效果报告

reportType => "CRITERIA_PERFORMANCE_REPORT",

示例还指定要为报告提取的一些字段。

# Create selector.
my $selector = Google::Ads::AdWords::Reports::Selector->new({
    fields => [
      "CampaignId", "AdGroupId", "Id",          "CriteriaType",
      "Criteria",   "FinalUrls", "Impressions", "Clicks",
      "Cost"
    ]
});

Ruby

打开 download_criteria_report_with_selector.rb

您将看到我们已在上一个示例中见过的样板代码,它通过从 adwords_api.yml 配置文件中提取值来进行身份验证:

def download_criteria_report_with_selector(file_name)
  # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
  # when called without parameters.
  adwords = AdwordsApi::Api.new

不过,此示例中代码的有趣之处在于创建定义所需报告的对象层级结构:

# Define report definition. You can also pass your own XML text as a string.
report_definition = {
  :selector => {
    :fields => ['CampaignId', 'AdGroupId', 'Id', 'Criteria', 'CriteriaType',
        'FinalUrls', 'Impressions', 'Clicks', 'Cost'],
  },
...

  :report_name => 'Last 7 days CRITERIA_PERFORMANCE_REPORT',
  :report_type => 'CRITERIA_PERFORMANCE_REPORT',
  :download_format => 'CSV',
  :date_range_type => 'LAST_7_DAYS',
}

然后将其传递给 report_utils.download_report_as_file 方法:

# Download report, using "download_report_as_file" utility method.
# To retrieve the report as return value, use "download_report" method.
report_utils.download_report_as_file(report_definition, file_name)
puts "Report was downloaded to '%s'." % file_name
end

下面我们运行 download_criteria_report_with_selector.rb。控制台将列出已下载文件的位置。

您会注意到,该示例代码指定了一个报告类型,在本例中为条件效果报告

:report_type => 'CRITERIA_PERFORMANCE_REPORT',

示例还指定要为报告提取的一些字段。

:fields => ['CampaignId', 'AdGroupId', 'Id', 'Criteria', 'CriteriaType',
          'FinalUrls', 'Impressions', 'Clicks', 'Cost'],

有关报告类型及其包含的字段的完整列表,请参阅报告类型页面。

您可以使用此代码示例以及报告类型页面上的信息来定义、创建和下载所需的任何类型的报告。

AdWords 查询语言 (AWQL)

除了定义具有对象层级结构的报告之外,您还可以使用 AdWords 查询语言 (AWQL)。这是一种类似 SQL 的语言,与通过对象相比,这种语言生成报告的方式更为简洁。

Java

将我们刚刚运行的示例代码与 DownloadCriteriaReportWithAWQL.java 进行比较:获得的报告都一样,但 AWQL 更简洁一些。两种方式生成的报告类型和字段都一样。

String query = "SELECT CampaignId, AdGroupId, Id, Criteria, CriteriaType, "
    + "Impressions, Clicks, Cost FROM CRITERIA_PERFORMANCE_REPORT "
    + "WHERE Status IN [ENABLED, PAUSED] "
    + "DURING YESTERDAY";

C#

将我们刚刚运行的示例代码与 DownloadCriteriaReportWithAWQL.cs 进行比较:获得的报告都一样,但 AWQL 更简洁一些。两种方式生成的报告类型和字段都一样。

string query = "SELECT CampaignId, AdGroupId, Id, Criteria, CriteriaType, Impressions, " +
    "Clicks, Cost FROM CRITERIA_PERFORMANCE_REPORT WHERE Status IN [ENABLED, PAUSED] " +
    "DURING LAST_7_DAYS";

Python

将我们刚刚运行的示例代码与 download_criteria_report_with_awql.py 进行比较:获得的报告都一样,但 AWQL 更简洁一些。两种方式生成的报告类型和字段都一样。

report_query = ('SELECT CampaignId, AdGroupId, Id, Criteria, CriteriaType, '
                'FinalUrls, Impressions, Clicks, Cost '
                'FROM CRITERIA_PERFORMANCE_REPORT '
                'WHERE Status IN [ENABLED, PAUSED] '
                'DURING LAST_7_DAYS')

PHP

将选择器报告下载示例与 DownloadCriteriaReportWithAwql.php 进行比较。两者定义的报告类型和字段都一样,获得的报告也一样,但 AWQL 方式更简洁一些:

// Create report query to get the data for last 7 days.
$reportQuery = 'SELECT CampaignId, AdGroupId, Id, Criteria, CriteriaType, '
    . 'Impressions, Clicks, Cost FROM CRITERIA_PERFORMANCE_REPORT '
    . 'WHERE Status IN [ENABLED, PAUSED] DURING LAST_7_DAYS';

Perl

将我们刚刚运行的示例代码与 download_criteria_report_with_awql.pl 进行比较:获得的报告都一样,但 AWQL 更简洁一些。两种方式生成的报告类型和字段都一样。

my $report_query =
  "SELECT CampaignId, AdGroupId, Id, Criteria, CriteriaType, " .
  "Impressions, Clicks, Cost FROM CRITERIA_PERFORMANCE_REPORT " .
  "WHERE Status IN [ENABLED, PAUSED] " . "DURING $last_4_days, $yesterday";

在这种情况下,在后面紧跟 AWQL 的代码中定义报告的日期范围:

# Create report query.
my (undef, undef, undef, $mday, $mon, $year) = localtime(time - 60 * 60 * 24);
my $yesterday = sprintf("%d%02d%02d", ($year + 1900), ($mon + 1), $mday);
(undef, undef, undef, $mday, $mon, $year) =
  localtime(time - 60 * 60 * 24 * 4);
my $last_4_days = sprintf("%d%02d%02d", ($year + 1900), ($mon + 1), $mday);

Ruby

将我们刚刚运行的示例代码与 download_criteria_report_with_awql.rb 进行比较:获得的报告都一样,但 AWQL 更简洁一些。两种方式生成的报告类型和字段都一样。

report_query = 'SELECT CampaignId, AdGroupId, Id, Criteria, CriteriaType, ' +
    'Impressions, Clicks, Cost FROM CRITERIA_PERFORMANCE_REPORT ' +
    'WHERE Status IN [ENABLED, PAUSED] ' +
    'DURING %s' % date_range

在这种情况下,在后面紧跟 AWQL 的代码中定义日期范围:

# Prepare a date range for the last week. Instead you can use 'LAST_7_DAYS'.
date_range = '%s,%s' % [
    DateTime.parse((Date.today - 7).to_s).strftime('%Y%m%d'),
    DateTime.parse((Date.today - 1).to_s).strftime('%Y%m%d')
]

您已经了解了报告的基本原理,就拥有了开始构建自己的自定义报告平台所需的工具。

将代码示例用于实现自动化

在这里,我们将介绍使用代码示例来更新您的 AdWords 帐号的方式以及其他一些常用的用例,并了解如何以这些示例为基础,实现几乎任何类型的自动化。

暂停和恢复广告组

API 最常见的一种用例就是暂停和恢复广告组。例如,您可以在某商品库存售罄时暂停广告,从而更好地利用广告预算。

此用例凸显了将您自己的系统(例如库存跟踪)与 AdWords API 集成所带来的优势。

我们将使用代码示例暂停和恢复广告组:

Java

启动 IDE 并打开 UpdateAdGroup.java 示例。

我们再次看到之前见过的 main 中的典型样板代码。这次 main 在底部附近有一个用于广告组 ID 的占位符字符串。

public static void main(String[] args) throws Exception {
    // Generate a refreshable OAuth2 credential.
    Credential oAuth2Credential = new OfflineCredentials.Builder()
        .forApi(Api.ADWORDS)
        .fromFile()
        .build()
        .generateCredential();

    // Construct an AdWordsSession.
    AdWordsSession session = new AdWordsSession.Builder()
        .fromFile()
        .withOAuth2Credential(oAuth2Credential)
        .build();

    Long adGroupId = Long.parseLong("INSERT_AD_GROUP_ID_HERE");
}

这个 ID 从哪里来呢?您可以通过 AdGroupService 接口的 get() 方法以编程方式获取。获取 ID 的捷径是在查看该广告组时从 AdWords 网页界面的网址中抓取。

runExample 方法的代码同样有趣。让我们逐步了解其运行过程:

首先该代码获得对 AdGroupService 接口的引用,因为它将更新广告组。要更新其他实体,您需要使用相应的服务。对象、方法和服务中提供了完整的服务列表。

// Get the AdGroupService.
AdGroupServiceInterface adGroupService =
    adWordsServices.get(session, AdGroupServiceInterface.class);

然后,该代码会创建新的广告组对象,并将新对象的 ID 设置为其要更新的广告组的 ID。

// Create ad group with updated status.
AdGroup adGroup = new AdGroup();
adGroup.setId(adGroupId);

然后将状态设为 PAUSED

adGroup.setStatus(AdGroupStatus.PAUSED);

然后,使用新创建的广告组对象作为操作数,使用 SET 作为运算符,创建 AdGroupOperation

// Create operations.
AdGroupOperation operation = new AdGroupOperation();
operation.setOperand(adGroup);
operation.setOperator(Operator.SET);

最后,该代码调用 AdGroupService 接口的 mutate() 方法,传入广告组操作对象。

// Update ad group.
AdGroupReturnValue result = adGroupService.mutate(operations);

接下来,使用测试客户帐号中的广告组 ID 替换占位符,然后尝试运行代码。运行后,请在 AdWords 网页界面中登录测试帐号,并确认状态已更改。

C#

在 IDE 中,打开 UpdateAdGroup.cs 示例。

我们再次看到在之前章节中见过的 main 中的典型样板代码。这次 main 在底部附近有一个用于广告组 ID 的占位符字符串。

public static void Main(string[] args) {
    UpdateAdGroup codeExample = new UpdateAdGroup();
    Console.WriteLine(codeExample.Description);
    try {
      long adGroupId = long.Parse("INSERT_ADGROUP_ID_HERE");
      codeExample.Run(new AdWordsUser(), adGroupId);
    }
}

这个 ID 从哪里来呢?您可以通过 AdGroupService 接口的 get() 方法以编程方式获取。获取 ID 的捷径是在查看该广告组时从 AdWords 网页界面的网址中抓取。

runExample 方法的代码同样有趣。让我们逐步了解其运行过程:

首先该代码获得对 AdGroupService 接口的引用,因为它将更新广告组。要更新其他实体,您需要使用相应的服务。对象、方法和服务指南中提供了完整的服务列表。

public void Run(AdWordsUser user, long adGroupId) {
    // Get the AdGroupService.
    AdGroupService adGroupService =
        (AdGroupService) user.GetService(AdWordsService.v201710.AdGroupService);
}

然后,该代码会创建新的 AdGroup 对象,并将新对象的 ID 设置为其要更新的广告组的 ID。

// Create the ad group.
AdGroup adGroup = new AdGroup();
adGroup.status = AdGroupStatus.PAUSED;
adGroup.id = adGroupId;

该代码还将状态设置为 PAUSED

adGroup.status = AdGroupStatus.PAUSED;

然后,使用新创建的 adGroup 对象作为操作数,使用 SET 作为运算符,创建 AdGroupOperation

// Create the operation.
AdGroupOperation operation = new AdGroupOperation();
operation.@operator = Operator.SET;
operation.operand = adGroup;

最后,该代码调用 AdGroupService 接口的 mutate() 方法,传入 AdGroupOperation 对象。

// Update the ad group.
AdGroupReturnValue retVal = adGroupService.mutate(new AdGroupOperation[] {operation});

接下来,使用测试客户帐号中的广告组 ID 替换占位符,然后尝试运行代码。运行后,请在 AdWords 网页界面中登录测试帐号,并确认状态已更改。

Python

在 IDE 中,打开 update_ad_group.py 示例。

我们再次看到典型的样板代码,其中 LoadFromStorage 方法从 googleads.yaml 配置文件中提取凭据和属性。这次系统会为广告组的 ID 添加一个占位符字符串。

AD_GROUP_ID = 'INSERT_AD_GROUP_ID_HERE'

这个 ID 从哪里来呢?您可以通过 AdGroupService 接口的 get() 方法以编程方式获取。获取 ID 的捷径是在查看该广告组时从 AdWords 网页界面的网址中抓取。

之后的代码很有趣。让我们逐步了解其运行过程:

首先该代码获得对 AdGroupService 接口的引用,因为它将更新广告组。要更新其他实体,您需要使用相应的服务。对象、方法和服务指南中提供了完整的服务列表。

def main(client, ad_group_id):
  # Initialize appropriate service.
  ad_group_service = client.GetService('AdGroupService', version='v201710')

然后,代码将 ID 设置为其要更新的广告组的 ID,并将状态设置为 PAUSED

# Construct operations and update an ad group.
  operations = [{
      'operator': 'SET',
      'operand': {
          'id': ad_group_id,
          'status': 'PAUSED'

然后,该代码使用新创建的广告组对象作为操作数,使用 SET 作为运算符,创建广告组操作。同时,将状态设置为 PAUSED

# Construct operations and update an ad group.
  operations = [{
      'operator': 'SET',
      'operand': {
          'id': ad_group_id,
          'status': 'PAUSED'

最后,该代码调用广告组服务接口的 mutate() 方法,传入广告组操作对象。

ad_groups = ad_group_service.mutate(operations)

接下来,使用测试客户帐号中的广告组 ID 替换占位符,然后尝试运行代码。运行后,请在 AdWords 网页界面中登录测试帐号,并确认状态已更改。

PHP

在 IDE 中,打开 PauseAd.php

特定广告通过广告组和广告 ID 进行标识:

const AD_GROUP_ID = 'INSERT_AD_GROUP_ID_HERE';
const AD_ID = 'INSERT_AD_ID_HERE';

在查看广告组时,可以通过 AdGroupServiceget() 方法或 AdWords 网页界面的网址提取广告组 ID。

让我们逐步了解 runExample() 的运行过程:

  1. 因为将更新广告组,需要获得对 AdGroupService 的引用。
    $adGroupAdService =
        $adWordsServices->get($session, AdGroupAdService::class);
    
  2. 创建一个广告对象。
    $ad = new Ad();
    $ad->setId($adId);
    
  3. 创建一个广告组广告对象并设置其广告组 ID 和广告。
    $adGroupAd = new AdGroupAd();
    $adGroupAd->setAdGroupId($adGroupId);
    $adGroupAd->setAd($ad);
    
  4. 将广告组广告的状态设置为 PAUSED
    $adGroupAd->setStatus(AdGroupAdStatus::PAUSED);
    
  5. 设置一个操作并通过 mutate() 方法将其发送到 AdGroupAdService。
    // Create ad group ad operation and add it to the list.
    $operation = new AdGroupAdOperation();
    $operation->setOperand($adGroupAd);
    $operation->setOperator(Operator::SET);
    $operations[] = $operation;
    
    // Pause the ad on the server.
    $result = $adGroupAdService->mutate($operations);
    

使用测试客户帐号中的相应 ID 替换占位符并运行代码。运行完成后,请在 AdWords 网页界面中登录测试帐号,并确认状态已更改。

Perl

在 IDE 中,打开 update_ad_group.pl 示例。

我们再次在底部看到之前见过的典型样板代码,它从 adwords.properties 配置文件中获取凭据。

在此示例中,用占位符字符串代替您要暂停的广告组和广告的 ID。

# Replace with valid values of your account.
my $ad_group_id = "INSERT_AD_GROUP_ID_HERE";

这个 ID 从哪里来呢?您可以通过 AdGroupService 接口的 get() 方法以编程方式获取。获取 ID 的捷径是在查看该广告组时从 AdWords 网页界面的网址中抓取。

此示例中代码的有趣之处体现在运行时。让我们逐步了解其运行过程:

首先,它使用指定的 adGroupID 创建具有更新状态的广告组。要更新其他实体,请使用其相应的服务。对象、方法和服务指南中提供了完整的服务列表。然后代码将状态设置为 PAUSED

# Create ad group with updated status.
my $ad_group = Google::Ads::AdWords::v201710::AdGroup->new({
    id     => $ad_group_id,
    status => "PAUSED"
});

然后,使用新创建的广告组对象作为操作数,使用 SET 作为运算符,创建广告组操作。

# Create operation.
my $operation = Google::Ads::AdWords::v201710::AdGroupOperation->new({
    operand  => $ad_group,
    operator => "SET"
});

最后,该代码调用 AdGroupService 接口的 mutate() 方法,传入广告组操作对象。

# Update ad group.
my $result = $client->AdGroupService()->mutate({operations => [$operation]});

接下来,使用测试客户帐号中的广告组 ID 替换占位符,然后尝试运行代码。运行后,请在 AdWords 网页界面中登录测试帐号,并确认状态已更改。

Ruby

打开 update_ad_group.rb 示例。

我们再次从中看到之前见过的典型样板代码,它从 adwords_api.yml 配置文件中获取凭据。再往下一点我们会看到广告组 ID 的占位符字符串。

# ID of an ad group to update.
ad_group_id = 'INSERT_AD_GROUP_ID_HERE'.to_i

这个 ID 从哪里来呢?您可以通过 AdGroupService 接口的 get() 方法以编程方式获取。获取 ID 的捷径是在查看该广告组时从 AdWords 网页界面的网址中抓取。

同样,示例代码的有趣之处体现在运行时。让我们逐步了解其运行过程:

首先该代码获得对 AdGroupService 接口的引用,因为它将更新广告组。要更新其他实体,您需要使用相应的服务。对象、方法和服务指南中提供了完整的服务列表。

ad_group_srv = adwords.service(:AdGroupService, API_VERSION)

然后,该代码创建新的广告组对象,将新对象的 ID 设置为要更新的广告组的 ID,并使用 SET 作为运算符将其状态设置为 PAUSED

# Prepare for updating ad group.
operation = {
  :operator => 'SET',
  :operand => {
    :status => 'PAUSED',
    :id => ad_group_id
  }
}

最后,该代码调用 AdGroupService 接口的 mutate() 方法,传入广告组操作对象。

# Update ad group.
response = ad_group_srv.mutate([operation])

接下来,使用测试客户帐号中的广告组 ID 替换占位符,然后尝试运行代码。运行后,请在 AdWords 网页界面中登录测试帐号,并确认状态已更改。

模式回顾

通过 API 进行的大多数更新操作都会使用我们在前面暂停和恢复广告组时所使用的同一过程和模式,因此,我们很有必要回顾一下这些步骤:

  1. 创建新对象。
  2. 将其 ID 设置为要修改的实体的 ID。
  3. 为这个新对象的属性设置新的值。
  4. SET 作为运算符,以这个新的实体对象作为操作数,创建操作对象。
  5. 将这个操作对象传递到相应服务的 mutate() 方法中。

这是一个更新过程,所以我们使用 SET 运算符。添加或移除时则需要使用 ADDREMOVE 运算符。

如果感到困惑,可看看其他代码示例,您会很快了解这种模式。

了解该模式后,您可以轻松进行其他许多更新,例如修改广告组出价。

修改广告组的出价

另一个常见用例是以编程方式修改出价,经典示例是下雨时提高雨伞广告的出价。您的应用可以使用天气网络服务,然后通过 AdWords API 来提高相应广告组的出价。

您可以修改我们在上面看到的 UpdateAdGroup 示例来进行这一更新:需要设置出价策略,而不是设置 AdGroupStatus。有关详细信息,请参阅出价指南

制作新的广告系列

另一个用例:

Java

在 IDE 中查看 AddCampaigns.java

它包含大量代码,但仍遵循上述模式。在这种情况下,创建对象层级结构后,我们使用 ADD 运算符通过 BudgetService 添加新预算,通过 CampaignService 新建广告系列。

我们不需要在这里设置 ID,因为这些新实体还没有 ID。

C#

在 IDE 中查看 AddCampaigns.cs

它包含大量代码,但仍遵循上述模式。在这种情况下,创建对象层级结构后,我们使用 ADD 运算符通过 BudgetService 添加新预算,通过 CampaignService 新建广告系列。

我们不需要在这里设置 ID,因为这些新实体还没有 ID。

Python

在 IDE 中查看 add_campaigns.py

它包含大量代码,但仍遵循上述模式。在这种情况下,创建对象层级结构后,我们使用 ADD 运算符通过 BudgetService 添加新预算,通过 CampaignService 新建广告系列。

我们不需要在这里设置 ID,因为这些新实体还没有 ID。

PHP

在 IDE 中,打开 AddCampaigns.php

一如既往,runExample() 中包含了大部分逻辑。我们设置预算、广告系列和出价策略,并进行了网络定位和频次上限等可选设置。最后,我们用 ADD 运算符来封装这一广告系列,然后通过 mutate() 把这一操作发送给 CampaignService。

Perl

在 IDE 中查看 add_campaigns.pl

它包含大量代码,但仍遵循上述模式。在这种情况下,创建对象层级结构后,我们使用 ADD 运算符通过 BudgetService 添加新预算,通过 CampaignService 新建广告系列。

我们不需要在这里设置 ID,因为这些新实体还没有 ID。

Ruby

查看 add_campaigns.rb

它包含大量代码,但仍遵循上述模式。在这种情况下,创建对象层级结构后,我们使用 ADD 运算符通过 BudgetService 添加新预算,通过 CampaignService 新建广告系列。

我们不需要在这里设置 ID,因为这些新实体还没有 ID。

后续步骤

您已经了解了基础知识,现在最好查看对象、方法和服务以及相关指南,了解有关 API 的体系结构、服务和功能的更多信息。

然后,您就可以开始构建自己的应用,通过 AdWords API 实现自动化以提高效率并通过自定义报告获得更多洞见。

发送以下问题的反馈:

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