AdWords UI と API の対応について - 2015/04/17 AdWords API ワークショップ 東京

1. AdWords UI と AdWords API の対
応について
AdWords UI と API
timoboz@google.com

2. アジェンダ
● イントロダクション - AdWords API について
● 基本 - キャンペーン、広告について
● レポーティング – API 経由でのレポート取得

3. イントロダクション
AdWords API について

4. UI vs. API
● UI = ユーザー インターフェイス
○ サービスを利用する人間のためのインターフェイス
○ 入力：クリック、テキスト入力など
○ 出力：ブラウザ・HTML、ネイティブ UI など
● API = アプリケーション プログラミング インターフェイス
○ サービスを利用するアプリケーションのためのインターフェイ
ス
○ 入力：メソッドの呼び出し、SOAP メッセージなど
○ 出力：クライアント ライブラリ、ウェブサービスなど

5. これら AdWords に当てはめると
AdWords AdWords UI
API
AdWords API
AdWords アプリ
ケーション ユーザー
AdWords Editor
?サードパーティ アプ
リケーション

6. 基本
キャンペーン、広告について

7. U
I
認証
● Google Account Manager
による認証
● ブラウザのクッキーを利用した
シングル サインオン

8. A
PI
api.adwords.refreshToken=INSERT_REFERSH_TOKEN_HERE
api.adwords.clientId=INSERT_CLIENT_ID_HERE
api.adwords.clientSecret=INSERT_CLIENT_SECRET_HERE
api.adwords.developerToken=INSERT_DEVELOPER_TOKEN_HERE
認証（続き）
● 認証の仕組み：OAuth 2
○ RefreshToken を取得
○ 必要なすべての値を properties / ini / config ファイ
ルに保存
○ 残りは起動時にクライアント ライブラリが処理 A
PI

9. U
I
AdWords オブジェクト
● AdWords はいくつかのオブジェクトから構成されてい
る
（キャンペーン、広告グループ、広告など）
● UI 上ではそれぞれの基本オブジェクトはタブとして表
示

10. U
I
AdWords の主なオブジェクト
● アカウント：AdWords の利用するお客様
● キャンペーン：広告グループを論理的にまとめるも
の（予算を定義）
● 広告グループ：同じキーワード群でトリガーされる類
似の広告の集合
● 広告：広告が表示される時に、実際に表示されるコ
ンテンツ（テキスト、画像など）

11. U
I
AdWords の主なオブジェクト（続き）
アカウント
キャンペーン キャンペーン
広告グループ 広告グループ
広告
オンライン エレクトロニクス ストア
テレビ カメラ
プラズマ テレビ 液晶テレビ
最高のプラズマテレビをお探し
のお客様はぜひ当店へ！2015年モデルのプラズマ
テレビが新登場！
広告
キーワード
プラズマテレビ 購入
最新 プラズマテレビ
プラズマテレビ 価格
キャンペーン
電話
キーワード
キーワード

12. A
PI
オブジェクト、サービス、オペレーション
● 基本原則：オブジェクトごとに 1 種のサービス
○ get オブジェクトを取得。Selector で取得項目、条件を指定
○ query オブジェクトを取得。AWQL で取得項目、条件を指定
○ mutate 下記の operator を使用してオブジェクトを変更
■ ADD 新規オブジェクトを作成
■ SET オブジェクトを更新
■ REMOVE オブジェクトを削除

13. A
PI
一般的な例
AdWordsSession session = [...]
AdWordsServices services = [...]
XYServiceInterface service =
services.get(session, XYServiceInterface.class);
Selector selector = new Selector();
selector.setFields(new String[] {"Id", "Name"});
XYPage page = service.get(selector);
for (XY object : page.getEntries()) {
System.out.println(object.getId() +
" - " + object.getName());
} A
PI
API を使うための基本
的なオブジェクト
サービスを作成
データを取得
具体的な内容を指定
- 取得フィールド、条件、期
間、その他...
結果内の各データを取得
注意: Selector で指定した
フィールドのみ値が返されます

14. A
PI
一般的な例
AdWordsSession session = [...]
AdWordsServices services = [...]
CampaignServiceInterface service =
services.get(session, CampaignServiceInterface.class);
Selector selector = new Selector();
selector.setFields(new String[] {"Id", "Name"});
CampaignPage page = service.get(selector);
for (Campaign object : page.getEntries()) {
System.out.println(object.getId() +
" - " + object.getName());
} A
PI
Selector selector = new SelectorBuilder()
.fields("Id", "Name").build()
Syntactic Sugar

15. A
PI
キャンペーンに関係するサービスの例
A
PI
CampaignService
AdGroupService AdGroupAdService
CampaignCriterionService

