GAPIC

O código-fonte no diretório src/Google/Ads/GoogleAds/vX da biblioteca de cliente PHP da API Google Ads, em que X é a versão da API Google Ads, é gerado automaticamente usando o Gerador de cliente de API gerado (GAPIC) com base nos arquivos .proto publicados.

O código-fonte gerado é modificado para conter referências a características e classes necessárias para criar os clientes de serviço que funcionam com a API Google Ads usando a classe GoogleAdsClient, criada ao chamar GoogleAdsClientBuilder::build(). GoogleAdsClient e GoogleAdsClientBuilder são classes criadas manualmente localizadas em src/Google/Ads/GoogleAds/Lib/vX/.

Código-fonte GAPIC v2

Desde a versão v20.1.0, a biblioteca de cliente também inclui uma nova versão do código-fonte GAPIC em src/Google/Ads/GoogleAds/vX, que permite a passagem de um objeto de solicitação para os métodos dos clientes do serviço. Essa nova versão, chamada GAPIC v2, também serve como preparação para novos recursos no futuro. O código-fonte GAPIC anterior, o GAPIC v1, ainda é gerado e incluído em cada versão até o fim de 2023.

Com a biblioteca de cliente PHP da API Google Ads, você pode selecionar a versão a ser vinculada a GoogleAdsClient usando a configuração useGapicV2Source. Quando essa configuração é definida como true, a biblioteca de cliente gera um objeto GoogleAdsClient que cria clientes de serviço GAPIC v2.

Locais de turmas gerados

Veja abaixo as diferenças nos locais dos arquivos entre as versões do GAPIC para os dois tipos de classes:

Clientes gerados pelo GAPIC e arquivos relacionados GAPIC v1 
src/Google/Ads/GoogleAds/VX/Services/Gapic/
GAPIC v2: nenhum. Somente um arquivo pós-processado é produzido.
Clientes pós-processados GAPIC v1 
src/Google/Ads/GoogleAds/VX/Services/
GAPIC v2 
src/Google/Ads/GoogleAds/VX/Services/Client/

Uso

A GAPIC v1 exige que você passe cada parâmetro de solicitação diretamente para um método, enquanto a GAPIC v2 exige que você passe um objeto de solicitação. Observe que, em alguns casos, há mais de uma maneira de criar um objeto de solicitação, já que o GAPIC v2 também gera um método conveniente chamado build() para transmitir parâmetros obrigatórios.

Exemplo 1.1: métodos com parâmetros obrigatórios

O exemplo de código a seguir compara a chamada de CampaignService::mutate() nas GAPIC v1 e v2. Todos os parâmetros ($customerId e $operations) são obrigatórios. Portanto, o build() que aceita ambos os parâmetros é gerado no código GAPIC v2.

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

Exemplo 1.2: métodos com parâmetros obrigatórios e opcionais

O exemplo de código a seguir compara a chamada de GoogleAdsServiceClient::search() nas GAPIC v1 e v2. Nesse exemplo, o build() gerado no código-fonte da GAPIC v2 aceita apenas dois parâmetros ($customerId e $query), porque eles são obrigatórios. Para definir um tamanho de página, que é um parâmetro opcional, é necessário fazer a configuração explicitamente usando setPageSize(). Como alternativa, você pode transmitir todos os parâmetros para o construtor de SearchGoogleAdsRequest, como mostrado no padrão 3.

Padrão 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)
);
Padrão 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);
Padrão 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);

Exemplo 2: métodos apenas com parâmetros opcionais

Compare a chamada de GeoTargetConstantServiceClient::suggestGeoTargetConstants() nas GAPIC v1 e v2. Como todos os parâmetros de GeoTargetConstantServiceClient::suggestGeoTargetConstants() são opcionais, build() não é gerado no código-fonte da GAPIC v2 nesse caso. Você precisa criar o objeto de solicitação por conta própria.

Padrão 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);
Padrão 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])
    ])
);