アナリティクス アドバイザーを使用してデータをクエリして分析する

Data APIchat メソッドは、アナリティクス アドバイザー(自然言語を使用して Google アナリティクス データのクエリ、分析、診断を行うのに役立つ AI を活用した分析アシスタント)へのプログラムによるアクセスを提供します。

アナリティクス アドバイザーは Google アナリティクスのユーザー インターフェースでインタラクティブに利用できますが、chat API を使用すると、デベロッパー、自律型 AI エージェント、内部ツールが HTTP 経由でアナリティクス アドバイザーとプログラムでやり取りできます。

重要: このサービスは AI を使用しており、不正確な情報が表示されることがあります。チャット アクティビティはサービスの改善に使用されることがあります。サービスのご利用には Google の利用規約AI 利用ポリシープライバシー ポリシーが適用されます。

概要

chat メソッドを使用すると、単一ターンのアドホック データ質問とマルチターンの会話セッションの両方を行うことができます。

  1. 単一ターンのクエリ: 「先週のトラフィック チャネルの上位は?」などの分析に関する質問をすぐに投げかけ、構造化データテーブルとともに自然言語の回答を受け取ります。
  2. マルチターンの会話: sessionId を渡して会話の履歴を保持し、診断用のフォローアップの質問(「その期間にオーガニック トラフィックが減少したのはなぜですか?」など)をします。
  3. 構造化データ レスポンス: テキストによる説明に加えて、レスポンスには列見出しと行を含む構造化された table ブロックが含まれます。
  4. Chat の割り当てのモニタリング: returnPropertyQuotatrue に設定して、1 日あたりと 1 時間あたりの残りの Chat トークン割り当てを確認します。

認証

chat メソッドの呼び出しには、次のスコープによる OAuth 2.0 認証が必要です。

始める前に

  1. gcloud CLI をインストールして初期化します

  2. アプリケーションのデフォルト認証情報を生成し、アカウントに必要なスコープを付与するには、次のコマンドを実行します。

    gcloud auth application-default login --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/analytics.chatbot.read"
    
  3. Google アナリティクスの UI で、ユーザー アカウントに Google アナリティクスのプロパティへのアクセス権を付与します。

  4. 次のように入力して、環境変数を構成します。PROJECT_ID は プロジェクトの ID に、PROPERTY_ID は Google アナリティクスのプロパティの ID に置き換えます。

      export PROJECT_ID=PROJECT_ID
      export PROPERTY_ID=PROPERTY_ID

例 1: 割り当てトラッキングを含むシングルターン クエリ

新しい会話を開始するには、userQuery を含む ChatRequest を作成します。returnPropertyQuotatrue に設定して、残りのトークン残高を検査します。

シナリオ: デバイス別の収益とコンバージョン率

過去 30 日間のデバイス別の収益とセッションのコンバージョン率を比較したい。

HTTP リクエスト

curl -X POST \
  "https://analyticsdata.googleapis.com/v1alpha/properties/${PROPERTY_ID}:chat" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "userQuery": "Compare our revenue and conversion rate across mobile vs desktop over the last 30 days.",
    "returnPropertyQuota": true
  }'

HTTP レスポンス

レスポンスには次のものが含まれます。

  • フォローアップ ターンに使用できる、新たに割り当てられた sessionId
  • 自然言語の要約(text)と構造化された表(table)の両方を含む blocks のリスト。テキスト ブロックには、テキストを太字にする(機能)、見出し、リンクなどのマークダウン形式を含めることができます。
  • 宿泊施設の propertyQuota の詳細。
{
  "sessionId": "692e9ab9-b338-4426-b006-a05f21ac7cd6",
  "blocks": [
    {
      "text": "Your report on revenue and conversion rates for mobile vs. desktop over the last 30 days (August 15 - September 13, 2026) is ready.\n\nHere is a summary of your revenue and conversion rate by device category:\n"
    },
   {
      "table": {
        "headers": [
          {
            "header": "Device Category",
            "dataType": "string"
          },
          {
            "header": "Total Revenue",
            "dataType": "string"
          },
          {
            "header": "User Conversion Rate",
            "dataType": "string"
          }
        ],
        "rows": [
          {
            "columns": [
              {
                "value": "Desktop"
              },
              {
                "value": "$17,412.62"
              },
              {
                "value": "99.9%"
              }
            ]
          },
          {
            "columns": [
              {
                "value": "Mobile"
              },
              {
                "value": "$15,309.41"
              },
              {
                "value": "99.46%"
              }
            ]
          }
      }
    },
    {
      "text": "**Revenue and Conversion Rate Trends:**\n\nRevenue from desktop devices saw a peak on August 18th, while mobile revenue peaked on August 30th. Conversion rates remained high and relatively stable for both desktop and mobile throughout the period."
    },
    {
      "text": "This product uses AI and may display inaccurate info. Your chat activity may be used to improve the product and your use is subject to Google's [Terms](https://policies.google.com/terms), [AI Use Policy](https://policies.google.com/terms/generative-ai/use-policy), and [Privacy Policy](https://policies.google.com/privacy). [Learn more about Chat AI Privacy](https://support.google.com/helpguide/answer/14185196)."
    }
  ],
   "propertyQuota": {
    "tokensPerDay": {
      "consumed": 26849,
      "remaining": 3723151
    },
    "tokensPerHour": {
      "consumed": 26849,
      "remaining": 473151
    }
  }
}

例 2: マルチターンの会話型診断

コンテキストを維持しながらフォローアップの質問をするには、リクエストに前のレスポンスで返された sessionId を含めます。

シナリオ: 前の期間と比較する

前のデバイスの比較に続いて、アドバイザーに結果を前の期間と比較するよう依頼します。

HTTP リクエスト

curl -X POST \
  "https://analyticsdata.googleapis.com/v1alpha/properties/${PROPERTY_ID}:chat" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "692e9ab9-b338-4426-b006-a05f21ac7cd6",
    "userQuery": "Compare results with the same period in the previous mounth."
  }'

