Cách dùng cơ bản

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

Khởi động ứ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 một dịch vụ

Sau khi khởi chạy ứng dụng, bạn có thể tạo các phiên bản 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 phiên bản 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 (V25 trong bản phát hành mới nhất; các bản phát hành phụ như v25.1 sẽ sử dụng mô-đun phiên bản chính của chúng, V25). Để nhắm đến một phiên bản API cụ thể được hỗ trợ, hãy truyền version => "V25" đến Client->new({...}) hoặc gọi $api_client->set_version("V25").

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

Sau đây là ví dụ về cách thực hiện một lệnh gọi API để nhận chiến dịch. Đoạn mã này minh hoạ cách khởi chạy ứng dụng khách, tạo một 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::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};
}

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), điều này khiến các phương thức dịch vụ phát ra cảnh báo và trả về một đố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)), 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. Bạn có thể bắt lỗi này trong một khối 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};
  }
}

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

Bạn có thể tìm thấy một số mẫu mã hữu ích trong thư mục examples. 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 nội dung khai báo về cách 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