Grundlegende Nutzung

In diesem Leitfaden werden die Grundlagen der Verwendung der Perl-Clientbibliothek für die Google Ads API erläutert.

Client initialisieren

Erstellen Sie zum Verwenden der Bibliothek eine Instanz von Google::Ads::GoogleAds::Client. Der Client kann auf verschiedene Arten konfiguriert werden, wie im Konfigurationsleitfaden beschrieben. Ein gängiger Ansatz ist die Verwendung einer googleads.properties-Datei:

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

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

Dienste erstellen

Nachdem der Client initialisiert wurde, können Sie Instanzen der verschiedenen API-Dienste erstellen. Wenn Sie beispielsweise mit Kampagnen interagieren möchten, erstellen Sie eine CampaignService-Instanz:

use strict;
use warnings;

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

Standardmäßig lädt $api_client Dienste für die DEFAULT_API_VERSION Ihrer installierten Bibliotheksversion (V25 in der neuesten Version; untergeordnete Versionen wie v25.1 verwenden das Modul der Hauptversion, V25). Wenn Sie auf eine bestimmte unterstützte API-Version abzielen möchten, übergeben Sie version => "V25" an Client->new({...}) oder rufen Sie $api_client->set_version("V25") auf.

API aufrufen

Hier ist ein Beispiel für einen API-Aufruf zum Abrufen von Kampagnen. In diesem Snippet wird gezeigt, wie der Client initialisiert, ein Dienst erstellt und eine Methode aufgerufen wird.

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

Fehler verarbeiten

API-Aufrufe können zu Fehlern führen. Standardmäßig ist die_on_faults auf 0 (false) festgelegt. Dies führt dazu, dass Dienstmethoden eine Warnung ausgeben und ein Google::Ads::GoogleAds::GoogleAdsException-Objekt zurückgeben, wenn ein API-Fehler auftritt. Sie können prüfen, ob die zurückgegebene Antwort ein GoogleAdsException ist, und get_google_ads_failure() aufrufen, um die einzelnen GoogleAdsError-Einträge zu prüfen.

Wenn Sie die_on_faults => 1 für Client->new({...}) festlegen (oder $api_client->set_die_on_faults(1) aufrufen), rufen Dienstmethoden die() mit der rohen JSON-Fehlerantwort auf, wenn ein API-Fehler auftritt. Diesen können Sie in einem eval-Block (if ($@)) abfangen.

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

Weitere Beispiele ansehen

Im Verzeichnis „examples“ finden Sie mehrere nützliche Codebeispiele. Für die meisten Beispiele sind Parameter erforderlich. Sie können die Parameter entweder als Argumente übergeben (empfohlen) oder die INSERT_XXXXX_HERE-Werte im Quellcode bearbeiten. Wenn Sie eine Nutzungsanweisung für ein Beispiel sehen möchten, übergeben Sie -help als Befehlszeilenargument.

perl examples/basic_operations/get_campaigns.pl -help