コードのサンプルと使用例

前回のガイドでは、最初の API 呼び出しを実行するための設定方法と、呼び出しに必要な各設定要素の詳細について解説しました。

このガイドでは、AdWords API の一般的なコードのサンプルを見ながら、その構造について解説します。

その後、一般的な使用例をいくつか紹介しながら、コードのサンプルを使って API の機能を実際にアプリケーションに組み込む方法について説明します。

API コードのサンプルの構造

クライアント ライブラリに用意されているコードのサンプルでは、一般的な API 機能をすべてカバーしています。大部分のバックエンド タスクを自動的に処理し、AdWords API アプリケーションの開発を大幅に簡素化できます。

以下で、AdWords API コードのサンプルの一般的な構造について説明します。使用する言語に対応するタブをクリックして詳細をご確認ください。

Java

IDE で、以前のガイドで使用したサンプル ファイルの GetCampaigns.java を開きます。

GetCampaigns.java の main に、以下の定型のコードがあります。

  • Credential の生成
  • AdWordsSession の生成
  • AdWordsServices のインスタンス化

これらのコードは、クライアント ライブラリのコードのサンプルを調べていくうちに理解できます。

サンプル ファイルの GetCampaigns 内には、必要性の高いコードがもうひとつあります。以前のガイドでは、ads.properties ファイルにクライアントのお客様 ID を設定しました。

ただし、クライアント センター(MCC)アカウントの配下に多数のクライアント アカウントがある場合は、ads.properties ファイルからクライアントのお客様 ID を削除し、AdWordsSession オブジェクトを利用することで、プログラムによって設定することもできます。その場合はこのオブジェクトを作成してから setClientCustomerID を呼び出して ID を動的に設定します。

/ Construct an AdWordsSession.
    AdWordsSession session = new AdWordsSession.Builder()
        .fromFile()
        .withOAuth2Credential(oAuth2Credential)
        .build();

    session.setClientCustomerID("123-456-7890");

    AdWordsServices adWordsServices = new AdWordsServices();

    runExample(adWordsServices, session);
  }

.NET

IDE で、以前のガイドで使用したサンプル ファイルの GetCampaigns.cs を開きます。

