オブジェクト、メソッド、サービス

このガイドでは、一般的なキャンペーン管理タスクを例に挙げながら、AdWords API のオブジェクトとメソッドについて概要を説明します。続いて API のサービスについて説明し、参照ページへのリンクも紹介します。

なお、このガイドのコードのサンプルでは、AdWords API Java ライブラリが使われています。他のプログラミング言語については、クライアント ライブラリの全リストをご覧ください。

AdWords API は AdWords の上級者向けツールです。AdWords の新規ユーザーの方や、基本コンセプトについて復習したい方は、AdWords の基本をご覧ください。

オブジェクトの階層とスコープ

すべての AdWords アカウントはオブジェクトの階層として見ることができます。

各アカウント内に、運用する広告キャンペーンを意味する Campaign があります。

各 Campaign 内には、広告を論理的なグループにまとめた AdGroup があります。

各 AdGroup 内には複数の AdGroupAdAdGroupCriteria があります。AdGroupAd は運用する広告を意味します。AdGroupCriterion は、広告表示のトリガーとなる条件としてのキーワードを意味します。

campaign criteria を指定することで、キャンペーン全体を対象とした広告配信のルールを定義できます。キャンペーン全体の予算や期間も指定できます。

また、キャンペーン単位の広告表示オプションで、電話番号や住所などの広告の追加情報を指定することもできます。

AdWords のすべてのオブジェクトは固有の ID で識別されます。一部の ID はすべての AdWords アカウントにまたがるグローバル レベルで固有となりますが、その他の ID はそうではなく、特定の範囲内でのみ固有となります。AdWords 内の各オブジェクト ID の固有性については、下記をご覧ください。

オブジェクト ID 固有性の範囲 グローバル レベルでの固有性
Budget ID グローバル あり
Campaign ID グローバル あり
AdGroup ID グローバル あり
Ad ID 広告グループ なし(AdGroupId と AdId のペアはグローバル レベルで固有)
AdGroupCriterion ID 広告グループ なし(AdGroupId と CriterionId のペアはグローバル レベルで固有)
CampaignCriterion ID キャンペーン なし(CampaignId と CriterionId のペアはグローバル レベルで固有)
Ad Extensions キャンペーン なし(CampaignId と AdExtensionId のペアはグローバル レベルで固有)
Feed ID グローバル あり
Feed Item ID グローバル あり
Feed Attribute ID フィード なし
Feed Mapping ID グローバル あり
Label ID グローバル あり

ID に関するこれらのルールは、AdWords オブジェクトを保管するローカルのデータベースを設計する際の参考になります。

別のオブジェクトから派生しているオブジェクトには、Type フィールドも含まれます。たとえば TextAd には、Ad オブジェクトから派生していることを示す Type フィールドが含まれます。動的言語を使用する場合は、このフィールドによってオブジェクトのタイプを判別できます。たとえば Ad オブジェクトのタイプが TextAd かどうかを確認できます。

メソッドと処理

AdWords API では、サービスを使用して AdWords オブジェクトを管理できます。たとえば、CampaignService で Campaign を管理し、AdGroupService で AdGroups を管理するといった具合です。

これらのサービスでは、getmutate の 2 つの標準メソッドがエクスポーズされます。

get メソッド

get メソッドは、AdWords オブジェクトの取得に使用されます。たとえば、CampaignService.get を使用するとキャンペーンのリストを取得できます。

すべての get メソッドは、入力情報として Selector を受け取り、結果として Page を返します。AdWords API のデフォルトでは、オブジェクトのすべてのフィールドがデフォルトで返されるわけではないため、セレクタを作成する際は取得する field のリストを指定する必要があります。

結果のフィルタリングには predicates、結果の並べ替えには ordering、結果を取得する期間の制限には dateRange を使用します。

大量のオブジェクトを取得する場合は paging も指定する必要があります。AdWords API では、ページングなしに大量のオブジェクトを取得しようとすると SizeLimitError.RESPONSE_SIZE_LIMIT_EXCEEDED エラーが発生するためです。

以下はこの概念をコードで示したもので、アカウント内のすべてのキャンペーンを取得して表示します。

// Get the CampaignService.
CampaignServiceInterface campaignService =
    adWordsServices.get(session, CampaignServiceInterface.class);

