Cách dùng cơ bản

Hướng dẫn này giải thích những thông tin cơ bản về cách sử dụng thư viện ứng dụng Perl cho Google Ads API.

Khởi chạy ứng dụng

Để bắt đầu sử dụng thư viện, hãy tạo một thực thể của Google::Ads::GoogleAds::Client. Bạn có thể định cấu hình ứng dụng theo nhiều cách, như được trình bày chi tiết trong Hướng dẫn định cấu hình. Một phương pháp phổ biến là sử dụng tệp googleads.properties:

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

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

Tạo dịch vụ

Sau khi khởi chạy ứng dụng, bạn có thể tạo các thực thể của nhiều dịch vụ API. Ví dụ: để tương tác với các chiến dịch, bạn sẽ tạo một thực thể CampaignService:

use strict;
use warnings;

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

Theo mặc định, $api_client sẽ tải các dịch vụ cho DEFAULT_API_VERSION của bản phát hành thư viện đã cài đặt (V26 trong bản phát hành mới nhất; các bản phát hành nhỏ như v25.1 sử dụng mô-đun phiên bản lớn, V25). Để nhắm đến một phiên bản API cụ thể được hỗ trợ, hãy truyền version => "V26" đến Client->new({...}) hoặc gọi $api_client->set_version("V26").

Thực hiện lệnh gọi API

Sau đây là ví dụ về cách thực hiện lệnh gọi API để lấy thông tin về chiến dịch. Đoạn mã này minh hoạ cách khởi chạy ứng dụng, tạo dịch vụ và gọi một phương thức.

use strict;
use warnings;
use Google::Ads::GoogleAds::Client;
use Google::Ads::GoogleAds::V26::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::V26::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};
}

Xử lý lỗi

Lệnh gọi API có thể dẫn đến lỗi. Theo mặc định, die_on_faults là 0 (false), khiến các phương thức dịch vụ phát ra cảnh báo và trả về đối tượng Google::Ads::GoogleAds::GoogleAdsException khi xảy ra lỗi API. Bạn có thể kiểm tra xem phản hồi được trả về có phải là GoogleAdsException hay không và gọi get_google_ads_failure() để kiểm tra từng mục GoogleAdsError.

Ngoài ra, nếu bạn đặt die_on_faults => 1 trên Client->new({...}) (hoặc gọi $api_client->set_die_on_faults(1)), thì các phương thức dịch vụ sẽ gọi die() bằng phản hồi lỗi JSON thô khi xảy ra lỗi API mà bạn có thể phát hiện trong khối eval (if ($@)).

use strict;
use warnings;
use Scalar::Util qw(blessed);
use Google::Ads::GoogleAds::Client;
use Google::Ads::GoogleAds::V26::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::V26::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};
  }
}

Khám phá các ví dụ khác

Bạn có thể tìm thấy một số mã mẫu hữu ích trong thư mục ví dụ. Hầu hết các ví dụ đều yêu cầu tham số. Bạn có thể truyền các tham số dưới dạng đối số (nên dùng) hoặc chỉnh sửa các giá trị INSERT_XXXXX_HERE trong mã nguồn. Để xem câu lệnh sử dụng cho một ví dụ, hãy truyền -help làm đối số dòng lệnh.

perl examples/basic_operations/get_campaigns.pl -help