GAPIC

El código fuente en el directorio src/Google/Ads/GoogleAds/vX de la biblioteca cliente de PHP de la API de Google Ads, donde X es la versión de la API de Google Ads, se genera de forma automática con el generador GAPIC (cliente de API generado), según los archivos proto publicados.

Luego, el código fuente generado se modifica para que contenga referencias a las características y clases necesarias para crear los clientes de servicio que funcionan con la API de Google Ads mediante la clase GoogleAdsClient, que se crea llamando a GoogleAdsClientBuilder::build(). Tanto GoogleAdsClient como GoogleAdsClientBuilder son clases creadas de forma manual y ubicadas en src/Google/Ads/GoogleAds/Lib/vX/.

Código fuente de GAPIC v2

A partir de la versión v20.1.0, la biblioteca cliente también incluye una versión nueva del código fuente de GAPIC en src/Google/Ads/GoogleAds/vX, que admite el paso de un objeto de solicitud a los métodos de los clientes de servicio. Esta versión nueva, llamada GAPIC v2, también sirve como preparación para las funciones nuevas en el futuro. El código fuente de GAPIC anterior, GAPIC v1, se sigue generando y, además, se incluye con cada versión hasta finales de 2023.

La biblioteca cliente de PHP de la API de Google Ads te permite seleccionar la versión que se vinculará a GoogleAdsClient mediante el parámetro de configuración useGapicV2Source. Cuando esta configuración se establece en true, la biblioteca cliente genera un objeto GoogleAdsClient que crea clientes de servicio de GCC v2.

Ubicaciones de clases generadas

A continuación, se muestran las diferencias en la ubicación de los archivos entre las versiones de GAPIC para los dos tipos de clase:

Clientes generados por GAPIC y archivos relacionados GAPIC v1 
src/Google/Ads/GoogleAds/VX/Services/Gapic/
GAPIC v2: Ninguna. Solo se produce un archivo con procesamiento posterior.
Clientes con procesamiento posterior GAPIC v1 
src/Google/Ads/GoogleAds/VX/Services/
GAPIC v2 
src/Google/Ads/GoogleAds/VX/Services/Client/

Uso

GAPIC v1 requiere que pases cada parámetro de solicitud directamente a un método, mientras que GAPIC v2 requiere que pases un objeto de solicitud. Ten en cuenta que, en algunos casos, tienes más de una manera de crear un objeto de solicitud, ya que GAPIC v2 también genera un método conveniente llamado build() para pasar parámetros obligatorios.

Ejemplo 1.1: Métodos con parámetros obligatorios

En el siguiente código de muestra, se compara la llamada a CampaignService::mutate() en las versiones 1 y 2 de GAPIC. Ten en cuenta que todos los parámetros ($customerId y $operations) son obligatorios, por lo que el build() que acepta ambos parámetros se genera en el código de GAPIC v2.

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

Ejemplo 1.2: Métodos con parámetros obligatorios y opcionales

En el siguiente código de muestra, se compara la llamada a GoogleAdsServiceClient::search() en las versiones 1 y 2 de GCC. En este ejemplo, el build() que se genera en el código fuente de GAPIC v2 solo acepta dos parámetros ($customerId y $query) porque son parámetros obligatorios. Para configurar el tamaño de la página, que es un parámetro opcional, debes configurarlo de manera explícita con setPageSize(). Como alternativa, puedes pasar todos los parámetros juntos al constructor de SearchGoogleAdsRequest, como se muestra en el patrón 3.

Patrón 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)
);
Patrón 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);
Patrón 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);

Ejemplo 2: Métodos solo con parámetros opcionales

Compara las llamadas a GeoTargetConstantServiceClient::suggestGeoTargetConstants() en las versiones 1 y 2 de GCC. Como todos los parámetros de GeoTargetConstantServiceClient::suggestGeoTargetConstants() son opcionales, build() no se genera en el código fuente de GAPIC v2 en este caso. Debes crear el objeto de solicitud tú mismo.

Patrón 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);
Patrón 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])
    ])
);