استفاده پایه

این راهنما اصول استفاده از کتابخانه کارخواه 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، استفاده می‌کنند). برای هدف‌یابی نسخه میانای برنامه‌سازی کاربردی پشتیبانی‌شده خاص، 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};
}

مدیریت کردن خطاها

فراخوان‌های میانای برنامه‌سازی کاربردی ممکن است منجر به خطا شوند. به‌طور پیش‌فرض، die_on_faults 0 (false) است، که باعث می‌شود روش‌های سرویس هشدار صادر کنند و هنگام وقوع خطای API، شیء Google::Ads::GoogleAds::GoogleAdsException را برگردانند. می‌توانید بررسی کنید که آیا پاسخ برگردانده‌شده GoogleAdsException است یا نه و get_google_ads_failure() را فراخوانی کنید تا ورودی‌های GoogleAdsError تکی را بازرسی کنید.

یا اگر die_on_faults => 1 را روی Client->new({...}) تنظیم کنید (یا $api_client->set_die_on_faults(1) را فراخوانی کنید)، روش‌های سرویس هنگام وقوع خطای میانای برنامه‌سازی کاربردی، die() را با پاسخ خطای JSON خام فراخوانی می‌کنند که می‌توانید آن را در بلوک 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