設定

Python クライアント ライブラリは、YAML ファイル、環境変数、YAML 文字列、または dict を使用して構成できます。

認証構成

Google Ads API へのアクセスに必要な OAuth 認証情報を管理する方法は複数あります。選択するアプローチによって、使用する構成フィールドが異なります。詳細については、認証ガイドをご覧ください。

YAML ファイルを使用した構成

クライアントの初期化時に使用する YAML ファイルを指定できます。このファイルには、Google Ads API にリクエストを行うために必要な情報が含まれています。このファイルは、load_from_storage メソッドを使用してクライアントが初期化されるときにアクセスされます。このファイルを生成する最も簡単な方法は、GitHub リポジトリから google-ads.yamlの例をコピーし、更新トークン、クライアント ID、クライアント シークレットなどの認証情報を含めるように変更することです。

パスを指定しない場合、ライブラリは $HOME ディレクトリでファイルを探します。

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage()

google-ads.yaml ファイルの場所を指定するには、呼び出すときにパスを文字列としてメソッドに渡します。

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage("path/to/google-ads.yaml")

特定の環境変数を定義してパスを指定することもできます。

import os
from google.ads.googleads.client import GoogleAdsClient

os.environ["GOOGLE_ADS_CONFIGURATION_FILE_PATH"] = "path/to/google-ads.yaml"
client = GoogleAdsClient.load_from_storage()

両方の値が指定されている場合（パスがメソッドに渡され、環境変数が存在する場合）、ライブラリはメソッドに渡されたパスを優先します。

環境変数を使用した構成

クライアントの load_from_env メソッドを使用すると、すべてのクライアント構成を環境変数として保存できます。環境変数は、google-ads.yaml ファイルで定義されているものと同じ名前である必要がありますが、すべて大文字で、GOOGLE_ADS_ 名前空間が接頭辞として付いている必要があります。たとえば、client_id は GOOGLE_ADS_CLIENT_ID として保存する必要があります。

環境変数は通常、$HOME ディレクトリにある .bashrc ファイルや .bash_profile ファイルなどの bash 構成ファイルで定義されます。コマンドラインを使用して定義することもできます。

ターミナルで .bashrc ファイルを使用して環境変数を定義する基本的な手順は次のとおりです。

# Append the line "export GOOGLE_ADS_CLIENT_ID=1234567890" to
# the bottom of your .bashrc file.
echo "export GOOGLE_ADS_CLIENT_ID=1234567890" >> ~/.bashrc
# Update your bash environment to use the most recently updated
# version of your .bashrc file.
source ~/.bashrc

環境変数は、コマンドラインからターミナル インスタンスに直接設定することもできます。

export GOOGLE_ADS_CLIENT_ID=1234567890
echo $GOOGLE_ADS_CLIENT_ID

load_from_env メソッドは、Python の組み込み os モジュールの environ 属性から構成データを読み込みます。例: os.environ["GOOGLE_ADS_CLIENT_ID"]

環境変数の構成を使用してクライアント インスタンスを初期化する方法の例を次に示します。

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_env()

環境変数を介して logging を構成するには、構成 値が、サンプル google-ads.yaml 構成ファイルの YAML キーの構造と一致する JSON オブジェクトである必要があります。

.bashrc ファイルを使用して設定する方法の例を次に示します。

export GOOGLE_ADS_LOGGING='{
  "version": 1,
  "disable_existing_loggers": false,
  "formatters": {
    "default_fmt": {
      "format": "[%(asctime)s - %(levelname)s] %(message).5000s",
      "datefmt": "%Y-%m-%d %H:%M:%S"
    }
  },
  "handlers": {
    "default_handler": {
      "class": "logging.StreamHandler",
      "formatter": "default_fmt"
    }
  },
  "loggers": {
    "": {
      "handlers": ["default_handler"],
      "level": "INFO"
    }
  }
}'

重要な点: load_from_env メソッドが呼び出されたときに環境変数 GOOGLE_ADS_CONFIGURATION_FILE_PATH が設定されている場合、構成値は、前述の環境変数ではなく、指定されたパスにある google-ads.yaml ファイルから取得されます。

YAML 文字列を使用した構成

YAML ファイルをメモリに読み込んだ場合は、初期化時にクライアントに直接提供できます。これを行うには、load_from_string メソッドを使用します。

from google.ads.googleads.client import GoogleAdsClient

with open("/path/to/yaml", "r", encoding="utf-8") as handle:
    yaml_content = handle.read()

client = GoogleAdsClient.load_from_string(yaml_content)

dict を使用した構成

dict を load_from_dict メソッドに直接渡すことができます。例:

from google.ads.googleads.client import GoogleAdsClient

credentials = {
    "refresh_token": "YOUR_REFRESH_TOKEN",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "use_proto_plus": True,
}

client = GoogleAdsClient.load_from_dict(credentials)

構成フィールド

クライアント ライブラリの構成では、次のフィールドがサポートされています。

認証

使用する認証アプローチに応じて、次のフィールド グループのいずれかのみを使用します。

  • アプリケーションのデフォルト認証情報を使用したシングルユーザー（ドキュメント）
    • use_application_default_credentials: ライブラリが認証にアプリケーションのデフォルト認証情報（ADC）を使用するかどうか（google-ads v28.3.0 以降でサポートされています）。
  • OAuth トークンを使用したシングルユーザー（ドキュメント）
    • client_id: OAuth クライアント ID。
    • client_secret: OAuth クライアント シークレット。
    • refresh_token: OAuth 更新トークン。
  • サービス アカウント（ドキュメント）
    • json_key_file_path: ローカル秘密鍵ファイルへのパス。これは、サービス アカウントを使用した認証に使用されます。
    • impersonated_email: Google Workspace ドメイン全体の委任を使用する場合に権限を借用するアカウントのメールアドレス（省略可）。

ライブラリの動作

これらのフィールドは、ライブラリの動作を決定します。

リクエスト レベルの構成

環境変数

環境変数を使用してライブラリを構成するには、次のものを使用します。

  • GOOGLE_ADS_ADS_ASSISTANT
  • GOOGLE_ADS_CLIENT_ID
  • GOOGLE_ADS_CLIENT_SECRET
  • GOOGLE_ADS_CONFIGURATION_FILE_PATH
  • GOOGLE_ADS_ENDPOINT
  • GOOGLE_ADS_HTTP_PROXY
  • GOOGLE_ADS_IMPERSONATED_EMAIL
  • GOOGLE_ADS_JSON_KEY_FILE_PATH
  • GOOGLE_ADS_LINKED_CUSTOMER_ID
  • GOOGLE_ADS_LOGIN_CUSTOMER_ID
  • GOOGLE_ADS_LOGGING
  • GOOGLE_ADS_REFRESH_TOKEN
  • GOOGLE_ADS_USE_PROTO_PLUS
  • GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS （v28.3.0 以降でサポートされています）

ログの構成

ログフィールド（logging 構成フィールドの下にあるフィールド）は、ライブラリが logging 名前空間のすべてのフィールドを logging.config.dictConfig メソッドに直接渡すため、logging.config 組み込みモジュールから直接派生します。詳細については、 ロギング ガイドをご覧ください。

  • version: スキーマ バージョンを表す整数値。
  • disable_existing_loggers: アプリケーションの他の場所で構成されたロガーを無効にするかどうか。
  • formatters: さまざまな種類のフォーマッタを定義するディクショナリ。
  • handlers: さまざまなハンドラを定義するディクショナリ。ログの書き込み先と使用するフォーマッタを制御します。
  • loggers: ハンドラとログレベルを含む、さまざまな種類のロガーを定義するディクショナリ。