FLINTERS Engineer's Blog

FLINTERSのエンジニアによる技術ブログ

MCCアカウントでGoogle Ads API を利用してみた

ブログ祭り梅雨 Google

1. はじめに

FLINTERS 新卒2年目エンジニアの伊藤です。 この記事はFLINTERSブログ祭りの記事です。テーマは #GoogleAdsAPI です。

Google Ads APIを利用するに当たって、アカウント周りの知識やトークンの発行等で苦労したため、なるべくわかりやすくまとめてみました。今回は、0からアカウントの作成、テストMCCアカウントを使用して試しにGoogle Ads APIを叩くところまでを記載しています。これからGoogle Ads APIを利用する方の参考になれば幸いです。

1.2 準備しておくもの

準備しておくものは簡単で、Googleアカウント2つです！！ MCCアカウントとテスト用MCCアカウントに紐づけるために必要になってきます。

1.3 全体像

Google Ads APIを叩くまでに必要になってくる、アカウントやアクセスキーを図にしてみました。今は何のこっちゃ分からないと思いますが、ひとつひとつ説明、作成していくのでご安心ください。ここでは、Google AdsとGoogle API Consoleの2つが出てくるんだなということを抑えていてください。

全体像

2. Google Adsに出てくるアカウント周りについて

実際に作業を行う前に、ややこしいGoogle Adsに出てくるアカウント周りについて簡単に整理してみました。

2.1 Google 広告アカウント*1とは？

Google広告を運用するためのアカウントです。似ていて分かりづらいですが、Googleアカウントとは違うので注意してください。Google 広告アカウントを作成するために、Googleアカウントが必要になります。1つのGoogleアカウントにつき、最大5つのGoogle広告アカウントを作成できます。

Google広告アカウント

2.2 GoogleアカウントでGoogle 広告アカウントを管理することのデメリット

会社単位でGoogle 広告を運用する際、Google 広告アカウントの数は膨大になってきます。例えば、150のGoogle 広告アカウントを使用している場合、Googleアカウントは最低でも30は必要になります。どのGoogleアカウントがどのGoogle 広告アカウントに紐づいているのか、把握するのも大変ですよね...また面倒くさいことに、GoogleアカウントごとにGoogle Adsの管理画面をログインし直さないといけません。そこで登場するのがMCCアカウントです。

2.3 MCCアカウント*2とは？

複数の Google 広告アカウントを簡単に管理することができるアカウントのことです。便利なことに、ひとつのMCCアカウントがあれば、たくさんのGoogle 広告アカウントを一括管理できます。もちろんGoogle Adsの管理画面をログインし直さなくても大丈夫です。

MCCアカウント

2.4 開発者トークン（Google Ads Dev Token）*3とは？

22文字の英数字からなる文字列で、Google API Consoleのプロジェクトに対してGoogle Ads APIへのアクセスを許可するものです。開発者トークンにはアクセスレベル*4が存在し、発行したばかりだとアクセスレベルが「テストアカウントへのアクセス」になるので、実運用では使用できなく、「ベーシックアクセス申請をする」から審査に出す必要があります。今回は、テストなので申請はしませんが、申請する際はこちらを参考にしてみてください。アクセスレベルが「テストアカウントへのアクセス」の開発者トークンが作成されると、テスト（MCC）アカウントに対してのみ、Google Ads APIのリクエストを行うことができます。

アクセスレベル アクセスできるアカウント 1日あたりのオペレーションの上限
テストアカウントへのアクセス テストアカウント 15,000 オペレーション / 日
基本アクセス テストアカウントと本番環境アカウント 15,000 オペレーション / 日
標準権限 テストアカウントと本番環境アカウント 1日あたりのオペレーション数無制限
2.5 テストMCCアカウント*5とは？

