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, en el que X es la versión de la API de Google Ads, se genera automáticamente con el generador de GAPIC (Generated API Client), según los archivos proto publicados.

Luego, el código fuente generado se modifica para que contenga referencias a 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 con una llamada a GoogleAdsClientBuilder::build(). Tanto GoogleAdsClient como GoogleAdsClientBuilder son clases creadas de forma manual ubicadas en src/Google/Ads/GoogleAds/Lib/vX/.

Código fuente 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 pasar 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, aún se genera y se incluye con cada versión hasta fines 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 GAPIC v2.

Ubicaciones de clases generadas

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

Clientes generados por GAPIC y archivos relacionados GAPIC v1 
src/Google/Ads/GoogleAds/VX/Services/Gapic/
GAPIC v2: Ninguna. Solo se genera un archivo con procesamiento posterior.
Clientes procesados posteriormente 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 en su lugar. 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 los 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 GAPIC v1 y v2. Ten en cuenta que todos los parámetros ($customerId y $operations) son obligatorios, por lo que el build() que acepta ambos se genera en el código 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 GAPIC v1 y v2. En este ejemplo, el build() que se genera en el código fuente de GAPIC v2 acepta solo dos parámetros ($customerId y $query) porque son obligatorios. Para configurar el tamaño de una 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 con parámetros opcionales únicamente

Compara la llamada a GeoTargetConstantServiceClient::suggestGeoTargetConstants() en GAPIC v1 y v2. Dado que todos los parámetros de GeoTargetConstantServiceClient::suggestGeoTargetConstants() son opcionales, en este caso, build() no se genera en el código fuente de GAPIC v2; tienes que 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])
    ])
);