Uso básico

En esta guía, se explican los conceptos básicos para usar la biblioteca cliente de Perl para la API de Google Ads.

Inicializa el cliente

Para comenzar a usar la biblioteca, crea una instancia de Google::Ads::GoogleAds::Client. El cliente se puede configurar de varias maneras, como se detalla en la guía de configuración. Un enfoque común es usar un archivo googleads.properties:

use strict;
use warnings;
use Google::Ads::GoogleAds::Client;

my $api_client = Google::Ads::GoogleAds::Client->new();

Crear un servicio

Una vez que se inicializa el cliente, puedes crear instancias de los distintos servicios de la API. Por ejemplo, para interactuar con las campañas, crearías una instancia de CampaignService:

use strict;
use warnings;

my $campaign_service = $api_client->CampaignService();

De forma predeterminada, $api_client carga servicios para el DEFAULT_API_VERSION de la versión de la biblioteca instalada (V25 en la versión más reciente; las versiones secundarias, como v25.1, usan su módulo de versión principal, V25). Para segmentar una versión de API compatible específica, pasa version => "V25" a Client->new({...}) o llama a $api_client->set_version("V25").

Realiza una llamada a la API

A continuación, se muestra un ejemplo de cómo hacer una llamada a la API para obtener campañas. En este fragmento, se muestra cómo inicializar el cliente, crear un servicio y llamar a un método.

use strict;
use warnings;
use Google::Ads::GoogleAds::Client;
use Google::Ads::GoogleAds::V25::Services::GoogleAdsService::SearchGoogleAdsRequest;

# Initialize the Google Ads client. See the Configuration guide for options.
my $api_client = Google::Ads::GoogleAds::Client->new();

# Get the GoogleAdsService.
my $google_ads_service = $api_client->GoogleAdsService();

# Specify the customer ID and query.
my $customer_id = "INSERT_CUSTOMER_ID_HERE";
my $query = "SELECT campaign.name, campaign.status FROM campaign";

# Create a search request.
my $search_request =
  Google::Ads::GoogleAds::V25::Services::GoogleAdsService::SearchGoogleAdsRequest
  ->new({
    customerId => $customer_id,
    query      => $query,
  });

# Execute the search request.
my $search_response = $google_ads_service->search($search_request);

# Iterate over the results and print campaign names.
foreach my $google_ads_row (@{$search_response->{results} || []}) {
  printf "Campaign with resource name '%s' and name '%s'.\n",
    $google_ads_row->{campaign}->{resourceName},
    $google_ads_row->{campaign}->{name};
}

Soluciona errores

Las llamadas a la API pueden generar errores. De forma predeterminada, die_on_faults es 0 (false), lo que hace que los métodos de servicio emitan una advertencia y devuelvan un objeto Google::Ads::GoogleAds::GoogleAdsException cuando se produce un error de API. Puedes verificar si la respuesta que se devolvió es un GoogleAdsException y llamar a get_google_ads_failure() para inspeccionar las entradas GoogleAdsError individuales.

Como alternativa, si configuras die_on_faults => 1 en Client->new({...}) (o llamas a $api_client->set_die_on_faults(1)), los métodos de servicio llaman a die() con la respuesta de error en formato JSON sin procesar cuando se produce una falla en la API, que puedes detectar en un bloque eval (if ($@)).

use strict;
use warnings;
use Scalar::Util qw(blessed);
use Google::Ads::GoogleAds::Client;
use Google::Ads::GoogleAds::V25::Services::GoogleAdsService::SearchGoogleAdsRequest;

my $api_client = Google::Ads::GoogleAds::Client->new();
my $google_ads_service = $api_client->GoogleAdsService();
my $customer_id = "INSERT_CUSTOMER_ID_HERE";
my $query = "SELECT campaign.name, campaign.status FROM campaign";
my $search_request =
  Google::Ads::GoogleAds::V25::Services::GoogleAdsService::SearchGoogleAdsRequest
  ->new({
    customerId => $customer_id,
    query      => $query,
  });

my $search_response = $google_ads_service->search($search_request);

if (blessed($search_response)
  && $search_response->isa("Google::Ads::GoogleAds::GoogleAdsException"))
{
  printf "An API exception occurred (HTTP %s, status '%s'): %s\n",
    $search_response->get_code(),
    $search_response->get_status(),
    $search_response->get_message();

  my $google_ads_failure = $search_response->get_google_ads_failure();
  if ($google_ads_failure) {
    foreach my $error (@{$google_ads_failure->{errors} || []}) {
      my ($error_type, $error_value) = %{$error->{errorCode} || {}};
      printf "  Error code (%s): %s\n",
        $error_type  || "unknown",
        $error_value || "UNKNOWN";
      printf "  Message: %s\n", $error->{message};
    }
  }
} else {
  foreach my $google_ads_row (@{$search_response->{results} || []}) {
    printf "Campaign name: %s\n", $google_ads_row->{campaign}->{name};
  }
}

Explora otros ejemplos

Puedes encontrar varios ejemplos de código útiles en el directorio de ejemplos. La mayoría de los ejemplos requieren parámetros. Puedes pasar los parámetros como argumentos (opción recomendada) o editar los valores de INSERT_XXXXX_HERE en el código fuente. Para ver una declaración de uso de un ejemplo, pasa -help como argumento de la línea de comandos.

perl examples/basic_operations/get_campaigns.pl -help