未承認の開発者トークンを使用して、APIを連携するために必要なアカウントです。本番用でAPI連携してしまうと、実際に運用している広告に影響が出たり、アカウントへの請求が発生してしまう可能性があるので、API実装の際はテスト用が役に立ちます。テスト用MCCアカウントは本番用MCCアカウントと同じ階層構造で設定、画面上での操作ができ、Google Adsの管理画面の右上に赤いテストアカウントのラベルが表示されます。もし表示されていない場合は、本番用のアカウントなので注意して下さい。

テストアカウント

もう一点注意しないといけないことが、本番用のMCCアカウントで発行した、アクセスレベルが「テストアカウントへのアクセス」である開発者トークンを使用しないといけないということです。（本当にややこしくて、自分はこれを理解するのに時間がかかりました...）

テストMCCアカウントの開発者トークンについて

3. Google Adsで実際に作業してみる

3.1 MCCアカウントの作成

こちらの「MCCアカウントを作成」からMCCアカウントを作成します。この時、本番用のGoogleアカウント（メールアドレス）でログインしてください。作成されたら、左上にMCCアカウントIDが表示されます。

MCCアカウントの作成

Google広告管理画面

本来は、ここにたくさんのGoogle広告アカウントが管理されているのですが、今回はテストでGoogle Ads APIを叩くだけで、広告運用しないため、Google広告アカウントは作成していません。

3.2 開発者トークンの発行

次に開発者トークンを発行します。左の「管理者」→「APIセンター」から必要な情報を入力します。

広告管理画面 > 管理者 > APIセンター

作成されたら以下のように表示されます。このとき、アクセスレベルは「テストアカウント」なので本番運用する際は、「アクセス権」からベーシックアクセスの申請する必要があります。

開発者トークン画面

3.3 テストMCCアカウントの作成

続いてテスト用MCCアカウントを作成します。 こちらのリンクの「テストアカウントとキャンペーンを作成する」→「テスト用MCCアカウントを作成する」で作成します。 以下のような画面が出たら、テスト用で使用する2つ目のGoogleアカウントに切り替えてください。

テスト用MCCアカウントを作成 > Googleアカウントの切り替え

テスト用MCCアカウントが作成されました！！右上に「テストアカウント」と表示されていますね。MCCアカウントIDは本番用とは違います。また、開発者トークンは先ほど本番用MCCアカウントで作成したトークンを使用するので、こちらでは作成しません。

テスト用Google広告管理画面

以上でGoogle Adsでの作業は終わりです！！

4. Google API Consoleで実際に作業してみる

Google Ads APIを利用するためには、Google API Consoleにプロジェクトを登録して、OAuth2.0を使った認証を通すためのアクセストークンを発行する必要があります*6。また、アクセストークンは一定時間後に有効が切れてしまうため、アクセストークンを更新するためのリフレッシュトークンを発行する必要があります。詳しい発行方法は後ほど説明します。

4.1 Google API Consoleにプロジェクトを作成*7

こちらのリンクから、Google API Consoleに移動し、Google Ads APIを利用するためのプロジェクトを作成します。 テスト用はないため、本番で利用するためのプロジェクト名を設定してください。

Google API Console > プロジェクト作成

4.2 Google Ads APIの有効化

Google API Console画面左から「APIとサービス」→「ライブラリ」で「Google Ads API」を検索してください。

APIとサービス > ライブラリ > Google Ads API

「有効にする」を押すことで、このプロジェクトではGoogle Ads APIを利用することができます。

Google Ads APIの有効化

4.3 OAuth同意画面の設定*8*9

少し複雑になるので、画像多めで説明していきます。

4.3.1 User Type

まずは、User Typeを「外部」に設定します。外部にすることでGoogleアカウントを持つすべてのユーザーが使用できるようになります。ただし、アプリの公開設定（Googleに審査）をしていない場合、公開ステータスが「テスト」のままになり、テストユーザーのリストに追加されたユーザーのみが、Google Ads APIを利用できます。

OAuth同意画面 > User Type > 外部

4.3.2 OAuth 同意画面

その後、アプリ名やアプリ同意に関して問い合わせるためのメールアドレス等のアプリ情報を入力します。 本番で運用する際は、アプリのロゴをきちんと用意する必要がありますが、今回は用意せずそのまま進みます。

