認証と認可

他の Google API と同様に、Google Ads API では、認証と承認に OAuth 2.0 プロトコルを使用しています。OAuth 2.0 を使うことで、Google Ads API クライアント アプリケーションは、ユーザーのログイン情報を保存したり処理したりしなくてもユーザーの Google 広告アカウントにアクセスできるようになります。

Google 広告のアクセスモデルについて

Google Ads API を効果的に使用するには、Google 広告のアクセスモデルの仕組みを理解する必要があります。Google 広告のアクセスモデルのガイドをお読みになることをおすすめします。

OAuth のワークフロー

Google Ads API を使用する際に使用される一般的なワークフローは 3 つあります。

サービス アカウントのフロー

ワークフローでユーザーの操作が必要ない場合は、このワークフローをおすすめします。このワークフローでは、ユーザーがサービス アカウントを Google 広告アカウントに追加する構成手順が必要です。アプリは、サービス アカウントの認証情報を使用して、ユーザーの Google 広告アカウントを管理できます。これを構成するには、Google Cloud コンソールで JSON キーファイルを作成してダウンロードし、google_ads_config.rb をホーム ディレクトリにコピーして、サービス アカウントのキーファイルの場所と権限を借用するユーザーのメールアドレスを指定するように変更します。

  # You can also authenticate using a service account. If "keyfile" is
  # specified below, then service account authentication will be assumed and
  # the above authentication fields ignored. Read more about service account
  # authentication here:
  # https://developers.google.com/google-ads/api/docs/oauth/service-accounts
  # c.keyfile = 'path/to/keyfile.json'
  # c.impersonate = 'INSERT_EMAIL_ADDRESS_TO_IMPERSONATE_HERE'

この情報をファイルに保存したくない場合は、環境変数を使用できます。GOOGLE_ADS_JSON_KEY_FILE_PATH と GOOGLE_ADS_IMPERSONATED_EMAIL をそれぞれ設定します。

export GOOGLE_ADS_JSON_KEY_FILE_PATH="/path/to/your/service-account-key.json"
export GOOGLE_ADS_IMPERSONATED_EMAIL="your_email@email.com"

また、googleauth gem を使用してサービス アカウントの JSON ファイルから認証情報を作成することで、実行時にプログラムで情報を渡すこともできます。

require 'googleauth'
require 'google/ads/google_ads'

# Path to your service account key file
key_file = "/path/to/your/service-account-key.json"

# Define the scopes needed for the Google Ads API
scopes = ['https://www.googleapis.com/auth/adwords']

# Create service account credentials
credentials = Google::Auth::ServiceAccountCredentials.make_creds(
  json_key_io: File.open(key_file),
  scope: scopes
)

# Initialize the Google Ads API client with these credentials
client = Google::Ads::GoogleAds::Client.new do |config|
  config.developer_token = "YOUR_DEVELOPER_TOKEN"
  # Inject the service account credentials
  config.oauth2_client = credentials
end

詳しくは、サービス アカウントのワークフロー ガイドを ご覧ください。

シングルユーザー認証フロー

サービス アカウントを使用できない場合は、このワークフローを使用できます。このワークフローでは、次の 2 つの構成手順が必要です。

  1. Google Ads API を使用して管理するすべてのアカウントへのアクセス権を 1 人のユーザーに付与します。一般的な方法としては、Google Ads API MCC アカウントへのアクセス権をユーザーに付与し、その MCC アカウントの下にあるすべての Google 広告アカウントをリンクします。
  2. ユーザーは、gcloud などのコマンドライン ツールまたは GenerateUserCredentials コードサンプルを実行して、すべての Google 広告アカウントをユーザーに代わって管理する権限をアプリに付与します。

OAuth 2.0 認証情報は、 google_ads_config.rb ファイルをホーム ディレクトリにコピーし、 開発者トークン、クライアント ID、クライアント シークレット、更新トークンを含めるように変更することで、Ruby 用に構成できます。

  # The developer token is required to authenticate that you are allowed to
  # make API calls.
  c.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'

  # Authentication tells the API that you are allowed to make changes to the
  # specific account you're trying to access.
  # The default method of authentication is to use a refresh token, client id,
  # and client secret to generate an access token.
  c.client_id = 'INSERT_CLIENT_ID_HERE'
  c.client_secret = 'INSERT_CLIENT_SECRET_HERE'
  c.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'

