API

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

Kode sumber yang dihasilkan kemudian dimodifikasi untuk memuat referensi ke trait dan yang diperlukan untuk membuat klien layanan yang dapat digunakan dengan Google Ads API 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 layanan klien metode. 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 dalam setiap rilis hingga akhir tahun 2023.

Library klien PHP Google Ads API memungkinkan Anda memilih versi yang akan ditautkan 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 di antara versi GAPIC untuk dua jenis class:

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 saat dalam beberapa kasus, Anda memiliki lebih dari satu cara untuk membuat objek permintaan karena GAPIC v2 juga menghasilkan metode praktis bernama build() untuk meneruskan wajib parameter.

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) adalah parameter yang diperlukan, 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() dalam GAPIC v1 dan v2. Dalam contoh ini, build() yang dihasilkan di GAPIC Kode sumber v2 hanya menerima dua parameter ($customerId dan $query) karena parameter tersebut adalah parameter wajib. Untuk meminta jumlah total hasil yang cocok kueri yang mengabaikan klausa LIMIT, Anda harus menyetelnya secara eksplisit menggunakan setReturnTotalResultsCount(). Atau, Anda dapat meneruskan semua parameter bersama-sama dengan 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

Bandingkan panggilan GeoTargetConstantServiceClient::suggestGeoTargetConstants() dalam 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])
    ])
);