OAuth2 認証

すべての AdWords API の呼び出しは、OAuth2 による認証を受ける必要があります。OAuth2 を使うことで、AdWords API クライアント アプリケーションは、ユーザー名やパスワードを保存したり処理したりしなくてもユーザーの AdWords アカウントにアクセスできるようになります。

OAuth2 認証情報を作成する

OAuth2 認証情報を作成する手順は以下のとおりです。

1. アプリケーションのタイプを指定する

まず、作成するアプリケーションのタイプを指定します。AdWords API で選べるアプリケーションのタイプは以下の 2 つです。

  • インストール型アプリケーション(推奨)
  • ウェブ アプリケーション

以下の表は、各タイプがどのようなケースに適しているかを示しています。

アプリケーションのタイプ 適しているケース
インストール型アプリケーション(推奨)
  • すべての AdWords アカウントを 1 つのクライアント センター(MCC)アカウントの配下に置いて管理している場合
  • API をはじめて利用する場合や、簡単な設定ですぐに利用を開始したい場合
  • アプリケーションを使い、複数のユーザーがいる共通の AdWords アカウントを管理する場合
ウェブ アプリケーション
  • アプリケーションにアクセスして AdWords アカウントのデータを参照する権利を付与できるユーザーとして認証を取得したい場合
  • 第三者のアカウントなどを管理するために、複数の認証情報を簡単に生成したい場合
  • アプリケーションでコールバック URL が必要な場合(コールバック URL はインストール型のアプリケーションのフローでは利用できません)

詳細については、Google ID プラットフォームの OAuth に関するドキュメントで、インストール型アプリケーションウェブ アプリケーションの項目をご覧ください。

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

アプリケーションのタイプを決めたら、利用するタイプのタブをクリックし、表示された手順に従って OAuth2 クライアント ID とクライアント シークレットを生成します。

インストール型アプリケーション
  1. Google Developers Console の認証に関するページを開きます。
  2. プロジェクトのメニューから [プロジェクトを作成] を選択し、プロジェクトの名前を入力します(表示されているプロジェクト ID は任意で編集することもできます)。[作成] をクリックします。
  3. 認証情報のページで [認証情報を作成] をクリックし、[OAuth クライアント ID] を選択します。
  4. [同意] 画面でのプロダクト名の設定を促された場合は、[同意画面を設定] をクリックして必要な情報を入力してから、[保存] をクリックして [認証情報] 画面に戻ります。
  5. [アプリケーション タイプ] は [その他] を選択し、必要な情報を追加します。
  6. [作成] をクリックします。
  7. 表示されたページでクライアント IDクライアント シークレットをクリップボードにコピーします。この 2 つはクライアント ライブラリの設定時に必要になります。
Client ID and client secret screenshot
ウェブ アプリケーション
  1. Google Developers Console の認証に関するページを開きます。
  2. プロジェクトのメニューから [プロジェクトを作成] を選択し、プロジェクトの名前を入力します(表示されているプロジェクト ID は任意で編集することもできます)。[作成] をクリックします。
  3. 認証情報のページで [認証情報を作成] をクリックし、[OAuth クライアント ID] を選択します。
  4. [同意] 画面でのプロダクト名の設定を促された場合は、[同意画面を設定] をクリックして必要な情報を入力してから、[保存] をクリックして [認証情報] 画面に戻ります。
  5. [アプリケーションのタイプ] は [ウェブ アプリケーション] を選択します。手順に従って JavaScript の生成元かリダイレクト URI(またはその両方)を入力します。
  6. [作成] をクリックします。
  7. 表示されたページでクライアント IDクライアント シークレットをクリップボードにコピーします。この 2 つはクライアント ライブラリの設定時に必要になります。
Client ID and client secret screenshot

3. クライアント ライブラリを設定して使用する

使用する言語のクライアント ライブラリの設定で OAuth2 認証情報を使うには、以下のガイドに従ってください。

OAuth2 Playground

