OAuth サービス アカウント

Google Apps ドメインのサービス アカウントを使うと、人手を介さずに AdWords API にアクセスできます。サービス アカウントでは OAuth 2.0 のフローが使用されるため、人による承認は不要となり、代わりにお客様のアプリケーションのみがアクセス可能なキー ファイルが使われます。このガイドでは、サービス アカウントを使って AdWords API にアクセスする方法をご説明します。

OAuth2 のオフライン フローとウェブ フローでは、アカウントへのアクセス権が付与された際に 1 回だけユーザーによる操作が必要になりますが、それ以降は、アクセス トークンが取り消されない限り、すべてのオペレーションを人手を介さず自動的に実行できます。このため、ドメイン限定の機能(成り代わり機能など)が必要な場合を除き、サービス アカウントではなく、オフライン フローかウェブ フローのどちらかを使うことを強くおすすめします。

  1. サービス アカウントに代わる手法
  2. AdWords API でサービス アカウントを使用するメリット
  3. 事前の準備
  4. サービス アカウントを使って AdWords API にアクセスする手順

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

デベロッパーの多くは、OAuth2.0 を使ったプログラムによって人手を介さずに API にアクセスしたいと考えているため、サービス アカウントの利用を検討しています。しかし、AdWords API でサービス アカウントを設定することは簡単ではないため、同じことをもっと簡単に実現する方法として、OAuth 2.0 を実装したアプリケーション フローを使ってリフレッシュ トークンを使い続けることをおすすめします。この方法を使えば、お客様のアプリケーションから必要に応じて新しいアクセス トークンをリクエストできます。

この方法の唯一の難点は、OAuth 2.0 をアプリケーションに実装するフローにおいて、そのアプリケーションをユーザーが手動で承認する必要がある点です。ただし、Google OAuth 2.0 のリフレッシュ トークンには有効期限がないため、この作業は 1 回だけで済みます。

AdWords API でサービス アカウントを使用するメリット

サービス アカウントを使用するメリットは、主に次の 2 つです。

  1. アプリケーションで Google API にアクセスするために必要となる承認作業は、設定手順で 1 回だけ行えば済むため、OAuth 2.0 の他のフローでは面倒な事態(人手による操作が必要になる、人手による操作を回避するためにアプリケーションでトークンをキャッシュしておく必要があるなど)を回避できます。
  2. OAuth 2.0 のアサーション フローで、必要に応じてアプリケーションが他のユーザーに成り代わることができます。

このガイドの後半では、AdWords API でサービス アカウントを使用する手順を説明します。ここで示されるサンプル コードでは、AdWords API 向け Google Ads Java クライアント ライブラリが使われていますが、AdWords API クライアント ライブラリの他の言語でも同じことができます。

事前の準備

