ГАПИК

Исходный код в каталоге src/Google/Ads/GoogleAds/v X клиентской PHP-библиотеки Google Ads API, где X — версия Google Ads API, автоматически генерируется с помощью генератора GAPIC (Generated API Client) на основе опубликованные файлы прототипов .

Затем сгенерированный исходный код модифицируется, чтобы содержать ссылки на характеристики и классы, необходимые для создания клиентов службы, которые работают с API Google Рекламы, с использованием класса GoogleAdsClient , который создается путем вызова GoogleAdsClientBuilder::build() . И GoogleAdsClient , и GoogleAdsClientBuilder — это классы, созданные вручную и расположенные в src/Google/Ads/GoogleAds/Lib/vX/ .

Исходный код GAPIC v2

Начиная с версии v20.1.0 , клиентская библиотека также включает новую версию исходного кода GAPIC в src/Google/Ads/GoogleAds/vX которая поддерживает передачу объекта запроса в методы клиентов обслуживания. Эта новая версия, получившая название GAPIC v2, также служит подготовкой к новым функциям в будущем. Более ранний исходный код GAPIC, GAPIC v1, по-прежнему генерируется и включается в каждую версию до конца 2023 года.

Клиентская библиотека PHP Google Ads API позволяет выбрать версию, которая будет связана с GoogleAdsClient с помощью параметра конфигурации useGapicV2Source . Если для этого параметра установлено значение true , клиентская библиотека генерирует объект GoogleAdsClient , который создает клиентов службы GAPIC v2.

Сгенерированные местоположения классов

Вот различия в расположении файлов между версиями GAPIC для двух типов классов:

Клиенты и связанные файлы, созданные GAPIC GAPIC v1 
src/Google/Ads/GoogleAds/VX/Services/Gapic/
GAPIC v2 : нет. Создается только файл постобработки.
Клиенты с постобработкой GAPIC v1 
src/Google/Ads/GoogleAds/VX/Services/
GAPIC v2 
src/Google/Ads/GoogleAds/VX/Services/Client/

Применение

GAPIC v1 требует, чтобы вы передавали каждый параметр запроса непосредственно методу, тогда как GAPIC v2 требует вместо этого передавать объект запроса. Обратите внимание, что в некоторых случаях у вас есть несколько способов создания объекта запроса, поскольку GAPIC v2 также генерирует удобный метод с именем build() для передачи необходимых параметров.

Пример 1.1: Методы с обязательными параметрами

В следующем примере кода сравнивается вызов CampaignService::mutate() в GAPIC v1 и v2. Обратите внимание, что все параметры ( $customerId и $operations ) являются обязательными параметрами, поэтому build() , принимающий оба параметра, генерируется в коде GAPIC v2.

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

Пример 1.2: Методы с обязательными и необязательными параметрами

В следующем примере кода сравнивается вызов GoogleAdsServiceClient::search() в GAPIC v1 и v2. В этом примере build() , созданный в исходном коде GAPIC v2, принимает только два параметра ( $customerId и $query ), поскольку они являются обязательными параметрами. Чтобы установить размер страницы (который является необязательным параметром), вам необходимо установить его явно с помощью setPageSize() . Альтернативно вы можете передать все параметры вместе в конструктор SearchGoogleAdsRequest , как показано в шаблоне 3.

Узор 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)
);
Узор 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);
Узор 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);

Пример 2: Методы только с необязательными параметрами

Сравните вызов GeoTargetConstantServiceClient::suggestGeoTargetConstants() в GAPIC v1 и v2. Поскольку все параметры GeoTargetConstantServiceClient::suggestGeoTargetConstants() являются необязательными, в этом случае build() не генерируется в исходном коде GAPIC v2 — вам придется создать объект запроса самостоятельно.

Узор 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);
Узор 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])
    ])
);