OAuth2 認証情報の生成には、OAuth2 Playground を使う方法もあります。OAuth2 Playground と Google Developers Console を併用すれば、手動で OAuth2 トークンを生成できます。

OAuth2 Playground は、1 つの MCC アカウントまたは 1 人の AdWords ユーザーのアカウントのみにアクセスする必要があるユーザーに適しています。複数のユーザーに認証情報の入力を求める場合は、前述のクライアント ライブラリを利用する方法が適しています。

設定方法

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

  1. Google Developers Console の認証に関するページを開きます。
  2. プロジェクトのメニューで既存のプロジェクトを選択するか、新しいプロジェクトを作成します。
  3. 認証情報のページで [認証情報を作成] をクリックし、[OAuth クライアント ID] を選択します。
  4. [アプリケーションのタイプ] に [ウェブ アプリケーション] を選択します。
  5. [承認済みのリダイレクト URI] に、https://developers.google.com/oauthplayground を含む行を追加します。
  6. [作成] をクリックします。
  7. 表示されたページに記載されているクライアント IDクライアント シークレットのメモをとります。この 2 つは以降の手順で必要になります。

トークンを生成する

  1. こちらのリンクから OAuth2 Playground に移動します。一部のキーと値は事前に入力されています。
  2. 右上の歯車アイコン をクリックし、[Use your own OAuth credentials] というチェックボックスをオンにします(オンになっていない場合)。
  3. 次の点をご確認ください。
    • [OAuth flow] が [Server-side] に設定されている。
    • [Access type] が [Offline] に設定されている(これにより、アクセス トークンだけでなくリフレッシュ トークンも取得できます)
  4. 前述の手順で取得した OAuth2 クライアント IDOAuth2 クライアント シークレットを入力します。 playground settings
  5. [Step 1 - Select & authorize APIs] で、下部のテキスト ボックスに以下の URL を入力し(入力されていない場合)、[Authorize APIs] をクリックします。

    https://www.googleapis.com/auth/adwords

    authorize apis

  6. ログインを求められた場合は、アクセス権を付与して承認したいアカウントにログインします。または、画面右上に表示されているログイン中の Google ユーザーが、認証情報を取得したい AdWords アカウントまたは MCC アカウントと同一であることを確認します。

  7. アプリによる AdWords キャンペーンの管理を有効にすることを確認するメッセージが表示されます。[許可] をクリックして続行します。

  8. [Step 2 - Exchange authorization code for tokens] タブに、[Authorization code] が表示されます。[Exchange authorization code for tokens] をクリックします。 playground authcode token
  9. 各設定が適切に完了すると、[Refresh token] と [Access token] の欄に値が入力されます(この値は [Step 2 - Exchange authorization code for tokens] タブを展開し直さないと表示されない場合があります)。 playground refresh token
  10. [Refresh token] の値とクライアント IDクライアント シークレットをコピーして使用するクライアント ライブラリの設定ファイルに貼り付けます。使用するクライアント ライブラリで設定オプションを使用する方法については、上記の手順をご覧ください。

クライアント ID から OAuth2 Playground を削除する

リフレッシュ トークンを取得したら、OAuth2 Playground を承認済みのリダイレクト URI にする必要はなくなります。OAuth2 Playground を承認済み URI から削除する方法は以下のとおりです。

  1. Google Developers Console の認証情報のページに移動します。
  2. プロジェクトのメニューからプロジェクトを選択します。
  3. 認証情報のページで、編集するクライアント ID の名前をクリックします。
  4. 承認済みのリダイレクト URI のリストか https://developers.google.com/oauthplayground を削除します。リスト内に少なくとも 1 つ、リダイレクト URI を残しておく必要がある点にご注意ください。
  5. [保存] をクリックします。

AdWords API のリクエストの送信と、使用するクライアント ライブラリ用のコードのサンプルの実行に必要な OAuth 認証情報の取得はこれで完了です。

