Google Ads API ご利用ガイド

このガイドでは、Google Ads API のオンボーディング、認証、最初の呼び出しを行うためのエンドツーエンドのプロセスについて詳しく説明します。

1. 前提条件とアカウント階層

Google Ads API を操作する前に、アカウント階層を理解し、正しい最上位アカウント構造を確立する必要があります。

  • クライアント センター（MCC）アカウント: Google 広告クライアント センター（MCC）アカウント（旧称クライアント センター）は、複数のクライアント アカウントを表示して管理するために使用されるメイン アカウントです。Google Ads API 開発者トークンを申請するには、MCC アカウントが必要です。
  • クライアント アカウント: キャンペーン、広告グループ、広告が作成され、請求が構成される標準アカウント。

アクション アイテム: MCC アカウントをお持ちでない場合は、 Google 広告クライアント センター（MCC）アカウントで作成してください。

2. 開発者トークンを取得する

開発者トークンは、Google Ads API に対してアプリケーションを一意に識別し、呼び出し量のアクセス階層を制御します。

お申し込み手順

  1. Google 広告 MCC アカウント にログインします。
  2. [ツールと設定] > [設定] > [API センター] （または [管理] > [API センター] ）に移動します。
  3. デベロッパーの詳細フォームに記入し、API 利用規約に同意します。
  4. フォームを送信します。

アクセスレベル

  • 承認待ち: 新しく作成されたトークンは、すぐに [保留中] ステータスになります。保留中のトークンを使用してすぐにテスト アカウント に接続できますが、本番環境アカウントでは機能しません。
  • 基本アクセス: 承認されると、1 日あたり最大 15,000 回の API オペレーションが許可されます。
  • 標準アクセス: 最低限必要な機能（RMF）を満たすアプリケーションの場合、1 日あたりの API オペレーション数は無制限です。

3. テスト アカウントを設定する

本番環境アカウントに対して開発とテストを行うと、不要な広告費用が発生したり、キャンペーンが変更されたりするリスクがあります。テスト アカウントに対してすべてのアクティブな開発を行うことを強くおすすめします。

テスト用の MCC アカウントを作成する

  1. Google 広告テスト用 MCC アカウントの作成ページに移動します。
  2. 本番環境の Google 広告 MCC アカウントにまだリンクされていない Google アカウントでログインします。
  3. わかりやすいアカウント名（例: MyCompany Test MCC）を入力します。
  4. 主な用途として [他のユーザーのアカウントを管理する] を選択します。
  5. 請求先住所の国、タイムゾーン、通貨を選択します。[保存して次へ] をクリックします。

テスト用のクライアント アカウントを作成する

テスト用の MCC アカウントを作成したら、テスト キャンペーンを実行するために、少なくとも 1 つの子クライアント アカウントを作成する必要があります。

  1. 新しく作成したテスト用の MCC アカウント にログインします。
  2. 左側のナビゲーション メニューで [アカウント] をクリックし、 [サブアカウントの設定]（または [パフォーマンス]）を選択します。
  3. 青色の [+]（プラス）ボタンをクリックし、[新しいアカウントを作成] を選択します。
  4. [Google 広告アカウント] を選択します。
  5. アカウント名（例: Test Client Account A）を入力します。
  6. タイムゾーンと通貨を選択し、[保存して次へ] をクリックします。
  7. この新しいクライアント アカウントの 10 桁のお客様 ID （例: 1234567890、ハイフンなし）をメモします。

テスト アカウントに関する重要なルール

  • 開発者トークンの使用: テスト用の MCC アカウントから開発者トークンを申請しないでください。必ず本番環境の MCC アカウント の保留中または承認済みの開発者トークンを使用してください。
  • 請求: テスト アカウントでは実際の広告は配信されないため、実際の請求先情報を入力する必要はありません。

4. Google Cloud プロジェクトのセットアップ

すべての API リクエストは、Google Ads API が有効になっている Google Cloud プロジェクトを使用して認証する必要があります。

