Feedforce Developer Blog

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

真・Google Ads API 徹底入門 その1 基礎編

Google Ads API Google 広告 Ruby

こんにちは id:hano_tea です。最近は外出自粛ということで、日々無人島に旅立ってカブ取引に命を賭けています。

完全に余談ですが、弊社 Slack には #animal_crossing チャンネルがあり、日々 各島のカブ価情報が共有されて楽しい無人島ぐらしの様子が流れています。余談でした。

さて、突然ですが皆様、 Google Ads API は利用していますでしょうか？

完全移行は未だ行われてはいませんが、ベータ版に戻った Ads API は今でも継続的に改善、アップデートが重ねられ、 初期の Ads API から新たに追加された機能なども色々あります。

また、Ruby Client Library も使い勝手が日々向上しており、よりシンプルなコードで広告操作が出来るようになってきました。

上述のようにかなり API としての機能が拡充され、こなれてきた印象を受ける Ads API ですが、 Adwords API ともかなり勝手は異なり、初めて扱う人にとっても決してわかりやすいとは言い難いと思っています。

そこで本記事では、 Ruby の Client Library を使って Google Ads API の扱い方について、 基礎知識から情報の取得、オブジェクトの作成まで順に解説していこうと思います。

Ruby クライアントライブラリでの話にはなっていますが、他の言語のライブラリでも共通して使える知識は多いかと思うので、 別言語を利用している方も参考にしていただければと思います。

目次

そもそも Google Ads API (Beta) とは

そもそも Google Ads API (Beta) とは、その名の通り Google 広告を操作するための API です。

developers.google.com

元々は Adwords API というものが存在しており、長きに渡って使われ続けていたのですが、 一昨年頃に Google の広告が Adwords から Google Ads にリブランディングされ、 それとほぼ同時期に API も Ads API という新しいものがリリースされました。

本当は昨年4月に Ads API にリプレースされる予定…だったのですが、主にレポート取得周りのパフォーマンスの問題かららしいのですが、 正式版からベータ版に逆戻り、リプレースの予定も未定になってしまいました。 頑張って移行したのに

ベータ版ということもあり、まだ若干足りない機能があったりもしますが、 概ね Google 広告の管理画面で出来ることの大半の機能はカバーされています。

ライブラリや内部で使っている技術の話

Google Ads API はクライアントライブラリが公式から、各種プログラミング言語で提供されています。

developers.google.com

2020年4月16日現在、以下のプログラミング言語用のライブラリが提供されています。

  • Java
  • .NET
  • PHP
  • Python
  • Ruby
  • Perl

実は言語ごとに微妙に提供されている機能に差があったりして、 例えば Python と Ruby はなぜか情報取得時のページングの細かい制御が出来なかったります。地味に辛い。

クライアントライブラリを使用して API を叩くことが基本になるはずなので普段あまり意識することはないのですが、 内部的には gRPC が利用されています。 が、とりあえず利用する分には gRPC のことを知らなくても特に問題はなかったりします。

合わせて Protocl Buffers も使われていますが、 これも特に知らなくてもあんまり困らないように出来ています。興味があればリンク先を参照してください。

クライアントライブラリを利用して Google Ads API を使うときの流れ

基本的には以下のような流れで API を使うイメージです。

  • Google Ads API 周りの処理の起点となる Client を作成する
    • 認証情報類はこの時点で与える
  • API リクエストに必要な情報を組み立てる
    • 各種情報やレポートデータの検索・取得の場合はそのためのクエリを組み立てる
    • オブジェクトの作成や更新をする場合は作成する予定のオブジェクトを Client の便利メソッドを駆使して用意
  • Client に生えているメソッドを使って Service と呼ばれるオブジェクトを生成、 API へのリクエストを行う
    • 例: client.service.google_ads.search(customer_id, query)
      • この例では GoogleAdsService の Search というメソッドを呼び出しています

API を叩くのに必要な Client の設定方法、内容

