Data API 的 chat 方法支持以程序化方式访问 Google Analytics 中的 Ask Advisor，后者是一款由 AI 赋能的 Analytics 助手，可帮助您使用自然语言查询、分析和诊断 Google Analytics 数据。
虽然 Ask Advisor 可以在 Google Analytics
界面中以交互方式使用，但 chat API
允许开发者、自主 AI 智能体和内部工具通过 HTTP 以编程方式与
Ask Advisor 互动。
重要提示：此产品使用了 AI 技术，可能会显示不准确的信息。您的聊天 活动可能会用于改进该产品，您在使用时须遵守 Google 的《条款》、《AI 使用 政策》和 《隐私权政策》。
概览
chat 方法支持
单轮临时数据问题和多轮对话会话：
- 单轮查询 ：提出即时分析问题（例如“上周我们的热门流量渠道是什么？”），并接收自然语言回答以及结构化数据表。
- 多轮对话：传递
sessionId以保留对话记录，并提出诊断性后续问题 （例如“为什么该时段的自然流量会下降？”）。 - 结构化数据响应：除了文本叙述之外，响应
包含带有列标题和行的结构化
table块。 - 聊天配额监控：通过将每日和每小时剩余的聊天令牌
配额设置为
returnPropertyQuotatrue来检查。
身份验证
调用 chat 方法
需要使用以下范围进行 OAuth 2.0 授权：
准备工作
安装并初始化 gcloud CLI。
如需生成 应用默认 凭据 并为您的账号授予必要的范围，请运行以下命令：
gcloud auth application-default login --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/analytics.chatbot.read"在 Google Analytics 界面中，向您的用户 账号授予对 Google Analytics 媒体资源的访问权限。
输入以下命令来配置环境变量。 将
PROJECT_ID替换为您的 项目的 ID，并将PROPERTY_ID替换为您的 Google Analytics 媒体资源的 ID。export PROJECT_ID=
PROJECT_IDexport PROPERTY_ID=PROPERTY_ID
示例 1：单轮查询和配额跟踪
如需开始新的对话，请构建 ChatRequest
包含您的 userQuery。
将 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，可用于后续轮次。 - 包含自然语言摘要 (
text) 和结构化表格 (table) 的blocks列表。文本块可以包含 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
。
场景：与上一时间段进行比较
在之前的设备比较之后，您要求 Advisor 将结果与上一时间段进行比较。
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 响应
Ask Advisor 使用会话记忆将结果与上一时间段相关联。
{
"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：数值浮点数。
聊天配额管理
Ask Advisor 请求会根据查询的复杂程度消耗聊天令牌。
当returnPropertyQuota
为 true 时，当前配额状态会在
propertyQuota
中返回：
tokensPerDay：每日令牌限制和剩余余额。tokensPerHour：每小时滑动窗口速率限制和剩余余额。
建议的集成应用
The properties.chat 方法
可解锁跨团队和工具的多种集成架构：
企业聊天和协作机器人
将您的团队聊天工作区直接关联到 Google Analytics。
自主 AI 智能体和模型上下文协议 (MCP) 工具
为 LLM 编排器（例如 Gemini、LangChain 或 Claude）配备 GA 分析工具：
自动执行简报和提醒
创建主动调查异常的计划服务：
- 每日 Cron 作业查询：“总结昨天的关键效果指标，并 找出转化次数的任何异常下降。”
- 如果发现异常，脚本会自动触发后续查询以诊断根本原因，并将摘要发布到内部信息中心或 CRM 系统。
后续步骤
- 试用交互式 Ask Advisor Colab 笔记本，使用 Python 客户端库运行单轮和多轮查询。
- 查看
properties.chatREST API 参考文档。 - 详细了解 Data API 配额和限制。