基本用法

本指南介绍了如何使用 Google Ads API 的 Perl 客户端库的基础知识。

初始化客户端

如需开始使用该库，请创建 Google::Ads::GoogleAds::Client 的实例。客户端可以通过多种方式进行配置，详情请参阅配置指南。一种常见的方法是使用 googleads.properties 文件：

use strict;
use warnings;
use Google::Ads::GoogleAds::Client;

my $api_client = Google::Ads::GoogleAds::Client->new();

创建服务

初始化客户端后，您可以创建各种 API 服务的实例。例如，如需与广告系列互动，您可以创建 CampaignService 实例：

use strict;
use warnings;

my $campaign_service = $api_client->CampaignService();

默认情况下，$api_client 会为已安装的库版本（最新版本为 V25；次要版本（如 v25.1）使用其主要版本模块 V25）的 DEFAULT_API_VERSION 加载服务。如需以特定支持的 API 版本为目标，请将 version => "V25" 传递给 Client->new({...}) 或调用 $api_client->set_version("V25")。

进行 API 调用

以下示例展示了如何通过 API 调用获取广告系列。此代码段演示了如何初始化客户端、创建服务和调用方法。

use strict;
use warnings;
use Google::Ads::GoogleAds::Client;
use Google::Ads::GoogleAds::V25::Services::GoogleAdsService::SearchGoogleAdsRequest;

# Initialize the Google Ads client. See the Configuration guide for options.
my $api_client = Google::Ads::GoogleAds::Client->new();

# Get the GoogleAdsService.
my $google_ads_service = $api_client->GoogleAdsService();

# Specify the customer ID and query.
my $customer_id = "INSERT_CUSTOMER_ID_HERE";
my $query = "SELECT campaign.name, campaign.status FROM campaign";

# Create a search request.
my $search_request =
  Google::Ads::GoogleAds::V25::Services::GoogleAdsService::SearchGoogleAdsRequest
  ->new({
    customerId => $customer_id,
    query      => $query,
  });

# Execute the search request.
my $search_response = $google_ads_service->search($search_request);

# Iterate over the results and print campaign names.
foreach my $google_ads_row (@{$search_response->{results} || []}) {
  printf "Campaign with resource name '%s' and name '%s'.\n",
    $google_ads_row->{campaign}->{resourceName},
    $google_ads_row->{campaign}->{name};
}

处理错误

API 调用可能会导致错误。默认情况下，die_on_faults 为 0 (false)，这会导致服务方法在发生 API 错误时发出警告并返回 Google::Ads::GoogleAds::GoogleAdsException 对象。您可以检查返回的响应是否为 GoogleAdsException，并调用 get_google_ads_failure() 来检查各个 GoogleAdsError 条目。

或者，如果您在 Client->new({...}) 上设置 die_on_faults => 1（或调用 $api_client->set_die_on_faults(1)），则当 API 出现故障时，服务方法会使用原始 JSON 错误响应调用 die()，您可以在 eval 块 (if ($@)) 中捕获该响应。

use strict;
use warnings;
use Scalar::Util qw(blessed);
use Google::Ads::GoogleAds::Client;
use Google::Ads::GoogleAds::V25::Services::GoogleAdsService::SearchGoogleAdsRequest;

my $api_client = Google::Ads::GoogleAds::Client->new();
my $google_ads_service = $api_client->GoogleAdsService();
my $customer_id = "INSERT_CUSTOMER_ID_HERE";
my $query = "SELECT campaign.name, campaign.status FROM campaign";
my $search_request =
  Google::Ads::GoogleAds::V25::Services::GoogleAdsService::SearchGoogleAdsRequest
  ->new({
    customerId => $customer_id,
    query      => $query,
  });

my $search_response = $google_ads_service->search($search_request);

if (blessed($search_response)
  && $search_response->isa("Google::Ads::GoogleAds::GoogleAdsException"))
{
  printf "An API exception occurred (HTTP %s, status '%s'): %s\n",
    $search_response->get_code(),
    $search_response->get_status(),
    $search_response->get_message();

  my $google_ads_failure = $search_response->get_google_ads_failure();
  if ($google_ads_failure) {
    foreach my $error (@{$google_ads_failure->{errors} || []}) {
      my ($error_type, $error_value) = %{$error->{errorCode} || {}};
      printf "  Error code (%s): %s\n",
        $error_type  || "unknown",
        $error_value || "UNKNOWN";
      printf "  Message: %s\n", $error->{message};
    }
  }
} else {
  foreach my $google_ads_row (@{$search_response->{results} || []}) {
    printf "Campaign name: %s\n", $google_ads_row->{campaign}->{name};
  }
}

探索其他示例

您可以在 examples 目录中找到多个有用的代码示例。大多数示例都需要参数。您可以将参数作为实参传递（推荐），也可以修改源代码中的 INSERT_XXXXX_HERE 值。如需查看示例的用法语句，请传递 -help 作为命令行实参。

perl examples/basic_operations/get_campaigns.pl -help