int offset = 0;

// Create selector.
SelectorBuilder builder = new SelectorBuilder();
Selector selector = builder
    .fields(CampaignField.Id, CampaignField.Name)
    .orderAscBy(CampaignField.Name)
    .offset(offset)
    .limit(PAGE_SIZE)
    .build();

CampaignPage page = null;
do {
  // Get all campaigns.
  page = campaignService.get(selector);

  // Display campaigns.
  if (page.getEntries() != null) {
    for (Campaign campaign : page.getEntries()) {
      System.out.printf("Campaign with name '%s' and ID %d was found.%n", campaign.getName(),
          campaign.getId());
    }
  } else {
    System.out.println("No campaigns were found.");
  }

  offset += PAGE_SIZE;
  selector = builder.increaseOffsetBy(PAGE_SIZE).build();
} while (offset < page.getTotalNumEntries());

サービスごとの使用可能なセレクタのフィールドについては、セレクタのフィールドに関する参考ページをご覧ください。

クライアント ライブラリには、すべてのキャンペーン管理サービスの get メソッドのコードのサンプルが含まれています。各言語のクライアント ライブラリで利用できるキャンペーン管理サービスのサンプルについては、以下をご覧ください。

query メソッド

query メソッドは get メソッドの代わりとなるもので、セレクタではなく AdWords クエリ言語(AWQL)という SQL と同様の言語を使用します。多くの場合、同じリクエストでも AWQL でコーディングすると簡素化されます。query メソッドは一般的なサービスのほとんどに対応していますが、変換データには対応していません。

AWQL の有効性を上記の例で考えてみましょう。セレクタでは 4 行のコードを記述しますが、AWQL なら同一の情報を 1 つの文字列にまとめることができます。

String query = "SELECT Id, Name, Status ORDER BY Name";

FROM 句がない点に留意してください。これは、query メソッドを使用しているサービスによって、選択元が既に指定されるためです。レポートで使用する場合にのみ、AWQL は FROM 句に対応します。この文字列を使用するには、サービスの query メソッドを呼び出します。

CampaignPage page = null;
do {
  String pageQuery = query + String.format(" LIMIT %d, %d", offset, PAGE_SIZE);
  // Get all campaigns.
  page = campaignService.query(pageQuery);

  // Display campaigns.
  if (page.getEntries() != null) {
    for (Campaign campaign : page.getEntries()) {
      System.out.printf("Campaign with name '%s' and ID %d was found.%n", campaign.getName(),
          campaign.getId());
    }
  } else {
    System.out.println("No campaigns were found.");
  }

  offset += PAGE_SIZE;
} while (offset < page.getTotalNumEntries());

この呼び出しでは、上記の例の get の呼び出しと同じ結果が返されます。AWQL では、同じリクエストを get 呼び出しよりも簡潔で直感的に記述できます。詳細については、AWQL ガイドをご覧ください。

mutate メソッド

mutate メソッドは、AdWords オブジェクトの変換(作成、更新、削除)に使用します。

オブジェクトを変換するには、そのための Operation オブジェクトを作成する必要があります。たとえば Campaign を変換する場合は CampaignOperation を使用します。

Operator フィールドでは、実行する処理のタイプ(ADD、SET、または REMOVE)を指定します。operand フィールドでは変換するオブジェクトを指定します。キャンペーンを追加するコードは以下のようになります。

// Get the CampaignService.
CampaignServiceInterface campaignService =
    adWordsServices.get(session, CampaignServiceInterface.class);

// Create campaign.
Campaign campaign = new Campaign();
campaign.setName("Interplanetary Cruise #" + System.currentTimeMillis());
campaign.setStatus(CampaignStatus.PAUSED);
BiddingStrategyConfiguration biddingStrategyConfiguration = new BiddingStrategyConfiguration();
biddingStrategyConfiguration.setBiddingStrategyType(BiddingStrategyType.MANUAL_CPC);

// You can optionally provide a bidding scheme in place of the type.
ManualCpcBiddingScheme cpcBiddingScheme = new ManualCpcBiddingScheme();
cpcBiddingScheme.setEnhancedCpcEnabled(false);
biddingStrategyConfiguration.setBiddingScheme(cpcBiddingScheme);