HTTP レスポンス

アナリティクス アドバイザーは、セッション メモリを使用して結果を前の期間と関連付けます。

{
  "sessionId": "eb3284b2-49ce-4aed-b6d0-fdc15cb87b5f",
  "blocks": [
    {
      "text": "The following table provides a detailed comparison of total revenue and user conversion rate by device category for the two periods.\n"
    },
    {
      "table": {
        "headers": [
          {
            "header": "Device Category",
            "dataType": "string"
          },
          {
            "header": "Metric",
            "dataType": "string"
          },
          {
            "header": "Jul 16 - Aug 15, 2026",
            "dataType": "string"
          },
          {
            "header": "Aug 16 - Sep 14, 2026",
            "dataType": "string"
          }
        ],
        "rows": [
          {
            "columns": [
              {
                "value": "Desktop"
              },
              {
                "value": "Total Revenue"
              },
              {
                "value": "$17,412.62"
              },
              {
                "value": "$19,565.46"
              }
            ]
          },
          {
            "columns": [
              {
                "value": "Desktop"
              },
              {
                "value": "User Conversion Rate"
              },
              {
                "value": "1.90%"
              },
              {
                "value": "1.95%"
              }
            ]
          },
          {
            "columns": [
              {
                "value": "Mobile"
              },
              {
                "value": "Total Revenue"
              },
              {
                "value": "$13,997.19"
              },
              {
                "value": "$15,309.41"
              }
            ]
          },
          {
            "columns": [
              {
                "value": "Mobile"
              },
              {
                "value": "User Conversion Rate"
              },
              {
                "value": "1.95%"
              },
              {
                "value": "1.99%"
              }
            ]
          }
      }
    }
  ]
}

レスポンスの構造とデータブロック

ChatResponse オブジェクトは、blocks 配列で構造化されたコンポーネントを返します。

ブロックタイプ フィールド 説明
ナレーション テキスト blocks[].text 人が読める形式の説明と、分析結果の概要。
構造化テーブル blocks[].table headers(名前とデータ型)と rows(セル値)を含む表形式のデータの内訳。

表のヘッダーのデータ型

blocks[].table.headers の列は、セマンティック データ型を表します。

  • string: カテゴリカル テキスト値("desktop""/shop/apparel" など)。
  • float: 数値の浮動小数点数。

チャットの割り当て管理

Analytics Advisor のリクエストは、クエリの複雑さに応じてチャット トークンを消費します。returnPropertyQuotatrue の場合、現在の割り当て状態は propertyQuota で返されます。

  • tokensPerDay: 1 日あたりのトークンの上限と残高。
  • tokensPerHour: 1 時間のスライディング ウィンドウのレート制限と残高。

統合アプリケーションの候補

properties.chat メソッドは、チームとツールにまたがる複数の統合アーキテクチャをアンロックします。

エンタープライズ チャットとコラボレーション ボット

チームチャット ワークスペースを Google アナリティクスに直接接続します。

  • スレッド セッション: sessionId をチャット スレッド ID に保存して、チームメンバーがフォローアップの質問を共同で行えるようにします。
  • リッチカードのレンダリング: table レスポンス ブロックをインタラクティブなカード ウィジェットにフォーマットします。

自律型 AI エージェントと Model Context Protocol(MCP)ツール

LLM オーケストレーター(Gemini、LangChain、Claude など)に GA 分析ツールを装備します。

  • LLM に複雑な runReport クエリを生成させるのではなく、LLM エージェントは自然言語のインテントで chat メソッドを呼び出すことができます。
  • エージェントは、事実に基づいた要約と構造化されたテーブルを受け取り、それらを統合してマルチチャネル マーケティングの推奨事項を作成します。

自動化されたエグゼクティブ ブリーフィングとアラート

異常を事前に調査するスケジュールされたサービスを作成します。

  • 毎日の cron ジョブは、「昨日の主要なパフォーマンス指標を要約し、コンバージョンの異常な減少を特定する」というクエリを実行します。
  • 異常が検出されると、スクリプトは根本原因を診断するためのフォローアップ クエリを自動的にトリガーし、概要ダイジェストを内部ダッシュボードまたは CRM システムに投稿します。