アプリ情報の入力

4.3.3 OAuthスコープ*10

次はOAuthのスコープを設定します。この設定により、アクセストークンに付与されるアクセス権の範囲を制限できます。「スコープを追加または削除」→「スコープの手動追加」→「https://www.googleapis.com/auth/adwords」を入力することでOAuthスコープを設定できます。APIによっては違いますが、Google Ads APIは「機密性の高いスコープ」に分類されます。そのため、本番運用する際はOAuth検証プロセスを完了する必要があります。OAuth検証について、以下の記事を参考にしてみてください。（ここが本当に大変そう...）

参考：Google OAuth申請の注意点

OAuthスコープの追加

4.3.4 テストユーザー

現在、Googleに審査出していないため公開ステータスは「テスト」となっています。このステータスの間はテストユーザーに追加されたユーザーのみがAPIを利用できます。 ここが重要なのですが、テストユーザーとして本番MCCアカウントに紐づいているGoogleアカウントとテスト用MCCアカウントに紐づいているGoogleアカウントを登録します。 つまり、この作業によってテスト用MCCアカウントでAPIを利用することができるようになるということです。

テストユーザーの追加

以上がOAuth同意画面の設定でした。

OAuth同意画面設定の完了

4.4 認証情報の作成

「認証情報」→「＋認証情報を作成」→「OAuthクラインとID」からOAuth クライアントIDとクライアントシークレットを作成します。

認証情報 > 認証情報を作成 > OAuthクライアントID

アプリケーションの種類は「ウェブアプリケーション」で、承認済みのリダイレクトURIは「http://localhost」とします。

OAuthクライアントIDの作成

以上で、認証情報の作成は完了です！

認証情報の表示について

4.5 トークンの発行

先ほど作成した認証情報を使用して、コード、リフレッシュトークン、アクセストークンの順で発行を行います。主な流れは以下になります。

コード > リフレッシュトークン > アクセストークン発行の流れ

4.5.1 コードの発行*11

以下のURLをブラウザで検索して、コードを発行します。

https://accounts.google.com/o/oauth2/auth?client_id=${CLIENT_ID}&redirect_uri=${REDIRECT_URI}&scope=https://www.googleapis.com/auth/adwords&access_type=offline&response_type=code

client_idは先ほど発行したOAuthクライアントIDを、redirect_uriには承認済みのリダイレクトURIで指定した「http://localhost」を入力します。ここで、テスト用MCCアカウントに紐づいているGoogleアカウントを選択してアクセスを許可します。

アクセスの許可

許可が完了するとURLにコードが生成されますので、コピーしておいてください。

コード生成

4.5.2 リフレッシュトークンの発行

リフレッシュトークンはアクセストークンを更新するためのトークンです。以下のcurlコマンドを叩きます。先ほど発行したコードと認証情報を入力してください。

curl \
  --data "grant_type=authorization_code" \
  --data "client_id=${CLIENT_ID}" \
  --data "client_secret=${CLIENT_SECRET}" \
  --data "redirect_uri=http://localhost" \
  --data "code=${CODE}" \
  https://www.googleapis.com/oauth2/v3/token

以下のようにリフレッシュトークンが発行されます。

{
  "access_token": "***************",
  "expires_in": 3599,
  "refresh_token": "1//*************",
  "token_type": "Bearer"
}

リフレッシュトークンは一度発行してしまえば、有効期限はないので、大事に保管してください。

※もし流出してしまったら、コードの発行から戻って再発行してください。

4.5.3 アクセストークンの発行*12

先ほどもアクセストークンを発行できたのですが、リフレッシュトークンを使用してちゃんとアクセストークンが発行できるか確認します。以下のcurlコマンドを叩きます。リフレッシュトークンは先ほど発行されたものを入力してください。

