Lista GAPIC

Kod źródłowy w katalogu src/Google/Ads/GoogleAds/vX biblioteki klienta PHP interfejsu Google Ads API, gdzie X to wersja interfejsu Google Ads API, jest generowany automatycznie za pomocą generatora GAPIC (Generated API Client) na podstawie opublikowanych plików proto.

Następnie wygenerowany kod źródłowy jest modyfikowany tak, by zawierał odwołania do cech i klas wymaganych do utworzenia klientów usługi działających z interfejsem Google Ads API za pomocą klasy GoogleAdsClient, która jest tworzona przez wywołanie GoogleAdsClientBuilder::build(). Zarówno GoogleAdsClient, jak i GoogleAdsClientBuilder to klasy utworzone ręcznie w zadaniu src/Google/Ads/GoogleAds/Lib/vX/.

Kod źródłowy GAPIC v2

Od wersji v20.1.0 biblioteka klienta zawiera też w src/Google/Ads/GoogleAds/vX nową wersję kodu źródłowego GAPIC, która obsługuje przekazywanie obiektu żądania do metod klientów usługi. Ta nowa wersja, o nazwie GAPIC v2, służy również jako przygotowanie do obsługi nowych funkcji w przyszłości. Wcześniejszy kod źródłowy GAPIC, GAPIC w wersji 1, jest nadal generowany i dołączany do każdej wersji do końca 2023 roku.

Biblioteka klienta PHP interfejsu Google Ads API umożliwia wybranie wersji, którą chcesz połączyć z kontem GoogleAdsClient za pomocą ustawienia konfiguracji useGapicV2Source. Gdy to ustawienie ma wartość true, biblioteka klienta generuje obiekt GoogleAdsClient, który tworzy klienty usługi GAPIC v2.

Wygenerowane lokalizacje zajęć

Oto różnice w lokalizacji plików między wersjami GAPIC dla 2 typów klas:

Klienty wygenerowane przez GAPIC i powiązane pliki GAPIC v1 
src/Google/Ads/GoogleAds/VX/Services/Gapic/
GAPIC v2: brak. Tworzony jest tylko plik po przetworzeniu.
Przetworzeni klienci GAPIC v1 
src/Google/Ads/GoogleAds/VX/Services/
GAPIC v2 
src/Google/Ads/GoogleAds/VX/Services/Client/

Wykorzystanie

GAPIC v1 wymaga przekazania każdego parametru żądania bezpośrednio do metody, natomiast GAPIC v2 wymaga przekazania obiektu żądania. Pamiętaj, że w niektórych przypadkach istnieje więcej niż jeden sposób tworzenia obiektu żądania, ponieważ GAPIC w wersji 2 generuje też wygodną metodę build() do przekazywania wymaganych parametrów.

Przykład 1.1: Metody z wymaganymi parametrami

Poniższy przykładowy kod porównuje możliwość wywoływania funkcji CampaignService::mutate() w GAPIC w wersjach 1 i 2. Pamiętaj, że wszystkie parametry ($customerId i $operations) są parametrami wymaganymi, więc build(), który akceptuje oba parametry, jest generowany w kodzie GAPIC w wersji 2.

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

Przykład 1.2: Metody z wymaganymi i opcjonalnymi parametrami

Poniższy przykładowy kod porównuje możliwość wywoływania funkcji GoogleAdsServiceClient::search() w GAPIC v1 i v2. W tym przykładzie build() wygenerowany w kodzie źródłowym GAPIC w wersji 2 akceptuje tylko 2 parametry ($customerId i $query), ponieważ są one wymagane. Aby ustawić rozmiar strony, który jest opcjonalnym parametrem, musisz go ustawić bezpośrednio za pomocą setPageSize(). Możesz też przekazać wszystkie parametry razem do konstruktora SearchGoogleAdsRequest, jak pokazano we wzorcu 3.

Wzór 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)
);
Wzór 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);
Wzór 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);

Przykład 2. Metody z tylko opcjonalnymi parametrami

Porównaj wywoływanie funkcji GeoTargetConstantServiceClient::suggestGeoTargetConstants() w GAPIC w wersjach 1 i 2. Ponieważ wszystkie parametry GeoTargetConstantServiceClient::suggestGeoTargetConstants() są opcjonalne, pole build() nie jest w tym przypadku generowane w kodzie źródłowym GAPIC v2 – musisz utworzyć obiekt żądania samodzielnie.

Wzór 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);
Wzór 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])
    ])
);