mainAdWordsUser を参照する定型のコードがあります。
public static void Main(string[] args) {
      GetCampaigns codeExample = new GetCampaigns();
      Console.WriteLine(codeExample.Description);
      try {
        codeExample.Run(new AdWordsUser());

.NET ライブラリで最も重要なクラスは AdsUser クラスです。通常、AdsUser クラスでは、単一の広告アカウントがカプセル化されます。この例では AdWords アカウントです。

AdsWordsUser クラスを利用すると、API 呼び出しに使用できる既定のサービスクラスを作成できます。その際はアプリケーションの app.config ファイルで指定した設定が使用されます。

// Create a new AdWordsUser with the App.config settings.
AdWordsUser user = new AdWordsUser();

ただし、クライアント センター(MCC)アカウントの配下に多数のクライアント アカウントがある場合は、プログラムによって ID を設定できます。その場合は AdsUser オブジェクトの Config プロパティを使用してランタイム時に該当のユーザーを設定します。

// Create a default AdWordsUser instance. If any configuration
// is available in App.config, those will be used.
AdWordsUser user = new AdWordsUser();

// Override a specific setting at runtime.
AdWordsAppConfig config = (AdWordsAppConfig) user.Config;
user.Config.clientCustomerId = "123-456-7890";

また、以下のようにコンストラクタを使って AdWordsAppConfig インスタンスを許可する方法もあります。

// Create a config object with the values in App.config.
AdWordsAppConfig config = new AdWordsAppConfig();

// Override any specific setting you wish to change.
user.Config.clientCustomerId = "123-456-7890";

AdWordsUser user = new AdWordsUser(config);

Python

IDE で、以前のガイドで使用したサンプル ファイルの get_campaigns.py を開きます。

このファイルのコメントは、LoadFromStorage メソッドによって googleads.yaml ファイルから認証情報とプロパティが取得されることを示しています。以前のガイドでは、googleads.yaml でクライアントのお客様 ID を設定しました。LoadFromStorage メソッドのデフォルトでは、この名前を含むファイルがホーム ディレクトリ内で検索されますが、適切な yaml コンテンツを含む任意のファイルのパスを渡すこともできます。 デフォルトの場所を使用する場合 - ホーム ディレクトリ:

adwords_client = adwords.AdWordsClient.LoadFromStorage()
任意のファイルの場所を渡す場合:
adwords_client = adwords.AdWordsClient.LoadFromStorage('C:\My\Directory\googleads.yaml')

ただし、クライアント センター(MCC)アカウントの配下に多数のクライアント アカウントがある場合は、以下のコードを使用することで、ランタイム時にプログラムによってクライアントのお客様 ID を設定することができます。

adwords_client = AdWordsClient.LoadFromStorage()
adwords_client.SetClientCustomerId('123-456-7890')

PHP

IDE で、以前のガイドで使用したサンプル ファイルの GetCampaigns.php を開きます。

サンプル ファイルの GetCampaigns 内に、設定ファイルの auth.ini から認証情報を取得するコードがあります。

try {
  // Get AdWordsUser from credentials in "../auth.ini"
  // relative to the AdWordsUser.php file's directory.
  $user = new AdWordsUser();

サンプル ファイルの GetCampaigns 内には、必要性の高いコードがもうひとつあります。以前のガイドでは、auth.ini ファイルにクライアントのお客様 ID を設定しました。

ただし、クライアント センター(MCC)アカウントの配下に多数のクライアント アカウントがある場合は、auth.ini ファイルからクライアントのお客様 ID を削除し、プログラムによって ID を設定できます。その場合は設定するクライアントのお客様 ID をパラメータとして含む AdWordUser オブジェクトの SetClientCustomerId() を呼び出します。

// Create an AdWordsUser instance using the default constructor, which will load
// information from the auth.ini file as described above.
$user = new AdWordsUser();
$user->SetClientCustomerId('123-456-7890');

Perl

IDE で、以前のガイドで使用したサンプル ファイルの get_campaigns.pl を開きます。

サンプル ファイル内に、設定ファイルの adwords.properties から認証情報を取得するコードがあります。

# Get AdWords Client, credentials will be read from ~/adwords.properties.
my $client = Google::Ads::AdWords::Client->new({version => "v201702"});

以前のガイドでは、adwords.properties ファイルにクライアントのお客様 ID を設定しました。

ただし、クライアント センター(MCC)アカウントの配下に多数のクライアント アカウントがある場合は、adwords.properties からクライアントのお客様 ID を削除し、set_client_id を呼び出すことで、プログラムによって ID を設定できます。

# Get AdWords Client, credentials will be read from ~/adwords.properties.
my $client = Google::Ads::AdWords::Client->new({version => "v201702"});
$client->set_client_id("123-456-7890");

Ruby

以前のガイドで使用したサンプル ファイルの get_campaigns.pl を開きます。

サンプル ファイルの main 内に、設定ファイルの adwords_api.yml から認証情報を取得する定型のコードがあります。

  # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
  # when called without parameters.
  adwords = AdwordsApi::Api.new

サンプル ファイル内には、必要性の高いコードがもうひとつあります。以前のガイドでは、設定ファイルの adwords_api.yml にクライアントのお客様 ID を設定しました。

ただし、クライアント センター(MCC)アカウントの配下に多数のクライアント アカウントがある場合は、adwords_api.yml ファイルからクライアントのお客様 ID を削除し、AdWordsSession オブジェクトを利用することで、プログラムによって ID を設定することもできます。その場合はオブジェクトを作成してから、adwords.config.set を呼び出して ID を動的に設定します。

# Set a new CID value
adwords.config.set("authentication.client_customer_id", "123-456-7890")

コードのサンプルにアクセスする

AdWords API コードのサンプルは、クライアント ライブラリとサンプルのページですべて参照できます。これらのサンプルは、以下の API の主要機能をすべてカバーしています。

  • アカウント管理
  • キャンペーン管理
  • エラー処理
  • 最適化
  • レポート
  • ターゲット設定

一般的な AdWords API コードのサンプルの構造について説明したので、続いてコードのサンプルを利用して API のほぼすべての機能を利用する方法を解説するため、使用例をいくつか紹介します。

API の主要機能はレポートと自動化の 2 つに大別されます。まずはレポート機能から見ていきます。

コードのサンプルでレポート機能を使用する

まず、条件の掲載結果レポートをダウンロードするコードのサンプルから説明します。

Java

IDE に移動して DownloadCriteriaReport.java を開きます。

main 内に、前述したものと同一の定型のコードがあります。

public static void main(String[] args) throws Exception {
    // Generate a refreshable OAuth2 credential.
    Credential oAuth2Credential = new OfflineCredentials.Builder()
        .forApi(Api.ADWORDS)
        .fromFile()
        .build()
        .generateCredential();

    // Construct an AdWordsSession.
    AdWordsSession session = new AdWordsSession.Builder()
        .fromFile()
        .withOAuth2Credential(oAuth2Credential)
        .build();

しかし、このクラスの重要なコードが含まれているのは RunExample メソッドです。ここでは、必要なレポートを定義するオブジェクト階層を作成します。

// Create report definition.
    ReportDefinition reportDefinition = new ReportDefinition();
    reportDefinition.setReportName("Criteria performance report #" + System.currentTimeMillis());
    reportDefinition.setDateRangeType(ReportDefinitionDateRangeType.YESTERDAY);
    reportDefinition.setReportType(ReportDefinitionReportType.CRITERIA_PERFORMANCE_REPORT);
    reportDefinition.setDownloadFormat(DownloadFormat.CSV);

続いてこれを ReportDownloader のインスタンスに渡します。

 ReportDownloadResponse response =
          new ReportDownloader(session).downloadReport(reportDefinition);
      response.saveToFile(reportFile);

DownloadCriteriaReport.java を実行します。

IDE コンソールにダウンロードしたファイルの場所が出力されます。

このコードのサンプルでは、criteria performance report というレポートのタイプが指定されています。

reportDefinition.setReportType(ReportDefinitionReportType.CRITERIA_PERFORMANCE_REPORT);

サンプルでは、取得するレポート項目も指定されています。

Selector selector = new Selector();
    selector.getFields().addAll(Lists.newArrayList("CampaignId",
        "AdGroupId",
        "Id",
        "CriteriaType",
        "Criteria",
        "FinalUrls",
        "Impressions",
        "Clicks",
        "Cost"));

.NET

IDE に移動して DownloadCriteriaReport.cs を開きます。

前述の例と同一の定型のコードがあります。app.config ファイルから値を取得して認証を処理するためのものです。

public static void Main(string[] args) {
      GetCampaigns codeExample = new GetCampaigns();
      Console.WriteLine(codeExample.Description);
      try {
        codeExample.Run(new AdWordsUser());

しかしこのコードで重要なのは、必要なレポートを定義するオブジェクト階層を作成する場所です。

public void Run(AdWordsUser user, string fileName) {
      ReportDefinition definition = new ReportDefinition() {
        reportName = "Last 7 days CRITERIA_PERFORMANCE_REPORT",
        reportType = ReportDefinitionReportType.CRITERIA_PERFORMANCE_REPORT,
        downloadFormat = DownloadFormat.GZIPPED_CSV,
        dateRangeType = ReportDefinitionDateRangeType.LAST_7_DAYS,

DownloadCriteriaReport.cs を実行します。

コンソールにダウンロードしたファイルの場所が出力されます。

このコードのサンプルでは、criteria performance report というレポートのタイプが指定されています。

reportType = ReportDefinitionReportType.CRITERIA_PERFORMANCE_REPORT,

サンプルでは、取得するレポート項目も指定されています。

selector = new Selector() {
          fields = new string[] {"CampaignId", "AdGroupId", "Id", "CriteriaType", "Criteria",
              "FinalUrls", "Clicks", "Impressions", "Cost"},
          predicates = new Predicate[] {
            Predicate.In("Status", new string[] {"ENABLED", "PAUSED"})

Python

IDE に移動して download_criteria_report.py を開きます。

前述の例と同一の定型のコードがあります。設定ファイルの googleads.yaml から値を取得して認証を処理するためのものです。

adwords_client = adwords.AdWordsClient.LoadFromStorage()
  main(adwords_client)

しかしこのサンプルで重要なのは、必要なレポートを定義するオブジェクト階層のコードです。

 # Create report definition.
  report = {
      'reportName': 'Last 7 days CRITERIA_PERFORMANCE_REPORT',
      'dateRangeType': 'LAST_7_DAYS',
      'reportType': 'CRITERIA_PERFORMANCE_REPORT',
      'downloadFormat': 'CSV',
      'selector': {
          'fields': ['CampaignId', 'AdGroupId', 'Id', 'CriteriaType',
                     'Criteria', 'FinalUrls', 'Impressions', 'Clicks', 'Cost']

続いてこれを ReportDownloader のインスタンスに渡します。

 report_downloader.DownloadReport(
      report, sys.stdout, skip_report_header=False, skip_column_header=False,
      skip_report_summary=False)

download_criteria_report.py を実行します。

コンソールにダウンロードしたファイルの場所が出力されます。

このコードのサンプルでは、criteria performance report というレポートのタイプが指定されています。

サンプルでは、「selector」セクション内で、「CampaignId」や「AdGroupId」などの取得するレポート項目も指定されています。

PHP

IDE に移動して DownloadCriteriaReport.php を開きます。

前述の例と同一の定型のコードがあります。設定ファイルの auth.ini から値を取得して認証を処理するためのものです。

  // Get AdWordsUser from credentials in "../auth.ini"
  // relative to the AdWordsUser.php file's directory.
  $user = new AdWordsUser();

しかしこのコードで重要なのは、必要なレポートを定義するセレクタを作成する場所です。

  // Create report definition.
  $reportDefinition = new ReportDefinition();
  $reportDefinition->selector = $selector;
  $reportDefinition->reportName = 'Criteria performance report #' . uniqid();
  $reportDefinition->dateRangeType = 'LAST_7_DAYS';
  $reportDefinition->reportType = 'CRITERIA_PERFORMANCE_REPORT';
  $reportDefinition->downloadFormat = 'CSV';

続いてこれをレポートのダウンローダーに渡します。

  // Download report.
  ReportUtils::DownloadReport($reportDefinition, $filePath, $user, $options);
  printf("Report with name '%s' was downloaded to '%s'.\n",
      $reportDefinition->reportName, $filePath);

DownloadCriteriaReport.php を実行します。

コンソールにダウンロードしたファイルの場所が出力されます。

このコードのサンプルでは、criteria performance report というレポートのタイプが指定されています。

$reportDefinition->reportType = 'CRITERIA_PERFORMANCE_REPORT';

サンプルでは、取得するレポート項目も指定されています。

$selector->fields = array('CampaignId', 'AdGroupId', 'Id', 'Criteria',
      'CriteriaType', 'Impressions', 'Clicks', 'Cost');

Perl

IDE に移動して download_criteria_report.pl を開きます。

前述の例と同一の定型のコードがあります。設定ファイルの adwords.properties から値を取得して認証を処理するためのものです。

# Get AdWords Client, credentials will be read from ~/adwords.properties.
my $client = Google::Ads::AdWords::Client->new({version => "v201702"});

しかしこのコードで重要なのは、必要なレポートを定義するセレクタとレポートの定義を作成する場所です。

my $report_definition = Google::Ads::AdWords::Reports::ReportDefinition->new({
      reportName     => "Last 7 days CRITERIA_PERFORMANCE_REPORT #" . $today,
      dateRangeType  => "LAST_7_DAYS",
      reportType     => "CRITERIA_PERFORMANCE_REPORT",
      downloadFormat => "CSV",
      selector       => $selector
  });

続いてこれを ReportDownloader のインスタンスに渡します。

 # Download the report using the appropriate method on ReportDownloadHandler.
  my $result;
  if ($output_file) {
    $result = $report_handler->save($output_file);
  } else {
    $result = $report_handler->get_as_string();
  }

download_criteria_report.pl を実行します。

コンソールにダウンロードしたファイルの場所が出力されます。

このコードのサンプルでは、criteria performance report というレポートのタイプが指定されています。

reportType     => "CRITERIA_PERFORMANCE_REPORT",

サンプルでは、取得するレポート項目も指定されています。

# Create selector.
  my $selector = Google::Ads::AdWords::Reports::Selector->new({
      fields => [
        "CampaignId", "AdGroupId", "Id",          "CriteriaType",
        "Criteria",   "FinalUrls", "Impressions", "Clicks",
        "Cost"
      ]});

Ruby

download_criteria_report.rb を開きます。

前述の例と同一の定型のコードがあります。設定ファイルの adwords_api.yml から値を取得して認証を処理するためのものです。

def download_criteria_report(file_name)
  # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
  # when called without parameters.
  adwords = AdwordsApi::Api.new

しかしこのコードで重要なのは、必要なレポートを定義するオブジェクト階層を作成する場所です。

  # Define report definition. You can also pass your own XML text as a string.
  report_definition = {
    :selector => {
      :fields => ['CampaignId', 'AdGroupId', 'Id', 'Criteria', 'CriteriaType',
          'FinalUrls', 'Impressions', 'Clicks', 'Cost'],
    },
...

    :report_name => 'Last 7 days CRITERIA_PERFORMANCE_REPORT',
    :report_type => 'CRITERIA_PERFORMANCE_REPORT',
    :download_format => 'CSV',
    :date_range_type => 'LAST_7_DAYS',

続いてこれを download_report のインスタンスに渡します。

 # Download report, using "download_report_as_file" utility method.
 # To retrieve the report as return value, use "download_report" method.
  report_utils.download_report_as_file(report_definition, file_name)
  puts "Report was downloaded to '%s'." % file_name
end

download_criteria_report.rb を実行します。

コンソールにダウンロードしたファイルの場所が出力されます。

このコードのサンプルでは、criteria performance report というレポートのタイプが指定されています。

:report_type => 'CRITERIA_PERFORMANCE_REPORT',

サンプルでは、取得するレポート項目も指定されています。

:fields => ['CampaignId', 'AdGroupId', 'Id', 'Criteria', 'CriteriaType',
          'FinalUrls', 'Impressions', 'Clicks', 'Cost'],

利用できるレポートのタイプと項目の全リストについては、レポートのタイプのページをご覧ください。

このサンプルのコードを使い、レポートのタイプのページに記載されている情報も参考にすれば、どのようなレポートでも定義、作成、ダウンロードすることができます。

AdWords クエリ言語(AWQL)

オブジェクト階層でレポートを定義する方法以外に、AdWords クエリ言語(AWQL)を利用する方法もあります。オブジェクトより簡単にレポートを作成できる SQL のような言語です。

Java

前のセクションで実行したコードのサンプルと DownloadCriteriaReportWithAWQL.java を比較してみましょう。同じレポートを取得しますが、AWQL の方が簡潔です。レポートのタイプと項目はどちらの方法でも同じです。

String query = "SELECT CampaignId, AdGroupId, Id, Criteria, CriteriaType, "
        + "Impressions, Clicks, Cost FROM CRITERIA_PERFORMANCE_REPORT "
        + "WHERE Status IN [ENABLED, PAUSED] "
        + "DURING YESTERDAY";

.NET

前のセクションで実行したコードと DownloadCriteriaReportWithAWQL.cs を比較してみましょう。同じレポートを取得しますが、AWQL の方が簡潔です。レポートのタイプと項目はどちらの方法でも同じです。

string query = "SELECT CampaignId, AdGroupId, Id, Criteria, CriteriaType, Impressions, " +
          "Clicks, Cost FROM CRITERIA_PERFORMANCE_REPORT WHERE Status IN [ENABLED, PAUSED] " +
          "DURING LAST_7_DAYS";

Python

前のセクションで実行したコードと download_criteria_report_with_awql.py を比較してみましょう。同じレポートを取得しますが、AWQL の方が簡潔です。レポートのタイプと項目はどちらの方法でも同じです。

report_query = ('SELECT CampaignId, AdGroupId, Id, Criteria, CriteriaType, '
                  'FinalUrls, Impressions, Clicks, Cost '
                  'FROM CRITERIA_PERFORMANCE_REPORT '
                  'WHERE Status IN [ENABLED, PAUSED] '
                  'DURING LAST_7_DAYS')

PHP

前のセクションで実行したコードと DownloadCriteriaReportWithAwql.php を比較してみましょう。同じレポートを取得しますが、AWQL の方が簡潔です。レポートのタイプと項目はどちらの方法でも同じです。

$reportQuery = 'SELECT CampaignId, AdGroupId, Id, Criteria, CriteriaType, '
      . 'Impressions, Clicks, Cost FROM CRITERIA_PERFORMANCE_REPORT '
      . 'WHERE Status IN [ENABLED, PAUSED] DURING ' . $dateRange;

この例のコードでは、AWQL の直前で期間が定義されています。

  // Prepare a date range for the last week. Instead you can use 'LAST_7_DAYS'.
  $dateRange = sprintf('%d,%d',
      date('Ymd', strtotime('-7 day')), date('Ymd', strtotime('-1 day')));

Perl

前のセクションで実行したコードと download_criteria_report_with_awql.pl を比較してみましょう。同じレポートを取得しますが、AWQL の方が簡潔です。レポートのタイプと項目はどちらの方法でも同じです。

my $report_query =
    "SELECT CampaignId, AdGroupId, Id, Criteria, CriteriaType, " .
    "Impressions, Clicks, Cost FROM CRITERIA_PERFORMANCE_REPORT " .
    ""WHERE Status IN [ENABLED, PAUSED] " . "DURING $last_4_days, $yesterday";";

この例のコードでは、AWQL の直前で期間が定義されています。

  # Create report query.
  my (undef, undef, undef, $mday, $mon, $year) = localtime(time - 60 * 60 * 24);
  my $yesterday = sprintf("%d%02d%02d", ($year + 1900), ($mon + 1), $mday);
  (undef, undef, undef, $mday, $mon, $year) =
    localtime(time - 60 * 60 * 24 * 4);
  my $last_4_days = sprintf("%d%02d%02d", ($year + 1900), ($mon + 1), $mday);

Ruby

前のセクションで実行したコードと download_criteria_report_with_awql.rb を比較してみましょう。同じレポートを取得しますが、AWQL の方が簡潔です。レポートのタイプと項目はどちらの方法でも同じです。

report_query = 'SELECT CampaignId, AdGroupId, Id, Criteria, CriteriaType, ' +
      'Impressions, Clicks, Cost FROM CRITERIA_PERFORMANCE_REPORT ' +
      'WHERE Status IN [ENABLED, PAUSED] ' +
      'DURING %s' % date_range

この例のコードでは、AWQL の直前で期間が定義されています。

  # Prepare a date range for the last week. Instead you can use 'LAST_7_DAYS'.
  date_range = '%s,%s' % [
      DateTime.parse((Date.today - 7).to_s).strftime('%Y%m%d'),
      DateTime.parse((Date.today - 1).to_s).strftime('%Y%m%d')
  ]

レポート機能の基本事項についての説明は以上です。独自のカスタム レポートの作成に必要なツールが揃いました。

コードのサンプルを使って自動化を行う

以下で、コードのサンプルを使って AdWords アカウントに変更を加える方法とその他の一般的な使用例について解説します。ほぼすべての自動化機能の土台として応用できるので、その点についても説明します。

広告グループの一時停止と再開

広告グループの一時停止と再開は、API の特に一般的な使用例に挙げられます。たとえば広告費の無駄をなくすため、商品の在庫が切れたら広告を一時停止するといった方法が考えられます。

利用している在庫管理などのシステムと AdWords API を連動させる効果的な使用方法です。

ここでは、コードのサンプルを活用して広告グループの一時停止と再開を設定します。

Java

IDE を起動してサンプル ファイルの UpdateAdGroup.java を開きます。

前述の例と同じように、main 内に定型のコードがあります。この例では main 内の下部付近に、広告グループの ID 用のプレースホルダ文字列があります。

public static void main(String[] args) throws Exception {
    // Generate a refreshable OAuth2 credential.
    Credential oAuth2Credential = new OfflineCredentials.Builder()
        .forApi(Api.ADWORDS)
        .fromFile()
        .build()
        .generateCredential();

    // Construct an AdWordsSession.
    AdWordsSession session = new AdWordsSession.Builder()
        .fromFile()
        .withOAuth2Credential(oAuth2Credential)
        .build();

    Long adGroupId = Long.parseLong("INSERT_AD_GROUP_ID_HERE");

広告グループ ID は、AdGroupService インターフェースの GET メソッドを介したプログラムによって取得します。ID は、AdWords の管理画面で該当の広告グループを表示し、その URL から簡単に取得することもできます。

ここでも runExample メソッドに重要なコードがあります。その仕組みについて詳しく見ていきます。

まず、広告グループの変更に使う AdGroupService インターフェースの参照を取得します。他のエンティティを変更する場合は対応するサービスを使用します。利用できる全サービスのリストは、オブジェクト、メソッド、サービスのガイドをご覧ください。

// Get the AdGroupService.
    AdGroupServiceInterface adGroupService =
        adWordsServices.get(session, AdGroupServiceInterface.class);

続いて新しい広告グループ オブジェクトを作成し、その ID を変更する広告グループの ID に設定します。

// Create ad group with updated status.
    AdGroup adGroup = new AdGroup();
    adGroup.setId(adGroupId);

ステータスを PAUSED に設定します。

adGroup.setStatus(AdGroupStatus.PAUSED);

その後、新たに作成された広告グループ オブジェクトをオペランド、SET を演算子として使用し、AdGroupOperation を作成します。

// Create operations.
    AdGroupOperation operation = new AdGroupOperation();
    operation.setOperand(adGroup);
    operation.setOperator(Operator.SET);

最後に AdGroupService インターフェースの mutate メソッドを呼び出し、広告グループの演算オブジェクトを渡します。

// Update ad group.
    AdGroupReturnValue result = adGroupService.mutate(operations);

プレースホルダをテスト用クライアント アカウントの広告グループ ID に置き換え、コードを実行します。実行したら、テスト アカウントで AdWords の管理画面にログインし、ステータスが変わっていることを確認してください。

.NET

IDE で、サンプル ファイルの UpdateAdGroup.cs を開きます。

このファイルでも前述の例と同様、main 内に一般的な定型のコードがあります。この例では main 内の下部付近に、広告グループの ID 用のプレースホルダ文字列があります。

public static void Main(string[] args) {
      UpdateAdGroup codeExample = new UpdateAdGroup();
      Console.WriteLine(codeExample.Description);
      try {
        long adGroupId = long.Parse("INSERT_ADGROUP_ID_HERE");
        codeExample.Run(new AdWordsUser(), adGroupId);

広告グループ ID は、AdGroupService インターフェースの GET メソッドを介したプログラムによって取得します。ID は、AdWords の管理画面で該当の広告グループを表示し、その URL から簡単に取得することもできます。

ここでも runExample メソッドに重要なコードがあります。その仕組みについて詳しく見ていきます。

まず、広告グループの変更に使う AdGroupService インターフェースの参照を取得します。他のエンティティを変更する場合は対応するサービスを使用します。利用できる全サービスのリストは、オブジェクト、メソッド、サービスのガイドをご覧ください。

public void Run(AdWordsUser user, long adGroupId) {
      // Get the AdGroupService.
      AdGroupService adGroupService =
          (AdGroupService) user.GetService(AdWordsService.v201702.AdGroupService);

続いて新しい AdGroup オブジェクトを作成し、その ID を変更する広告グループの ID に設定します。

// Create the ad group.
      AdGroup adGroup = new AdGroup();
      adGroup.status = AdGroupStatus.PAUSED;
      adGroup.id = adGroupId;

ステータスも PAUSED に設定します。

adGroup.status = AdGroupStatus.PAUSED;

その後、新たに作成された adGroup オブジェクトをオペランド、SET を演算子として使用し、AdGroupOperation を作成します。

// Create the operation.
      AdGroupOperation operation = new AdGroupOperation();
      operation.@operator = Operator.SET;
      operation.operand = adGroup;

最後に AdGroupService インターフェースの mutate メソッドを呼び出し、AdGroupOperation オブジェクトを渡します。

// Update the ad group.
        AdGroupReturnValue retVal = adGroupService.mutate(new AdGroupOperation[] {operation});

プレースホルダをテスト用クライアント アカウントの広告グループ ID に置き換え、コードを実行します。実行したら、テスト アカウントで AdWords の管理画面にログインし、ステータスが変わっていることを確認してください。

Python

IDE で、サンプル ファイルの update_ad_group.py を開きます。

このファイルにも一般的な定型のコードがあり、LoadFromStorage メソッドによって設定ファイルの googleads.yaml から認証情報とプロパティを取得しています。この例では、広告グループの ID 用のプレースホルダ文字列が追加されています。

AD_GROUP_ID = 'INSERT_AD_GROUP_ID_HERE'

広告グループ ID は、AdGroupService インターフェースの GET メソッドを介したプログラムによって取得します。ID は、AdWords の管理画面で該当の広告グループを表示し、その URL から簡単に取得することもできます。

その後に重要なコードがあります。その仕組みについて詳しく見ていきます。

まず、広告グループの変更に使う AdGroupService インターフェースの参照を取得します。他のエンティティを変更する場合は対応するサービスを使用します。利用できる全サービスのリストは、オブジェクト、メソッド、サービスのガイドをご覧ください。

def main(client, ad_group_id):
  # Initialize appropriate service.
  ad_group_service = client.GetService('AdGroupService', version='v201702')

続いて ID を変更する広告グループのものに、ステータスを PAUSED に設定します。

# Construct operations and update an ad group.
  operations = [{
      'operator': 'SET',
      'operand': {
          'id': ad_group_id,
          'status': 'PAUSED'

その後、新たに作成された広告グループ オブジェクトをオペランド、SET を演算子として広告グループの演算オブジェクトを作成し、ステータスを PAUSED に設定します。

# Construct operations and update an ad group.
  operations = [{
      'operator': 'SET',
      'operand': {
          'id': ad_group_id,
          'status': 'PAUSED'

最後に広告グループ サービス インターフェースの mutate メソッドを呼び出し、広告グループの演算オブジェクトを渡します。

ad_groups = ad_group_service.mutate(operations)

プレースホルダをテスト用クライアント アカウントの広告グループ ID に置き換え、コードを実行します。実行したら、テスト アカウントで AdWords の管理画面にログインし、ステータスが変わっていることを確認してください。

PHP

IDE で、サンプル ファイルの PauseAd.php を開きます。

このファイルにも一般的な定型のコードがあり、設定ファイルの auth.ini から認証情報を取得しています。

今回は広告グループと広告の ID 用のプレースホルダ文字列があります。

// Enter parameters required by the code example.
$adGroupId = 'INSERT_AD_GROUP_ID_HERE';
$adId = 'INSERT_AD_ID_HERE';

広告グループ ID は、AdGroupService インターフェースの GET メソッドを介したプログラムによって取得します。ID は、AdWords の管理画面で該当の広告グループを表示し、その URL から簡単に取得することもできます。

このサンプルで重要なのは、実行時のコードです。その仕組みについて詳しく見ていきます。

まず、広告グループの変更に使う AdGroupService インターフェースの参照を取得します。他のエンティティを変更する場合は対応するサービスを使用します。利用できる全サービスのリストは、オブジェクト、メソッド、サービスのガイドをご覧ください。

  // Get the service, which loads the required classes.
  $adGroupAdService = $user->GetService('AdGroupAdService', ADWORDS_VERSION);

続いて既存の ID を使って広告が作成されます。

  // Create ad using an existing ID. Use the base class Ad instead of TextAd to
  // avoid having to set ad-specific fields.
  $ad = new Ad();
  $ad->id = $adId;

続いて新しい広告グループ オブジェクトを作成し、その ID を変更する広告グループの ID に設定します。

  // Create ad group ad.
  $adGroupAd = new AdGroupAd();
  $adGroupAd->adGroupId = $adGroupId;
  $adGroupAd->ad = $ad;

ステータスを PAUSED に設定します。

  // Update the status.
  $adGroupAd->status = 'PAUSED';

その後、新たに作成された広告グループ オブジェクトをオペランド、SET を演算子として、AdGroupOperation を作成します。

  // Create operation.
  $operation = new AdGroupAdOperation();
  $operation->operand = $adGroupAd;
  $operation->operator = 'SET';
  $operations = array($operation);

最後に広告グループ サービス インターフェースの mutate メソッドを呼び出し、広告グループの演算オブジェクトを渡します。

  // Make the mutate request.
  $result = $adGroupAdService->mutate($operations);

プレースホルダをテスト用クライアント アカウントの広告グループ ID に置き換え、コードを実行します。実行したら、テスト アカウントで AdWords の管理画面にログインし、ステータスが変わっていることを確認してください。

Perl

IDE で、サンプル ファイルの update_ad_group.pl を開きます。

このファイルの下部にも、前述のものと同様の一般的な定型のコードがあり、設定ファイルの adwords.properties から認証情報を取得しています。

このファイルでは、一時停止する広告グループと広告の ID 用のプレースホルダ文字列が追加されています。

# Replace with valid values of your account.
my $ad_group_id = "INSERT_AD_GROUP_ID_HERE";

広告グループ ID は、AdGroupService インターフェースの GET メソッドを介したプログラムによって取得します。ID は、AdWords の管理画面で該当の広告グループを表示し、その URL から簡単に取得することもできます。

このサンプルで重要なのは、実行時のコードです。その仕組みについて詳しく見ていきます。

まず、指定された adGroupID を使ってステータスが変更された広告グループを作成します。他のエンティティを変更をする場合は対応するサービスを使用します。利用できる全サービスのリストは、オブジェクト、メソッド、サービスのガイドをご覧ください。続いてステータスを PAUSED に設定します。

 # Create ad group with updated status.
  my $ad_group = Google::Ads::AdWords::v201702::AdGroup->new({
      id     => $ad_group_id,
      status => "PAUSED"
  });

その後、新たに作成された広告グループ オブジェクトをオペランド、SET を演算子として、広告グループの演算オブジェクトを作成します。

# Create operation.
  my $operation = Google::Ads::AdWords::v201702::AdGroupOperation->new({
      operand  => $ad_group,
      operator => "SET"
  });

最後に AdGroupService インターフェースの mutate メソッドを呼び出し、広告グループの演算オブジェクトを渡します。

# Update ad group.
  my $result = $client->AdGroupService()->mutate({operations => [$operation]});

プレースホルダをテスト用クライアント アカウントの広告グループ ID に置き換え、コードを実行します。実行したら、テスト アカウントで AdWords の管理画面にログインし、ステータスが変わっていることを確認してください。

Ruby

サンプル ファイルの update_ad_group.rb を開きます。

このファイルにも、前述のものと同様の一般的な定型のコードがあり、設定ファイルの adwords_api.yml から認証情報を取得しています。もう少し詳しく見ると、広告グループの ID 用のプレースホルダ文字列があります。

    # ID of an ad group to update.
    ad_group_id = 'INSERT_AD_GROUP_ID_HERE'.to_i

広告グループ ID は、AdGroupService インターフェースの GET メソッドを介したプログラムによって取得します。ID は、AdWords の管理画面で該当の広告グループを表示し、その URL から簡単に取得することもできます。

このサンプルでも、重要なのは実行時のコードです。その仕組みについて詳しく見ていきます。

まず、広告グループの変更に使う AdGroup サービス インターフェースの参照を取得します。他のエンティティを変更する場合は対応するサービスを使用します。利用できる全サービスのリストは、オブジェクト、メソッド、サービスのガイドをご覧ください。

ad_group_srv = adwords.service(:AdGroupService, API_VERSION)

続いて、新しい広告グループ オブジェクトを作成してその ID を変更する広告グループの ID に設定し、ステータスは PAUSED に設定します。この際は SET を演算子として使用します。

# Prepare for updating ad group.
  operation = {
    :operator => 'SET',
    :operand => {
      :status => 'PAUSED',
      :id => ad_group_id
    }
  }

最後に AdGroupService インターフェースの mutate メソッドを呼び出し、広告グループの演算オブジェクトを渡します。

# Update ad group.
  response = ad_group_srv.mutate([operation])

プレースホルダをテスト用クライアント アカウントの広告グループ ID に置き換え、コードを実行します。実行したら、テスト アカウントで AdWords の管理画面にログインし、ステータスが変わっていることを確認してください。

パターンを見直す

広告グループの一時停止と再開で使用した上記の手順とパターンは、API を利用したほとんどの変更作業に応用できるため、以下の手順を見直しておくことが大切です。

  1. 新しいオブジェクトを作成します
  2. そのオブジェクトの ID を変更するエンティティの ID に設定します
  3. 新しいオブジェクトにプロパティの新しい値を設定します
  4. SET を演算子 この新しいエンティティ オブジェクトをオペランドとして演算オブジェクトを作成します
  5. この演算オブジェクトを適切なサービスの MUTATE メソッドに渡します

この例では変更作業を処理するため、SET の演算子を使用しています。追加や削除の場合は ADD や REMOVE の演算子を使います。

仕組みがよくわからない場合は、他のコードのサンプルも確認すればすぐにパターンを把握できます。

パターンを把握したら、広告グループの入札単価の変更など、その他のさまざまな変更作業を簡単に設定できるようになります。

広告グループの入札単価を変更する

API の一般的な使用例としては、プログラムによる入札単価の変更も挙げられます。簡単な例として、雨の日に傘の広告の入札単価を引き上げるケースを見ていきます。その場合はアプリケーションがウェブ上の天気予報を参照し、AdWords API を介して該当の広告グループの入札単価を引き上げるよう設定できます。

この変更は、上記の例と同様の UpdateAdGroup のサンプルを使用して設定します。その際は AdGroupStatus の代わりに入札戦略を設定します。詳細は入札単価設定に関するガイドをご覧ください。

新しいキャンペーンを作成する

この使用例については以下をご覧ください。

Java

IDE で AddCampaigns.java を開きます。

多数のコードがありますが、パターンは前述の例と同様です。この例では、オブジェクト階層を作成してから、ADD 演算子を使用し、BudgetService を介して新しい予算を、CampaignService を介して新しいキャンペーンを追加しています。

ここでは、対象が新しいエンティティで ID がまだないため、ID を設定する必要はありません。

.NET

IDE で AddCampaigns.cs を開きます。

多数のコードがありますが、パターンは前述の例と同様です。この例では、オブジェクト階層を作成してから、ADD 演算子を使用し、BudgetService を介して新しい予算を、CampaignService を介して新しいキャンペーンを追加しています。

ここでは、対象が新しいエンティティで ID がまだないため、ID を設定する必要はありません。

Python

IDEで add_campaigns.py を開きます。

多数のコードがありますが、パターンは前述の例と同様です。この例では、オブジェクト階層を作成してから、ADD 演算子を使用し、BudgetService を介して新しい予算を、CampaignService を介して新しいキャンペーンを追加しています。

ここでは、対象が新しいエンティティで ID がまだないため、ID を設定する必要はありません。

PHP

IDE で AddCampaigns.php を開きます。

多数のコードがありますが、パターンは前述の例と同様です。この例では、オブジェクト階層を作成してから、ADD 演算子を使用し、BudgetService を介して新しい予算を、CampaignService を介して新しいキャンペーンを追加しています。

ここでは、対象が新しいエンティティで ID がまだないため、ID を設定する必要はありません。

Perl

IDE で add_campaigns.pl を開きます。

多数のコードがありますが、パターンは前述の例と同様です。この例では、オブジェクト階層を作成してから、ADD 演算子を使用し、BudgetService を介して新しい予算を、CampaignService を介して新しいキャンペーンを追加しています。

ここでは、対象が新しいエンティティで ID がまだないため、ID を設定する必要はありません。

Ruby

add_campaigns.rb を開きます。

多数のコードがありますが、パターンは前述の例と同様です。この例では、オブジェクト階層を作成してから、ADD 演算子を使用し、BudgetService を介して新しい予算を、CampaignService を介して新しいキャンペーンを追加しています。

ここでは、対象が新しいエンティティで ID がまだないため、ID を設定する必要はありません。

次のステップ

基本を理解したら、オブジェクト、メソッド、サービスに関するガイドや、アーキテクチャとコンセプトのセクション内の他のガイドをご覧ください。この API のアーキテクチャや利用できるサービス、API をアプリケーションに統合する方法の詳細を学ぶことができます。

これらのガイドを読んだら独自のアプリケーションを作成する準備は完了です。自動化による効率性の向上、カスタム レポートによる情報の透明性の向上など、この API を最大限に有効活用してください。

フィードバックを送信...

ご不明な点がありましたら、Google のサポートページをご覧ください。