OAuth2 サービス アカウント

ここでは、サービス アカウントを使って AdWords API にアクセスする方法を説明します。

サービス アカウントは、個々のエンドユーザーではなく、アプリケーションに属するアカウントです。サービス アカウントを利用すれば、ウェブ アプリケーションと Google サービスとのサーバー間通信が可能になります。サービス アカウントの代わりにアプリケーションによって Google API が呼び出されるため、ユーザーが直接関与することはありません。

AdWords API では、Google Apps ドメインを介したサービス アカウントからのアクセスが可能です。

サービス アカウントは手動認証を必要としない OAuth2 フローに対応していますが、アプリケーションだけがアクセスできるキーファイルを使用します。

サービス アカウントの主なメリットは次の 2 つです。

  • アプリケーションによる Google API へのアクセスに必要な承認作業を、設定の一環として行います。そのため、手動操作や、手動操作を避けるためのアプリケーションでのトークンのキャッシュ作成など、OAuth2 の他のフローでは必要となる面倒な作業が不要です。
  • OAuth2 アサーション フローでは、必要に応じて他のユーザーの代理としてアプリケーションを機能させることができます。

サービス アカウントに代わる手法

開発者がサービス アカウントを利用する目的は、多くの場合、OAuth2 を使用することにより手動作業なしでプログラムによる API へのアクセスを行うことです。

しかし、AdWords API 用にサービス アカウントによるアクセスを設定する手順は複雑なため、同じ機能をより簡単に設定できる方法として、OAuth2 のインストール型アプリケーションのフローでリフレッシュ トークンを維持する方法をおすすめします。この方法では、必要に応じていつでもアプリケーションから新しいアクセス トークンをリクエストできます。

この設定では、上記のインストール型アプリケーションの設定手順に従い、クライアント ライブラリを設定してアプリを認証する必要があります。Google の OAuth2 リフレッシュ トークンには有効期限がないため、この設定は 1 回だけで済みます。

前提条件

サービス アカウントによるアクセスを設定する

まず、以下の手順に従い Google Developers Console でサービス アカウント キーを生成する必要があります。

  1. Google Apps for Work アカウントにログインし、Google Developers Console を開きます。
  2. 右上のプロジェクトのメニューから [プロジェクトの作成] を選択し、必要な情報を入力して [作成] をクリックします。少し待つと新しいプロジェクトがアクティブ状態になります。
  3. 左上のメニューから [IAM と管理] を選択し、左側のメニューから [サービス アカウント] を選択します。
  4. 上部の [サービス アカウントを作成] をクリックします。
  5. サービス アカウントの名前を入力します。
  6. [新しい秘密鍵の提供] をオンにして、キーのタイプとして [JSON] または [P12] を選択します。現在、JSON は Java、.NET、Ruby、PHP のクライアント ライブラリに対応しています。それ以外では P12 を使用してください。
  7. [Google Apps ドメイン全域委任] をオンにして、同意画面のプロダクト名を入力します。
  8. [作成] をクリックします。秘密鍵のタイプに P12 を選択していた場合は、キーのファイルがダウンロードされ、その秘密鍵のパスワードを含む画面が表示されます。このパスワードは再度表示されることはないため、すぐに保存してください。P12 の秘密鍵を使用する際に入力する必要があります。

    秘密鍵のタイプに JSON を選択していた場合は、JSON のキーのファイルがダウンロードされます。

    P12 または JSON のキーのファイルは、他のユーザーがアクセスできない安全な場所に保管してください。

  9. プロジェクトの [サービス アカウント] ページに新しいサービス アカウントが表示されます。

セキュリティ上の課題

Google Apps の管理機能はドメイン単位のため、サービス アカウントに承認済みの Google サービスへのアクセスを許可するキーのファイルは、安全な場所に保管することが重要になります。このサービス アカウントにはドメインのすべてのユーザーになり代わることができる権限が付与されるため、ファイルの保護は特に重要です。

