GAPIC

کد منبع در فهرست راهنمای src/Google/Ads/GoogleAds/VX کتابخانه کارخواه PHP در Google Ads API، که X شماره نسخه Google Ads API است، به‌طور خودکار بااستفاده از GAPIC (Generated API Client) Generator، براساس فایل‌های proto منتشرشده تولید می‌شود.

سپس کد منبع تولیدشده اصلاح می‌شود تا حاوی ارجاعاتی به ویژگی‌ها و کلاس‌های موردنیاز برای ایجاد مشتریان سرویس باشد که بااستفاده از کلاس GoogleAdsClient که با فراخوانی GoogleAdsClientBuilder::build() ایجاد می‌شود، با Google Ads API کار می‌کنند. GoogleAdsClient و GoogleAdsClientBuilder هر دو کلاس‌هایی هستند که به‌صورت دستی نگهداری می‌شوند و در src/Google/Ads/GoogleAds/Lib/VX/ قرار دارند.

مکان‌های کلاس تولیدشده

کارخواهان سرویس پس‌پردازش‌شده در src/Google/Ads/GoogleAds/VX/Services/Client/ (برای مثال، V26) قرار دارند و کلاس‌های پیام درخواست و پاسخ مربوطه (مانند MutateCampaignsRequest و SearchGoogleAdsRequest) در src/Google/Ads/GoogleAds/VX/Services/ قرار دارند. نسخه‌های جزئی API (مثل v25.1) در دایرکتوری نسخه اصلی (V25) تولید می‌شوند.

کاربرد

باید یک شیء درخواست ایجاد کنید و آن را به کارخواه سرویسی که می‌خواهید استفاده کنید ارسال کنید. بسته به اینکه پارامترها الزامی یا اختیاری باشند، چند روش برای ایجاد شیء درخواست دارید، ازجمله روش کارخانه build() ایستا برای ارسال پارامترهای الزامی.

نمونه ۱.۱: روش‌های دارای پارامترهای الزامی

نمونه کد زیر نحوه فراخوانی CampaignServiceClient::mutateCampaigns() را نشان می‌دهد. چون هر دو $customerId و $campaignOperations پارامترهای الزامی هستند، یک روش کارخانه build() ایستا که هر دو پارامتر را می‌پذیرد در کلاس درخواست تولید می‌شود.

الگوی ۱: روش ساخت ایستا (توصیه‌شده)

$campaignServiceClient = $googleAdsClient->getCampaignServiceClient();
$response = $campaignServiceClient->mutateCampaigns(
    MutateCampaignsRequest::build(
        $customerId,
        $campaignOperations
    )
);

الگوی ۲: تنظیم‌کننده‌های روان

$campaignServiceClient = $googleAdsClient->getCampaignServiceClient();
$request = (new MutateCampaignsRequest())
    ->setCustomerId($customerId)
    ->setCampaignOperations($campaignOperations);
$response = $campaignServiceClient->mutateCampaigns($request);

مثال ۱.۲: روش‌هایی با پارامترهای الزامی و اختیاری

کد نمونه زیر GoogleAdsServiceClient::search() را فراخوانی می‌کند. در این مثال، روش build() تولیدشده فقط دو پارامتر را می‌پذیرد ($customerId و $query) زیرا این پارامترها الزامی هستند. برای درخواست تعداد کل نتایجی که با پُرسمان مطابقت دارند و نادیده گرفتن عبارت LIMIT، می‌توانید آن را به‌طور صریح بااستفاده از setReturnTotalResultsCount() تنظیم کنید. یا می‌توانید همه پارامترها را باهم در یک آرایه انجمنی به سازنده SearchGoogleAdsRequest ارسال کنید، همان‌طور که در «الگوی ۳» نشان داده شده است.

الگوی ۱: روش ساخت ایستا با تنظیم‌کننده‌های روان

$googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient();
$response = $googleAdsServiceClient->search(
    SearchGoogleAdsRequest::build($customerId, $query)
        ->setReturnTotalResultsCount(true)
);

الگوی ۲: تنظیم‌کننده‌های روان

$googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient();
$request = (new SearchGoogleAdsRequest())
    ->setCustomerId($customerId)
    ->setQuery($query)
    ->setReturnTotalResultsCount(true);
$response = $googleAdsServiceClient->search($request);

الگوی ۳: سازنده آرایه

$googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient();
$request = new SearchGoogleAdsRequest([
    'customer_id' => $customerId,
    'query' => $query,
    'return_total_results_count' => true
]);
$response = $googleAdsServiceClient->search($request);

مثال ۲: روش‌هایی که فقط پارامترهای اختیاری دارند

این مثال نحوه فراخوانی GeoTargetConstantServiceClient::suggestGeoTargetConstants() را نشان می‌دهد. ازآنجایی‌که همه پارامترهای GeoTargetConstantServiceClient::suggestGeoTargetConstants() اختیاری هستند، در این مورد build() در کد منبع تولید نمی‌شود—باید شیء درخواست را بااستفاده از تنظیم‌کننده‌ها یا سازنده آرایه بسازید.

الگوی ۱: تنظیم‌کننده‌های روان (توصیه‌شده)

$geoTargetConstantServiceClient =
    $googleAdsClient->getGeoTargetConstantServiceClient();
$request = (new SuggestGeoTargetConstantsRequest())
    ->setLocale($locale)
    ->setCountryCode($countryCode)
    ->setLocationNames(new LocationNames(['names' => $locationNames]));
$response =
    $geoTargetConstantServiceClient->suggestGeoTargetConstants($request);

الگوی ۲: سازنده آرایه

$geoTargetConstantServiceClient =
    $googleAdsClient->getGeoTargetConstantServiceClient();
$response = $geoTargetConstantServiceClient->suggestGeoTargetConstants(
    new SuggestGeoTargetConstantsRequest([
        'locale' => $locale,
        'country_code' => $countryCode,
        'location_names' => new LocationNames(['names' => $locationNames])
    ])
);