基本用法

本指南說明如何使用 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 會載入DEFAULT_API_VERSION已安裝程式庫版本的服務 (最新版本為 V25；次要版本 (例如 v25.1) 會使用主要版本模組 V25)。如要指定支援的 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};
  }
}

查看其他範例

您可以在範例目錄中找到幾個實用的程式碼範例。大多數範例都需要參數。您可以將參數當做引數傳遞 (建議)，也可以編輯原始碼中的 INSERT_XXXXX_HERE 值。如要查看範例的用法陳述式，請將 -help 做為指令列引數傳遞。

perl examples/basic_operations/get_campaigns.pl -help