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 広告アカウントを管理できます。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 ペアを追加し、構成 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 であるか未設定で、OAuth ユーザー認証情報キー（client_id、client_secret、refresh_token）が未設定またはコメントアウトされている場合、ライブラリはサービスアカウントフローを使用して自動的に承認します。

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

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

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

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

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

gcloud CLI ツールを使用する場合（推奨）

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

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 トークンを直接処理する場合

手順に沿ってコンソールプロジェクトを設定し、プロジェクトのクライアント ID とクライアントシークレットを含む JSON ファイルをダウンロードします。
Python クライアントライブラリをマシンにクローンし、そのディレクトリに移動します。
```
git clone https://github.com/googleads/google-ads-python.git
cd google-ads-python
```
手順 1 でダウンロードした JSON ファイルの絶対パスを指定して、サンプルを実行します。
```
python examples/authentication/generate_user_credentials.py \
    -c PATH_TO_CREDENTIALS_JSON
```
完了すると、更新トークンがコンソールに出力されます。これをコピーして、次のステップのために保存します。

選択した構成に次の設定を追加して、ライブラリを構成します。

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

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

認証と承認 コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

Google 広告のアクセスモデルを理解する

OAuth ワークフロー

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

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

gcloud CLI ツールを使用する場合（推奨）

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

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

手動認証

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

認証と承認

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

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