गैप

Google Ads API PHP क्लाइंट लाइब्रेरी की src/Google/Ads/GoogleAds/vX डायरेक्ट्री में मौजूद सोर्स कोड, जिसमें X Google Ads API का वर्शन है. यह पब्लिश की गई प्रोटो फ़ाइलों के आधार पर, GAPIC (जनरेट किया गया एपीआई क्लाइंट) जनरेटर का इस्तेमाल करके अपने-आप जनरेट होता है.

इसके बाद, जनरेट किए गए सोर्स कोड में बदलाव किया जाता है, ताकि उसमें विशेषताओं और क्लास के रेफ़रंस शामिल किए जा सकें. ये ऐसे सर्विस क्लाइंट बनाने के लिए ज़रूरी होते हैं जो Google Ads API के साथ काम करने के लिए, GoogleAdsClient क्लास का इस्तेमाल करते हैं. इस क्लास को GoogleAdsClientBuilder::build() को कॉल करके बनाया जाता है. GoogleAdsClient और GoogleAdsClientBuilder, दोनों src/Google/Ads/GoogleAds/Lib/vX/ में मौजूद मैन्युअल तरीके से बनाई गई क्लास हैं.

GAPIC v2 सोर्स कोड

v20.1.0 वर्शन से, क्लाइंट लाइब्रेरी में src/Google/Ads/GoogleAds/vX में GAPIC सोर्स कोड का एक नया वर्शन भी शामिल है. यह सेवा क्लाइंट के तरीकों में अनुरोध ऑब्जेक्ट को पास करने की सुविधा देता है. GAPIC v2 के नाम से मौजूद यह नया वर्शन, आने वाले समय में नई सुविधाओं के लिए भी तैयार किया जाएगा. पुराना GAPIC सोर्स कोड, GAPIC v1 अब भी जनरेट होता है. साथ ही, इसे 2023 के आखिर तक हर रिलीज़ के साथ शामिल किया जाता है.

Google Ads API PHP क्लाइंट लाइब्रेरी की मदद से, कॉन्फ़िगरेशन सेटिंग useGapicV2Source का इस्तेमाल करके, GoogleAdsClient से लिंक किए जाने वाले वर्शन को चुना जा सकता है. अगर यह सेटिंग true पर सेट है, तो क्लाइंट लाइब्रेरी एक GoogleAdsClient ऑब्जेक्ट जनरेट करती है. यह GAPIC v2 सर्विस क्लाइंट बनाती है.

जनरेट की गई क्लास की जगहें

यहां दो क्लास टाइप के लिए, GAPIC वर्शन के बीच फ़ाइल की जगह के अंतर के बारे में बताया गया है:

GAPIC से जनरेट किए गए क्लाइंट और संबंधित फ़ाइलें GAPIC v1 
src/Google/Ads/GoogleAds/VX/Services/Gapic/
GAPIC v2: कोई नहीं. सिर्फ़ प्रोसेस पूरी होने के बाद बनी फ़ाइल बनाई जाती है.
पोस्ट-प्रोसेस किए गए क्लाइंट GAPIC v1 
src/Google/Ads/GoogleAds/VX/Services/
GAPIC v2 
src/Google/Ads/GoogleAds/VX/Services/Client/

इस्तेमाल का तरीका

GAPIC v1 के लिए ज़रूरी है कि आप हर अनुरोध पैरामीटर को सीधे किसी तरीके से पास करें. वहीं, GAPIC v2 को इसके बजाय अनुरोध ऑब्जेक्ट पास करना होता है. ध्यान दें कि कुछ मामलों में, आपके पास अनुरोध ऑब्जेक्ट बनाने के एक से ज़्यादा तरीके होते हैं. ऐसा इसलिए, क्योंकि GAPIC v2 ज़रूरी पैरामीटर पास करने के लिए, build() नाम का एक आसान तरीका भी जनरेट करता है.

उदाहरण 1.1: ज़रूरी पैरामीटर वाले तरीके

यहां दिया गया सैंपल कोड, GAPIC v1 और 2 में CampaignService::mutate() को कॉल करने की तुलना करता है. ध्यान दें कि सभी पैरामीटर ($customerId और $operations) ज़रूरी पैरामीटर हैं. इसलिए, दोनों पैरामीटर को स्वीकार करने वाला build(), GAPIC v2 कोड में जनरेट होता है.

पैटर्न 1 GAPIC v1 
$campaignServiceClient
    = $googleAdsClient->getCampaignServiceClient();
