認証と認可

他の 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 広告アカウントを管理できるようになります。Python ライブラリは次のように構成されています。

  • google-ads.yaml ファイルまたは YAML 文字列を使用している場合は、次の構成を追加して、ローカル環境の秘密鍵 JSON ファイルへのパスを設定します。

    json_key_file_path: JSON_KEY_FILE_PATH

    次に、load_from_storage または load_from_string メソッドを呼び出します。

    from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage()

  • dict を使用してライブラリを構成する場合は、次のキーと値のペアを含め、構成 dict を渡して load_from_dict メソッドを呼び出します。

    from google.ads.googleads.client import GoogleAdsClient

configuration = {
  # ...
  "json_key_file_path": JSON_KEY_FILE_PATH
  # ...
}

client = GoogleAdsClient.load_from_dict(configuration)

  • 環境変数を使用している場合は、bash 構成または環境に次を追加します。

    export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH

    次に、load_from_env メソッドを呼び出します。

    from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_env()
  ```

これらの構成方法のいずれかに json_key_file_path 構成オプションが存在し、use_application_default_credentials オプションが False または未設定の場合、ライブラリはサービス アカウント フローを使用して自動的に承認します。

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

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

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

  1. Google 広告 API を使用して管理するすべてのアカウントへのアクセス権を 1 人のユーザーに付与します。一般的なアプローチは、ユーザーに Google Ads API MCC アカウントを付与し、その MCC アカウントの下にすべての Google 広告アカウントをリンクすることです。

  2. ユーザーが gcloud CLI や generate_user_credentials コード例などのツールを実行して、ユーザーに代わってすべての Google 広告アカウントを管理する権限をアプリに付与します。

ライブラリは、ユーザーの OAuth 2.0 認証情報を使用して次のように初期化できます。

gcloud CLI ツールを使用している場合（推奨）

  1. 認証情報を生成するドキュメントに沿って、ローカル環境でアプリケーションのデフォルト認証情報（ADC）を設定します。

  2. google-ads.yaml または YAML 文字列に次の構成を追加します。

    use_application_default_credentials: true

    次に、load_from_storage メソッドまたは load_from_string メソッドを呼び出します。

    from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage()

    dict を使用してライブラリを構成する場合は、次の Key-Value ペアを含めて load_from_dict メソッドを呼び出します。

    from google.ads.googleads.client import GoogleAdsClient

configuration = {
  # ...
  "use_account_default_credentials": True
  # ...
}

client = GoogleAdsClient.load_from_dict(configuration)

    環境変数を使用している場合は、bash 構成または環境に次を追加します。

    export GOOGLE_ADS_USE_ACCOUNT_DEFAULT_CREDENTIALS=true

    次に、load_from_env メソッドを呼び出します。

    from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_env()

OAuth トークンを直接処理する場合

  1. 手順に沿ってコンソール プロジェクトを設定し、プロジェクトのクライアント ID とクライアント シークレットを含む JSON ファイルをダウンロードします。

  2. Python クライアント ライブラリのクローンをマシンに作成し、そのディレクトリに移動します。

    $ git clone https://github.com/googleads/google-ads-python.git
$ cd google-ads-python

  3. 例を実行します。手順 1 でダウンロードした JSON ファイルの絶対パスを指定します。

    $ python examples/authentication/generate_user_credentials.py -c PATH_TO_CREDENTIALS_JSON

    完了すると、更新トークンがコンソールに出力されます。コピーして、次のステップのために保存します。

  4. 次の設定を任意の構成に追加して、ライブラリを構成します。

    google-ads.yaml または YAML 文字列に次の構成を追加します。

    client_id: INSERT_OAUTH2_CLIENT_ID_HERE
client_secret: INSERT_OAUTH2_CLIENT_SECRET_HERE
refresh_token: INSERT_REFRESH_TOKEN_HERE

    次に、load_from_storage メソッドまたは load_from_string メソッドを呼び出します。

    from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage()

    dict を使用してライブラリを構成する場合は、次の Key-Value ペアを含めて load_from_dict メソッドを呼び出します。

    from google.ads.googleads.client import GoogleAdsClient

configuration = {
  # ...
  "client_id": INSERT_OAUTH2_CLIENT_ID_HERE
  "client_secret": INSERT_OAUTH2_CLIENT_SECRET_HERE
  "refresh_token": INSERT_REFRESH_TOKEN_HERE
  # ...
}

client = GoogleAdsClient.load_from_dict(configuration)

    環境変数を使用している場合は、bash 構成または環境に次を追加します。

    export GOOGLE_ADS_CLIENT_ID=INSERT_OAUTH2_CLIENT_ID_HERE
export GOOGLE_ADS_CLIENT_SECRET=INSERT_OAUTH2_CLIENT_SECRET_HERE
export GOOGLE_ADS_REFRESH_TOKEN=INSERT_REFRESH_TOKEN_HERE

    次に、load_from_env メソッドを呼び出します。

    from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_env()

詳細については、シングル ユーザー認証のワークフロー ガイドを参照してください。

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

アプリでユーザーがログインし、アプリがユーザーの代わりに Google 広告アカウントを管理することを承認できるようにする場合は、このワークフローをおすすめします。アプリは OAuth 2.0 ユーザー認証情報をビルドして管理します。ライブラリは、ユーザーの認証情報を使用して次のように初期化できます。これは、アプリケーションが実行時に認証フローを実行するか、データストアから認証情報を読み込んで認証情報を取得することを前提としています。

dict は、実行時に認証情報を取得する際に使用する最も簡単な構成メカニズムです。

from google.ads.googleads.client import GoogleAdsClient

configuration = {
  # ...
  "client_id": client_id
  "client_secret": client_secret
  "refresh_token": refresh_token
  # ...
}

client = GoogleAdsClient.load_from_dict(configuration)

詳しくは、マルチユーザー認証のワークフロー ガイドを参照してください。

手動認証

任意の方法で認証情報を作成し、クライアント クラスを直接インスタンス化して、GoogleAdsClient に手動で提供できます。作成する認証情報オブジェクトが google.auth.credentials.Credentials のインスタンスであると仮定すると、次のように渡すことができます。

from google.ads.googleads.client import GoogleAdsClient
from google.auth import default

# This line retrieves ADCs from the environment. You can use any authentication
# approach as long as the `credentials` variable is an instance of
# `google.auth.credentials.Credentials`
credentials = default(scopes=["https://www.googleapis.com/auth/adwords"])

client = GoogleAdsClient(
  credentials=credentials,
  # ... insert remaining parameters
)

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

ユーザーがアカウントに直接アクセスするか、Google 広告クライアント センター（MCC）アカウントを介して、複数の Google 広告アカウントを管理することは一般的です。Python クライアント ライブラリには、このようなケースを処理する方法を示す次のコード例が用意されています。

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