Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

認証と承認

他の 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 をホームディレクトリにコピーして、サービスアカウントのキーファイルの場所（および Google Workspace のドメイン全体の委任を使用するときになりすますユーザーのメールアドレス（省略可））を指定するように変更します。

# 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'
# Optional unless using Google Workspace domain-wide delegation:
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"
# Optional unless using Google Workspace domain-wide delegation:
export GOOGLE_ADS_IMPERSONATED_EMAIL="your_email@email.com"

実行時にサービスアカウントキーファイルのパス（およびオプションの権限借用メール）をプログラムで渡すこともできます。

require 'google/ads/google_ads'

client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.keyfile = '/path/to/your/service-account-key.json'
  # Optional unless using Google Workspace domain-wide delegation:
  config.impersonate = 'INSERT_EMAIL_ADDRESS_TO_IMPERSONATE_HERE'
end

または、googleauth gem を使用してサービスアカウントの認証情報を作成し、credentials.updater_proc を config.authentication に渡すこともできます。

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 = File.open(key_file) do |io|
  Google::Auth::ServiceAccountCredentials.make_creds(
    json_key_io: io,
    scope: scopes
  )
end

# Initialize the Google Ads API client with these credentials.
client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  # Inject the service account credential updater proc.
  config.authentication = credentials.updater_proc
end

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

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

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

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

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

# 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_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.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 を含めるように変更します。

# 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 to 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_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.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 クライアントライブラリには、このようなケースを処理する方法を示す次のコード例が用意されています。

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

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

Ruby クライアントライブラリ（v36.1.0 以降）は、アプリケーションのデフォルト認証情報（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 に設定します。

# 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_USE_APPLICATION_DEFAULT_CREDENTIALS を設定します。

export GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS="true"

実行時にプログラムで情報を渡すこともできます。Ruby コードでクライアントを初期化するときに、config.use_application_default_credentials = true を設定し、明示的な OAuth 2.0 認証情報は指定しないでください。ライブラリは、Google Cloud コマンドラインツールによって設定された認証情報を自動的に検出して使用します。

# Initialize the client using Application Default Credentials.
client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.use_application_default_credentials = true

  # 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 client_id, client_secret, or refresh_token here.
end

Ruby クライアントライブラリの構成に使用できるオプションの詳細については、構成ページをご覧ください。