認証と承認

他の 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 ファイルのパスを設定します（ドメイン全体の委任を使用している場合は、必要に応じて impersonated_email を追加します）。

    json_key_file_path: JSON_KEY_FILE_PATH
# Optional: only set if using Google Workspace domain-wide delegation:
# impersonated_email: IMPERSONATED_EMAIL

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

    from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage()

  • dict を使用してライブラリを構成する場合は、次の Key-Value ペアを含め、load_from_dict メソッドを呼び出し、 構成 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 または未設定で、OAuth ユーザー認証鍵（client_id、client_secret、refresh_token）が未設定またはコメントアウトされている場合、ライブラリはサービス アカウント フローを使用して自動的に承認します。

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

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

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

  1. Google Ads 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_application_default_credentials": True,
    # ...
}

client = GoogleAdsClient.load_from_dict(configuration)

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

    export GOOGLE_ADS_USE_APPLICATION_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,
    use_proto_plus=True,
)

複数のアカウントを管理する

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

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