API を有効にする手順

  1. Google Cloud コンソールに移動します。
  2. 新しいプロジェクトを作成するか、既存のプロジェクトを選択します。
  3. [API とサービス] > [ライブラリ] に移動します。
  4. [Google Ads API] を検索し、[有効にする] をクリックします。

料金と課金

  • API 料金なし: Google Cloud プロジェクトの作成、Google Ads API の有効化、OAuth 2.0 認証情報の生成は無料 です。Google は、Google Ads API の呼び出しや使用に対して料金を請求しません。
  • その他のクラウド リソース: アプリケーションのホストや広告データの保存に、無料枠を超えて他の有料の Google Cloud サービス（Compute Engine、Cloud Run、BigQuery など）を積極的に使用する場合にのみ、Google Cloud の料金が発生します。

5. OAuth 2.0 認証の構成

Google Ads API は、OAuth 2.0 を使用してリクエストを認証および認可します。

デスクトップ アプリケーション フローの手順

  1. Google Cloud プロジェクトで、[API とサービス] > [OAuth 同意画面] に移動し、同意画面を構成します。アプリがテスト ステータスのときに、[テストユーザー] セクションにメールアドレスを追加して、認可時のアクセス エラーを防ぎます。
  2. [API とサービス] > [認証情報] に移動します。
  3. [認証情報を作成] > [OAuth クライアント ID] をクリックします。
  4. アプリケーションの種類として [デスクトップ アプリ] を選択します。
  5. [作成] をクリックし、OAuth 認証情報ファイルを client_secret.json としてダウンロードします（または、Client ID と Client Secret をコピーします）。

更新トークンを生成する

クライアント ID とクライアント シークレットを取得したら、更新トークンを生成する必要があります。これを行うには、Google OAuth 2.0 Playground またはクライアント ライブラリ スクリプトを使用します。

方法 A: Google OAuth 2.0 Playground を使用する

  1. Google OAuth 2.0 Playground に移動します。
  2. 右上隅にある歯車アイコン（OAuth 2.0 の設定） をクリックします。
  3. [Use your own OAuth credentials] のチェックボックスをオンにします。
  4. OAuth2 の Client ID と Client Secret を入力し、[閉じる] をクリックします。
  5. 左側の [ステップ 1（API を選択して認可する）] で、[Input your own scopes] フィールドに Google Ads API スコープを入力します: https://www.googleapis.com/auth/adwords
  6. [Authorize APIs] をクリックします。メッセージが表示されたら、Google 広告 MCC アカウント（またはテスト アカウント）にアクセスできる Google アカウントでログインします。
  7. 同意画面で [続行] をクリックします。
  8. [ステップ 2（トークンの認証コードを交換する）] で、青色の [Exchange authorization code for tokens] ボタンをクリックします。
  9. Refresh token と Access token がレスポンス パネルに表示されます。Refresh token をコピーして保存します。

方法 B: クライアント ライブラリ スクリプトを使用する（Python の例）

公式の Python クライアント ライブラリには、認証情報を生成するためのヘルパー スクリプトが組み込まれています。または、Google Cloud コンソールから client_secret.json をダウンロードして、次のスタンドアロン Python スクリプトを実行することもできます。

  1. 必要な OAuth ライブラリをインストールします。
pip install google-auth-oauthlib
  1. client_secret.json と同じディレクトリに generate_refresh_token.py という名前のスクリプトを作成して実行します。
from google_auth_oauthlib.flow import InstalledAppFlow

CLIENT_SECRETS_FILE = "client_secret.json"
SCOPES = ["https://www.googleapis.com/auth/adwords"]

def main():
    flow = InstalledAppFlow.from_client_secrets_file(
        CLIENT_SECRETS_FILE, SCOPES
    )
    credentials = flow.run_local_server(port=0)
    
    print("\nAuthorization Successful!\n")
    print(f"Refresh Token: {credentials.refresh_token}")

if __name__ == "__main__":
    main()

6. クライアント ライブラリと認証情報の設定

