API

Kode sumber di direktori src/Google/Ads/GoogleAds/vX library klien PHP Google Ads API, dengan X adalah versi Google Ads API yang otomatis dibuat menggunakan Generator GAPIC (Klien API yang Dihasilkan), berdasarkan file proto yang dipublikasikan.

Kode sumber yang dihasilkan kemudian diubah agar memuat referensi ke ciri dan class yang diperlukan untuk membuat klien layanan yang berfungsi dengan Google Ads API menggunakan class GoogleAdsClient, yang dibuat dengan memanggil GoogleAdsClientBuilder::build(). GoogleAdsClient dan GoogleAdsClientBuilder adalah class yang dibuat secara manual yang berada di src/Google/Ads/GoogleAds/Lib/vX/.

Kode sumber GAPIC v2

Sejak versi v20.1.0, library klien juga menyertakan versi baru kode sumber GAPIC di src/Google/Ads/GoogleAds/vX yang mendukung penerusan objek permintaan ke metode klien layanan. Versi baru ini, yang disebut GAPIC v2, juga berfungsi sebagai persiapan untuk fitur baru di masa mendatang. Kode sumber GAPIC sebelumnya, GAPIC v1, masih dibuat dan disertakan dengan setiap rilis hingga akhir tahun 2023.

Library klien PHP Google Ads API memungkinkan Anda memilih versi yang akan ditautkan ke GoogleAdsClient menggunakan setelan konfigurasi useGapicV2Source. Jika setelan ini disetel ke true, library klien akan menghasilkan objek GoogleAdsClient yang membuat klien layanan GAPIC v2.

Lokasi kelas yang dibuat

Berikut adalah perbedaan lokasi file antara kedua versi GAPIC kedua jenis class tersebut:

Klien yang dihasilkan GAPIC dan file terkait GAPIC v1 
src/Google/Ads/GoogleAds/VX/Services/Gapic/
GAPIC v2: Tidak ada. Hanya file yang telah diproses kembali yang akan dihasilkan.
Klien yang telah diproses GAPIC v1 
src/Google/Ads/GoogleAds/VX/Services/
GAPIC v2 
src/Google/Ads/GoogleAds/VX/Services/Client/

Penggunaan

GAPIC v1 mengharuskan Anda meneruskan setiap parameter permintaan secara langsung ke metode, sedangkan GAPIC v2 mengharuskan Anda meneruskan objek permintaan. Perhatikan bahwa dalam beberapa kasus, Anda memiliki lebih dari satu cara untuk membuat objek permintaan karena GAPIC v2 juga menghasilkan metode praktis bernama build() untuk meneruskan parameter diperlukan.

Contoh 1.1: Metode dengan parameter yang diperlukan

Kode contoh berikut membandingkan pemanggilan CampaignService::mutate() di GAPIC v1 dan v2. Perhatikan bahwa semua parameter ($customerId dan $operations) merupakan parameter wajib, sehingga build() yang menerima kedua parameter akan dibuat dalam kode GAPIC v2.

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

Contoh 1.2: Metode dengan parameter wajib dan parameter opsional

Kode contoh berikut membandingkan pemanggilan GoogleAdsServiceClient::search() di GAPIC v1 dan v2. Dalam contoh ini, build() yang dihasilkan dalam kode sumber GAPIC v2 hanya menerima dua parameter ($customerId dan $query) karena parameter tersebut merupakan parameter yang diperlukan. Untuk meminta jumlah total hasil yang cocok dengan kueri yang mengabaikan klausa LIMIT, Anda harus menetapkannya secara eksplisit menggunakan setReturnTotalResultsCount(). Atau, Anda dapat meneruskan semua parameter bersama ke konstruktor SearchGoogleAdsRequest, seperti yang ditunjukkan pada pola 3.

Pola 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)
);
Pola 2 GAPIC v1 
N/A
GAPIC v2 
$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$request = (new SearchGoogleAdsRequest())
    ->setCustomerId($customerId)
    ->setQuery($query)
    ->setReturnTotalResultsCount(true);
$response = $googleAdsServiceClient->search($request);
Pola 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);

Contoh 2: Metode dengan hanya parameter opsional

Membandingkan pemanggilan GeoTargetConstantServiceClient::suggestGeoTargetConstants() di GAPIC v1 dan v2. Karena semua parameter GeoTargetConstantServiceClient::suggestGeoTargetConstants() bersifat opsional, dalam kasus ini build() tidak dibuat dalam kode sumber GAPIC v2—Anda harus membuat objek permintaan sendiri.

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