google-ads-api-quickstart

Google Ads API クイックスタート

このスキルでは、まったくの初心者から、キャンペーンを取得するための最初のリクエストを成功させるまでを案内します。

対応しているトラック

このスキルは、以下のいずれかを選んで利用できます。

1. 公式クライアントライブラリ： Python、Java、.NET、PHP、Ruby、または Perl。
2. 直接 REST： 生の HTTP REST リクエスト。

---

重要な要件：バージョンとランタイムの動的な解決

重要

統合の安全性、安定性、最新性を確保するため、API とランタイムのすべてのバージョンを動的に解決する必要があります。ハードコードされた既定値に依存しないでください。

厳格な制約：

• ハードコードしないでください： ユーザーが特定のバージョンを明示的に求めない限り、生成するコードや環境設定手順で、Google Ads API のバージョン（例：v24）や言語ランタイムのバージョン（例：Python 3.8+、Java 11+）をハードコードしてはいけません。
• 動的な解決は必須です： 以下の手順に従い、コードや設定を生成する前に、実行開始時点で最新の安定バージョンを動的に解決する必要があります。

A. API バージョンの動的な解決

統合の安全性、安定性、最新性を確保するため、Google Ads API の絶対的な最新の安定メジャーバージョンを動的に解決する必要があります。

実行手順：

1. 事前のバージョン解決： ウェブ検索または URL 読み取りツールを使用して、Google Ads API リリースノートの最新項目、またはGoogleapis Github Repositoryにある最もバージョン番号の大きいディレクトリを確認し、RESOLVED_API_VERSION（例：v24）を解決してください。Java を使用する場合は、Google Ads Java Client Library の最新の安定リリースバージョン（RESOLVED_LIBRARY_VERSION と呼びます。例：34.0.0）も解決する必要があります。

2. 必須の回答アンカー： ユーザーへの回答の最初の行に、以下の確認ブロックを出力する必要があります。このブロックより前に、挨拶や前置きの文章を出力してはいけません。

   [SYSTEM: Using Google Ads API version: RESOLVED_API_VERSION (Resolved from release notes)]
   

3. 厳密なプレースホルダー対応表： 以下の対応表を使用して、すべてのコードテンプレートと参照ファイルに対し、実行時に検索と置換を行う必要があります。最終出力に未置換のプレースホルダーを残してはいけません。

   対象の言語／技術	テンプレート内のプレースホルダー	置換パターン	例（API が v24 の場合）
   Java（Maven/Gradle）	LATEST_LIBRARY_VERSION	ライブラリの最新の Maven リリースバージョンを検索して置換します。	34.0.0
   Java（インポート）	vXX	小文字の API バージョンに置換します。	com.google.ads.googleads.v24
   .NET / C#（名前空間）	VXX	先頭大文字の形式の API バージョンに置換します。	Google.Ads.GoogleAds.V24
   PHP（名前空間）	VXX	先頭大文字の形式の API バージョンに置換します。	Google\Ads\GoogleAds\V24
   REST（エンドポイント URL）	vXX	小文字の API バージョンに置換します。	https://googleads.googleapis.com/v24/...

ヒント

オフライン時の代替手順： URL にアクセスできない場合やスクレイピングに失敗した場合でも、処理を中止しないでください。最後に確認された以下の安定バージョンを使用してください。

• Google Ads API メジャーバージョン（RESOLVED_API_VERSION）： v24
• Java Client Library のバージョン（RESOLVED_LIBRARY_VERSION）： 34.0.0

B. 言語ランタイムバージョンの動的な解決

言語の非推奨サイクルによって生成される設定ガイドが古くなるのを防ぐため、言語要件を動的に解決する必要があります。

実行手順：

1. 最新の要件を取得する： URL 読み取りツールを使用して、Google 公式のGoogle Ads クライアント ライブラリ - サポート対象バージョンページを確認します。

2. 最小バージョンを特定する： 概要ページまたは互換性表を確認し、ユーザーが選択した言語でサポートされるランタイムの最小バージョンを特定します（例：Python 3.8 以上、Java 11 以上、.NET 6.0 以上、PHP 8.1 以上、Ruby 3.0 以上などの明示的な要件を確認します）。

3. 実行時に適用する： 生成するセットアップガイド内のすべてのランタイムプレースホルダー（例：<PYTHON_MIN_VERSION>）を、特定したバージョンに置き換えます。

