Google Analytics コネクタを使用すると、Treasure AI Studio のエージェントがチャット中に GA4 のデータを読み取れます。アクセス権のあるプロパティについて、集客・ページ・イベント・キーイベントのレポートを取得し、指定したディメンションと指標から任意のレポートを組み立て、今サイトにいるユーザーを確認できます。サイトの行動に関する問いに、GA4 のタブとエクスポートではなくほかのデータと並べて答えを出したいとき — たとえばキャンペーンの流入チャネルと、実際にコンバージョンしたセグメントを突き合わせるとき — に使用します。
このコネクションは読み取り専用で、範囲も意図的に絞られています。エージェントが読めるのはレポートと、それを組み立てるために使えるディメンション・指標です。Analytics の内容を変更することはできず、プロパティの設定内容や管理情報を読むこともできません。Treasure AI が要求するのは読み取り専用の Google スコープなので書き込みはアカウントに届く前に Google 側で拒否され、さらにアカウントのポリシーで範囲が絞られています。一覧は エージェントができること を参照してください。
まず コネクション で全体像（コネクタとコネクションの違い、管理者とユーザーの役割）を確認してください。このページでは Google Analytics 固有の手順を説明します。
アカウントで Google Analytics コネクタを有効化してコネクションを認可し、チャット中にエージェントが自分のプロパティの GA4 レポートを読み取れるようにします。
- Treasure AI Studio のアカウント管理者権限 — ステップ 1（コネクタの有効化）でのみ必要です
- Google アナリティクス 4 プロパティに少なくとも 1 つアクセスできる Google アカウント。エージェントはこのアカウントとして読み取るため、到達範囲はそのアカウント自身の Analytics のアクセス権に従います（エージェントに見える範囲 を参照）
- 対象が GA4 プロパティであること。このコネクタは Google の GA4 API を使用するため、ユニバーサル アナリティクスのプロパティには対応していません
Google Analytics の設定に関わるのは 2 つの役割で、いずれも 1 回で済みます。Google Cloud 側で設定する作業はありません。OAuth アプリケーションは Treasure AI が管理します。
| 役割 | やること | 頻度 |
|---|---|---|
| Treasure AI Studio の管理者 | [コネクタ設定] で Google Analytics コネクタを追加して保存します。入力する項目はありません。 | 組織で 1 回 |
| 各メンバー | [コネクション] から自分のコネクションを認可し、使用する Google アカウントを選んで要求された権限を許可します。 | 1 人 1 回 |
登録する OAuth アプリケーションも、作成してプロパティへのアクセス権を与えるサービスアカウントも、追加するネットワークポリシーのルールもありません。各メンバー自身の Google アカウントがそのまま認可になります。
このコネクタが使用する Google OAuth アプリケーションは Treasure AI が管理するため、Google Cloud コンソールで作成する作業はなく、入力する Client ID やシークレットもありません。設定フォームは空です。
- Treasure AI Studio で [設定] → [コネクタ設定]（[組織] の下）を開きます。
- [コネクタを追加]（または [最初のコネクタを追加]）をクリックし、[Google Analytics] を選びます。
- [保存] をクリックします。入力する項目はありません。コネクタは有効な状態で保存されるため、全ユーザーの [コネクション] タブの [利用可能] にただちに Google Analytics が表示されます。
![コネクタ設定の [Configure Google Analytics] フォーム。入力項目は 1 つもなく、見出しの下に [Save] と [Cancel] ボタンだけがある](/assets/ai-studio-connector-configure-google-analytics.f5a42b1612bc3d95f2d0ebfcd96d3451d4c47cef0a852484054c20121e4d7be8.fdfbfafb.webp)
管理者の作業はこれで終わりです。保存後の行には有効化トグルがありますが、これをオフにすると新規の認可が止まるだけではありません。エージェントに許可された操作から Google Analytics がただちに外れます。新規のチャットだけでなく実行中のチャットにも及びます。進行中の処理が中断されるわけではありませんが、エージェントが次に行う操作が拒否されるため、既存のコネクションもすべて使えなくなります。オンに戻すまでこの状態が続き、その間もメンバーのコネクション自体は残ります。
接続したメンバーは、そのメンバーが到達できるすべてのプロパティの GA4 レポートデータを読み取る権限をエージェントに与えます。それ以外は何も与えません。エージェントはプロパティの設定変更、カスタムディメンション・カスタム指標の作成やアーカイブ、データ保持期間の変更をいずれも行えず、プロパティの設定内容や管理情報を読むこともできません。Treasure AI が要求するのは Google の読み取り専用 Analytics スコープのみなので、メンバーがエージェントに何を頼んでも Google が書き込みを拒否します。加えて書き込み操作はアカウントのポリシーでも個別にブロックされています。有効化の前に検討すべきなのは、そのメンバーの Google アカウントが何を読めるか、という点だけです。
Google Analytics コネクタは egress ドメインを提示しません。コネクタ設定にも「このドメインを許可してください」というリマインダーは表示されません。これは意図的な設計です。エージェントのサンドボックスは Analytics の API を呼び出しません。リクエストはサンドボックスの外にある Treasure AI のコネクタサービスが実行するため、サンドボックスの egress を制御するネットワークポリシーはこの通信に適用されず、新しいルールを追加する必要もありません。
エージェントに GA4 のデータで作業させたいメンバーは、それぞれ自分のコネクションを認可します。[設定] から事前に行うことも、チャットから必要になった時点で行うこともできます。
- [設定] → [コネクション] を開きます。
- [利用可能] から [Google Analytics] を見つけて [接続] をクリックします。
![コネクションページ。[利用可能] に Treasure AI Voice・Google Analytics・Google Calendar・Google Search Console・Treasure Data が並び、それぞれに [接続] ボタンがある](/assets/ai-studio-connections-google-available.961f60ca9f0438f15ef1d0a25d2b063119fcd44264cb7def42d2740de928964e.fdfbfafb.webp)
- Google のポップアップで、Analytics のアクセス権を持つ Google アカウントを選びます。複数のアカウントにサインインしている場合は慎重に選んでください。ここで選んだアカウントがそのままコネクションに紐づきます。
- 要求されている権限を確認して許可します。Google が要求する権限は 1 つ（Analytics のデータの閲覧）で、そのアカウントが到達できるすべてのプロパティが対象になります。
![Google の権限確認画面。「See and download your Google Analytics data」の 1 項目だけが並び、[Cancel] と [Allow] ボタンがある](/assets/ai-studio-connections-google-analytics-consent.7053c102eb7cc71bb7ca8756aba8b9a420b1f59be573e1eae71c1be7a798b02c.fdfbfafb.webp)
- ポップアップが閉じると、接続済みの一覧に [Google Analytics] と接続日が表示されます。
コネクションが認可するのは 1 つの Google アカウントで、それを通じてそのアカウントがアクセスできるすべての GA4 プロパティが対象になります。Studio が保持する Google Analytics のコネクションはメンバーごとに 1 つのため、別の Google アカウントに切り替えるにはコネクションを削除して認可し直します。
あとでコネクションを削除するには、横の削除（ゴミ箱）アイコンをクリックします。エージェントはただちにアクセスを失います。このコネクションは書き込みを行わないため、Analytics 側に取り消すべきものはありません。なお、Google アカウントのサードパーティ接続の一覧には Treasure AI Studio が残るため、そちらでも削除する必要があります。
事前に認可しておく必要はありません。接続前にエージェントへサイトのトラフィックについて尋ねると、チャット内に [Connection Required]（コネクションが必要）カードが表示されます。そこで [Connect] をクリックすれば、会話から離れずに同じ認可を実行できます。カードは表示名ではなく内部 ID の google_analytics を示します。チャットから接続する を参照してください。
Google Analytics への接続が済んだら、普通の言葉で尋ねてください。コマンドもチャット内の設定も不要です。例:
- 「先月、エンゲージメントのあったセッションを最も多く生んだチャネルは? 前月と比べてどう変わった?」
- 「GA4 のプロパティを一覧して。どれを使うか指定するから」
- 「直近 28 日間のランディングページ上位 20 件をユーザー数順で、エンゲージメント率と平均エンゲージメント時間つきで出して」
- 「今四半期、キーイベントの伸びが最も大きい国は?」
- 「今サイトに何人いる? 何を見ている?」
- 「先週のコンバージョンをデバイスとブラウザで分解して」
- 「キャンペーンの流入元を、実際に購入した CDP のセグメントと突き合わせて」
どの操作を使うかはエージェントが自分で決めます。通常はまずプロパティを一覧し、指定されたプロパティに対してレポートを実行します。GA4 プロパティは数値のプロパティ ID で識別され、properties/ の接頭辞はあってもなくても構いません。分からない場合は、まずプロパティを一覧するようエージェントに依頼し、返ってきたものから選んでください。
GA4 のレポートには、エージェントが答えられる範囲を左右する制約があります。これは Treasure AI ではなく Google 側の制約です。すべてのディメンションとすべての指標を組み合わせられるわけではありません。エージェントは実行前に組み合わせの可否を確認でき、照会できない場合はそう伝えます。またレポートにはプロパティ単位の API 割り当てがあり、大きなレポートを続けて実行すると使い切ることがあります。残りの割り当ては、レポートと一緒に返させることができます。
GA4 側を変更する作業 — プロパティの編集、カスタムディメンションの追加、データ保持期間の変更 — は人の担当のままです。エージェントは見えている状況と問題点を伝えるところまでで、変更は Google Analytics で行います。プロパティがどう設定されているかという問いも同様です。エージェントが扱うのはレポートのデータで、プロパティの設定情報ではありません。
エージェントが使える操作は次のとおりです。どれを使うかは依頼の内容からエージェントが自分で選びます。操作を直接実行するためのコマンド構文はありませんが、メッセージの中で操作名を挙げればエージェントをその操作へ誘導できます。
| 領域 | 操作 | 内容 |
|---|---|---|
| プロパティを探す | google_analytics.list_properties | 接続した Google アカウントが見られる GA4 プロパティを、アカウントの文脈とともに一覧します。どれを使うか指定するために使います。1 ページ最大 200 件（ページング対応）です。 |
| 定型レポート | google_analytics.run_pages_report、google_analytics.run_events_report、google_analytics.run_acquisition_report、google_analytics.run_key_events_report | よく聞かれる問いに対応した 4 本の用意済みレポートです。ページごとのページビュー・ユーザー・セッション・エンゲージメント、イベントの件数・ユーザー・キーイベント・価値、セッションとユーザーの流入元、キーイベントの件数とコンバージョン率。 |
| 任意のレポート | google_analytics.run_report、google_analytics.run_pivot_report | 必要なディメンション・指標・期間・フィルタ・並び順・コホート・比較・集計からレポートを組み立てます。フラットな表と、クロス集計のピボットの両方に対応します。定型レポートで扱える内容はすべてこちらでも表現できます。 |
| 今の状況 | google_analytics.run_realtime_report | リアルタイムレポートを読み取ります。今この瞬間にサイトで発生しているユーザーとイベントです。 |
| レポートの前に | google_analytics.get_metadata、google_analytics.check_compatibility | プロパティで使えるディメンションと指標（そのプロパティ独自のものを含む）を一覧し、選んだ組み合わせが照会可能かをレポートを消費する前に確認します。 |
エージェント経由で Google Analytics の内容が変わることはなく、読み取りの範囲もレポートまでで止まります。知っておく価値があるのは次の点です。
- プロパティの変更はできません。 プロパティの設定（名称・タイムゾーン・通貨）を編集できません。とくにタイムゾーンの変更は、過去のすべてのレポートの日単位の区切りを動かすため、人が意図して行う操作のままにしてあります。
- カスタムディメンション・カスタム指標の変更はできません。 作成もアーカイブもできません。GA4 のアーカイブは取り消せず、枠数にも上限があるため、誤りを元に戻せません。
- データ保持期間の変更はできません。 プロパティのデータ保持設定を変更できません。期間を短くすると過去のデータが恒久的に削除されます。
- 設定情報の読み取りはできません。 プロパティのデータストリーム・カスタムディメンション・カスタム指標を設定情報として一覧したり、プロパティの設定概要を読むことはできません。カスタムディメンションとカスタム指標は、レポートを組み立てる前に読むメタデータを通じて「レポートで使える項目」としてのみ見えます。
- アカウントやユーザーの管理はできません。 プロパティやアカウントの作成、アクセス権を持つユーザーの変更はできません。
- ユニバーサル アナリティクスは対象外です。 このコネクタは Google の GA4 API 経由で GA4 プロパティを読み取ります。ユニバーサル アナリティクスのプロパティは対象になりません。
- ほかの Google プロダクトは対象外です。 このコネクタが到達するのは Google Analytics だけです。Google Search Console と Google Calendar は別のコネクタで、それぞれ個別の認可が必要です。
Google Analytics コネクタはあなた自身の Google の認可を持つため、到達範囲は接続した Google アカウントの Analytics のアクセス権によって決まります。
- そのアカウントが Google Analytics で開けるすべての GA4 プロパティが対象で、それ以外は対象外です。コネクションを 1 つのプロパティに限定する方法はありません。
- 各プロパティのロールが許す範囲のデータ。 Google はプロパティまたはアカウント単位でロールを割り当てており、エージェントはそれをそのまま引き継ぎます。Analytics で閲覧しかできないプロパティは、エージェントも読み取りしかできません。
- レポートのデータだけ。 同じプロパティの中でも、エージェントが読むのはレポートとそれを組み立てるための項目で、プロパティの設定内容やユーザー一覧は対象外です。
- 読み取り以外は何もありません。 この認可には書き込みの能力が一切含まれません。アカウントのロールがどうであれ、どのプロパティに対しても書き込めません。
これを適用するのはリクエストを受け取った Google 側であり、Treasure AI Studio ではありません。プロンプトで範囲を広げることはできません。エージェントは範囲を狭めること（1 つのプロパティだけ、1 つの期間だけを見るよう指示する）はできますが、広げることはできません。
| 項目 | 値 |
|---|---|
| コネクタ | Google Analytics |
| 内部 ID | google_analytics — チャットの [Connection Required] カードに表示される ID |
| 認証 | OAuth 2.0 認可コード + PKCE（user-to-machine）、プラットフォーム管理の Google OAuth アプリケーション |
| 要求する Google スコープ | 1 つ: https://www.googleapis.com/auth/analytics.readonly。読み書き可能な analytics.edit スコープは意図的に要求しません |
| 必要な設定 | なし。管理者は入力項目のないままコネクタを保存します |
| アクセス | 読み取り専用、かつレポートに範囲を絞っています — プロパティの一覧、定型レポート 4 本、任意レポートとピボットレポート、リアルタイムレポート、レポートを組み立てるためのメタデータと互換性チェック。エージェント経由で Analytics の内容を変更することはできず、設定情報を読むこともできません |
| 使用する Google API | Analytics Data API v1beta（https://analyticsdata.googleapis.com/v1beta）、リアルタイムと割り当てのための v1alpha エンドポイント、Analytics Admin API v1beta（https://analyticsadmin.googleapis.com/v1beta） |
| 対応プロパティ | GA4 プロパティのみ。ユニバーサル アナリティクスには非対応 |
| プロパティの識別子 | 数値の GA4 プロパティ ID（properties/ の接頭辞はあってもなくても可） |
| 1 ページあたりのプロパティ数 | 最大 200 件（トークンによるページング） |
| ディメンションと指標の組み合わせ | すべての組み合わせが照会できるわけではありません。レポートで失敗して気づく前に、エージェントが実行前に可否を確認できます |
| 割り当て | Google はプロパティ単位で Data API の割り当てを適用します。大きなレポートを続けて実行すると使い切ることがあります。残りの割り当てはレポートと一緒に返させることができますが、レポートを実行せずに読み取る手段はありません |
| エージェントの識別情報 | 認可した Google アカウントとして読み取ります。書き込みを行わないため、そのアカウントの操作として Analytics に記録されるものはありません |
| リクエストの実行場所 | エージェントのサンドボックス外にある Treasure AI のコネクタサービス |
| egress ドメイン | なし — サンドボックスは Analytics の API に到達しないため、ネットワークポリシーのルールは不要です |
| トークンの有効期間 | 短命なアクセストークンを自動で更新します。そのためコネクションは接続し直さずにセッションをまたいで有効なままです |
| メンバーあたりのコネクション数 | 1 つ（Google アカウント 1 つ分と、そのアカウントがアクセスできるすべての GA4 プロパティが対象） |
| 症状 | 対処 |
|---|---|
| コネクションタブに Google Analytics が表示されない | 管理者が [コネクタ設定] で Google Analytics コネクタを追加し、有効化する必要があります。 |
| エージェントがプロパティを 1 つも見つけられない | Analytics のアクセス権を実際に持つ Google アカウントを認可したか確認してください。ポップアップのアカウント選択は流してしまいやすい箇所です。異なる場合はコネクションを削除し、正しいアカウントで接続し直します。ユニバーサル アナリティクスのプロパティはそもそも表示されません。表示されるのは GA4 プロパティだけです。 |
| プロパティが見つからないとエージェントが報告する | 数値の GA4 プロパティ ID を使ってください。プロパティの表示名ではなく、プロパティを一覧するようエージェントに依頼して返ってきた識別子を使います。 |
| ディメンションと指標が非互換だというエラーでレポートが失敗する | GA4 はすべての組み合わせを許可していません。先に組み合わせの可否を確認し、成立する組み合わせを提案するようエージェントに依頼するか、リクエストを 2 本のレポートに分けてください。 |
| 数値が GA4 の画面と一致しない | 期間・プロパティ・フィルタが一致しているか確認してください。GA4 自体もデータのしきい値処理とサンプリングを行うため、細かく分解したレポートの合計が、粗い粒度の同じレポートより小さくなるのは正常です。 |
| 大きなレポートを何本か実行したあとで失敗するようになる | そのプロパティの Data API の割り当てを使い切っています。次のレポートに残りの割り当ても返させるようエージェントに依頼し、レポートの本数やサイズを減らすか、時間をおいて再実行してください。 |
| プロパティの設定変更を頼んだら断られた | 想定どおりの動作です。このコネクションは読み取り専用で、プロパティの編集・カスタムディメンションとカスタム指標の作成やアーカイブ・データ保持期間の変更はいずれもブロックされており、読み取り専用スコープでもそもそも拒否されます。変更は Google Analytics で行ってください。 |
| プロパティのデータストリームを聞いたら答えられなかった | 想定どおりの動作です。設定情報の読み取りはこのコネクタの範囲外です。データストリームは Google Analytics で確認してください。知りたいのが「この数字が何を含んでいるか」であれば、ストリーム別に分解したレポートをエージェントに依頼してください。 |
| エージェントが再接続を求めてくる | 認可が失効したか、Google 側で取り消されています（Google アカウントのサードパーティ接続から Treasure AI Studio を削除した場合も含みます）。[設定] → [コネクション] から接続し直してください。 |
| コネクションタブからコネクタが消えた | 管理者が無効化した可能性があります。コネクション自体は保持されますが、コネクタが再度有効化されるまでエージェントは Google Analytics を利用できません。 |
- コネクション — コネクションの全体像と管理者向けの制御
- Google Search Console への接続 — エージェントに Google 検索のパフォーマンスデータを読み取らせる
- Google Calendar への接続 — エージェントにカレンダーの読み取りと予定の作成・更新をさせる
- スキルとマーケットプレイス — スキルがエージェントにドメイン専門知識を与える仕組み
- セキュリティ概要 — Studio でのアクセス制御の仕組み