استفاده اساسی

این راهنما اصول اولیه استفاده از کتابخانه کلاینت Perl برای 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 نسخه کتابخانه نصب شده شما را بارگذاری می‌کند ( 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 است یا خیر و برای بررسی ورودی‌های GoogleAdsError تابع get_google_ads_failure() را فراخوانی کنید.

از طرف دیگر، اگر در Client->new({...}) die_on_faults => 1 تنظیم کنید (یا $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::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