campaign.setBiddingStrategyConfiguration(biddingStrategyConfiguration);

// You can optionally provide these field(s).
campaign.setStartDate(new DateTime().plusDays(1).toString("yyyyMMdd"));
campaign.setEndDate(new DateTime().plusDays(30).toString("yyyyMMdd"));
campaign.setAdServingOptimizationStatus(AdServingOptimizationStatus.ROTATE);
campaign.setFrequencyCap(new FrequencyCap(5L, TimeUnit.DAY, Level.ADGROUP));

// Only the budgetId should be sent, all other fields will be ignored by CampaignService.
Budget budget = new Budget();
budget.setBudgetId(budgetId);
campaign.setBudget(budget);

campaign.setAdvertisingChannelType(AdvertisingChannelType.SEARCH);

// Set the campaign network options to Search and Search Network.
NetworkSetting networkSetting = new NetworkSetting();
networkSetting.setTargetGoogleSearch(true);
networkSetting.setTargetSearchNetwork(true);
networkSetting.setTargetContentNetwork(false);
networkSetting.setTargetPartnerSearchNetwork(false);
campaign.setNetworkSetting(networkSetting);

// Set options that are not required.
GeoTargetTypeSetting geoTarget = new GeoTargetTypeSetting();
geoTarget.setPositiveGeoTargetType(GeoTargetTypeSettingPositiveGeoTargetType.DONT_CARE);
campaign.setSettings(new Setting[] {geoTarget});

// You can create multiple campaigns in a single request.
Campaign campaign2 = new Campaign();
campaign2.setName("Interplanetary Cruise banner #" + System.currentTimeMillis());
campaign2.setStatus(CampaignStatus.PAUSED);
BiddingStrategyConfiguration biddingStrategyConfiguration2 = new BiddingStrategyConfiguration();
biddingStrategyConfiguration2.setBiddingStrategyType(BiddingStrategyType.MANUAL_CPC);
campaign2.setBiddingStrategyConfiguration(biddingStrategyConfiguration2);

Budget budget2 = new Budget();
budget2.setBudgetId(budgetId);
campaign2.setBudget(budget2);

campaign2.setAdvertisingChannelType(AdvertisingChannelType.DISPLAY);

// Create operations.
CampaignOperation operation = new CampaignOperation();
operation.setOperand(campaign);
operation.setOperator(Operator.ADD);
CampaignOperation operation2 = new CampaignOperation();
operation2.setOperand(campaign2);
operation2.setOperator(Operator.ADD);

CampaignOperation[] operations = new CampaignOperation[] {operation, operation2};

// Add campaigns.
CampaignReturnValue result = campaignService.mutate(operations);

// Display campaigns.
for (Campaign campaignResult : result.getValue()) {
  System.out.printf("Campaign with name '%s' and ID %d was added.%n", campaignResult.getName(),
      campaignResult.getId());
}

AdWords API のクライアント ライブラリには、すべてのキャンペーン管理サービスに対応する mutate メソッドを使用するコードのサンプルが用意されています。

AdWords アカウントで変換できるオブジェクトの数には、タイプごとに上限があります。AdWords オブジェクトのタイプごとの変換数の上限については、ヘルプセンターの記事をご覧ください。ただし、この上限はキャンペーンをプランニングする際の目安としてのみ使用し、アプリケーションには書き込まないでください。

mutate の呼び出しを実行する際は、1 回のリクエストで 1 つの処理を送る操作を何度も繰り返すより、1 回のリクエストで複数の処理を送信した方が効率的です。これにより、サーバーとやり取りする回数が減るため、アプリケーションのパフォーマンスが向上します。

また、単一の親エンティティに対する処理をグループ化することも最適化のポイントなります。たとえば広告を追加する場合は、複数の広告グループに対して広告の追加を個別にリクエストするのではなく、同じ広告グループに対する広告の追加を 1 つのリクエストにまとめます。詳細については、推奨設定ガイドをご覧ください。

operator フィールド

前述したように、operator フィールドでは実行する変換処理のタイプとして ADD、SET、または REMOVE を指定します。

