GAPIC

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

Luego, se modifica el código fuente generado para que contenga referencias a los rasgos y las clases necesarios para crear los clientes de servicio que funcionan con la API de Google Ads a través de la clase GoogleAdsClient, que se crea llamando a GoogleAdsClientBuilder::build(). Tanto GoogleAdsClient como GoogleAdsClientBuilder son clases que se mantienen de forma manual y se encuentran en src/Google/Ads/GoogleAds/Lib/VX/.

Ubicaciones de clases generadas

Los clientes de servicio posprocesados se encuentran en src/Google/Ads/GoogleAds/VX/Services/Client/ (por ejemplo, V25), y las clases de mensajes de solicitud y respuesta correspondientes (como MutateCampaignsRequest y SearchGoogleAdsRequest) se encuentran en src/Google/Ads/GoogleAds/VX/Services/. Las versiones secundarias de la API (como v25.1) se generan dentro de su directorio de versión principal (V25).

Uso

Debes crear un objeto de solicitud y pasarlo al cliente de servicio que deseas usar. Según si los parámetros son obligatorios u opcionales, tienes varias formas de crear un objeto de solicitud, incluido un método de fábrica build() estático para pasar parámetros obligatorios.

Ejemplo 1.1: Métodos con parámetros obligatorios

En el siguiente código de muestra, se muestra cómo llamar a CampaignServiceClient::mutateCampaigns(). Dado que tanto $customerId como $campaignOperations son parámetros obligatorios, se genera un método de fábrica estático build() que acepta ambos parámetros en la clase de solicitud.

Patrón 1: Método de compilación estático (recomendado)

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

Patrón 2: Establecedores fluidos

$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 llama a GoogleAdsServiceClient::search(). En este ejemplo, el método build() generado solo acepta dos parámetros ($customerId y $query) porque son obligatorios. Para solicitar la cantidad total de resultados que coinciden con la búsqueda sin tener en cuenta la cláusula LIMIT, puedes establecerla de forma explícita con setReturnTotalResultsCount(). Como alternativa, puedes pasar todos los parámetros juntos en un array asociativo al constructor de SearchGoogleAdsRequest, como se muestra en el patrón 3.

Patrón 1: Método de compilación estático con setters fluidos

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

Patrón 2: Establecedores fluidos

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

Patrón 3: Constructor de arrays

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

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

En este ejemplo, se muestra cómo llamar a GeoTargetConstantServiceClient::suggestGeoTargetConstants(). Dado que todos los parámetros de GeoTargetConstantServiceClient::suggestGeoTargetConstants() son opcionales, build() no se genera en el código fuente en este caso. Debes construir el objeto de solicitud con los métodos de configuración o el constructor de arrays.

Patrón 1: Fluent setters (recomendado)

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

Patrón 2: Constructor de array

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