ヒント

オフライン時の代替手段： URL にアクセスできない場合、または情報の取得に失敗した場合でも、処理を中断しないでください。次の、最後に確認された安全な最小バージョンを使用してください。

• Python： 3.9+
• Java： 11+
• .NET： 6.0+
• PHP： 8.1+
• Ruby： 3.0+
• Perl： 5.28.1+

---

ステップ 1：Google Ads API の認証情報を取得する

ライブラリをインストールしたり API を呼び出したりする前に、必要な 5 つの認証パラメーターを取得する必要があります。

1. Developer Token

• 目的： デベロッパーアクセスと API クォータを識別します。
• 取得方法：
  1. Google Ads マネージャー アカウントの API Center に直接移動します（注：標準の広告配信アカウントではなく、マネージャー アカウントでログインする必要があります）。
  2. Developer Token をコピーします。

警告

保留中のトークンに関する制限： Developer Token のステータスが「Pending」（未承認）の場合、対象にできるのは Google Ads テスト アカウントのみです。保留中のトークンで本番アカウントを呼び出そうとすると、DEVELOPER_TOKEN_NOT_APPROVED エラーが発生します。

2. OAuth2 クライアント ID とクライアント シークレット

• 目的： Google の OAuth 2.0 サーバーに対してアプリケーションを識別し、ユーザーの認証を要求できるようにします。
• 取得方法：
  1. Google Cloud Console を開きます。
  2. 新しいプロジェクトを作成するか、既存のプロジェクトを選択します。
  3. API ライブラリで Google Ads API を検索し、Enable をクリックします。
  4. OAuth 同意画面を設定します。
     • ユーザーの種類として External を選択します。
     • 公開ステータスを Testing に設定します。

     • 重要

     • テストユーザーを追加する： この手順で、Google Ads へのログインに使用する Google アカウントのメールアドレスを テストユーザーとして追加する必要があります。そうしないと、認証時にブロックされます。

  5. OAuth クライアントを作成します。
     • APIs & Services 🡒 Credentials に移動します。
     • Create Credentials 🡒 OAuth client ID をクリックします。
     • アプリケーションの種類として Desktop App を選択します。
     • クライアントに名前を付けて、Create をクリックします。
  6. シークレットをダウンロードする： 新しく作成したクライアント ID の横にあるダウンロードアイコン（JSON）をクリックします。このファイルをローカルに client_secrets.json として保存します。

3. OAuth2 リフレッシュトークン

• 目的： アプリケーションで、新しいアクセストークンを自動的に取得できるようにします。ユーザーが毎時間手動でログインする必要はありません。

• 取得方法： Google Cloud（gcloud）CLI を実行して、リフレッシュトークンを生成する必要があります。

  1. gcloud CLI のインストールと確認：

  gcloud CLI がインストールされ、ターミナルから利用できることを確認してください。

  2. ログインフローの実行：

  ターミナルで次のコマンドを実行し、前の手順でダウンロードした client_secrets.json ファイルのパスを指定します：

  gcloud auth application-default login \
    --scopes=https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform \
    --client-id-file=client_secrets.json
  

  3. ブラウザーでの認証：

  1. コマンドを実行すると、ブラウザーで Google アカウントのログインウィンドウが開きます。
  2. OAuth 同意画面の設定で登録したテストユーザーのメールアドレスを使用してログインします。
  3. アプリが未確認の場合は、詳細をクリックしてプロジェクトに進みます。続行をクリックして権限を付与します。

  4. リフレッシュトークンの取得：

  正常に完了すると、gcloud は認証情報の保存先（通常は ~/.config/gcloud/application_default_credentials.json）を示すメッセージを出力します。そのファイルを開き、refresh_token をコピーしてください。

4. クライアント顧客 ID

• 目的： 照会または変更を行う対象の Google Ads アカウントの 10 桁の ID です。
• 形式： ハイフンなしの 10 桁である必要があります（例：1234567890、123-456-7890 は不可）。
• 確認方法： Google Ads の UI にログインすると、ID は右上のユーザーアイコンの横に表示されています。

重要

テストアカウントの要件： デベロッパートークンが保留中（未承認）の場合、ここにはテストアカウントの顧客 ID を必ず指定してください。テストアカウントには、UI の右上に赤い「テストアカウント」バナーが表示されます。