ADD は新しいオブジェクトの作成、SET は既存のオブジェクトの更新、REMOVE は既存のオブジェクトの削除です。ただしサービスによっては一部の演算子を使用できない場合があります。

たとえば、いったん作成した AdWords キャンペーンを完全に削除することはできず、削除済みというマークを付けることができるだけです。削除済みにしたオブジェクトでも、詳細情報と統計データを取得することはできます。

AdWords API の CampaignService は REMOVE 演算子には対応していないため、Campaign を削除する場合は SET 演算子を使ってステータスを REMOVED に変更する必要があります。

また、キャンペーンのターゲットのオブジェクトは変更できず、ADD か REMOVE のみ使用できます。

以下の表では、AdWords オブジェクトのタイプごとに、ステータスを変更する際の処理方法をまとめています。

タイプ 新しいオブジェクトの追加 アクティブ 一時停止 削除 / 無効化
Campaign アクション: mutate
処理: ADD
ステータス: ENABLED
アクション: mutate
処理: SET
ステータス: ENABLED
アクション: mutate
処理: SET
ステータス: PAUSED
アクション: mutate
処理: SET
ステータス: REMOVED
AdGroup アクション: mutate
処理: ADD
ステータス: ENABLED
アクション: mutate
処理: SET
ステータス: ENABLED
アクション: mutate
処理: SET
ステータス: PAUSED
アクション: mutate
処理: SET
ステータス: REMOVED
AdGroupAd アクション: mutate
処理: ADD
ステータス: ENABLED
アクション: mutate
処理: SET
ステータス: ENABLED
アクション: mutate
処理: SET
ステータス: PAUSED
アクション: mutate
処理: REMOVE
ステータス: DISABLED
BiddableAdGroupCriterion アクション: mutate
処理: ADD
ステータス: ENABLED
アクション: mutate
処理: SET
ステータス: ENABLED
アクション: mutate
処理: SET
ステータス: PAUSED
アクション: mutate
処理: REMOVE
ステータス: REMOVED
UserList アクション: mutate
処理: ADD
ステータス: OPEN
なし なし アクション: mutate
処理: SET
ステータス: CLOSED
Experiment アクション: mutate
処理: ADD
ステータス: ENABLED
なし なし アクション: mutate
処理: SET
ステータス: REMOVED
Feed アクション: mutate
処理: ADD
ステータス: ENABLED
なし なし アクション: mutate
処理: REMOVE
ステータス: REMOVED
FeedMapping アクション: mutate
処理: ADD
ステータス: ENABLED
なし なし アクション: mutate
処理: REMOVE
ステータス: REMOVED
FeedItem アクション: mutate
処理: ADD
ステータス: ENABLED
なし なし アクション: mutate
処理: REMOVE
ステータス: REMOVED
CustomerFeed アクション: mutate
処理: ADD
ステータス: ENABLED
なし なし アクション: mutate
処理: REMOVE
ステータス: REMOVED
CampaignFeed アクション: mutate
処理: ADD
ステータス: ENABLED
なし なし アクション: mutate
処理: REMOVE
ステータス: REMOVED
AdGroupFeed アクション: mutate
処理: ADD
ステータス: ENABLED
なし なし アクション: mutate
処理: REMOVE
ステータス: REMOVED

同時変換

複数のユーザーがアプリケーションを使って同一のオブジェクトに変更を加える場合や、処理能力を高めるために複数のスレッドを使用して同時並行で AdWords オブジェクトを変換する場合は、AdWords が同一のオブジェクトに対する同時変換をどう処理しているのかを把握することが重要になります。

AdWords オブジェクトには、複数のソースから同時並行で変更を加えることはできません。同一のアプリケーションや異なるアプリケーションの複数のスレッド(アプリケーションと AdWords Editor の同時セッションなど)で同じオブジェクトを更新する場合などがこれに該当します。AdWords API では、オブジェクトの更新前にロックをかけることはできません。2 つのソースによって同時にオブジェクトが変換された場合は、CONCURRENT_MODIFICATION_ERROR というエラーが発生します。

AdWords API の同時変換の詳細については、こちらのブログ記事をご覧ください。

非同期変換と同期変換

