Feedforce Developer Blog

フィードフォース開発者ブログ

真・Google Ads API 徹底入門 その4 公式ドキュメントの歩き方編

Google Ads API Google 広告 Ruby

こんにちは id:hano_tea です。

真・Google Ads API 徹底入門の最後の記事、 公式ドキュメントの歩き方編です。

真・Google Ads API 徹底入門のこれまでの記事は以下からどうぞ。

developer.feedforce.jp

developer.feedforce.jp

developer.feedforce.jp

最終回となる今回は Google Ads API に関連するドキュメント類の読み方、歩き方について解説します。

目次

公式ドキュメントの構成

解説中に度々出てきていますが、公式ドキュメントは以下のページになります。

developers.google.com

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
  • Support & Policies

上記リスト中でも書きましたが、 Guides, Reference が重要なページになります。 Libraries & Examples も結構役に立ちます。

以下では解説があったほうがよさそうな Reference, Reports に焦点を当てていきます。 Guides, Libraries & Examples はやりたいことベースでページを見ていけばいいので特に解説は不要な気がしています。

Reference

developers.google.com

Reference には Google Ads API を利用する際に利用する各種 Service やオブジェクトそのものの情報などがまとまっています。 一番よく使うページではありますが、情報量が非常に多いので、必要な情報を探しだしたり、やりたいことベースで情報を探すのには多少の慣れが必要です。

Google Ads API は基本的に Service を中心にして何らかの操作を行なっているというのは Search, Mutate の各記事内で説明したとおりです。 そのため、このリファレンスも基本的には Service の情報を起点として調べるのが最もよくあるシチュエーションだと思います。

例えばキャンペーンに対して Mutate をする際に調べる流れとしては、

  1. 自分が操作したい対象のオブジェクトのサービスのリファレンスページを探す
  2. MutateCampaign に必要なリクエスト内容について調べる
    • 例: MutateCampaignRequest へのリンクをクリック
  3. Request 時に必要なフィールドが出てくる
    • このレベルは基本的に customer_id と operations でほぼ共通のはず
    • 例: MutateCampaignsRequest
  4. 行いたい Operation のページを開く
    • 例: CampaignOperation
    • 内容はどれもたぶんほぼ共通、 create/update は対象オブジェクト、 remove はリソース名を要求されるはず
  5. Operation ページの中身にある各オブジェクトの詳細ページに飛んで必要なリクエスト内容を確認する
    • 例: Campaign
    • 慣れるとこのリソース毎のページを直に確認、にショートカットもできそう
  6. 必要に応じてリクエストに必要なリソースの詳細を更に調べる
    • 例えば ShoppingSetting などが別リソースの例として挙げられる

のようになります。 リンクをひたすらたどっていくような感じになるのですが、別タブをどんどん開いていくような感じで掘っていくのをおすすめします。

Reports

developers.google.com

Report は各種オブジェクトや広告成果レポートの情報を取得する際に役立つ情報が掲載されています。 初見だとどう読めば良いのかが若干分かりにくいので、簡単に読み方を説明します。

Resource with metrics

Resource with metrics のページは名前の通り、 metrics を取得できるようなリソースの情報がまとまっているセクションです。

上部のテキストボックスに何らかのキーワードを入力すると、ページ内でその語句を含んでいるような情報のみに表示内容がフィルタされます。 目的の情報が決まっている場合は活用するとスムーズに必要な情報にたどり着けるかと思います。

f:id:hano_tea:20200427182646p:plain
上部テキストボックスから対象を絞り込める

その下の Attributed resources には、「このリソースから参照できる別リソース」の一覧が表示されています。

f:id:hano_tea:20200427182940p:plain
関連して取得できるリソースが一覧になっている

どういうことかというと、例えば 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 となっています。

f:id:hano_tea:20200427183157p:plain

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 を扱う上でもう1点確認しておきたいものとして、各言語用クライアントライブラリのリポジトリが挙げられます。 ここでは Ruby のクライアントライブラリの話について触れておきます。

github.com

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 は継続的にアップデートされ、新機能も日々追加されていくはずですが、 そんな中でもこの記事に書いた基礎的な知識が末永く役立てばいいな、と思います。

▲