Utilizzo di base

Questa guida spiega le nozioni di base sull'utilizzo della libreria client Perl per l'API Google Ads.

Inizializza il client

Per iniziare a utilizzare la libreria, crea un'istanza di Google::Ads::GoogleAds::Client. Il client può essere configurato in diversi modi, come descritto nella guida alla configurazione. Un approccio comune è utilizzare un file googleads.properties:

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

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

Crea un servizio

Una volta inizializzato il client, puoi creare istanze dei vari servizi API. Ad esempio, per interagire con le campagne, devi creare un'istanza di CampaignService:

use strict;
use warnings;

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

Per impostazione predefinita, $api_client carica i servizi per la versione DEFAULT_API_VERSION della libreria installata (V25 nell'ultima release; le release secondarie come v25.1 utilizzano il modulo della versione principale, V25). Per scegliere come target una versione API specifica supportata, passa version => "V25" a Client->new({...}) o chiama $api_client->set_version("V25").

Esegui una chiamata API

Ecco un esempio di come effettuare una chiamata API per ottenere le campagne. Questo snippet mostra l'inizializzazione del client, la creazione di un servizio e la chiamata di un metodo.

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};
}

Gestisci gli errori

Le chiamate API possono generare errori. Per impostazione predefinita, die_on_faults è 0 (false), il che fa sì che i metodi di servizio emettano un avviso e restituiscano un oggetto Google::Ads::GoogleAds::GoogleAdsException quando si verifica un errore API. Puoi verificare se la risposta restituita è un GoogleAdsException e chiamare get_google_ads_failure() per esaminare le singole voci GoogleAdsError.

In alternativa, se imposti die_on_faults => 1 su Client->new({...}) (o chiami $api_client->set_die_on_faults(1)), i metodi di servizio chiamano die() con la risposta di errore JSON non elaborata quando si verifica un errore API, che puoi intercettare in un blocco 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};
  }
}

Esplora altri esempi

Puoi trovare diversi esempi di codice utili nella directory examples. La maggior parte degli esempi richiede parametri. Puoi passare i parametri come argomenti (opzione consigliata) o modificare i valori INSERT_XXXXX_HERE nel codice sorgente. Per visualizzare una dichiarazione di utilizzo per un esempio, passa -help come argomento della riga di comando.

perl examples/basic_operations/get_campaigns.pl -help