AdWords API の mutate メソッドは同期型です。API 呼び出しを行うと、オブジェクト変換が完了した後に応答が返されるため、リクエストのたびに応答を待つ必要があります。この手法ではコードが比較的簡素になりますが、負荷分散に悪影響が生じたり、呼び出しの完了を待つ間にリソースの浪費が生じたりすることがあります。

別のアプローチとして、BatchJobService を使用してオブジェクトを非同期的に変換する方法もあります。この方法では複数のサービスのバッチ処理を実行できます。処理の完了を待つ必要はありません。バッチ処理が送信されると、AdWords API サーバーによって処理が非同期的に実行されるためマシンに他の処理を実行する余地が生まれ、ジョブの完了まで定期的にステータスを確認できるようになります。

非同期型の処理の詳細については、バッチ処理に関するガイドをご覧ください。

変換の検証

validateOnly SOAP ヘッダーを使用すると、実際のデータに呼び出しを実行することなく、API 呼び出しをテストできます。実際の処理を行う前にパラメータの不足やフィールドの値の正確性をチェックすることができます。

この機能を使用するには、RequestHeadervalidateOnly フィールドを true に設定します。クライアント ライブラリでは、このフィールドはデフォルトで false に設定されます。

この機能ではリクエストが実行されたかのように完全に検証されますが、最終的な実行はスキップされます。エラーが検出されなかった場合は空の応答が返されます。検証に失敗した場合は、失敗の内容を示すエラー メッセージが返されます。

Java のライブラリで validateOnly を設定する方法の例は以下のとおりです。

Credential oAuth2Credential = new OfflineCredentials.Builder()
    .forApi(Api.ADWORDS)
    .fromFile()
    .build()
    .generateCredential();

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

session.setValidateOnly(true);

このセッションで実行された API 呼び出しは、すべて validateOnly ヘッダーが true に設定されます。

validateOnly ヘッダーは、広告に一般的なポリシー違反が含まれていないかチェックする際に特に役立ちます。特定の語句や句読点、大文字の使用、長さなどの点でポリシー違反が含まれている広告は、自動的に不承認になります。広告を一括でアップロードしようとした際に問題のある広告が 1 つでもあると他の広告もすべてアップロードに失敗する可能性があります。新しい広告を validateOnly でテストすることで不承認になる広告を簡単に確認できます。具体例については、ポリシー違反エラーを処理するためのコードのサンプルをご覧ください。

クライアント ライブラリを使用しない場合は、適切な SOAP ヘッダーを設定すれば変換リクエストを検証できます。

AdWords API サービス

このセクションでは、AdWords API で利用できるサービスについて解説します。各サービスの詳細情報が記載されたページへのリンクも用意しています。

AdWords API のサービスは、機能によって 4 つのカテゴリに分類できます。

キャンペーンのデータ管理

キャンペーンのデータ管理サービスでは、AdWords キャンペーンとそれに関連するエンティティに操作を加えることができます。各キャンペーンのデータ管理サービスは、キャンペーンのデータ階層内のエンティティに対応しています。

サービス 説明
CampaignService キャンペーンを作成、更新、削除します。キャンペーンは広告グループで構成され、それぞれに予算と入札戦略、配信期間、ターゲット設定があります。
AdGroupService 広告グループを作成、更新、削除します。広告グループは広告と条件のセットで構成され、その条件のデフォルトの入札単価も指定できます。
AdGroupAdService 広告を作成、更新、削除します。
CampaignExtensionSettingService 広告表示オプションを作成、更新、削除します。キャンペーンの広告表示オプションを利用すると、所在地や追加リンク、電話番号などの補完情報をキャンペーン内のすべての標準のテキスト広告に追加できます。
CampaignCriterionService
AdGroupCriterionService
条件を作成、更新、削除します。条件とは、広告を表示するかどうかを決める条件のことを指します。
ConversionTrackerService
OfflineConversionFeedService
ユーザーが広告をクリックした後の行動を調べることで、広告とキーワードの有効性を測定します。OfflineConversionFeedService では、オフライン コンバージョンのデータのインポートを処理します。
DataService 指定された条件を基に広告キャンペーンの管理データを取得します。
FeedService
FeedItemService
FeedMappingService
AdGroupFeedService
CampaignFeedService
カスタムのデータフィードを作成してサイトリンク表示オプションや電話番号表示オプション、アプリリンク表示オプションを管理します。
AdwordsUserListService ユーザーリストを作成、更新、削除します。ユーザーリストとユーザーリストの条件を使用することで、ウェブサイト上でコンバージョンに至ったことがあるユーザーに広告を表示できます。
BudgetService 予算を作成、更新、削除します。複数のキャンペーン全体で共有する予算を管理できます。

