基本的な使い方

このガイドでは、Google Ads API の Perl クライアント ライブラリを使用する際の基本について説明します。

クライアントを初期化する

ライブラリの使用を開始するには、Google::Ads::GoogleAds::Client のインスタンスを作成します。クライアントは、構成ガイドで説明されているように、複数の方法で構成できます。一般的なアプローチは、googleads.properties ファイルを使用することです。

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

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

サービスの作成

クライアントを初期化したら、さまざまな API サービスのインスタンスを作成できます。たとえば、キャンペーンを操作するには、次のように CampaignService インスタンスを作成します。

use strict;
use warnings;

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

デフォルトでは、$api_client はインストールされているライブラリ リリースの DEFAULT_API_VERSION のサービスを読み込みます（最新リリースでは V25。v25.1 などのマイナー リリースでは、メジャー バージョン モジュール V25 を使用します）。特定のサポート対象 API バージョンをターゲットにするには、version => "V25" を Client->new({...}) に渡すか、$api_client->set_version("V25") を呼び出します。

API 呼び出しを行う

キャンペーンを取得する API 呼び出しを行う方法の例を次に示します。このスニペットは、クライアントの初期化、サービスの作成、メソッドの呼び出しを示しています。

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

エラーを処理する

API 呼び出しでエラーが発生することがあります。デフォルトでは、die_on_faults は 0（false）です。これにより、API エラーが発生すると、サービス メソッドは警告を出力し、Google::Ads::GoogleAds::GoogleAdsException オブジェクトを返します。返されたレスポンスが GoogleAdsException かどうかを確認し、get_google_ads_failure() を呼び出して個々の GoogleAdsError エントリを検査できます。

また、Client->new({...}) で die_on_faults => 1 を設定した場合（または $api_client->set_die_on_faults(1) を呼び出した場合）、API エラーが発生すると、サービス メソッドは未加工の JSON エラー レスポンスで die() を呼び出します。これは 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};
  }
}

その他の例

examples ディレクトリには、有用なコードサンプルがいくつかあります。ほとんどの例ではパラメータが必要です。パラメータは引数として渡す（推奨）か、ソースコードで INSERT_XXXXX_HERE の値を編集します。例の使用方法を表示するには、-help をコマンドライン引数として渡します。

perl examples/basic_operations/get_campaigns.pl -help