本文へスキップ
キャスターアプリケーションズ

著者: 清家 那生

AI エージェントに Google Ads API・GA4 Data API・自社 DB を直接照会させる。広告データを横断分析する構成

人の問いを受けた AI エージェント (Claude Code) が、手順書と認証情報を読み、Google Ads API・GA4 Data API・Search Console API・Cloudflare D1・Clarity を照会して答えを突き合わせ、人が確かめる構成図

目次 8
  1. AI エージェントが 5 つの API をコマンドで直接照会する
  2. 認証はサービスアカウントにまとめ、事業ごとに鍵を分ける
  3. 突き合わせの鍵を先に決める
  4. スクリプトを作らず、手順書を AI に読ませる
  5. 実例: CVR 1% の広告の調査で投げた照会
  6. AI が API の応答を読み違えた 3 つの例と、防ぎ方
  7. 書き込みは人の承認を挟む
  8. ハマりどころ

想定読者は、広告やアクセス解析のデータを AI エージェントに分析させたいエンジニアです。経営判断の観点 (AI に横断させる前にそろえるものと、AI の答えの確かめ方) は記事「GA4 と広告のデータを AI で分析する方法」にまとめています。

「この広告はなぜ登録率が低いのか」に答えるには、Google 広告の検索語句、GA4 の滞在時間、自社 DB の実際の登録数を突き合わせる必要があります。管理画面を 3 つ開いて CSV を書き出し、スプレッドシートで結合するのは、問いが 1 つ増えるたびに同じ手間がかかります。

私たちが立ち上げから関わっている人材紹介会社では、AI エージェントにこれらの API を直接照会させています。問いを日本語で投げると、エージェントが Google Ads API の GAQL、GA4 Data API のレポート、自社 DB の SQL をその場で組み、結果を突き合わせて答えます。分析用のダッシュボードや集計スクリプトは作っていません。

この構成の肝は、AI そのものより、その周りの設計です。認証・突き合わせの鍵・手順書・人の確認を先に決めておけば、AI エージェントは広告データの横断分析を任せられる道具になります。 逆にここを決めないと、AI は API の応答をもっともらしく読み違えます。実際に起きた読み違えも含めて書きます。

AI エージェントが 5 つの API をコマンドで直接照会する

照会先は、Google 広告、GA4、Search Console、自社 DB (Cloudflare D1)、Microsoft Clarity の 5 つです。当社が使っている AI エージェントは Claude Code で、各 API を curl で叩きます。全体の流れは冒頭の図のとおりです。

データ源API分かること主な制約
Google 広告Google Ads API (googleAds:searchStream に GAQL)検索語句、費用、クリック、配信設定検索語句が分かるのは費用の一部だけ
GA4Analytics Data API (runReport)滞在時間、端末、スクロール、イベントトラッカーを止めた人の分が丸ごと欠ける
Search ConsoleSearch Console API (searchAnalytics/query)自然検索の語、表示回数、順位2〜3 日遅れ
自社 DBCloudflare D1 の REST (/d1/database/{id}/query)実際の登録数、クリック ID、流入元なし (サンプリングなしで数えられる)
ClarityData Export API (project-live-insights)デッドクリック、スクロール深度、JS エラー直近 1〜3 日分、1 日 10 回程度

この構成は、AI がコマンドを実行して API を呼べることが前提です。会話画面だけの ChatGPT では、自社の鍵を使って API を呼べません。OpenAI の Codex CLI や Google の Gemini CLI のように、コマンドを実行できる AI エージェントなら同じ考え方で組めます。

MCP サーバーは使っていません。データ源ごとにサーバーを入れると構成が重くなりますし、エージェントがコマンドで API を呼べるので、別に必要ありませんでした。

認証はサービスアカウントにまとめ、事業ごとに鍵を分ける

Google の 3 つの API (広告・GA4・Search Console) は、1 つのサービスアカウントの鍵で認証します。サービスアカウントには GCP 側のロールを一切付けず、権限は各サービスの側でユーザーとして追加します。

サービス権限の付け方スコープ
Google 広告広告アカウントの「アクセスとセキュリティ」に、サービスアカウントのメールを「標準」で直接追加https://www.googleapis.com/auth/adwords
GA4プロパティのアクセス管理に「閲覧者」で追加https://www.googleapis.com/auth/analytics.readonly
Search Console「ユーザーと権限」に追加https://www.googleapis.com/auth/webmasters.readonly

