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 GAPIC (cliente da API gerado), 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, que é criada chamando GoogleAdsClientBuilder::build(). Tanto GoogleAdsClient quanto 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 é compatível com a transmissão de um objeto de solicitação para os métodos dos clientes de 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, GAPIC v1, ainda é gerado e incluído em cada versão até o final 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 definição de 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 das classes geradas

Estas são as diferenças na localização dos arquivos entre as versões GAPIC dos dois tipos de classe:

Clientes gerados por GAPIC e arquivos relacionados GAPIC v1 
src/Google/Ads/GoogleAds/VX/Services/Gapic/
GAPIC v2: nenhuma. 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ê transmita cada parâmetro de solicitação diretamente para um método, enquanto a GAPIC v2 exige que você transmita um objeto de solicitação. Em alguns casos, há mais de uma maneira de criar um objeto de solicitação, já que a GAPIC v2 também gera um método conveniente chamado build() para transmitir os 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() na 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() no GAPIC v1 e v2. Neste exemplo, o build() gerado no código-fonte 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, você precisa defini-lo explicitamente usando setPageSize(). Como alternativa, você pode transmitir todos os parâmetros juntos para o construtor de SearchGoogleAdsRequest, conforme 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 com apenas parâmetros opcionais

Compare como chamar 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 GAPIC v2 nesse caso. Nesse caso, você precisa criar o objeto de solicitação.

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])
    ])
);