GAPIC

O código-fonte na classe src/Google/Ads/GoogleAds/vX diretório da biblioteca de cliente PHP da API Google Ads, em que X é a API Google Ads versão, é gerada automaticamente usando o cliente de API gerado do Google Cloud, com base no proto arquivos.

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 do Google Ads usando a classe GoogleAdsClient, que é criada chamando GoogleAdsClientBuilder::build(). Tanto GoogleAdsClient quanto GoogleAdsClientBuilder são turmas criadas manualmente localizadas em src/Google/Ads/GoogleAds/Lib/vX/

Código-fonte GAPIC v2

A partir da versão v20.1.0, a biblioteca de cliente também inclui uma nova versão do código-fonte GAPIC no src/Google/Ads/GoogleAds/vX, que oferece suporte à transmissão de um objeto de solicitação para o serviço dos clientes métodos. 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, está ainda gerados e incluídos em cada lançamento até o final de 2023.

A biblioteca de cliente PHP da API Google Ads permite selecionar a versão a ser vinculada 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

Veja a seguir as diferenças nos locais dos arquivos entre as versões GAPIC da dois tipos de classe:

src/Google/Ads/GoogleAds/VX/Services/Gapic/

src/Google/Ads/GoogleAds/VX/Services/

src/Google/Ads/GoogleAds/VX/Services/Client/

Uso

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

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

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

$campaignServiceClient
    = $googleAdsClient->getCampaignServiceClient();
$response = $campaignServiceClient->mutateCampaigns(
    $customerId,
    $campaignOperations
);
      

$campaignServiceClient
    = $googleAdsClient->getCampaignServiceClient();
$response = $campaignServiceClient->mutateCampaigns(
    MutateCampaignsRequest::build(
      $customerId,
      $campaignOperations
    )
);
      

N/A

$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() na GAPIC v1 e v2. Neste exemplo, o build() que é gerado na GAPIC O código-fonte da v2 aceita apenas dois parâmetros ($customerId e $query) porque eles são parâmetros obrigatórios. Para solicitar o número total de resultados correspondentes a consulta ignorando a cláusula LIMIT, você precisa defini-la explicitamente usando setReturnTotalResultsCount(). Como alternativa, transmita todos os parâmetros ao construtor de SearchGoogleAdsRequest, conforme mostrado no padrão 3.

$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$response = $googleAdsServiceClient->search(
    $customerId,
    $query,
    ['returnTotalResultsCount' => true]
);
      

$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$response = $googleAdsServiceClient->search(
    SearchGoogleAdsRequest::build($customerId, $query)
        ->setReturnTotalResultsCount(true)
);
      

N/A

$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$request = (new SearchGoogleAdsRequest())
    ->setCustomerId($customerId)
    ->setQuery($query)
    ->setReturnTotalResultsCount(true);
$response = $googleAdsServiceClient->search($request);
      

N/A

$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$request = (new SearchGoogleAdsRequest([
    'customer_id' => $customerId,
    'query' => $query,
    'return_total_results_count' => true
]);
$response = $googleAdsServiceClient->search($request);
      

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

Comparar como chamar GeoTargetConstantServiceClient::suggestGeoTargetConstants() em 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. terá que criar o objeto de solicitação por conta própria.

$geoTargetConstantServiceClient =
    $googleAdsClient->getGeoTargetConstantServiceClient();
$response = $geoTargetConstantServiceClient->suggestGeoTargetConstants([
    'locale' => $locale,
    'countryCode' => $countryCode,
    'locationNames' => new LocationNames(['names' => $locationNames])
]);
      

$geoTargetConstantServiceClient =
    $googleAdsClient->getGeoTargetConstantServiceClient();
$request = (new SuggestGeoTargetConstantsRequest())
    ->setLocale($locale)
    ->setCountryCode($countryCode)
    ->setLocationNames(new LocationNames(['names' => $locationNames]));
$response =
    $geoTargetConstantServiceClient->suggestGeoTargetConstants($request);
      

N/A

$geoTargetConstantServiceClient =
    $googleAdsClient->getGeoTargetConstantServiceClient();
$response = $geoTargetConstantServiceClient->suggestGeoTargetConstants(
    new SuggestGeoTargetConstantsRequest([
        'locale' => $locale,
        'country_code' => $countryCode,
        'location_names' => new LocationNames(['names' => $locationNames])
    ])
);