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

يوضّح هذا الدليل أساسيات استخدام مكتبة برامج Perl لعميل Google Ads API.

إعداد العميل

لبدء استخدام المكتبة، أنشئ مثيلاً من Google::Ads::GoogleAds::Client. يمكن ضبط إعدادات العميل بعدة طرق، كما هو موضّح بالتفصيل في دليل الإعداد. يتم عادةً استخدام ملف googleads.properties:

use Google::Ads::GoogleAds::Client;

my $api_client = Google::Ads::GoogleAds::Client->new();

إنشاء خدمة

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

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

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

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

use strict;
use warnings;
use Google::Ads::GoogleAds::Client;
use Google::Ads::GoogleAds::V22::Services::GoogleAdsService::SearchGoogleAdsRequest;

# Initialize the Google Ads client. See the [Configuration guide](configuration) for more 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::V22::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};
}

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

يمكن أن تؤدي طلبات البيانات من واجهة برمجة التطبيقات إلى حدوث استثناءات. يجب تضمين طلبات البيانات من واجهة برمجة التطبيقات في حِزم eval لحصر Google::Ads::GoogleAds::GoogleAdsException والتعامل معه.

use strict;
use warnings;
use Google::Ads::GoogleAds::Client;
use Google::Ads::GoogleAds::GoogleAdsException;
use Google::Ads::GoogleAds::V22::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::V22::Services::GoogleAdsService::SearchGoogleAdsRequest->new({
    customerId => $customer_id,
    query      => $query
});

eval {
    my $search_response = $google_ads_service->search($search_request);
    # Process successful response.
    foreach my $google_ads_row (@{$search_response->{results}}) {
        printf "Campaign name: %s\n", $google_ads_row->{campaign}->{name};
    }
};
if ($@) {
    if (blessed($@) && $@->isa('Google::Ads::GoogleAds::GoogleAdsException')) {
        my $exception = $@;
        printf "A Google Ads exception occurred:\n";
        printf " Request ID: %s\n", $exception->get_request_id();
        foreach my $error (@{$exception->get_errors()}) {
            printf " Error code: %s\n", $error->{errorCode};
            printf " Message: %s\n", $error->{message};
        }
    } else {
        # Print other types of exceptions.
        print "An error occurred: $@\n";
    }
}

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

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

perl examples/basic_operations/get_campaigns.pl -help