最適化

最適化サービスでは、掲載結果データを取得して新しい条件設定の参考にすることができます。

サービス 説明
ReportDefinitionService さまざまな掲載結果レポートを作成、ダウンロードします。
TargetingIdeaService 指定したパラメータを基にして新しいキーワードとプレースメントの候補を生成します。
TrafficEstimatorService 提案されたキャンペーン、広告グループ、キーワードのトラフィックの推定値を取得します。
ExperimentService ウェブテストを作成、実施して、キーワードや入札単価、プレースメントをテストできます。

アカウントの管理

アカウント管理サービスを使用してアカウントのアクティビティをトラッキングできます。

サービス 説明
CustomerService クライアント アカウントの基本情報を取得します。
CustomerSyncService 指定した期間内におけるキャンペーンの変更履歴データを取得します。
ManagedCustomerService クライアント アカウントと、MCC アカウントとクライアント アカウントのリンク設定を管理します。

ユーティリティ

以下のユーティリティ サービスを使用すると、AdWords API によって有用性の高いさまざまなタスクを実行できます。

サービス 説明
BatchJobService 大量のキャンペーンのデータ処理を非同期的に実行します。バッチ処理は、標準のウェブサービスに対する同期的な呼び出しよりも完了に時間がかかりますが、その他の点でメリットがあります。詳細はバッチ処理に関するガイドをご覧ください。
GeoLocationService 指定した住所の座標とカノニカル アドレスを取得します。
MediaService メディアベースの広告(イメージ広告や動画広告)で使用するメディアの ID をアップロード、取得します。
ConstantDataService API で使用する定数値を取得します。
LocationCriterionService 地域に関する条件の ID を取得します。

キャンペーン データ

キャンペーン データの処理は、AdWords API を使って実行する基本的なタスクのひとつです。以下の表では、キャンペーン データの各エンティティと、他のキャンペーン データとそのエンティティとの関係性をまとめています。

エンティティ
子エンティティ(数量)
データのタイプ 説明
キャンペーン
広告グループ(1 以上)
キャンペーンのターゲットのリスト(7)
キャンペーンの広告表示オプション(0 以上)
キャンペーンの条件(0 以上)
Campaign キャンペーンは広告グループで構成され、それぞれに予算と入札戦略、配信期間があります。
広告グループ
広告(1 以上)
条件(1 以上)
AdGroup
広告グループは広告と条件のセットで構成され、その条件のデフォルトの入札単価も指定できます。
広告
広告表示オプションの上書き(0 以上)
AdGroupAd 利用できる広告のタイプは API リファレンスにまとめられており、抽象型の Ad タイプのサブクラスとなります。
条件
なし
AdGroupCriterionCampaignCriterion 条件とは、広告を表示する場合(入札可能な条件)と表示しない場合(除外条件)を決める条件を指します。 広告グループの条件は、親の広告グループ内の広告に影響します。常に除外条件となるキャンペーンの条件では、キャンペーンの広告を表示しない条件を定義します。
広告表示オプション
なし
CampaignExtensionSetting キャンペーンの広告表示オプションを利用すると、所在地や追加リンク、電話番号などの補完情報をキャンペーン内のすべての標準のテキスト広告に追加できます。
フィード
なし
Feed フィードはデータと広告表示オプション(サイトリンク、アプリリンク、電話番号)をつなぐパイプの役目を果たします。
ユーザーリスト
なし
UserList ユーザーリストを使用すると、ウェブサイトで関心を示したことがあるユーザーをトラッキングできます。ユーザーリスト条件を作成して既存のユーザーリストにリンクさせることで、このグループのユーザーを広告のターゲットに設定できます。
予算
なし
Budget 予算は、キャンペーンの広告掲載費用を管理するために使用します。予算は複数のキャンペーン全体で共有できます。その場合は最適な予算配分が自動的に行われます。

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

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