コードの構造

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

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

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

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

クライアント ライブラリにあるコードのサンプルは、一般的な API 機能のほぼすべてを網羅したものとなっています。これらのサンプルは、大部分のバックエンド タスクを自動的に処理するなど、AdWords API アプリの開発に必要な作業を大幅に軽減するよう記述されています。

AdWords API コードのサンプルの一般的な構造を見てみましょう。以下で、必要な言語のタブをクリックしてください。

Java

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

GetCampaigns.java の main には、以下の処理を行う定型のコードがあります。

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

クライアント ライブラリのコードのサンプルをいくつか見ていくと、これらのコードが毎回のように使われているのがわかります。

GetCampaigns のサンプルには、もう 1 行コードを追加することも考えられます。前のガイドで、ads.properties ファイルにクライアントのお客様 ID を設定したことを思い出してください。

クライアント センター(MCC)アカウントの配下に多数のクライアント アカウントがある場合は、ads.properties ファイルからクライアントのお客様 ID を削除し、代わりに AdWordsSession オブジェクトを利用してプログラムにより ID を設定できます。その場合はこのオブジェクトを作成してから、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);

C#

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

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

C# ライブラリで最も重要なクラスは AdsUser クラスです。通常、AdsUser クラスでは 1 つの広告アカウント(この例では AdWords アカウント)をカプセル化します。

AdWordsUser クラスを利用すると、アプリケーションの app.config ファイルに指定されている設定で、API 呼び出しに使用できる事前設定済みのサービスクラスを作成できます。

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

クライアント センター(MCC)アカウントの配下に多数のクライアント アカウントがある場合は、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 を開きます。

このサンプルではまず、OAuth トークンを生成しています。

// Generate a refreshable OAuth2 credential for authentication.
$oAuth2Credential = (new OAuth2TokenBuilder())
    ->fromFile()
    ->build();

次に、生成したトークンを使用して、runExample() 関数を実行する API セッションを構築しています。

// Construct an API session configured from a properties file and the OAuth2
// credentials above.
$session = (new AdWordsSessionBuilder())
    ->fromFile()
    ->withOAuth2Credential($oAuth2Credential)
    ->build();
self::runExample(new AdWordsServices(), $session);

runExample() はこのサンプルのメイン関数です。この関数では、CampaignService のセレクタを使用してキャンペーンの ID と名前が取得されます。

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 => "v201802"});

前のガイドで、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 => "v201802"});
$client->set_client_id("123-456-7890");

Ruby

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

サンプル ファイルの 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

サンプルにはもう 1 行コードを追加することも考えられます。前のガイドで、設定ファイルの 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 コンソールに出力されます。

このコードのサンプルでは、レポートのタイプ(この場合、条件の掲載結果レポート)が指定されています。

reportDefinition.setReportType(ReportDefinitionReportType.CRITERIA_PERFORMANCE_REPORT);

また、取得するレポート項目も指定されています。

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

C#

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. を実行します。

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

このコードのサンプルでは、レポートのタイプ(この場合、条件の掲載結果レポート)が指定されています。

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_with_selector.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_with_selector.py を実行します。

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

このコードのサンプルでは、レポートのタイプ(この場合、条件の掲載結果レポート)が指定されています。

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

PHP

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

このサンプルには AdWordsSession の認証と作成を行う標準的なコードが含まれています。メイン関数の runExample() 内で、セレクタが構築され、レポートが定義されています。

// Create selector.
$selector = new Selector();
$selector->setFields(['CampaignId', 'AdGroupId', 'Id', 'Criteria',
    'CriteriaType', 'Impressions', 'Clicks', 'Cost']);

// Create report definition.
$reportDefinition = new ReportDefinition();
$reportDefinition->setSelector($selector);
$reportDefinition->setReportName(
    'Criteria performance report #' . uniqid());
$reportDefinition->setDateRangeType(
    ReportDefinitionDateRangeType::LAST_7_DAYS);
$reportDefinition->setReportType(
    ReportDefinitionReportType::CRITERIA_PERFORMANCE_REPORT);
$reportDefinition->setDownloadFormat(DownloadFormat::CSV);

このサンプルでは、CRITERIA_PERFORMANCE_REPORT というレポートのタイプと、取得するレポート項目も指定されています。

このレポートの定義をレポートのダウンローダーに渡します。

// Download report.
$reportDownloader = new ReportDownloader($session);
$reportDownloadResult =
    $reportDownloader->downloadReport($reportDefinition);
$reportDownloadResult->saveToFile($filePath);
printf("Report with name '%s' was downloaded to '%s'.\n",
    $reportDefinition->getReportName(), $filePath);

続いて、DownloadCriteriaReportWithSelector.php を実行します。ダウンロードしたファイルの場所がコンソールに出力されます。

Perl

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

前と同様に、設定ファイルの adwords.properties から値を取得して認証を処理する定型コードがあります。

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

このサンプルで注目したいのは、セレクタとレポート定義を作成する部分のコードです。

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_with_selector.pl を実行します。

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

このコードのサンプルでは、レポートのタイプ(この場合、条件の掲載結果レポート)が指定されています。

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_with_selector.rb を開きます。

前と同様に、設定ファイルの adwords_api.yml から値を取得して認証を処理する定型コードがあります。

def download_criteria_report_with_selector(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',
}

これを report_utils.download_report_as_file メソッドに渡します。

# 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_with_selector.rb を実行します。ダウンロードしたファイルの場所がコンソールに出力されます。

このコードのサンプルでは、レポートのタイプ(この場合、条件の掲載結果レポート)が指定されています。

: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";

C#

