GAPIC

Google Ads API PHP istemci kitaplığının src/Google/Ads/GoogleAds/vX dizinindeki kaynak kodu, X burada Google Ads API sürümüdür ve yayınlanan protokol dosyalarına göre GAPIC (Oluşturulan API İstemcisi) Oluşturucu kullanılarak otomatik olarak oluşturulur.

Oluşturulan kaynak kod, daha sonra GoogleAdsClientBuilder::build() çağrısıyla oluşturulan GoogleAdsClient sınıfını kullanarak Google Ads API ile çalışan hizmet istemcilerini oluşturmak için gereken özelliklere ve sınıflara referansları içerecek şekilde değiştirilir. Hem GoogleAdsClient hem de GoogleAdsClientBuilder, src/Google/Ads/GoogleAds/Lib/vX/ konumunda manuel olarak oluşturulan sınıflardır.

GAPIC v2 kaynak kodu

v20.1.0 sürümünden itibaren istemci kitaplığı, src/Google/Ads/GoogleAds/vX sürümünde bir istek nesnesinin hizmet istemcilerinin yöntemlerine iletilmesini destekleyen yeni bir GAPIC kaynak kodu sürümünü de içerir. GAPIC v2 adlı bu yeni sürüm, aynı zamanda gelecekteki yeni özellikler için hazırlık olarak da kullanılıyor. Önceki GAPIC kaynak kodu olan GAPIC v1, hâlâ oluşturulmakta ve 2023'ün sonuna kadar her sürüme dahil edilmektedir.

Google Ads API PHP istemci kitaplığı, useGapicV2Source yapılandırma ayarını kullanarak GoogleAdsClient konumuna bağlanacak sürümü seçmenize olanak tanır. Bu ayar true olarak ayarlandığında istemci kitaplığı, GAPIC v2 hizmet istemcileri oluşturan bir GoogleAdsClient nesnesi oluşturur.

Oluşturulan sınıf konumları

İki sınıf türü için GAPIC sürümleri arasındaki dosya konumları farklılıkları aşağıda belirtilmiştir:

GAPIC tarafından oluşturulan istemciler ve ilgili dosyalar GAPIC v1 
src/Google/Ads/GoogleAds/VX/Services/Gapic/
GAPIC v2: Yok. Yalnızca işlenmiş bir dosya oluşturulur.
İşlenmiş istemciler GAPIC v1 
src/Google/Ads/GoogleAds/VX/Services/
GAPIC v2 
src/Google/Ads/GoogleAds/VX/Services/Client/

Kullanım

GAPIC v1, her istek parametresini doğrudan bir yönteme iletmenizi gerektirir. GAPIC v2 ise bunun yerine bir istek nesnesi iletmenizi gerektirir. GAPIC v2, zorunlu parametrelerin iletilmesi için build() adlı kullanışlı bir yöntem de oluşturduğundan bazı durumlarda istek nesnesi oluşturmak için birden fazla yöntem kullanabileceğinizi unutmayın.

Örnek 1.1: Gerekli parametrelere sahip yöntemler

Aşağıdaki örnek kod, GAPIC v1 ve v2'de CampaignService::mutate() çağrısını karşılaştırmaktadır. Tüm parametrelerin ($customerId ve $operations) gerekli parametreler olduğunu, bu nedenle her iki parametreyi de kabul eden build() öğesinin GAPIC v2 kodunda oluşturulduğunu unutmayın.

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

Örnek 1.2: Gerekli parametreler ve isteğe bağlı parametreler içeren yöntemler

Aşağıdaki örnek kod, GAPIC v1 ve v2'de GoogleAdsServiceClient::search() çağrısını karşılaştırmaktadır. Bu örnekte, GAPIC v2 kaynak kodunda oluşturulan build(), gerekli parametreler olduklarından yalnızca iki parametreyi ($customerId ve $query) kabul etmektedir. Sorguyla eşleşen toplam sonuç sayısını istemek için LIMIT ifadesini yok sayar ve setReturnTotalResultsCount() kullanarak açıkça ayarlamanız gerekir. Alternatif olarak, tüm parametreleri birlikte kalıp 3'te gösterildiği gibi SearchGoogleAdsRequest oluşturucusuna aktarabilirsiniz.

Desen 1 GAPIC v1 
$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$response = $googleAdsServiceClient->search(
    $customerId,
    $query,
    ['returnTotalResultsCount' => true]
);
GAPIC v2 
$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$response = $googleAdsServiceClient->search(
    SearchGoogleAdsRequest::build($customerId, $query)
        ->setReturnTotalResultsCount(true)
);
Desen 2 GAPIC v1 
N/A
GAPIC v2 
$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$request = (new SearchGoogleAdsRequest())
    ->setCustomerId($customerId)
    ->setQuery($query)
    ->setReturnTotalResultsCount(true);
$response = $googleAdsServiceClient->search($request);
Kalıp 3 GAPIC v1 
N/A
GAPIC v2 
$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$request = (new SearchGoogleAdsRequest([
    'customer_id' => $customerId,
    'query' => $query,
    'return_total_results_count' => true
]);
$response = $googleAdsServiceClient->search($request);

2. Örnek: Yalnızca isteğe bağlı parametreleri olan yöntemler

GAPIC v1 ve v2'de GeoTargetConstantServiceClient::suggestGeoTargetConstants() çağrısını karşılaştırın. Tüm GeoTargetConstantServiceClient::suggestGeoTargetConstants() parametreleri isteğe bağlı olduğundan, GAPIC v2 kaynak kodunda build() oluşturulmaz. İstek nesnesini kendiniz oluşturmanız gerekir.

Desen 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);
Desen 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])
    ])
);