使用 Analytics 顧問查詢及分析資料

Data API 的 chat 方法提供 Analytics 顧問的程式輔助存取權，這項 AI 輔助分析工具可協助您使用自然語言查詢、分析及診斷 Google Analytics 資料。

Analytics 顧問可在 Google Analytics 使用者介面中互動使用，而 chat API 則可讓開發人員、自主式 AI 代理程式和內部工具，透過 HTTP 以程式輔助方式與 Analytics 顧問互動。

注意： chat 方法適用於 Data API 的 v1alpha 版本。

重要事項：本產品使用 AI 技術，可能會顯示不正確的資訊。您的對話記錄可能會用於改良產品，使用本產品時，請務必遵守 Google 的《條款》、《AI 使用政策》和《隱私權政策》。

總覽

chat 方法可支援單輪臨時資料問題和多輪對話工作階段：

1. 單輪查詢：立即提出分析問題 (例如「我們上週的熱門流量管道有哪些？」)，並以自然語言取得答案和結構化資料表。
2. 多輪對話：傳遞 sessionId ，即可保留對話記錄並提出診斷後續問題 (例如「為什麼該期間的自然流量會下降？」)。
3. 結構化資料回覆：除了文字敘述，回覆內容還包含結構化 table 區塊，並附上欄標題和資料列。
4. 監控 Chat 配額：將 returnPropertyQuota 設為 true，即可檢查每日和每小時的剩餘 Chat 權杖配額。

驗證

呼叫 chat 方法時，需要使用下列範圍進行 OAuth 2.0 授權：

• https://www.googleapis.com/auth/analytics.chatbot.read

附註： 這個範圍與標準報表方法 (例如 runReport) 所需的範圍不同。

事前準備

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 Analytics 使用者介面中，授予使用者帳戶Google Analytics 資源的存取權。

4. 輸入下列內容，設定環境變數。 將 PROJECT_ID 替換為專案 ID， 並將 PROPERTY_ID 替換為 Google Analytics 資源 ID。

     export PROJECT_ID=PROJECT_ID
     export PROPERTY_ID=PROPERTY_ID

範例 1：單輪查詢 (含配額追蹤)

如要發起新對話，請建構包含 userQuery 的 ChatRequest。 設定 returnPropertyQuota 檢查剩餘的權杖餘額。true

情境：依裝置劃分的收益和轉換率

您想比較過去 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，可用於後續回合。
• blocks 清單，包含自然語言摘要 (text) 和結構化表格 (table)。文字區塊可包含 Markdown 格式，例如粗體文字、標題和連結。
• 房源的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 回應

Analytics 顧問會使用工作階段記憶體，將結果與前一期建立關聯。

{
  "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 要求的聊天權杖用量取決於查詢複雜度。當 returnPropertyQuota 為 true 時，系統會在 propertyQuota 中傳回目前的配額狀態：

• tokensPerDay：每日詞元限制和剩餘餘額。
• tokensPerHour：每小時滑動視窗的速率限制和剩餘餘額。

建議的整合應用程式

properties.chat 方法可解鎖團隊和工具的數種整合架構：

企業即時通訊和協作機器人

直接將團隊即時通訊工作區連結至 Google Analytics。

• 討論串工作階段：將 sessionId 儲存至聊天討論串 ID，讓團隊成員共同提出後續問題。
• 複合式資訊卡顯示：將 table 回覆區塊格式化為互動式資訊卡小工具。

自主式 AI 代理程式和 Model Context Protocol (MCP) 工具

為 LLM 編排器 (例如 Gemini、LangChain 或 Claude) 配備正式發布版分析工具：

• LLM 代理程式可透過自然語言意圖叫用 chat 方法，不必強迫 LLM 生成複雜的 runReport 查詢。
• 代理會收到高準確度的摘要和結構化表格，並綜合這些資訊，提出多管道行銷建議。

自動產生高階主管簡報和警報

建立預定服務，主動調查異常狀況：

• 每日執行的 Cron 工作會查詢：「請摘要說明昨天的主要成效指標，並找出轉換次數異常減少的情況。」
• 如果發現異常狀況，指令碼會自動觸發後續查詢，診斷根本原因，並將摘要發布至內部資訊主頁或 CRM 系統。