代码示例和用例

在此之前,我们引导您进行了设置,以进行首次 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);
  }

.NET

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

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

.NET 库中最重要的类是 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

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

try {
  // Get AdWordsUser from credentials in "../auth.ini"
  // relative to the AdWordsUser.php file's directory.
  $user = new AdWordsUser();

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

但是,如果您在经理帐号下有很多客户帐号,该怎么办?在这种情况下,您可以从 auth.ini 文件中移除客户帐号的客户 ID,并使用要设置为客户帐号的客户 ID 的参数,通过调用 AdWordUser 对象的 SetClientCustomerId() 进行编程设置:

// Create an AdWordsUser instance using the default constructor, which will load
// information from the auth.ini file as described above.
$user = new AdWordsUser();
$user->SetClientCustomerId('123-456-7890');

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 => "v201609"});

回想一下,在前一个指南中,我们在 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 => "v201609"});
$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"));

.NET

转到 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.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.py。

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

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

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

PHP

转到 IDE 并打开 DownloadCriteriaReport.php

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

  // Get AdWordsUser from credentials in "../auth.ini"
  // relative to the AdWordsUser.php file's directory.
  $user = new AdWordsUser();

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

  // Create report definition.
  $reportDefinition = new ReportDefinition();
  $reportDefinition->selector = $selector;
  $reportDefinition->reportName = 'Criteria performance report #' . uniqid();
  $reportDefinition->dateRangeType = 'LAST_7_DAYS';
  $reportDefinition->reportType = 'CRITERIA_PERFORMANCE_REPORT';
  $reportDefinition->downloadFormat = 'CSV';

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

  // Download report.
  ReportUtils::DownloadReport($reportDefinition, $filePath, $user, $options);
  printf("Report with name '%s' was downloaded to '%s'.\n",
      $reportDefinition->reportName, $filePath);

下面我们运行 DownloadCriteriaReport.php。

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

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

$reportDefinition->reportType = 'CRITERIA_PERFORMANCE_REPORT';

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

$selector->fields = array('CampaignId', 'AdGroupId', 'Id', 'Criteria',
      'CriteriaType', 'Impressions', 'Clicks', 'Cost');

Perl

转到 IDE 并打开 download_criteria_report.pl

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

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

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

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.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.rb

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

def download_criteria_report(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',

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

 # 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.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";

.NET

将我们刚刚运行的示例代码与 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 更简洁一些。两种方式生成的报告类型和字段都一样。

$reportQuery = 'SELECT CampaignId, AdGroupId, Id, Criteria, CriteriaType, '
      . 'Impressions, Clicks, Cost FROM CRITERIA_PERFORMANCE_REPORT '
      . 'WHERE Status IN [ENABLED, PAUSED] DURING ' . $dateRange;

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

  // Prepare a date range for the last week. Instead you can use 'LAST_7_DAYS'.
  $dateRange = sprintf('%d,%d',
      date('Ymd', strtotime('-7 day')), date('Ymd', strtotime('-1 day')));

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 网页界面中登录测试帐号,并确认状态已更改。

.NET

在 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.v201609.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='v201609')

然后,代码将 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 示例。

我们再次看到典型的样板代码,此代码从 auth.ini 配置文件中提取身份验证信息。

这次,广告组和广告的 ID 有一个占位符字符串。

// Enter parameters required by the code example.
$adGroupId = 'INSERT_AD_GROUP_ID_HERE';
$adId = 'INSERT_AD_ID_HERE';

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

不过,这个例子是在运行示例时出现有趣的代码。让我们逐步了解其运行过程:

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

  // Get the service, which loads the required classes.
  $adGroupAdService = $user->GetService('AdGroupAdService', ADWORDS_VERSION);

然后使用现有 ID 制作广告。

  // Create ad using an existing ID. Use the base class Ad instead of TextAd to
  // avoid having to set ad-specific fields.
  $ad = new Ad();
  $ad->id = $adId;
然后,该代码会创建新的广告组对象,并将新对象的 ID 设置为其要更新的广告组的 ID。

  // Create ad group ad.
  $adGroupAd = new AdGroupAd();
  $adGroupAd->adGroupId = $adGroupId;
  $adGroupAd->ad = $ad;

然后将状态设为 PAUSED

  // Update the status.
  $adGroupAd->status = 'PAUSED';

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

  // Create operation.
  $operation = new AdGroupAdOperation();
  $operation->operand = $adGroupAd;
  $operation->operator = 'SET';
  $operations = array($operation);

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

  // Make the mutate request.
  $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::v201609::AdGroup->new({
      id     => $ad_group_id,
      status => "PAUSED"
  });

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

# Create operation.
  my $operation = Google::Ads::AdWords::v201609::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 网页界面的网址中抓取。

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

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

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。

.NET

在 IDE 中查看 AddCampaigns.cs

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

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

Python

在 IDE 中查看 add_campaigns.py

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

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

PHP

在 IDE 中查看 AddCampaigns.php

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

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

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
需要帮助?请访问我们的支持页面