Utilisation de base

Ce guide explique les bases de l'utilisation de la bibliothèque cliente Perl pour l'API Google Ads.

Initialiser le client

Pour commencer à utiliser la bibliothèque, créez une instance de Google::Ads::GoogleAds::Client. Le client peut être configuré de plusieurs façons, comme indiqué dans le guide de configuration. Une approche courante consiste à utiliser un fichier googleads.properties :

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

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

Créer un service

Une fois le client initialisé, vous pouvez créer des instances des différents services d'API. Par exemple, pour interagir avec des campagnes, vous devez créer une instance CampaignService :

use strict;
use warnings;

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

Par défaut, $api_client charge les services pour DEFAULT_API_VERSION de la version de la bibliothèque installée (V25 dans la dernière version ; les versions mineures telles que v25.1 utilisent leur module de version majeure, V25). Pour cibler une version d'API compatible spécifique, transmettez version => "V25" à Client->new({...}) ou appelez $api_client->set_version("V25").

Effectuer un appel d'API

Voici un exemple d'appel d'API pour obtenir des campagnes. Cet extrait montre comment initialiser le client, créer un service et appeler une méthode.

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

Gérer les erreurs

Les appels d'API peuvent entraîner des erreurs. Par défaut, die_on_faults est défini sur 0 (false), ce qui entraîne l'émission d'un avertissement par les méthodes de service et le renvoi d'un objet Google::Ads::GoogleAds::GoogleAdsException en cas d'erreur d'API. Vous pouvez vérifier si la réponse renvoyée est une GoogleAdsException et appeler get_google_ads_failure() pour inspecter les entrées GoogleAdsError individuelles.

Sinon, si vous définissez die_on_faults => 1 sur Client->new({...}) (ou appelez $api_client->set_die_on_faults(1)), les méthodes de service appellent die() avec la réponse d'erreur JSON brute lorsqu'une erreur d'API se produit, que vous pouvez intercepter dans un bloc 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};
  }
}

Découvrir d'autres exemples

Vous trouverez plusieurs exemples de code utiles dans le répertoire d'exemples. La plupart des exemples nécessitent des paramètres. Vous pouvez transmettre les paramètres en tant qu'arguments (recommandé) ou modifier les valeurs INSERT_XXXXX_HERE dans le code source. Pour afficher une instruction d'utilisation d'un exemple, transmettez -help comme argument de ligne de commande.

perl examples/basic_operations/get_campaigns.pl -help