引数を指定せずにインスタンス化すると、クライアントはホーム ディレクトリから構成ファイルを自動的に読み取ります。

client = Google::Ads::GoogleAds::GoogleAdsClient.new

ファイルを別の場所に保存する場合は、このファイルを保存するパスを渡してクライアントをインスタンス化します。

client = Google::Ads::GoogleAds::GoogleAdsClient.new('path/to/google_ads_config.rb')

この情報をファイルに保存したくない場合は、環境変数を使用できます。それぞれ設定します。

export GOOGLE_ADS_DEVELOPER_TOKEN="INSERT_DEVELOPER_TOKEN_HERE"
export GOOGLE_ADS_CLIENT_ID="INSERT_CLIENT_ID_HERE"
export GOOGLE_ADS_CLIENT_SECRET="INSERT_CLIENT_SECRET_HERE"
export GOOGLE_ADS_REFRESH_TOKEN="INSERT_REFRESH_TOKEN_HERE"

また、実行時にプログラムで情報を渡すこともできます。

client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'
  config.client_id = 'INSERT_CLIENT_ID_HERE'
  config.client_secret = 'INSERT_CLIENT_SECRET_HERE'
  config.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'
end

詳しくは、シングルユーザー認証ワークフロー ガイドを ご覧ください。

マルチユーザー認証フロー

アプリでユーザーがログインし、ユーザーに代わって Google 広告アカウントを管理する権限をアプリに付与できる場合は、このワークフローをおすすめします。アプリは OAuth 2.0 ユーザー認証情報を構築して管理します。このワークフローは、シングルユーザー フローと同様に構成できますが、login_customer_id も指定します。

構成ファイルを使用することをおすすめします。google_ads_config.rb ファイルをホーム ディレクトリにコピーし、開発者トークン、クライアント ID、クライアント シークレット、更新トークン、お客様 ID を含めるように変更します。

  # The developer token is required to authenticate that you are allowed to
  # make API calls.
  c.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'

  # Authentication tells the API that you are allowed to make changes to the
  # specific account you're trying to access.
  # The default method of authentication is to use a refresh token, client id,
  # and client secret to generate an access token.
  c.client_id = 'INSERT_CLIENT_ID_HERE'
  c.client_secret = 'INSERT_CLIENT_SECRET_HERE'
  c.refresh_token = 'INSERT_REFRESH_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. If you need to use different values for this field, then
  # make sure fetch a new copy of the service after each time you change the
  # value.
  # c.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'

引数を指定せずにインスタンス化すると、クライアントはホーム ディレクトリから構成ファイルを自動的に読み取ります。

client = Google::Ads::GoogleAds::GoogleAdsClient.new

ファイルを別の場所に保存する場合は、このファイルを保存するパスを渡してクライアントをインスタンス化します。

client = Google::Ads::GoogleAds::GoogleAdsClient.new('path/to/google_ads_config.rb')

この情報をファイルに保存したくない場合は、環境変数を使用できます。それぞれ設定します。

export GOOGLE_ADS_DEVELOPER_TOKEN="INSERT_DEVELOPER_TOKEN_HERE"
export GOOGLE_ADS_CLIENT_ID="INSERT_CLIENT_ID_HERE"
export GOOGLE_ADS_CLIENT_SECRET="INSERT_CLIENT_SECRET_HERE"
export GOOGLE_ADS_REFRESH_TOKEN="INSERT_REFRESH_TOKEN_HERE"
export GOOGLE_ADS_LOGIN_CUSTOMER_ID="INSERT_LOGIN_CUSTOMER_ID_HERE"

また、実行時にプログラムで情報を渡すこともできます。

client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'
  config.client_id = 'INSERT_CLIENT_ID_HERE'
  config.client_secret = 'INSERT_CLIENT_SECRET_HERE'
  config.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'
  config.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'