サービス アカウントを使って AdWords API にアクセスする手順

  1. Google API コンソールで、次の手順でサービス アカウント キーを生成します。

    1. Google API コンソールに移動します。
    2. [API アクセス] タブをクリックします。
    3. [別のクライアント ID を作成] をクリックします。
    4. [アプリケーションの種類] として [サービス アカウント] を指定して [クライアント ID を作成] をクリックします。
    5. 秘密キーをダウンロードして、自分以外に誰もアクセスできない安全な場所に保存します。
    6. API アクセス情報の下に、[サービス アカウント] という新しいセクションが表示されます。後でこのページの [メール アドレス] をコピーする必要があるため、すぐにアクセスできるようにしておきます。

  2. Google の OAuth 2.0 サービスでサービス アカウントとアサーション フローを使用するには、Google Apps にご自分のドメインを登録しておく必要があります。この理由は、ユーザーの成り代わりはドメインレベルで制御されるためです(これより細かい単位でアクセスが制御されることはありません)。言い換えると、サービス アカウントを使った成り代わりが許可されているドメインでは、そのすべてのユーザーが同じドメインの別のユーザーに成り代わることができます。たとえば、この理由から、サービス アカウントで Gmail アカウントに成り代わることはできません。

    セキュリティ上の課題

    サービス アカウントは Google Apps のドメイン レベルで管理されるため、サービス アカウントに対して承認済みの Google サービスへのアクセスを許可する *.p12 キー ファイルの安全性を確保する必要があります。特に、サービス アカウントに対してドメインのすべてのユーザーに成り代わる権限を付与する場合は、このファイルの保護が極めて重要になります。また、サービス アカウントごとにアクセス可能な Google API を 1 つに限定するのも良い方法です(この場合は、次のセクションで説明する「scope」フィールドを使用します)。こうした予防措置を行うと、サービス アカウントの *.p12 キー ファイルに不正なアクセスが発生した場合でも、アクセスされるデータ量を抑えることができます。

    サービス アカウントに成り代わりの権限を付与する手順

    1. 次の URL にアクセスして、新しく承認された API クライアントを Google Apps ドメインに追加します。
      https://www.google.com/a/cpanel/YOUR_DOMAIN/ManageOauthClients
      注: 「YOUR_DOMAIN」の部分は、ご自身の実際のドメイン(例: mydomain.com)に置き換えてください。

    2. 手順 1 において API コンソールで作成したクライアント ID を [クライアント名] として、新しい Author API クライアントを追加します。

    3. API のスコープに次の URL を入力します。
      https://adwords.google.com/api/adwords

    4. 成り代わりの権限を付与するすべてのサービス アカウントで上記の手順を繰り返します。

  3. これで、OAuth 2.0 のアサーション フローでサービス アカウントを使って AdWords アカウントにアクセスできるようになりました。次に示すサンプル コードは、OAuth 2.0 のアサーション フローでサービス アカウントを使用してアクセス トークンを取得し、テスト アカウントに設定されたすべてのキャンペーンを取得する、基本的な AdWords API を呼び出しています。

    private static Credential getOAuth2Credential() throws Exception {
      // Service account credential.
      GoogleCredential credential = new GoogleCredential.Builder().setTransport(
          new NetHttpTransport())
          .setJsonFactory(new GsonFactory())
          .setServiceAccountId(
              "****@developer.gserviceaccount.com")
          .setServiceAccountScopes("https://adwords.google.com/api/adwords")
          .setServiceAccountPrivateKeyFromP12File(new File("/path/to/key.p12"))
          // 成り代わるユーザーを指定します。呼び出すアカウント
          //(ご自身の AdWords API クライアント センター アカウントか広告主様のアカウント)の有効なログイン用メール アドレスで
          // 指定します。
          .setServiceAccountUser("user@yourdomain.com")
          .build();
    
      credential.refreshToken();
      return credential;
    }
    
    public static void runExample(AdWordsServices adWordsServices, AdWordsSession session) throws Exception {
      // CampaignService を取得します。
      CampaignServiceInterface campaignService =
          adWordsServices.get(session, CampaignServiceInterface.class);
    
      // セレクタを作成します。
      Selector selector = new Selector();
      selector.setFields(new String[] {"Id", "Name"});
    
      // すべてのキャンペーンを取得します。
      CampaignPage page = campaignService.get(selector);
    
      // キャンペーンを表示します。
      if (page.getEntries() != null) {
        for (Campaign campaign : page.getEntries()) {
          System.out.println("Campaign with name \"" + campaign.getName() + "\" and id \""
              + campaign.getId() + "\" was found.");
        }
      } else {
        System.out.println("No campaigns were found.");
      }
    }
    
    public static void main(String[] args) throws Exception {
      // OAuth2 の認証情報を取得する。
      Credential credential = getOAuth2Credential();
    
      // AdWordsSession を構成します。
      AdWordsSession session = new AdWordsSession.Builder()
          .fromFile()
          .withOAuth2Credential(credential)
          .build();
    
      AdWordsServices adWordsServices = new AdWordsServices();
      runExample(adWordsServices, session);
    }

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

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