案件では、最初は個人の Google アカウントの refresh token で認証していました。2026 年 9 月にサービスアカウントへ移した理由は 2 つです。個人アカウントのパスワード変更などで CI が止まること。もう 1 つは、他のメンバーに鍵ファイル 1 つで同じ権限を渡せることです。

サービスアカウントは事業ごとに 1 つ作ります (ads-api-<事業名>)。鍵が届くのは、その事業の広告アカウントと GA4 プロパティだけです。複数の事業を同じ GCP プロジェクトで管理していても、ある事業の鍵で別の事業のデータは読めません。

access token は、鍵から JWT を作って発行します。依存パッケージの無い小さなスクリプトにしてあり、エージェントは照会の前にこれを呼びます。

import { createSign } from "node:crypto";

const now = Math.floor(Date.now() / 1000);
const b64url = (s) => Buffer.from(s).toString("base64url");
const header = b64url(JSON.stringify({ alg: "RS256", typ: "JWT" }));
const claims = b64url(JSON.stringify({
  iss: key.client_email, scope: scopes.join(" "),
  aud: "https://oauth2.googleapis.com/token", iat: now, exp: now + 3600,
}));
const sig = createSign("RSA-SHA256").update(`${header}.${claims}`).sign(key.private_key, "base64url");

const res = await fetch("https://oauth2.googleapis.com/token", {
  method: "POST",
  headers: { "content-type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({
    grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
    assertion: `${header}.${claims}.${sig}`,
  }),
});

Google Ads API で 2 つ詰まりやすい点があります。

  • login-customer-id に管理者アカウント (MCC) の ID を入れると弾かれる。 サービスアカウントを広告アカウントに直接追加した場合、MCC の ID をヘッダーに付けると USER_PERMISSION_DENIED が返ります。ヘッダーを付けないか、広告アカウント自身の ID を入れます。2026 年 10 月 24 日に当社の広告アカウントで実際に当たりました。
  • デベロッパートークンのヘッダーが無くても通る。 当社の環境では、2026 年 10 月時点で developer-token ヘッダー無しの照会が通っています。古い手順書を写すと付けたままになりますが、付けなくても動きます。

自社 DB (Cloudflare D1) は D1 に権限を絞った Cloudflare の API トークン、Clarity は管理画面で発行する期限付きのトークンで読みます。鍵とトークンはリポジトリ直下の .env.local と鍵ファイルに置き、どちらも Git の管理から外しています。

突き合わせの鍵を先に決める

AI に横断させる前に、データ源をどの値でつなぐかを決めておきます。ここが決まっていないと、AI は推測でつなぎます。

  • 行単位はクリック ID (gclid)。 自社 DB の登録に gclid が残っていれば、Google Ads API の click_view でキャンペーンとキーワードまで復元できます。ただし click_view は 1 日単位の日付指定が必須で、クリックから 90 日以内しか引けません。iOS で付く gbraid / wbraid は click_view では引けません。
  • 集計単位はキャンペーン ID と日付。 広告の着地 URL のサフィックスに ValueTrack の utm_campaign={campaignid} を入れておくと、自社 DB の utm_campaign 列だけでキャンペーンに結び付けられます。gbraid の層もこれで拾えます。
  • 獲得単価の分母は自社 DB の登録数にする。 広告と GA4 の成果の数は計測の欠落があるので、分母に使いません。実際の獲得単価は、Google Ads API の費用を自社 DB の登録数で割って出します。

スクリプトを作らず、手順書を AI に読ませる

分析の問いは毎回違うので、集計スクリプトは作りません。代わりに、API ごとの呼び方と注意点を設計書 (docs/analytics-api-access.md) にまとめ、エージェントに読ませます。リポジトリの CLAUDE.md から、分析の作業ではこの設計書を読むように案内しています。

設計書に書いているのは次の 4 つです。

  • 認証情報の所在と、token の発行のしかた
  • API ごとの curl の雛形と、よく使うクエリの骨子
  • API ごとの制約 (遅延、上限、欠ける範囲)
  • 過去に読み違えたフィールドと、正しい読み方 (後の節)