$response = $campaignServiceClient->mutateCampaigns(
    $customerId,
    $campaignOperations
);
GAPIC v2 
$campaignServiceClient
    = $googleAdsClient->getCampaignServiceClient();
$response = $campaignServiceClient->mutateCampaigns(
    MutateCampaignsRequest::build(
      $customerId,
      $campaignOperations
    )
);
पैटर्न 2 GAPIC v1 
N/A
GAPIC v2 
$campaignServiceClient
    = $googleAdsClient->getCampaignServiceClient();
$request = (new MutateCampaignsRequest())
    ->setCustomerId($customerId)
    ->setCampaignOperations($campaignOperations);
$response = $campaignServiceClient->mutateCampaigns($request);

उदाहरण 1.2: ज़रूरी पैरामीटर और वैकल्पिक पैरामीटर वाले तरीके

यहां दिया गया सैंपल कोड, GAPIC v1 और 2 में GoogleAdsServiceClient::search() को कॉल करने की तुलना करता है. इस उदाहरण में, GAPIC v2 सोर्स कोड में जनरेट किए गए build() में सिर्फ़ दो पैरामीटर ($customerId और $query) स्वीकार किए जाते हैं, क्योंकि ये ज़रूरी पैरामीटर होते हैं. पेज का साइज़, जो एक वैकल्पिक पैरामीटर है, उसे सेट करने के लिए आपको इसे साफ़ तौर पर setPageSize() का इस्तेमाल करके सेट करना होगा. इसके अलावा, SearchGoogleAdsRequest के कंस्ट्रक्टर को सभी पैरामीटर एक साथ पास किए जा सकते हैं, जैसा कि 3 पैटर्न में दिखाया गया है.

पैटर्न 1 GAPIC v1 
$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$response = $googleAdsServiceClient->search(
    $customerId,
    $query,
    ['pageSize' => self::PAGE_SIZE]
);
GAPIC v2 
$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$response = $googleAdsServiceClient->search(
    SearchGoogleAdsRequest::build($customerId, $query)
        ->setPageSize(self::PAGE_SIZE)
);
पैटर्न 2 GAPIC v1 
N/A
GAPIC v2 
$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$request = (new SearchGoogleAdsRequest())
    ->setCustomerId($customerId)
    ->setQuery($query)
    ->setPageSize(self::PAGE_SIZE);
$response = $googleAdsServiceClient->search($request);
तीसरा पैटर्न GAPIC v1 
N/A
GAPIC v2 
$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$request = (new SearchGoogleAdsRequest([
    'customer_id' => $customerId,
    'query' => $query,
    'page_size' => self::PAGE_SIZE
]);
$response = $googleAdsServiceClient->search($request);

दूसरा उदाहरण: सिर्फ़ वैकल्पिक पैरामीटर वाले तरीके

GAPIC v1 और 2 में GeoTargetConstantServiceClient::suggestGeoTargetConstants() को कॉल करने की तुलना करें. GeoTargetConstantServiceClient::suggestGeoTargetConstants() के सभी पैरामीटर ज़रूरी नहीं हैं. इसलिए, इस मामले में GAPIC v2 सोर्स कोड में build() जनरेट नहीं होता. आपको अनुरोध ऑब्जेक्ट खुद बनाना होता है.

पैटर्न 1 GAPIC v1 
$geoTargetConstantServiceClient =
    $googleAdsClient->getGeoTargetConstantServiceClient();
$response = $geoTargetConstantServiceClient->suggestGeoTargetConstants([
    'locale' => $locale,
    'countryCode' => $countryCode,
    'locationNames' => new LocationNames(['names' => $locationNames])
]);
GAPIC v2 
$geoTargetConstantServiceClient =
    $googleAdsClient->getGeoTargetConstantServiceClient();
$request = (new SuggestGeoTargetConstantsRequest())
    ->setLocale($locale)
    ->setCountryCode($countryCode)
    ->setLocationNames(new LocationNames(['names' => $locationNames]));
$response =
    $geoTargetConstantServiceClient->suggestGeoTargetConstants($request);
पैटर्न 2 GAPIC v1 
N/A
GAPIC v2 
$geoTargetConstantServiceClient =
    $googleAdsClient->getGeoTargetConstantServiceClient();
$response = $geoTargetConstantServiceClient->suggestGeoTargetConstants(
    new SuggestGeoTargetConstantsRequest([
        'locale' => $locale,
        'country_code' => $countryCode,
        'location_names' => new LocationNames(['names' => $locationNames])
    ])
);