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, debes crear una instancia de CampaignService:

use strict;
use warnings;

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

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

Realiza una llamada a la API

Este es un ejemplo de cómo realizar 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::V26::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::V26::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 la API. Puedes verificar si la respuesta que se muestra 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 JSON sin procesar cuando se produce un error de 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::V26::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::V26::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 varias muestras de código útiles en el directorio examples. La mayoría de los ejemplos requieren parámetros. Puedes pasar los parámetros como argumentos (recomendado) 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 un argumento de línea de comandos.

perl examples/basic_operations/get_campaigns.pl -help