スクリプトにするのは、人がいない時間に定期的に動かす処理だけです。この案件では、自社 DB の登録を 6 時間おきに Google 広告へ送り返す処理がそれにあたり、Cloudflare の Cron から Data Manager API に送っています。

実例: CVR 1% の広告の調査で投げた照会

ある職種向けの広告で、CVR が別の職種向けの 8 分の 1 にとどまったときの調査です。エージェントが組んだ照会は、次のような形でした (ID は伏せています)。

検索語句を、一致の種類と配信先ごとに数えます。

SELECT search_term_view.search_term,
       segments.search_term_match_type,
       segments.ad_network_type,
       metrics.clicks, metrics.cost_micros
FROM search_term_view
WHERE campaign.id = <キャンペーン ID>
  AND segments.date BETWEEN '2026-07-12' AND '2026-07-20'

GA4 で、広告から来たセッションの滞在時間をキャンペーンと端末ごとに出します。

{
  "dateRanges": [{ "startDate": "2026-07-12", "endDate": "2026-07-20" }],
  "dimensions": [{ "name": "sessionCampaignName" }, { "name": "operatingSystem" }],
  "metrics": [{ "name": "sessions" }, { "name": "averageSessionDuration" }],
  "dimensionFilter": {
    "filter": { "fieldName": "sessionMedium", "stringFilter": { "value": "cpc" } }
  }
}

自社 DB で、実際の登録をキャンペーンごとに数えます。created_at は UNIX 秒です。

SELECT utm_campaign, COUNT(*) AS signups
FROM friends
WHERE created_at >= <開始の UNIX 秒> AND created_at < <終了の UNIX 秒>
GROUP BY utm_campaign;

3 つを突き合わせて分かったのは、来た人は本気でその職種を探していて (検索語句)、ページを長く読んでいたのに (iPhone で平均 103 秒)、登録していない (自社 DB で 1 件) ことでした。原因はページの訴求で、専用ページを作り直した後の CVR は 6.9% です。経緯はビジネス向けの記事に書いています。

AI が API の応答を読み違えた 3 つの例と、防ぎ方

AI エージェントは、API の応答をもっともらしく読み違えます。案件で起きた 3 つの例です。3 つとも気付いたのは人で、エージェントに元のデータを引き直させて訂正しました。

除外キーワードを、配信中のキーワードと読み違えた

上の調査で、エージェントは最初に「キーワードの登録が雑多なので、無関係な検索に広告が出ている」と結論しました。広告グループの条件に、無関係そうな語が大量に並んでいたためです。

実際には、その 82 本はすべて除外キーワードでした。過去に漏れた検索語句を完全一致で潰した履歴で、配信実績はゼロです。ad_group_criterion には、通常のキーワードと除外キーワードが同じ形で返ります。見るべきは negative です。

SELECT ad_group.name,
       ad_group_criterion.keyword.text,
       ad_group_criterion.keyword.match_type,
       ad_group_criterion.negative,
       ad_group_criterion.status
FROM ad_group_criterion
WHERE campaign.id = <キャンペーン ID>
  AND ad_group_criterion.type = KEYWORD

次にエージェントは「フレーズ一致の拡張が流出源」と説明し直しましたが、これも外れでした。検索語句を segments.search_term_match_type で数え直すと、フレーズ一致 (PHRASE / NEAR_PHRASE) からの無関係なクリックはゼロです。無関係な 97 クリックは全部が部分一致 (BROAD) からで、うち 81 クリックは segments.ad_network_type が検索パートナーでした。

キャンペーンの入札の目標を「無し」と読んだ

2026 年 9 月 4 日、「このキャンペーンは何を成果として入札しているか」を調べたときの読み違えです。エージェントは次の 2 つを根拠に、「この成果は入札に使われていない」「入札の目標が無い」と答えました。

  • conversion_action.primary_for_goal が false
  • campaign_conversion_goal の biddable が全行 false

どちらも答えになりません。primary_for_goal はアカウント単位の設定で、カスタム目標を持つキャンペーンには効きません。campaign_conversion_goal の biddable は標準のカテゴリだけを表すので、カスタム目標を使うキャンペーンでは全行が false になります。正しくは conversion_goal_campaign_config を引きます。

SELECT campaign.name,
       conversion_goal_campaign_config.goal_config_level,
       conversion_goal_campaign_config.custom_conversion_goal
