การใช้งานพื้นฐาน

คู่มือนี้อธิบายพื้นฐานการใช้ไลบรารีของไคลเอ็นต์ Perl สำหรับ Google Ads API

เริ่มต้นไคลเอ็นต์

หากต้องการเริ่มใช้ไลบรารี ให้สร้างอินสแตนซ์ของ 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 ของรุ่นไลบรารีที่ติดตั้ง (V26 ในรุ่นล่าสุด รุ่นย่อย เช่น v25.1 จะใช้โมดูลเวอร์ชันหลัก V25) หากต้องการกำหนดเป้าหมายเป็นเวอร์ชัน API ที่รองรับที่เฉพาะเจาะจง ให้ส่ง version => "V26" ไปยัง Client->new({...}) หรือเรียกใช้ $api_client->set_version("V26")

ทำการเรียก API

ต่อไปนี้เป็นตัวอย่างวิธีการเรียก API เพื่อรับแคมเปญ ข้อมูลโค้ดนี้แสดงการเริ่มต้นไคลเอ็นต์ การสร้างบริการ และการเรียกใช้เมธอด

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};
}

จัดการข้อผิดพลาด

การเรียก API อาจทำให้เกิดข้อผิดพลาด โดยค่าเริ่มต้น die_on_faults จะเป็น 0 (false) ซึ่งทำให้เมธอดบริการแสดงคำเตือนและแสดงผลออบเจ็กต์ Google::Ads::GoogleAds::GoogleAdsException เมื่อเกิดข้อผิดพลาดเกี่ยวกับ API คุณสามารถตรวจสอบว่าการตอบกลับที่แสดงผลเป็น GoogleAdsException หรือไม่ และเรียกใช้ get_google_ads_failure() เพื่อตรวจสอบรายการ GoogleAdsError แต่ละรายการ

หรือหากคุณตั้งค่า die_on_faults => 1 ใน Client->new({...}) (หรือเรียกใช้ $api_client->set_die_on_faults(1)) เมธอดบริการจะเรียกใช้ die() ด้วยการตอบสนองข้อผิดพลาด JSON แบบข้อมูลดิบเมื่อเกิดข้อผิดพลาดของ API ซึ่งคุณสามารถตรวจจับได้ในบล็อก 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};
  }
}

ดูตัวอย่างอื่นๆ

คุณดูตัวอย่างโค้ดที่มีประโยชน์หลายรายการได้ในไดเรกทอรีตัวอย่าง ตัวอย่างส่วนใหญ่ต้องใช้พารามิเตอร์ คุณสามารถส่งพารามิเตอร์เป็นอาร์กิวเมนต์ (แนะนำ) หรือแก้ไขค่า INSERT_XXXXX_HERE ในซอร์สโค้ดก็ได้ หากต้องการดูคำสั่งการใช้งานสำหรับตัวอย่าง ให้ส่ง -help เป็นอาร์กิวเมนต์บรรทัดคำสั่ง

perl examples/basic_operations/get_campaigns.pl -help