end

詳しくは、マルチユーザー認証ワークフロー ガイドを ご覧ください。Ruby クライアント ライブラリには、参考となるコードサンプルが含まれています。 GenerateUserCredentials は、ユーザーに代わって Google 広告アカウントを管理するために、実行時にユーザー認証を取得する方法を示すコマンドライン コードサンプルです。このコードサンプルは、ユーザー認証を必要とするデスクトップ アプリを構築する際の参考として使用できます。

ユーザーが複数のアカウントを管理している場合はどうなりますか？

ユーザーが複数の Google 広告アカウントを管理していることはよくあります。アカウントに直接アクセスする場合も、Google 広告 MCC アカウント経由で管理する場合もあります。Ruby クライアント ライブラリには、このようなケースを処理する方法を示す次のコードサンプルが用意されています。

  1. GetAccountHierarchy コードサンプルは、Google 広告 MCC アカウントの下にあるすべてのアカウントのリストを 取得する方法を示しています。
  2. ListAccessibleCustomers コードサンプルは、ユーザーが直接アクセスできるすべてのアカウントのリストを取得する方法を示しています。これらのアカウントは、LoginCustomerId 設定の有効な値として使用できます。

アプリケーションのデフォルト認証情報

Ruby クライアント ライブラリは、 アプリケーションのデフォルト認証情報（ADC）を使用した認証もサポートしています。これにより、アプリケーション構成内で OAuth 2.0 情報を構成しなくても、アプリケーションのデフォルト認証情報を設定できます。

これは、ローカル開発やさまざまな Google API に対する開発に特に便利です。正しい OAuth 2.0 スコープにアクセスできる限り、同じ認証情報を再利用できます。

Google Ads API の場合、アプリケーションのデフォルト認証情報が https://www.googleapis.com/auth/adwords OAuth 2.0 スコープにアクセスできることを確認してください。

アプリケーションのデフォルト認証情報を使用するには、 Google Cloud コマンドライン ツールを使用して ADC の認証を行うことをおすすめします。

gcloud auth application-default login

このコマンドを実行すると、ウェブブラウザが開き、Google アカウントの認証フローが完了します。承認されると、認証情報は標準の場所に保存されます。次に、ADC を使用するようにアプリケーションを更新する必要があります。

構成ファイルを使用することをおすすめします。google_ads_config.rb ファイルをホーム ディレクトリにコピーし、開発者トークンを追加して、 use_application_default_credentials を true に設定します。

  # The developer token is required to authenticate that you are allowed to
  # make API calls.
  c.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'

  # You can also authenticate using Application Default Credentials (ADC)
  # To understand how ADC discovers credentials in a given environment,
  # see: https://developers.google.com/identity/protocols/application-default-credentials.
  c.use_application_default_credentials = true

この情報をファイルに保存したくない場合は、環境変数を使用できます。GOOGLE_ADS_DEVELOPER_TOKEN と GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS を設定します。

export GOOGLE_ADS_DEVELOPER_TOKEN="INSERT_DEVELOPER_TOKEN_HERE"
export GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS="true"

また、実行時にプログラムで情報を渡すこともできます。Ruby コードでクライアントを初期化するときに、明示的な OAuth2 認証情報を指定しないでください。 ライブラリは、Google Cloud コマンドライン ツールで設定された認証情報を自動的に検出して使用します。開発者トークンは指定する必要があります。

# Initialize the client. It will automatically use Application Default Credentials.
client = Google::Ads::GoogleAds::Client.new do |config|
  # Developer Token is mandatory for the Google Ads API.
  config.developer_token = "YOUR_DEVELOPER_TOKEN"

  # Optional: Specify a login customer ID if you are accessing accounts
  # through a manager account.
  # config.login_customer_id = "YOUR_LOGIN_CUSTOMER_ID"

  # Do NOT include oauth2_client_id, oauth2_client_secret, or oauth2_refresh_token here.
end

Ruby クライアント ライブラリを構成するための利用可能なオプションの詳細については、構成 ページをご覧ください。