また、次のセクションで説明する「scope」フィールドを使用して、サービス アカウントごとにアクセス可能な Google API を 1 つに限定する方法も効果的です。こうした予防措置を講じると、サービス アカウントのキーのファイルに不正なアクセスが発生した場合でも、攻撃者がアクセスできるデータ量を抑えることができます。

なり代わりを許可する

サービス アカウントになり代わりの権限を付与する手順は以下のとおりです。

  1. https://admin.google.com/YOUR_DOMAIN/ManageOauthClients に移動し、承認済みの新しい API クライアントを Google Apps ドメインに追加します。
  2. 上記の手順でサービス アカウントのドメイン全域委任を有効にしたときに生成した P12 または JSON ファイルのクライアント ID を [クライアント名] として、承認済みの新しい API クライアントを追加します。
  3. API のスコープに次の URL を入力します。

    https://www.googleapis.com/auth/adwords

  4. なり代わりを許可する他のサービス アカウントでもこの手順を繰り返します。

以上でサービス アカウントを使用し、OAuth2 アサーション フローを介して AdWords アカウントにアクセスできるようになりました。

クライアント ライブラリを設定する

以下からご使用の言語を選択し、手順に従ってクライアント ライブラリを設定してください。

Java

GitHub の手順に従い、サービス アカウント用のクライアント ライブラリを設定します。

.NET

GitHub の手順に従い、サービス アカウント用のクライアント ライブラリを設定します。

Python

GitHub の手順に従い、サービス アカウント用のクライアント ライブラリを設定します。

PHP

GitHub の手順に従い、サービス アカウント用のクライアント ライブラリを設定します。

Perl

GitHub の手順に従い、サービス アカウント用のクライアント ライブラリを設定します。

Ruby

GitHub の手順に従い、サービス アカウント用のクライアント ライブラリを設定します。

OAuth 2.0 リクエストの最適化

複数のサーバー、プロセス、スレッド全体で認証情報を共有するわけではない場合は、過剰な数のリクエストが Google に送信される可能性があります。そうした場合は、Google のサーバーがアプリケーションのレートに制限を課し、その結果としてパフォーマンスの低下を招くことがあります。

このセクションでは、アプリと AdWords API とのやり取りを効率化するため、OAuth2 認証情報の管理を最適化する方法について解説します。

認証情報の共有戦略

API リクエスト全体で認証情報を共有することで、パフォーマンスを高め、過剰なリクエストを抑えてレート制限エラーを回避することができます。

以下のように、ご自分のアプリケーションの設計に合わせて認証情報の共有戦略を策定しましょう。

マルチスレッド型のアプリケーションでは、同じ認証情報を使って各スレッドのセッションを提供する必要があります。

マルチプロセスまたは分散型アプリケーションでは、プロセス全体で認証情報を共有するためにいくつかのインフラを実装する必要があります。スレッドをブロックせず、実装時に競合状態が発生しないようにする必要もあります。

各プロセスでマルチプロセスまたは分散型と、マルチスレッド型の両方の側面を持つアプリの場合は、両方の戦略が必要になります。

階層内の最上位の MCC アカウントなど、単一の AdWords アカウントの認証を行うための戦略について以下で説明します。

複数の AdWords アカウントの認証を行うための戦略については、その後に説明します。

マルチスレッド型アプリケーション

マルチスレッド型アプリケーションでは、スレッド間で認証情報を共有する必要があります。競合状態を避けるため、認証情報の更新は同期的に行う必要があります。

runtime

この図は、セッション(ユーザー)の共有プールから AdWords API にリクエストを送信するスレッドのランタイムを示しています。各スレッドで同じ認証情報オブジェクトを使用する必要があります。各 API リクエストで、スレッドが 1 つずつのセッション(ユーザー)を取得します。認証情報でアクセス トークンの更新が必要な場合は、競合状態を避けるため、認証情報オブジェクトをスレッドセーフにして同期的に更新を行う必要があります。

