こんにちは id:hano_tea です。
真・Google Ads API 徹底入門の最後の記事、 公式ドキュメントの歩き方編です。
真・Google Ads API 徹底入門のこれまでの記事は以下からどうぞ。
最終回となる今回は Google Ads API に関連するドキュメント類の読み方、歩き方について解説します。
目次
公式ドキュメントの構成
解説中に度々出てきていますが、公式ドキュメントは以下のページになります。
2020/04/15 現在、公式ドキュメントは以下のような構成になっています。
- Guides
- 重要
- Google Ads API に関わる概念的な話やコード以外の情報(GAQL の文法やレートリミットなど)、ベストプラクティスといった情報がまとまっているセクション
- リリースノートなども掲載されているので使う機会は多いです
- 便利ツール(GAQL Query Builder)もここにあります
- やりたいこと、目的から方法を調べることができますが、カバー範囲はそこまで広くはないです
- Migration
- 主に Adwords API を使用している人々に向けた移行ガイド
- Adwords を使っていなくても、 Guides と同じように目的からの逆引きに使えたりすることもあります
- あんまり見ることは多くないと思います
- Reference
- 重要
- 公式ドキュメントの中で最も使用頻度の高いセクション
- Google Ads API で使える Service, resource の一覧や詳細情報がまとまっています
- 何か Google Ads API でやりたいことがある時にまず見るページ
- Reports
便利な気がするんだけど実はあんまり見たことがない- Search でレポートデータを取得する際に便利なセクション
- Search で指定できるリソースや、各リソースに対応したメトリクス、セグメンテーションの情報が一覧できる
- Libraries & Examples
- 結構重要
- 特に以下の2つ
- ただしサンプルコードはやや古い機能を使っていたり、最新版で導入された便利機能などを使っていないことがあるので注意
- Support & Policies
- あんまり見ない
- API のアクセスレベルに関する情報とかレートリミット系の情報がいくつか入っている
- 気付いていなかったがなんか便利そうなページがいくつか増えてた
- Google Ads API ワークショップに関する情報
- 特に 2019 の Google Ads API ワークショップの動画集 があったので必見かも
- Google Ads Developer Starter Checklist
- Google Ads API の使い始め用ガイドっぽい…?
- Google Ads API ワークショップに関する情報
上記リスト中でも書きましたが、 Guides
, Reference
が重要なページになります。 Libraries & Examples
も結構役に立ちます。
以下では解説があったほうがよさそうな Reference
, Reports
に焦点を当てていきます。
Guides
, Libraries & Examples
はやりたいことベースでページを見ていけばいいので特に解説は不要な気がしています。
Reference
Reference には Google Ads API を利用する際に利用する各種 Service やオブジェクトそのものの情報などがまとまっています。 一番よく使うページではありますが、情報量が非常に多いので、必要な情報を探しだしたり、やりたいことベースで情報を探すのには多少の慣れが必要です。
Google Ads API は基本的に Service を中心にして何らかの操作を行なっているというのは Search, Mutate の各記事内で説明したとおりです。 そのため、このリファレンスも基本的には Service の情報を起点として調べるのが最もよくあるシチュエーションだと思います。
例えばキャンペーンに対して Mutate をする際に調べる流れとしては、
- 自分が操作したい対象のオブジェクトのサービスのリファレンスページを探す
- MutateCampaign に必要なリクエスト内容について調べる
- 例: MutateCampaignRequest へのリンクをクリック
- Request 時に必要なフィールドが出てくる
- このレベルは基本的に
customer_id
とoperations
でほぼ共通のはず - 例: MutateCampaignsRequest
- このレベルは基本的に
- 行いたい Operation のページを開く
- 例: CampaignOperation
- 内容はどれもたぶんほぼ共通、 create/update は対象オブジェクト、 remove はリソース名を要求されるはず
- Operation ページの中身にある各オブジェクトの詳細ページに飛んで必要なリクエスト内容を確認する
- 例: Campaign
- 慣れるとこのリソース毎のページを直に確認、にショートカットもできそう
- 必要に応じてリクエストに必要なリソースの詳細を更に調べる
- 例えば
ShoppingSetting
などが別リソースの例として挙げられる
- 例えば
のようになります。 リンクをひたすらたどっていくような感じになるのですが、別タブをどんどん開いていくような感じで掘っていくのをおすすめします。
Reports
Report は各種オブジェクトや広告成果レポートの情報を取得する際に役立つ情報が掲載されています。 初見だとどう読めば良いのかが若干分かりにくいので、簡単に読み方を説明します。
Resource with metrics
Resource with metrics のページは名前の通り、 metrics
を取得できるようなリソースの情報がまとまっているセクションです。
上部のテキストボックスに何らかのキーワードを入力すると、ページ内でその語句を含んでいるような情報のみに表示内容がフィルタされます。 目的の情報が決まっている場合は活用するとスムーズに必要な情報にたどり着けるかと思います。
その下の Attributed resources
には、「このリソースから参照できる別リソース」の一覧が表示されています。
どういうことかというと、例えば Campaign
の Attributed resources
には
bidding_strategy
campaign_budget
customer
の3つがありますが、 Campaign
に対して何らかのクエリを発行する際は、
対象としている Campaign
に関連している(紐ついている)上記3つのリソースの情報も取得できる、ということになります。
対象リソースから見て親にあたるようなリソースだったり、 あるいは対象リソースが1つだけ持っている(1vs1 関連のイメージ)ようなリソースの情報が取れることが多いです。
このページだけを見ていてもイマイチピンと来ないかもしれないですが、 Intaractive Query Builder 上で色々クエリを作ってみると理解しやすいかもしれないです。
リソース選択後に選べるようになるフィールド一覧で、 segments, metrics, 及び対象としたリソース以外にも、
リソースに紐ついたフィールドがいくつか出てきますが、それらはこの Attributed resources
に掲載されているものと一致しているはずです。
更にその下を見ていくと3カラムで構成された表が出てきます。 左から Resource fields
, Segments
, Metrics
となっています。
Resource fields
は対象オブジェクトそのものの情報のことで、 id
や name
, status
といったものが含まれます。
Segments
はレポートの取得時に使う、「どういう指標、属性でグルーピング、区切るか」という時に使える情報が一覧になっています。
例えば date
, month
, device
, conversion_action
など。
Metrics
はレポート取得時に使用できる「広告成果の指標」が一覧になっています。例えば impressions
, clicks
, all_conversions
など。
ここに掲載されている情報をもとに Search 用のクエリを組み立て、必要な情報を取得する、という感じに使っていきます。
Resource without metrics
without metrics の方は前述の with metrics とは違い、 metrics、すなわち紐付いた広告成果などがないタイプのリソースがこちらにまとまっています。
その特性上、そのオブジェクトそのものの情報しか取得できないため、ページの内容もシンプルになっています。
3カラムの表などはなく、 witn metrics の方でいうと Resource fields
に相当するような情報のみが掲載されているような感じ。
Google Ads API Ruby Client Lib Repository の歩き方
Google Ads API を扱う上でもう1点確認しておきたいものとして、各言語用クライアントライブラリのリポジトリが挙げられます。 ここでは Ruby のクライアントライブラリの話について触れておきます。
Client 作成まわり
Search 用のドキュメントの最初のほうにさらっと書いた認証情報を使った Client の作成周りはこちらのリポジトリ内にガイドがあります。
認証情報の受け渡し方はいくつかやり方があるので、ガイドを見ながら各環境で適したやり方を選んでもらうのが良いと思います。
Logging Guide
ログ周りは INFO レベルで出しておくと良いとうっすら触れましたが、リポジトリ上にも項目はあったりします。
(現状だと https://developers.google.com/google-ads/api/docs/client-libs/ruby/logging へのリンクがあるだけですが…)
Sample Codes
サンプルコード類はリファレンス内にも掲載されていましたが、リポジトリ内にもコードが存在していたりします。
全部見比べたわけではないですが、公式の Examples に掲載されていないものもリポジトリ内にあったりするので、 サンプルコードがほしい時はリポジトリ内の方を見たほうが多くの情報を得られると思います。
Generated Code について
実はリポジトリ上にあるコードは不完全…というか、いくつかのファイルが含まれていなかったりします。
ローカルにある gem のディレクトリ内にあるコードが完全版です。 vendor/bundle
とかにだいたいあると思います。
特に Factory 周りのコードはここの実装を見ないと分からない(GitHub 上では確認できない)ことも結構あるので、 必要に応じてローカルのファイルを確認するのをお勧めします。
(パス的には vendor/bundle/ruby/{ruby-version}/gems/google-ads-googleads-{gem-version}/lib/google/ads/google_ads/factories
以下にあるファイルなどが該当)
おわりに
というわけで、これにて真・Google Ads API 徹底入門記事は完結となります。
基礎編から気付いたら四記事分という分量になってしまいましたが、これさえ読めば Google Ads API のことは完全に理解できるはずです。たぶん
最近は Google Ads API 公式ドキュメントもかなり充実してきているので、それを読むだけでもだいたいのことは出来るかと思いますが、 扱う中でドキュメントにはあまり書いていない知識などもそれなりにあったという印象があったため、こうして知見をまとめてみました。
今後も Google Ads API は継続的にアップデートされ、新機能も日々追加されていくはずですが、 そんな中でもこの記事に書いた基礎的な知識が末永く役立てばいいな、と思います。