前のセクションで実行したコードのサンプルと 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 の方が簡潔です。指定しているレポートのタイプと項目も同じです。

// Create report query to get the data for last 7 days.
$reportQuery = 'SELECT CampaignId, AdGroupId, Id, Criteria, CriteriaType, '
    . 'Impressions, Clicks, Cost FROM CRITERIA_PERFORMANCE_REPORT '
    . 'WHERE Status IN [ENABLED, PAUSED] DURING LAST_7_DAYS';

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 メソッドに含まれています。処理を 1 段階ずつ見ていきましょう。

サンプルではまず、広告グループの変更に使う 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 の管理画面にログインし、ステータスが変わっていることを確認します。

C#

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 メソッドに含まれています。処理を 1 段階ずつ見ていきましょう。

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

public void Run(AdWordsUser user, long adGroupId) {
    // Get the AdGroupService.
    AdGroupService adGroupService =
        (AdGroupService) user.GetService(AdWordsService.v201802.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 から取得します。

注目したいコードはこの後です。処理を 1 段階ずつ見ていきましょう。

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

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

次に、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 を開きます。

個々の広告は、広告グループと広告の ID を使って識別されます。

const AD_GROUP_ID = 'INSERT_AD_GROUP_ID_HERE';
const AD_ID = 'INSERT_AD_ID_HERE';

広告グループ ID は、AdGroupService インターフェースの get() メソッドを介して取得できます。または、AdWords の管理画面で該当の広告グループを表示し、そのページの URL から取得します。

runExample() の処理を 1 段階ずつ見ていきましょう。

  1. 広告グループの変更に使う AdGroupService の参照を取得します。
    $adGroupAdService =
        $adWordsServices->get($session, AdGroupAdService::class);
    
  2. 広告オブジェクトを作成します。
    $ad = new Ad();
    $ad->setId($adId);
    
  3. 広告グループの広告オブジェクトを作成し、その広告グループ ID と広告を設定します。
    $adGroupAd = new AdGroupAd();
    $adGroupAd->setAdGroupId($adGroupId);
    $adGroupAd->setAd($ad);
    
  4. 広告グループの広告のステータスを PAUSED に設定します。
    $adGroupAd->setStatus(AdGroupAdStatus::PAUSED);
    
  5. 演算オブジェクトを設定し、mutate() メソッドを使って AdGroupAdService に送ります。
    // Create ad group ad operation and add it to the list.
    $operation = new AdGroupAdOperation();
    $operation->setOperand($adGroupAd);
    $operation->setOperator(Operator::SET);
    $operations[] = $operation;
    
    // Pause the ad on the server.
    $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 から取得します。

このサンプルで注目したいのは、実行時のコードです。処理を 1 段階ずつ見ていきましょう。

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

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

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

# Create operation.
my $operation = Google::Ads::AdWords::v201802::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 から取得します。

このサンプルでも、注目したいのは実行時のコードです。処理を 1 段階ずつ見ていきましょう。

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

ad_group_srv = adwords.service(:AdGroupService, API_VERSION)

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

# 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 演算子を使用しますが、追加や削除の作業には ADDREMOVE 演算子を使用します。

他のコードのサンプルもご覧いただければ、すぐにパターンを把握できるでしょう。

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

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

API の一般的な使用例には、プログラムによる入札単価の変更も挙げられます。標準的な例として雨の日に傘の広告の入札単価を引き上げる場合は、アプリでウェブの天気サービスを参照し、AdWords API を介して該当の広告グループの入札単価を引き上げます。

上記と同じ UpdateAdGroup のサンプルで、AdGroupStatus の代わりに入札戦略を設定すれば、この変更を実装できます。詳しくは入札単価設定に関するガイドをご覧ください。

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

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

Java

IDE で AddCampaigns.java を開きます。

コードは長くなりますが、パターンは上記と同じです。この例では、オブジェクト階層の作成後に ADD 演算子を使用して、BudgetService により新しい予算を、CampaignService により新しいキャンペーンを追加しています。

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

C#

IDE で AddCampaigns.cs を開きます。

コードは長くなりますが、パターンは上記と同じです。この例では、オブジェクト階層の作成後に ADD 演算子を使用して、BudgetService により新しい予算を、CampaignService により新しいキャンペーンを追加しています。

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

Python

IDE で add_campaigns.py を開きます。

コードは長くなりますが、パターンは上記と同じです。この例では、オブジェクト階層の作成後に ADD 演算子を使用して、BudgetService により新しい予算を、CampaignService により新しいキャンペーンを追加しています。

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

PHP

IDE で AddCampaigns.php を開きます。

通常どおり、メインの処理は runExample() で行われます。ここでは、予算、キャンペーン、入札戦略のほか、必要に応じてネットワークのターゲット設定やフリークエンシー キャップなども設定しています。最後に、キャンペーンを ADD 演算子でラップし、mutate() を介して演算オブジェクトを CampaignService に送っています。

Perl

IDE で add_campaigns.pl を開きます。

コードは長くなりますが、パターンは上記と同じです。この例では、オブジェクト階層の作成後に ADD 演算子を使用して、BudgetService により新しい予算を、CampaignService により新しいキャンペーンを追加しています。

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

Ruby

add_campaigns.rb を開きます。

コードは長くなりますが、パターンは上記と同じです。この例では、オブジェクト階層の作成後に ADD 演算子を使用して、BudgetService により新しい予算を、CampaignService により新しいキャンペーンを追加しています。

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

次のステップ

基本を理解したら、オブジェクト、メソッド、サービスのガイドや関連ガイドもご覧ください。この API のアーキテクチャやサービス、機能について詳しく学ぶことができます。

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

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

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