クライアント ライブラリでは、スレッド全体で直接的に認証情報を共有します。それぞれのクライアント ライブラリに、有効期限が切れるまで再利用される認証情報を含むセッション(ユーザー)オブジェクトが 1 つずつあります。スレッド全体で認証情報を共有する場合は、各セッションを同一の認証情報で作成するだけです。すべてのクライアント ライブラリの認証情報は、アクセス トークンの有効期限が切れたときに自動で同期的に更新されるスレッドセーフのオブジェクトとなります。

たとえば Java クライアント ライブラリの場合は、認証情報をシングルトンとして作成し、セッション全体で共有します。

マルチプロセスまたは分散型アプリケーション

マルチプロセスまたは分散型アプリケーションの場合、認証情報を共有するためには、認証情報を維持する必要があります。複数のプロセスやサーバーで同時に認証情報が更新されないようにするため(過度の更新リクエストの発生を防ぐため)、中核的なデータストアで事前に認証情報を更新し、プロセスやサーバー全体で共有することをおすすめします。

たとえば、個別のジョブまたはサービスによって認証情報を定期的に更新し、事前にデータストアにプッシュしてサーバープールで使用するようにできます。

refresh

この図は、定期的に実行され、認証情報のプロパティをデータストアに書き込む認証情報の更新ジョブを示しています。各サーバーで認証情報を取得してから、API へのリクエストが実行されます。

更新ジョブ

更新ジョブによって定期的に認証情報を更新し、データストアに保管します。このジョブは、現在の認証情報の期限切れを待つことなく更新を行うことができます。この場合、有効な認証情報がなくなるとアプリケーションが停止し、ウィンドウが開きます。

より効果的なのは、定期的な更新を強制し、更新を行うたびにデータストアの認証情報を新しい情報に置き換える方法です。一時的なエラーの際の時間的猶予を確保するため、現在の認証情報の有効期限が切れるかなり前の段階で更新ジョブを実行します。最初は 15 分ごとに設定することをおすすめします。

データストア

中核的なデータストアを使い、プロセスやサーバー間で認証情報を共有できます。

既存のデータストアを利用しても、サーバー間での認証情報の共有専用のデータストアを配置しても構いません。ソリューションにはキャッシュ サーバー(MemcachedInfinispan など)、NoSQL データストア(MongoDBなど)が考えられます。

データストアの役割は、API にリクエストを実行するすべてのサーバーに対する信頼性の高いインターフェースとなることです。サーバーやプロセスによって、現在の認証情報が更新ジョブによる処理よりも頻繁に読み込まれるため、高速の読み込み処理に合わせて最適化する必要があります。

認証情報は安全に保管する必要がある点にご注意ください。

認証情報は、算出した expiry_time(現在時刻+expires_in)と refresh_token に加え、access_token も保管する必要があります。expiry_timeaccess_token 更新リクエストの時点に expires_in を加算した値となります。

サーバープール

プール内の各サーバーやプロセスは、リクエストの前に最新の認証情報をデータストアから取得します。認証ジョブが適切に実行されれば、有効な認証情報が取得されますが、更新ジョブやデータストアにエラーが生じた場合は代替となるメカニズムが必要になります。

サーバーまたはプロセスがデータストアから認証情報を取得できなかった場合や、認証情報の有効期限が切れた場合は、問題が解決するまでアプリと API の接続が途切れないように、サーバーが自身の認証情報を更新する必要があります。

複数のスレッドを含むプロセスでは、前述のものと同一の共有戦略を策定し、スレッド全体で認証情報を共有する必要があります。

複数アカウントの認証

生成された AdWords MCC アカウントの認証情報を使用すれば、すべての子アカウントにアクセスできます。そのため、単一の MCC アカウントを使用しているユーザーの場合、通常は最上位の MCC アカウントの認証情報を生成し、その配下のすべての AdWords アカウントでのアプリの認証を行えば十分です。