Google は、gRPC エンドポイントとの認証、シリアル化、通信を処理する、公式にサポートされているクライアント ライブラリを提供しています。

サポートされている言語

  • Python: pip install google-ads
  • Java: Maven または Gradle で利用可能
  • PHP: composer require googleads/google-ads-php
  • .NET: Install-Package Google.Ads.GoogleAds
  • Ruby: gem install google-ads-googleads
  • Perl: cpanm Google::Ads::GoogleAds::Client

構成ファイル（google-ads.yaml）

認証情報を含む構成ファイルを作成します。デフォルトでは、クライアント ライブラリの初期化メソッド（GoogleAdsClient.load_from_storage() など）は、次の 2 つの場所で google-ads.yaml を自動的に検索します。

  1. スクリプトが実行される現在の作業ディレクトリ 。
  2. ユーザーのホーム ディレクトリ （Linux/macOS の場合は ~、Windows の場合は %HOMEPATH%）。

ファイルをカスタムの場所に保存する場合は、初期化メソッドにパスを明示的に渡すことができます（例: load_from_storage("path/to/google-ads.yaml")）。

developer_token: "INSERT_YOUR_DEVELOPER_TOKEN_HERE"
client_id: "INSERT_YOUR_OAUTH2_CLIENT_ID_HERE"
client_secret: "INSERT_YOUR_OAUTH2_CLIENT_SECRET_HERE"
refresh_token: "INSERT_YOUR_OAUTH2_REFRESH_TOKEN_HERE"
login_customer_id: "INSERT_YOUR_MANAGER_ACCOUNT_ID_HERE"

7. 最初の API 呼び出しを実行する

オンボーディングの設定を確認するには、クイックスタート スクリプトを実行して、テスト アカウントから既存のキャンペーンを取得します。

Python スクリプトの例（quickstart.py）

import sys
from google.ads.googleads.client import GoogleAdsClient
from google.ads.googleads.errors import GoogleAdsException

def main(client, customer_id):
    ga_service = client.get_service("GoogleAdsService")
    query = """
        SELECT
          campaign.id,
          campaign.name
        FROM campaign
        ORDER BY campaign.id
    """
    
    # Issues a search request
    stream = ga_service.search_stream(customer_id=customer_id, query=query)
    for batch in stream:
        for row in batch.results:
            print(
                f"Campaign with ID {row.campaign.id} and name "
                f"'{row.campaign.name}' was found."
            )

if __name__ == "__main__":
    # Initialize client from google-ads.yaml
    # By default, load_from_storage() searches for 'google-ads.yaml' in the
    # current working directory or the user's home directory (~). You can
    # also pass an explicit path: load_from_storage("path/to/google-ads.yaml")
    try:
        googleads_client = GoogleAdsClient.load_from_storage()
        # Replace with your test client account ID (without hyphens) from
        # Section 3, NOT your manager account ID (which belongs in
        # google-ads.yaml).
        test_customer_id = "1234567890" 
        main(googleads_client, test_customer_id)
    except GoogleAdsException as ex:
        print(
            f"Request failed with status {ex.error.code().name} and "
            f"includes the following errors:"
        )
        for error in ex.failure.errors:
            print(f"\tError with message '{error.message}'.")
            if error.location:
                for field_path_element in error.location.field_path_elements:
                    print(f"\t\tOn field: {field_path_element.field_name}")
        sys.exit(1)

8. ベスト プラクティスとリソース

  • ロギング: クライアント ライブラリで詳細なロギングを有効にして、リクエスト ID とレスポンス ID（request-id）をキャプチャします。これは、Google にサポートをリクエストする際に不可欠です。
  • エラー処理: GoogleAdsException の堅牢なエラー処理を実装します。具体的には、レート制限（RESOURCE_TEMPORARILY_EXHAUSTED）を管理します。
  • 公式ドキュメント: Google Ads API デベロッパー ドキュメント
  • クライアント ライブラリとコードサンプル: GitHub Google Ads リポジトリ
前へ
はじめに
次へ
クイックスタート