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

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

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

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

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)، ما يؤدي إلى إصدار طرق الخدمة تحذيرًا وإرجاع كائن 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