استفاده پایه

این راهنما اصول اولیه استفاده از کتابخانه کلاینت Perl برای API تبلیغات گوگل را توضیح می‌دهد.

کلاینت را مقداردهی اولیه کنید

برای شروع استفاده از کتابخانه، یک نمونه از Google::Ads::GoogleAds::Client ایجاد کنید. کلاینت را می‌توان به روش‌های مختلفی پیکربندی کرد، همانطور که در راهنمای پیکربندی به تفصیل شرح داده شده است. یک رویکرد رایج استفاده از فایل googleads.properties است:

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

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

ایجاد یک سرویس

پس از مقداردهی اولیه کلاینت، می‌توانید نمونه‌هایی از سرویس‌های مختلف API ایجاد کنید. به عنوان مثال، برای تعامل با کمپین‌ها، باید یک نمونه CampaignService ایجاد کنید:

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

یک فراخوانی API انجام دهید

در اینجا مثالی از نحوه برقراری تماس API برای دریافت کمپین‌ها آورده شده است. این قطعه کد، مقداردهی اولیه کلاینت، ایجاد یک سرویس و فراخوانی یک متد را نشان می‌دهد.

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

مدیریت خطاها

فراخوانی‌های API می‌توانند منجر به استثنائاتی شوند. شما باید فراخوانی‌های API خود را در بلوک‌های 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