الاستخدام الأساسي

يوضّح هذا الدليل أساسيات استخدام مكتبة برامج 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();

إنشاء خدمة

بعد إعداد العميل، يمكنك إنشاء مثيلات لخدمات واجهات برمجة التطبيقات المختلفة. على سبيل المثال، للتفاعل مع الحملات، عليك إنشاء مثيل CampaignService:

use strict;
use warnings;

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

بشكل تلقائي، تحمّل $api_client الخدمات الخاصة برقم الإصدار الرئيسي DEFAULT_API_VERSION من مكتبتك المثبّتة (V25 في أحدث إصدار، والإصدارات الثانوية مثل v25.1 تستخدم وحدة الإصدار الرئيسي، V25). لاستهداف إصدار معيّن من واجهة برمجة التطبيقات المتوافقة، مرِّر version => "V25" إلى Client->new({...}) أو اتّصِل بـ $api_client->set_version("V25").

إجراء طلب بيانات من واجهة برمجة التطبيقات

في ما يلي مثال على كيفية إجراء طلب بيانات من واجهة برمجة التطبيقات للحصول على الحملات. يوضّح هذا المقتطف عملية تهيئة البرنامج وإنشاء خدمة واستدعاء طريقة.

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

معالجة الأخطاء

يمكن أن تؤدي طلبات البيانات من واجهة برمجة التطبيقات إلى حدوث أخطاء. القيمة التلقائية لـ die_on_faults هي 0 (false)، ما يؤدي إلى أن تُصدر طرق الخدمة تحذيرًا وتعرض كائن 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::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};
  }
}

استكشاف أمثلة أخرى

يمكنك العثور على العديد من عيّنات الرموز المفيدة في دليل الأمثلة. تتطلّب معظم الأمثلة مَعلمات. يمكنك تمرير المَعلمات كوَسائط (وهذا الإجراء يُنصح به) أو تعديل قيم INSERT_XXXXX_HERE في الرمز المصدر. للاطّلاع على بيان استخدام لأحد الأمثلة، مرِّر -help كمعلَمة في سطر الأوامر.

perl examples/basic_operations/get_campaigns.pl -help