Google Ads API を扱う時は基本的に Client オブジェクトを作成し、それを使って様々な操作を行います。 API を実際に叩いてなにか情報を取得したり、オブジェクトを作成したりといった操作はもちろん、 オブジェクトの作成時に必要な Ruby オブジェクトの作成用のメソッドなども用意されています。

Client の作成は以下のようなコードで行います。作成した Client は使いまわします。

client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.client_id = 'GOOGLE_OAUTH2_CLIENT_ID'
  config.client_secret = 'GOOGLE_OAUTH2_CLIENT_SECRET'
  config.refresh_token = 'GOOGLE_REFRESH_TOKEN'
  config.developer_token = 'GOOGLE_DEVELOPER_TOKEN'
  config.login_customer_id = 'GOOGLE_ADS_ROOT_MCC_ID'
  config.logger = Logger.new(STDOUT, level: Logger::Severity::INFO)
end

Client の作成時には認証情報を一緒に渡す必要があります。 上記のコードでは環境変数を通して設定していますが、

  • Google OAuth2 Client の client id と client secret, refresh token
  • Google Ads の Developer token
  • Google Ads の Root MCC ID

が必要です。各認証情報の取得方法などについては今回は割愛します。以下のページを参考に取得、設定してください。

developers.google.com

必須ではないですが、ロガーを INFO レベルの出力で設定しておくと良いと思います。 DEBUG レベルで出力しても良いのですが、結構な量のログが吐き出されることも多く、 基本的には INFO レベルにしておいて出力量を抑えるのが良さそうです。

Service という概念

Google Ads API を使って何らかの広告の操作を行う時は、基本的に Service というものを使います。 以下は API Structure のヘルプページ内にある Service の項目へのリンクです。

developers.google.com

上記のページにも

Services retrieve and manipulate Google Ads entities.

とある通り、 Google Ads の各種エンティティに対する情報取得、あるいは変更などの操作を行うためのものです。

Service は基本的に Google Ads のオブジェクトと対応するような形で存在しています。 以下のページは service の一覧のページですが、いろいろなオブジェクトに対応した Service があることが分かると思います。

developers.google.com

リソースの ID と resource_name

ちょっと長いので要約: Google Ads API では ID ではなく resource_name を使いましょう

Google Ads API 上のオブジェクトにはご想像の通り、それぞれ ID が振られています。 ここでいう ID とは、例えば広告アカウントの ID のような10文字程度の数字のことを言います。

この ID、そこまで長くない数字だけで構成されていることから分かる通り、それ単体では一意にオブジェクトを特定することができません。 それゆえ、Google Ads API でそれらの ID が直接使われることはほとんどありません。

では特定のオブジェクトを一意に特定するための情報には何を使えばいいでしょうか。そこで出てくるのが resouce_name です。

Google Ads API では、この resource_name と呼ばれるものが ID として使われることが非常に多いです。 非常に多いのにドキュメントではあんまり触れられていないのですが

resource_name は公式ドキュメントで以下の箇所でちらっと出てきています。

developers.google.com

例えばキャンペーンであれば以下のような resource_name になります。

customers/{customer_id}/campaigns/{campaign_id}

上記のように、 resorce_name は、そのオブジェクトそのものの ID と、その親にあたるオブジェクトの ID を使ったパスのような形式になっています。 実際にどのオブジェクトの ID が resource_name に使われるかはオブジェクトごとに異なっているため、都度リファレンスを参照する必要があります。

階層が深くなってくると resource_name に含まれる ID が2つより多くなることがあります。例えば CampaignCriterion というオブジェクトがあるのですが、この resource_name は以下のようになります。

customers/{customer_id}/campaignCriteria/{campaign_id}~{criterion_id}

上記の場合、 customer_id, campaign_id, criterion_id の3つの ID が必要になります。

resource_name の組み立て規則はあまりはっきりしていないので、その都度必要なオブジェクトの resource_name の形式、必要な ID を リファレンスを見て調べる、という作業が必要になるかと思います。

次回予告

というわけで真・Google Ads API 徹底入門 その1 基礎編でした。 次回以降の記事ではこの記事で解説した内容を踏まえて、実際の Google Ads API を操作する方法について解説していきます。お楽しみに。

▲