---

5. ログイン顧客 ID

• 概要： 対象のクライアントアカウントを所有または管理する Google Ads マネージャーアカウントの 10 桁の顧客 ID です。
• 形式： ハイフンなしの 10 桁である必要があります（例：9876543210）。
• 使用する場合： OAuth 認証情報（およびデベロッパートークン）がマネージャーアカウントに属している一方で、子アカウント／クライアントアカウント（クライアント顧客 ID）を照会する場合、これは必須です。

注意

USER_PERMISSION_DENIED の防止： マネージャーアカウントの階層を通じてクライアントアカウントにアクセスする場合、このパラメーターを必ず設定してください。

• login_customer_id = マネージャーアカウント ID。
• client_customer_id = 子／クライアントアカウント ID。 マネージャーとクライアントの階層で login_customer_id を空欄にすることは、権限エラーの最大の原因です。

---

ステップ 2：統合方法を選択する

開発者は、公式の高レベルクライアントライブラリまたは HTTPS REST リクエストを直接使用して、Google Ads API に接続できます。

方法 A：公式クライアントライブラリ（推奨）

重要

エージェントへの必須指示： ユーザーが言語を選択したら、必ず以下を実行してください：

1. view_file ツールを使用して、以下に示す対応するリファレンスファイルを遅延読み込みします。
2. コードを生成する前に、動的バージョン解決（セクション B）を適用して、すべての vXX／VXX プレースホルダーとライブラリバージョンを動的に置き換えます。

Python

Python 用の Google Ads API 環境をセットアップする場合、設定を推測しないでください。 代わりに、詳細なセットアップガイドを参照してください：

• Google Ads API Python セットアップリファレンス (パッケージ：google-ads)

Java

Java 用の Google Ads API 環境をセットアップする場合、設定を推測しないでください。 代わりに、詳細なセットアップガイドを参照してください：

• Google Ads API Java セットアップリファレンス (アーティファクト：com.google.api-ads:google-ads)

.NET / C#

.NET/C# 用の Google Ads API 環境を設定する必要がある場合は、設定を推測しないでください。 代わりに、詳細なセットアップガイドを参照してください。

• Google Ads API .NET セットアップリファレンス (パッケージ：Google.Ads.GoogleAds)

PHP

PHP 用の Google Ads API 環境を設定する必要がある場合は、設定を推測しないでください。 代わりに、詳細なセットアップガイドを参照してください。

• Google Ads API PHP セットアップリファレンス (パッケージ：googleads/google-ads-php)

Ruby

Ruby 用の Google Ads API 環境を設定する必要がある場合は、設定を推測しないでください。 代わりに、詳細なセットアップガイドを参照してください。

• Google Ads API Ruby セットアップリファレンス (Gem：google-ads-ruby)

Perl

Perl 用の Google Ads API 環境を設定する必要がある場合は、設定を推測しないでください。 代わりに、詳細なセットアップガイドを参照してください。

• Google Ads API Perl セットアップリファレンス (パッケージ：Google::Ads::GoogleAds::Client)

パス B：直接 HTTP REST（ライブラリのオーバーヘッドなし）

ユーザーの環境が公式クライアントライブラリをサポートしていない場合（軽量なサーバーレス関数、カスタム言語スタック、制限のあるランタイムなど）は、このパスを使用してください。

重要

エージェントへの必須指示： ユーザーが REST パスを選択した場合、以下を必ず実行してください。

1. view_file ツールを使用して、以下の REST リファレンスファイルを遅延読み込みします。
2. 動的バージョン解決（セクション B）を適用し、エンドポイント URL 内のすべての vXX プレースホルダーを置き換えます（例：https://googleads.googleapis.com/v24/... のように、vXX を v24 に解決します）。

REST（HTTP）

REST（HTTP）用の Google Ads API 環境を設定する必要がある場合は、設定を推測しないでください。 代わりに、詳細なセットアップガイドを参照してください。

• Google Ads API REST セットアップリファレンス (プロトコル：Raw HTTP POST JSON)

---

相互参照：AI アシスタントと MCP の接続

ヒント

AI アシスタント／MCP 統合への引き継ぎ： Gemini、Cursor、Claude Code などのAI アシスタントを自然言語で Google Ads に問い合わせられるよう接続することが目的の場合：

