Google Ads API 認証の流れ

本稿ではGoogle Ads APIを利用するにあたり認証を通すまでの手順を記載します。
もちろん、手順は公式のドキュメントにも存在しますが、イメージキャプチャ踏まえ理解しやすくまとめられればと思います。

Google Ads API とは

公式ドキュメント

Google Ads API は AdWords API の次世代バージョンで、[Google 広告]
(https://ads.google.com/intl/ja_jp/getstarted/)の最新のプログラマティック インターフェース。デベロッパーは Google 広告プラットフォームを直接操作できるため、Google 広告の大規模で複雑なアカウントやキャンペーンを効率的に管理できる（抜粋）。

つまり、Google Ads API を用いて Google 広告 のサービスや機能へアクセスをすることができ、レポート数値などの管理を行うことが可能となります。

また、Google Ads API を利用するには下記に記載の手段があり、利用シーンにより最適な手段を選択できるようになっています。

• JSON REST エンドポイント
• gRPCインターフェース
• クライアントライブラリ

この記事では、上述した手段を利用できるようにするための認証方法を記載します。

認証を通してAPIを呼び出す

公式ドキュメント

基本はドキュメントに記載のクイックスタートにある手順に沿って進めていきます。

1. 開発者トークンの発行

開発者トークンとは、ドキュメントにも記載がありますが、特定のアカウントではなく、ご利用のプロジェクトに対してAPIへのアクセスを許可するものです。

実際に開発者トークンを発行するまでの流れを見てみましょう。

1-1. クライアントセンター（MCC）アカウントにログイン

クライアントセンター（MCC）アカウントについての詳細は下記をご確認ください。
Google 広告のクライアント センター（MCC）アカウントについて

ログイン後の画面はこのようになります。

※補足
この後実際にアクセス方法を記載しますが、事前に注意点を追記します。
この後の手順で説明しているアカウントは、全て本番用のアカウントでの設定となります。
ここでは開発者用のトークンを取得することがゴールとなります。
が、実際の開発時にAPIでアクセスを行う際、すでに開発者トークンが本番用に承認が通っていれば問題ないのですが、そうでない場合、テスト用アカウントをMCC上に作成した上でAPIを利用しなければなりません（承認が通っていないうちは、アクセス自体が拒否されてしまいます）。
MCC上でテストアカウントの作成を行うには下記のページを参考にしてください。

テストアカウントについて

※補足2
テストアカウント作成後、テストアカウントのクライアントIDを元にAPIをたたけるのですが、テストアカウント状態でキャンペーンの作成などができず、認証が正常に通っているか程度の確認しかできないです。
他にいい方法があれば追記します。

1-2. APIセンターにアクセス

MCCの「ツールと設定メニュー」からAPIセンターにアクセスを行うと開発者トークンが表示されます。

APIセンターのキャプチャ

秘匿情報のためぼかしていますが、赤枠で囲っている開発者トークンの右側にトークンが記載されていればOKです。
注意点としては、公式にも記載がありますがログイン時のアカウントが管理者でないとメニューが表示できないので、必ず管理者アカウントでログインするようにしてください。

2. クライアントライブラリを取得する

公式ドキュメント

前述でも述べたとおり、Google Ads API を実行する手段は複数あり、今回は認証からAPI実行までを確認するためクイックスタートのステップ通りクライアントライブラリを利用します。
クライアントライブラリはAPIの呼び出しから様々な機能を利用するためのオブジェクトを予めライブラリとしてまとめているもので、比較的導入がしやすいものとなっています。
また、言語サポートの選択肢も多いところが特徴です（サポート言語はドキュメントを確認）。

今回はPHPを利用します。
githubのREADMEにインストール方法やサンプルコードが記載されているので一読しておくと良いでしょう。

laravelなどのフレームワークを利用の際はcomposerにも対応しているので、下記のコマンドで取得することも可能です。

composer require googleads/google-ads-php

あるいは、composer.jsonに追記

"require": {
    "googleads/google-ads-php": "^3.2",
}

また、Google Ads API は gRPCが必要となるため、PHPのモジュールにgRPCがないときは事前にインストールが必要となります。
(インストール方法は後述)

3. Google Ads API に Google API Console プロジェクトを設定する

公式ドキュメント

Google の OAuth2 サーバーにアクセスするための認証情報は、Google 広告ユーザーを認証したり承認したりするために必要です。これらの認証情報によりアプリケーションが識別され、Google 広告のユーザーを管理するための OAuth トークンが生成さます（抜粋）。

この章では、Google API Console からプロジェクトを作成し、認証を通すまでの準備を行ます。

3-1. プロジェクトを作成する

まず初めに、Google Api Console へ移動しプロジェクトの作成を行ます。

Google Api Console にログインするとこのような画面が表示されます。
赤枠で囲んだところからプロジェクトを作成を行ます。

プロジェクト作成画面

プロジェクトの作成が完了するとリスト画面に登録したプロジェクトが表示されます。

3-2. プロジェクトで Google Ads API を有効にする

先ほど作成したプロジェクトで、利用できるAPIを選択し有効にする手順が必要となります。
左上のハンバーガーメニューから　APIとサービス > ダッシュボード　へ移動してください。

移動すると作成したプロジェクトのダッシュボード画面に移動します。
もし、先ほど作成したプロジェクト以外が選択されていた場合、赤枠の箇所で他のプロジェクトに切り替えることが可能です。

ダッシュボードの画面から「+ APIとサービスの有効化」をクリックし移動します。

上記キャプチャの画面で、「Google Ads API」を検索し有効化を行ます。

これで有効化は完了です。

3-3. クライアント ID とクライアント シークレットを作成する

OAuth2 クライアント ID とクライアント シークレットを生成します。

3-3-1. 認証情報ページを開く

こちらから認証情報ページを開きます。

3-3-2. 認証情報を作成

画面上部の「+ 認証情報を作成」を押し、「OAuth クライアント ID」を選択します。

同意画面のページでプロダクト名の設定を促された場合は、[同意画面を設定] をクリックして必要な情報を入力し、[保存] をクリックして認証情報ページに戻り、再度「+ 認証情報を作成」を押し、「OAuth クライアント ID」を選択し画面へ移動します。

3-3-3. OAuth クライアント ID の作成

ここでやっとOAuth クライアント ID の作成に入ります。
作成する際にアプリケーションの種類を選択できますので、利用シーンに適したものを選択します。

選択したアプリケーションの種類により入力項目が変わるので、必要事項を記入の上作成ボタンを押します。

3-3-4. クライアントID とクライアント シークレットを取得

正常に作成が完了すると、クライアントIDとクライアントシークレットの情報が表示されます。
この2つはクライアントライブラリの設定に必要となるためクリップポードなどにコピーしておきます。

4. Google Ads API で OAuth 用のクライアントライブラリを設定

公式ドキュメント

実際に設定したクライアントID、クライアントシークレットを利用してAPIにアクセスをするための認証とリフレッシュトークンを取得するまでをドキュメントに沿い実行してみます。

アプリケーションなどで利用する際、OAuth2アクセスは一定期間後に有効期限が切れるため、自動的に OAuth2 アクセスを更新するリフレッシュトークン（OAuth2 更新トークン）を取得します。

※認証を通すサンプルコードを実行しましたが、一部ドキュメントの記載と異なる部分があるためご容赦ください。

4-1. OAuth2 認証情報を使用してクライアント ライブラリをインストールする

まず、クライアントライブラリを選択します。
今回は言語PHPのウェブ アプリケーションのフローを参考に進めます。

リンク先には認証するためのフローが記載されているので、先にクライアントライブラリをインストールしましょう。

インストールするクライアントライブラリ

$ git clone https://github.com/googleads/google-ads-php.git
$ cd google-ads-php
$ composer install

適当な場所で上記のコマンドを実行するだけで利用できます。

4-2. クライアントライブラリを利用して認証を通す

ウェブアプリケーションのフローに記載のステップを実行していきます。

ステップ1で下記の注意書きがあります。

IMPORTANT: The example below requires that you register the following as one of the Authorized redirect URIs in your project:
http://localhost/oauth2callback

後ほど認証用のプログラムを実行するのですが、戻り値に認証を行うために遷移するURLが記載されています。
Google API Console で作成したOAuthクライアントIDの「承認済みのリダイレクト URI」に追加しておく必要があり、追加されていないと認証エラーとなってしまうので注意してください。

ステップ2でプログラムを実行します。
サンプルではAuthenticateInWebApplication.phpを実行しているので、これにのっとり実行していきます。

$ php examples/Authentication/AuthenticateInWebApplication.php
Enter your OAuth2 client ID here: [クライアントID]
Enter your OAuth2 client secret here: [クライアントシークレット]
Log into the Google account you use for Google Ads and visit the following URL in your web browser: 
https://accounts.google.com/o/oauth2/v2/auth?response_type=code&access_type=offline&client_id=xxx&redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&state=xxx&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fadwords

実行するとクライアントIDとクライアントシークレットの入力を求められるので、作成したものを入力してください。
最終的にURLが出力されるのでコピーしてご利用のブラウザで直接実行を行ます。
この時、ターミナルなどはそのままの状態にしておきましょう（認証が全て完了した後、リフレッシュトークンなどの情報が自動的に出力されます）。

試していた時に、結果のURLのパラメーターのredirect_urlの部分が http://127.0.0.1:[ランダムなポート]/oauth2callback となってしまい、ブラウザでの認証時にリダイレクト認証ページエラーが出てしまいました。
パラメーターの部分をlocalhostに変更するか、Google API Consoleの「承認ずみリダイレクトURI」に http://127.0.0.1:[ランダムなポート]/oauth2callback を登録することで回避できます。が、シンプルでないのでよくないですね。。

無事に認証が通ると下記のようにリフレッシュトークンが取得できるようになります。

$ php examples/Authentication/AuthenticateInWebApplication.php
Enter your OAuth2 client ID here: [クライアントID]
Enter your OAuth2 client secret here: [クライアントシークレット]
Log into the Google account you use for Google Ads and visit the following URL in your web browser: 
https://accounts.google.com/o/oauth2/v2/auth?response_type=code&access_type=offline&client_id=xxx&redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&state=xxx&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fadwords

Your refresh token is: [取得したリフレッシュトークン]
Copy the text below into a file named "google_ads_php.ini" in your home directory, and replace "INSERT_DEVELOPER_TOKEN_HERE" with your developer token:

[GOOGLE_ADS]
developerToken = "INSERT_DEVELOPER_TOKEN_HERE"
; Required for manager accounts only: Specify the login customer ID used to authenticate API calls.
; This will be the customer ID of the authenticated manager account. You can also specify this later
; in code if your application uses multiple manager account + OAuth pairs.
; loginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"
[OAUTH2]
clientId = "[クライアントID]"
clientSecret = "[クライアントシークレット]"
refreshToken = "[取得したリフレッシュトークン]"

これでAPIをキックするための認証情報は取得完了となります。

gRPC

APIを利用するためにはgRPCが必須となります。
メモ：詳細は追って追記

まとめ

ドキュメントと現状とで乖離がある部分や、なかなかわかりにくい記載などがあるためとっつきにくいですが、参考になればと思います。
トークンの取り扱いやクライアントライブラリのフレームワークへの反映など、実際に本番で利用する際に気をつけなければいけないことがあると思うので、その辺りは別途まとめる予定です。