API

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

Kode sumber yang dihasilkan kemudian diubah agar berisi referensi ke karakteristik 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 terletak 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 ditetapkan ke true, library klien akan menghasilkan objek GoogleAdsClient yang membuat klien layanan GAPIC v2.

Lokasi kelas yang dibuat

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

Klien yang dibuat GAPIC dan file terkait GAPIC v1 
src/Google/Ads/GoogleAds/VX/Services/Gapic/
GAPIC v2: Tidak ada. Hanya file pasca-pemrosesan yang 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 langsung ke suatu 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 yang diperlukan.

Contoh 1.1: Metode dengan parameter wajib

Kode contoh berikut membandingkan pemanggilan CampaignService::mutate() di GAPIC v1 dan v2. Perhatikan bahwa semua parameter ($customerId dan $operations) adalah parameter yang diperlukan, sehingga build() yang menerima kedua parameter tersebut akan dihasilkan 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 dibuat dalam kode sumber GAPIC v2 hanya menerima dua parameter ($customerId dan $query) karena merupakan parameter wajib. Untuk menetapkan ukuran halaman, yang merupakan parameter opsional, Anda harus menetapkannya secara eksplisit menggunakan setPageSize(). Atau, Anda dapat meneruskan semua parameter secara bersamaan ke konstruktor SearchGoogleAdsRequest, seperti yang ditunjukkan pada pola 3.

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

Contoh 2: Metode dengan hanya parameter opsional

Bandingkan pemanggilan GeoTargetConstantServiceClient::suggestGeoTargetConstants() di GAPIC v1 dan v2. Karena semua parameter GeoTargetConstantServiceClient::suggestGeoTargetConstants() bersifat opsional, dalam kasus ini build() tidak dihasilkan 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])
    ])
);