GAPIC

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

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

کد منبع GAPIC v2

از نسخه 20.1.0 ، کتابخانه سرویس گیرنده همچنین شامل نسخه جدیدی از کد منبع GAPIC در src/Google/Ads/GoogleAds/vX که از ارسال یک شی درخواست به روش های سرویس گیرندگان پشتیبانی می کند. این نسخه جدید که GAPIC v2 نام دارد به عنوان آماده سازی برای ویژگی های جدید در آینده نیز عمل می کند. کد منبع قبلی GAPIC، GAPIC v1، هنوز تولید می شود و تا پایان سال 2023 با هر نسخه همراه است.

کتابخانه سرویس گیرنده Google Ads API PHP به شما امکان می دهد نسخه ای را برای پیوند به GoogleAdsClient با استفاده از تنظیمات پیکربندی useGapicV2Source انتخاب کنید. وقتی این تنظیم روی true تنظیم شود، کتابخانه سرویس گیرنده یک شی GoogleAdsClient ایجاد می کند که سرویس گیرندگان GAPIC v2 را ایجاد می کند.

مکان های کلاس ایجاد شده

در اینجا تفاوت در مکان فایل بین نسخه های GAPIC برای دو نوع کلاس وجود دارد:

src/Google/Ads/GoogleAds/VX/Services/Gapic/

src/Google/Ads/GoogleAds/VX/Services/

src/Google/Ads/GoogleAds/VX/Services/Client/

استفاده

GAPIC v1 از شما می‌خواهد که هر پارامتر درخواست را مستقیماً به یک متد ارسال کنید، در حالی که GAPIC v2 از شما می‌خواهد به جای آن یک شی درخواست ارسال کنید. توجه داشته باشید که در برخی موارد، شما بیش از یک راه برای ایجاد یک شی درخواست دارید زیرا GAPIC v2 همچنین یک متد راحت به نام build() برای ارسال پارامترهای مورد نیاز تولید می‌کند.

مثال 1.1: روش هایی با پارامترهای مورد نیاز

کد نمونه زیر فراخوانی CampaignService::mutate() در GAPIC v1 و v2 مقایسه می کند. توجه داشته باشید که همه پارامترها ( $customerId و $operations ) پارامترهای مورد نیاز هستند، بنابراین build() که هر دو پارامتر را می پذیرد در کد GAPIC v2 تولید می شود.

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

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

N/A

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

مثال 1.2: روش هایی با پارامترهای مورد نیاز و پارامترهای اختیاری

کد نمونه زیر فراخوانی GoogleAdsServiceClient::search() در GAPIC v1 و v2 مقایسه می کند. در این مثال، build() که در کد منبع GAPIC v2 تولید می‌شود، تنها دو پارامتر ( $customerId و $query ) را می‌پذیرد، زیرا آنها پارامترهای مورد نیاز هستند. برای تنظیم اندازه صفحه، که یک پارامتر اختیاری است، باید آن را به صراحت با استفاده از setPageSize() تنظیم کنید. همچنین، می‌توانید تمام پارامترها را با هم به سازنده SearchGoogleAdsRequest ارسال کنید، همانطور که در الگوی 3 نشان داده شده است.

$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$response = $googleAdsServiceClient->search(
    $customerId,
    $query,
    ['pageSize' => self::PAGE_SIZE]
);
      

$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$response = $googleAdsServiceClient->search(
    SearchGoogleAdsRequest::build($customerId, $query)
        ->setPageSize(self::PAGE_SIZE)
);
      

N/A

$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$request = (new SearchGoogleAdsRequest())
    ->setCustomerId($customerId)
    ->setQuery($query)
    ->setPageSize(self::PAGE_SIZE);
$response = $googleAdsServiceClient->search($request);
      

N/A

$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$request = (new SearchGoogleAdsRequest([
    'customer_id' => $customerId,
    'query' => $query,
    'page_size' => self::PAGE_SIZE
]);
$response = $googleAdsServiceClient->search($request);
      

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

فراخوانی GeoTargetConstantServiceClient::suggestGeoTargetConstants() در GAPIC v1 و v2 مقایسه کنید. از آنجایی که تمام پارامترهای GeoTargetConstantServiceClient::suggestGeoTargetConstants() اختیاری هستند، build() در کد منبع GAPIC v2 در این مورد ایجاد نمی‌شود—شما باید خودتان شی درخواست را ایجاد کنید.

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

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

N/A

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