FROM conversion_goal_campaign_config

検算は、成果のアクション別の数で行います。metrics.conversions に載るアクションが入札の対象で、metrics.all_conversions にだけ載るものは記録されているだけです。

SELECT campaign.name, segments.conversion_action_name,
       metrics.conversions, metrics.all_conversions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

防ぎ方は、読み違えを手順書に書き足すこと

3 つに共通するのは、フィールドの名前から意味を推測したことです。negative を見落とす、primary_for_goal を「主な目標か」と読む。名前だけなら、人でも同じ読み違えをします。

私たちは、読み違えが起きるたびに、手順書に「このフィールドは答えにならない。代わりにこれを引く」を書き足しています。エージェントは照会の前に手順書を読むので、同じ読み違えを繰り返しません。そして結論が出たら、根拠になった元の行を引き直してから動きます。AI に任せているのは照会と突き合わせで、結論を採るかどうかは人が決めます。

書き込みは人の承認を挟む

Google Ads API は読むだけでなく、除外キーワードの追加や予算の変更もできます。書き込みは次の手順に限っています。

  1. エージェントが、検索語句レポートを根拠に除外キーワードの案を設計書に書く (語、一致の種類、実害のクリックと費用、理由)
  2. 人が案を読み、適用する語を決める
  3. エージェントが googleAds:mutate で適用する
  4. エージェントが照会し直し、全件が有効になったことを確かめる

ある日の追加では、店名の検索を除外する 18 語を案にし、承認を経て適用し、照会で 18 件すべての有効を確認しました。予算の変更と配信の開始・停止は、人の指示があるときだけ行います。

ハマりどころ

  • 検索語句レポートで語句まで分かるのは、費用の一部だけ。 案件では約 47% でした。残りは語句が伏せられるので、除外キーワードの確認は週 1 回など定期的に続けます。
  • GA4 と Search Console のクリック数は一致しない。 2026 年 7 月の案件で、GA4 の自然検索は 71 セッション、Search Console のクリックは 11 でした。Google 検索の実数は Search Console を正にします。
  • Search Console は 2〜3 日遅れ。 検索語 (query) を軸に入れると匿名化で行が落ち、ページ単位の合計と一致しません。インデックス登録のリクエストは API にありません。
  • Clarity の Data Export API は直近 1〜3 日分、1 日 10 回程度まで。 録画やヒートマップは API で取れません。毎日の監視に使い、無駄撃ちしないよう手順書に書いておきます。
  • Google Ads API は約 1 年で古いバージョンが止まる。 案件では v21 が 2026 年 8 月 12 日に止まり、v22 は 10 月 19 日から一部のリクエストが弾かれ始めたので v23 に上げました。UNSUPPORTED_VERSION が返ったらバージョンを上げます。
  • 競合の指標 (オークション分析) は API で取れない。 v23 にフィールドはありますが、取ろうとすると METRIC_ACCESS_DENIED で拒否されます。
  • GA4 のイベントのパラメータは、カスタムディメンションに登録しないと Data API で引けない。 登録より前のデータには効きません。

この構成で原因を特定し、CVR 1% の広告を 6.9% まで戻した経緯は、記事「広告の CVR 改善は原因の特定から。CVR 1% の広告を 6.9% にした実例」に書いています。経営者向けの、AI に横断させる前にそろえるものと確かめ方は、記事「GA4 と広告のデータを AI で分析する方法」にあります。案件の全体像は開発事例、登録を広告に返す仕組みは記事「LINE 登録を広告の成果として測る方法」にあります。

当社では、計測の仕組みづくりから、広告とページの改善、AI エージェントによる分析の基盤づくりまでをお手伝いしています。お問い合わせフォーム、または LINE 公式アカウントからお気軽にどうぞ。

無料の道具3 min

問い合わせが、どこで消えているか分かりますか?

集客効率AI診断

  • 入口の計測・返事と追いかけ・データの持ち方の 3 つを、100 点満点で採点
  • AI が、御社の課題を 3 つに絞って書く
  • 次に何を整えるかを、PDF で持ち帰れる

選択式 14 問ほど / 広告を使っていなくても答えられる / 結果はその場で表示 (メール不要)

関連する記事

3 分で診断する 無料で相談する