16. 広告表示オプション
● UI: すべての広告表示オプションは
1 つのタブにまとめられている
● V201409: Feed Services Old
○ 汎用的な feed を定義し、内容を追加、
マッピング, キャンペーンへの関連付け
● V201502: 専用のService New!
○ 広告表示オプションの種類ごとの feed items と各オブ
ジェクトへ関連付を行うサービス

17. A
PI
広告表示オプションの例
AdWordsSession session = [...]
AdWordsServices services = [...]
CampaignExtensionSettingServiceInterface service = [...]
SitelinkFeedItem sitelink = new SitelinkFeedItem();
sitelink.setSitelinkText("Store Hours");
sitelink.setSitelinkFinalUrls(new UrlList(new String[]
{"http://www.example.com/storehours"}));
CampaignExtensionSetting campaignExtSetting = new
CampaignExtensionSetting();
campaignExtSetting.setCampaignId(campaignId);
campaignExtSetting.setExtensionType(FeedType.SITELINK);
A
PI

18. A
PI
広告表示オプションの例（続き）
ExtensionSetting extSetting = new ExtensionSetting();
extSetting.setExtensions(
new ExtensionFeedItem[] {sitelink});
campaignExtSetting.setExtensionSetting(extSetting);
CampaignExtensionSettingOperation op = new
CampaignExtensionSettingOperation();
op.setOperand(campaignExtSetting);
op.setOperator(Operator.ADD);
CampaignExtensionSettingReturnValue returnValue =
service.mutate(
new CampaignExtensionSettingOperation[] {op});
A
PI

19. レポーティング
API 経由でのレポート取得

20. U
I
AdWords ダッシュボード
U
I

21. U
I
レポート と 管理
U
I
ダウンロード
カスタマイズ

22. A
PI
API を使用したレポーティング
● ReportDownloader を使用したレポート機能*
○ UI を使用する場合と同様、ストリーム・ファイルとしてダウ
ンロード可能
○ ReportDefinition を使用してレポート タイプ、列、フィ
ルタ、フォーマットなどを定義可能
○ 代替方法：AWQL
* Java の場合

23. A
PI
レポーティング例
Selector selector = new Selector();
selector.getFields().addAll(Lists.newArrayList(
"CampaignId", "Impressions", "Clicks"));
ReportDefinition rd = new ReportDefinition();
rd.setSelector(selector);
rd.setReportName("Test Report");
rd.setDateRangeType(ReportDefinitionDateRangeType.LAST_30_DAYS);
rd.setReportType(ReportDefinitionReportType.CAMPAIGN_PERFORMANCE_REPORT);
rd.setDownloadFormat(DownloadFormat.CSV);
rd.setIncludeZeroImpressions(false);
ReportDownloadResponse response =
new ReportDownloader(session).downloadReport(rd);
Streams.copy(response.getInputStream(), System.out);
A
PI
A
PI

24. A
PI
レポーティング例（続き）
"Test (Feb 2, 2015-Mar 3, 2015)"
Campaign ID,Impressions,Clicks
225151578,120310,869
225381138,2284,10
Total,122594,879
A
PI
A
PI

25. A
PI
レポーティング例（AWQL）
String query = "SELECT CampaignId, Impressions, Clicks"
+ " FROM CAMPAIGN_PERFORMANCE_REPORT" +
+ " WHERE Impressions > 0"
+ " DURING LAST_30_DAYS";
ReportDownloadResponse response =
new ReportDownloader(session).downloadReport(query, DownloadFormat.CSV);
Streams.copy(response.getInputStream(), System.out);
A
PI
A
PI

26. A
PI
API レポーティング マッピング
A
PI
A
PI
UI API 例
表示項目 fields selector.getFields().add("Name");
期間 dateRange reportDefinition.setDateRangeType(
ReportDefinitionDateRangeType.LAST_30_DAYS);
フィルタ predicates Predicate p = new Predicate();
p.setField("Impressions");
p.setOperator(PredicateOperator.GREATER_THAN);
p.getValues().add("3000");
形式 downloadFormat reportDefinition.setDownloadFormat(
DownloadFormat.CSV);
参考：https://developers.google.com/adwords/api/docs/guides/uireports

27. A
PI
API Reporting Mappings cont.
A
PI
UI API Example
分割 (フィールドにより定義 )
並べ替え サポートされていません
ページ分割 サポートされていません
スケジュール設定 サポートされていません
メール送信 サポートされていません
A
PI
参考：https://developers.google.com/adwords/api/docs/guides/uireports

28. A
PI
レポート タイプ
A
PI
CAMPAIGN_PERFORMANCE_REPORT
ADGROUP_PERFORMANCE_REPORT
完全な一覧はこちらをご覧ください： http://goo.gl/HlGePj

29. 関連資料
● AdWords ヘルプ
● API デベロッパー ガイド
● レポートの管理画面へのマッピング