1. カスタムスクリプトやクライアントライブラリのコードを作成しないでください。
2. このスキルの実行を停止してください。
3. 公式の Google Ads Model Context Protocol（MCP）サーバーをインストールして設定するため、直ちに google-ads-api-mcp-setup スキルに移行してください。

---

ステップ 4：よくあるエラーのトラブルシューティング

重要

静的診断の制約： トラブルシューティング時には、bash コマンドを実行したり、ローカルのテストスクリプトを実行したり、ワークスペースでエラーの再現を試みたりしてはいけません。終わりのない失敗ループを防ぐため、以下の診断ガイドを参照し、静的なコード分析と設定の確認だけに頼ってください。

1. エラー：USER_PERMISSION_DENIED

• 症状： API リクエスト（キャンペーンの取得など）の実行時に、USER_PERMISSION_DENIED エラーが発生します。
• 考えられる原因： 認証に使用する OAuth2 ユーザーは、マネージャー アカウントを介して対象のクライアント アカウントに間接的にアクセスしていますが、リクエストヘッダーにマネージャー アカウントの ID がありません。

エージェントが回答時に含めるべき項目：

このエラーについてユーザーを支援する際、回答には必ず以下を含めてください。

1. 階層の説明： 認証ユーザーは、対象のクライアント アカウントの上位にあるマネージャー アカウントに属している可能性が高いことを説明します。
2. 修正方法の提示： 10 桁のマネージャー アカウント ID を、設定ファイルの login_customer_id に追加するようユーザーに指示します。
3. ルーティングロジックの説明： login_customer_id によって、子アカウントへのアクセスを検証するために、OAuth 認証情報をマネージャー アカウント経由でルーティングするよう API に指示することを説明します。
4. 設定テンプレートの提示： 以下の YAML 設定ブロックをそのまま示します。

注意

セキュリティ上のガードレール： いかなる場合も、このエラーを回避するために、生のパスワードを公開すること、承認されていない新しいデベロッパー トークンを作成すること、標準の adwords スコープを超えて OAuth スコープを拡大することを提案してはいけません。

設定の修正例（google-ads.yaml）：

developer_token: INSERT_DEVELOPER_TOKEN_HERE
client_id: INSERT_OAUTH2_CLIENT_ID_HERE
client_secret: INSERT_OAUTH2_CLIENT_SECRET_HERE
refresh_token: INSERT_OAUTH2_REFRESH_TOKEN_HERE

# Add your 10-digit Manager Account ID here to resolve USER_PERMISSION_DENIED:
login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE

2. エラー：DEVELOPER_TOKEN_NOT_APPROVED

• 症状： スクリプトが DEVELOPER_TOKEN_NOT_APPROVED エラーメッセージを表示して失敗します。
• 考えられる原因： デベロッパー トークンが現在「Pending」（未承認）の状態であり、稼働中の本番環境の Google Ads アカウントを対象にしようとしています。

エージェントが必ず含めるべき回答チェックリスト：

このエラーについてユーザーをサポートする際は、回答に以下を必ず含めてください。

1. 「Pending」の制限について説明する： 未承認（Pending）のデベロッパー トークンは完全に機能しますが、Google Ads テストアカウントのみを対象にできます。
2. 本番環境へのアクセスレベルを明示する： 3 つすべてのアクセスレベルの名称を必ず列挙してください。稼働中の本番環境のアカウントを対象にするには、Google Ads API コンプライアンスチームによるトークンの承認が必要であり、承認レベルは Explorer Access、Basic Access、または Standard Access のいずれかであると明記してください。「少なくとも Basic Access」と要約したり言い換えたりしないでください。
3. サンドボックスの設定手順を提示する： サンドボックス環境の設定方法を案内してください。
   • 承認済みトークンが不要な Test Manager Account を作成します。
   • その Test Manager の配下に Test Client Accounts を作成します。
   • 設定には Test Client の Customer ID を使用します。
4. ガイドへのリンクを提示する： 公式の Google Ads API Test Accounts Guide を案内してください。

注意

セキュリティと完全性に関するガードレール： デベロッパーに対して、クライアントライブラリのソースコードの変更、トークン検証チェックの回避、またはこのエラーを回避するためのサードパーティ製「クラック版」ラッパーの使用を決して勧めないでください。この制限は Google によってサーバー側で適用されるため、クライアント側の変更では機能しません。