それ以外のケースでは、どの MCC アカウントの階層とも関連性を持っていない AdWords アカウントにアプリケーションがアクセスする必要があります。そのケースでは、アクセスする AdWords の各子アカウントや個々の階層内の最上位の各 MCC アカウントなど、複数のアカウントに対する複数の認証情報を生成して維持する必要があります。

マルチスレッド型アプリケーションとマルチプロセス / 分散型アプリケーションで、多少の修正を加えて同一の戦略を策定することができます。共有のデータストアを使用する場合は、認証情報をアカウントの識別子 customerId でインデックスに登録し、認証情報を適切なアカウントに関連付ける必要があります。また、更新ジョブではすべての認証情報を更新し続ける必要があります。新しいアカウントがリンクされた場合は更新ジョブのトリガーが必要になることがあります。

また、マルチスレッド型アプリケーションでは、認証情報オブジェクトが関連付けられているアカウントで処理を実行するスレッド全体でのみ、認証情報オブジェクトを共有する必要があります。

OAuth2 の具体的な仕組み

Google のクライアント ライブラリでは、以下で説明する処理が自動的に行われるため、具体的な仕組みに関心がある場合や、クライアント ライブラリを使用しない場合のみ読み進めてください。

このセクションは、既に OAuth 2.0 の仕様を把握しており、Google の API における OAuth 2.0 の使い方を理解されている上級者向けの説明です。

スコープ

1 つのアクセス トークンで、複数の API にさまざまなレベルのアクセス権を付与できます。scope という変数パラメータを使って、アクセス トークンで許可するリソースと操作を制御することが可能です。アクセス トークンのリクエスト中は、アプリによって scope パラメータの値が送信されます。

AdWords API の現行およびサポート終了済みのスコープは以下のとおりです。

スコープ 意味
https://www.googleapis.com/auth/adwords AdWords API に対する読み取りと書き込みのアクセスです。
https://adwords.google.com/api/adwords/ このスコープはサポートが終了しており、今後の認証取得には使用できません。既に認証されているトークンは機能します。

オフライン アクセス

多くのケースで、AdWords API クライアント アプリケーションによってオフライン アクセスがリクエストされます。たとえば、ユーザーがオンラインでウェブサイトを閲覧していないときでも、AdWords API クライアント アプリケーションで一括ジョブを実行したい場合などです。

ウェブ アプリケーション タイプのアプリケーションにオフライン アクセスをリクエストするには、必ず access_type パラメータを offline に設定してください。詳細については、Google の OAuth 2.0 ガイドをご覧ください。

インストール型アプリケーション タイプの場合、オフライン アクセスはデフォルトで有効で、明示的にリクエストする必要はありません。

HTTP リクエスト ヘッダー

AdWords API サーバーに対するリクエストの HTTP ヘッダーには、必ず次の形式でアクセス トークンを含める必要があります。

Authorization: Bearer THE_ACCESS_TOKEN

次に例を示します。

POST … HTTP/1.1
Host: …
Authorization: Bearer 1/fFAGRNJru1FTz70BzhT3Zg
Content-Type: text/xml;charset=UTF-8
Content-Length: …

<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2001/12/soap-envelope">
  …
</soap:Envelope>

アクセス トークンとリフレッシュ トークン

ほとんどのケースでは、リフレッシュ トークンを安全に保管して再利用できるようにしておく必要があります。アクセス トークンとリフレッシュ トークンをリクエストする方法の詳細については、ご自身のアプリケーション タイプに合わせて次のガイドをご覧ください。

アクセス トークンの期限切れ

アクセス トークンには有効期限があり(expires_in の値によります)、期限が過ぎるとトークンが無効になります。リフレッシュ トークンを使って、期限切れとなったアクセス トークンを更新できます。クライアント ライブラリでは、期限切れのアクセス トークンはデフォルトで自動的に更新されます。

フィードバックを送信...

ご不明な点がありましたら、Google のサポートページをご覧ください。