curl \
  --data "grant_type=refresh_token" \
  --data "client_id=${CLIENT_ID}" \
  --data "client_secret=${CLIENT_SECRET}" \
  --data "refresh_token=${REFRESH_TOKEN}" \
  https://www.googleapis.com/oauth2/v3/token

ここで、先ほど発行したものとは違うリフレッシュトークンを入力してしまった場合、invalid_grantというエラーが発生してしまいます。上手くいくと以下のようにアクセストークンが発行されます。

{
  "access_token": "***************",
  "expires_in": 3599,
  "scope": "https://www.googleapis.com/auth/adwords",
  "token_type": "Bearer"
}

これでやっと準備が整いました！！！

4.6 Google Ads APIを叩く
4.6.1 アクセス可能なGoogle Adsアカウントの一覧取得*13

まず、シンプルに先ほど発行したアクセストークンでAPIにアクセス可能なGoogle Ads アカウントの一覧を取得してみます。以下のcurlコマンドを叩きます。

curl -f --request GET "https://googleads.googleapis.com/v${API_VERSION}/customers:listAccessibleCustomers" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}"
  • API_VERSION : APIバージョン*14
  • DEVELOPER_TOKEN : 開発者トークン
  • OAUTH2_ACCESS_TOKEN : アクセストークン

上手くいけば、以下のようにテスト用MCCアカウントIDが表示されます。

{
  "resourceNames": [
    "customers/テスト用MCCアカウントID"
  ]
}
4.6.2 簡単なGAQL*15

続いて、GAQLというGoogle広告のクエリ言語を使ってAPIを叩くことで、Google Adsの情報を確認してみます。Google Adsのキャンペーンを確認してみる基本的なクエリを試しに叩いてみます。

curl -i -X POST https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:searchStream \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
   -H "developer-token: ${DEVELOPER_TOKEN}" \
   -H "login-customer-id: ${LOGIN_CUSTOMER_ID}" \
  --data '{
"query": "
  SELECT
    campaign.id,
    campaign.name,
    campaign.network_settings.target_content_network
  FROM campaign
  ORDER BY campaign.id"
}'
  • CUSTOMER_ID : Google広告アカウントID（今回は作成していないのでテスト用MCCアカウントIDを入力）
  • LOGIN_CUSTOMER_ID : MCCアカウントID（今回はテスト用MCCアカウントを入力）

※ 上記のIDはハイフンを省略して入力することに注意してください。（123-456-7890ではなく、1234567890と入力）

以下のような結果が返ってきます。

HTTP/2 200
request-id: *********
content-type: application/json; charset=UTF-8
vary: X-Origin
vary: Referer
...
accept-range: none

[ ]

とりあえずAPIを叩けることを確認できました！！！

※本番MCCアカウントではキャンペーンがちゃんと表示されると思います。

5. 終わりに

今回は、0からアカウントの作成、テストMCCアカウントを使用して試しにGoogle Ads APIを叩くところまでを行いました。かなりボリューミーな内容になってしまいましたが、これからGoogle Ads APIを利用する方の参考になれれば幸いです。

*1:Google広告ヘルプ 『Google アカウントとは』

*2:Google広告ヘルプ 『クライアント センター（MCC）アカウント: Google 広告 MCC アカウントについて』

*3:Google Ads API 『開発者トークンを取得する』

*4:Google Ads API 『アクセスレベルと許容される用途』

*5:Google Ads API 『テストアカウント』

*6:Google Identity 『OAuth 2.0 を使用して Google API にアクセスする』

*7:Google Ads API 『Google API Console プロジェクトをセットアップする』

*8:Google Ads API 『OAuth 同意画面を構成する』

*9:Google Cloud Platform Console Help『Setting up your OAuth consent screen』

*10:Google Identity『Google API の OAuth 2.0 スコープ』

*11:Google Identity『ウェブサーバー アプリケーションに OAuth 2.0 を使用する』

*12:Google Ads API『API 呼び出しを行う』

*13:Google Ads API『Examples』

*14:Google Ads API『リリースノート』

*15:Google Ads API『Google 広告クエリ言語』