Phương thức chat của Data API cung cấp quyền truy cập theo phương thức có lập trình vào Cố vấn Analytics – một trợ lý phân tích dựa trên AI giúp bạn truy vấn, phân tích và chẩn đoán dữ liệu Google Analytics bằng ngôn ngữ tự nhiên.
Mặc dù Cố vấn Analytics có sẵn ở dạng tương tác trong giao diện người dùng Google Analytics, nhưng API chat cho phép các nhà phát triển, tác nhân AI tự động và công cụ nội bộ tương tác với Cố vấn Analytics theo cách lập trình qua HTTP.
Quan trọng: Sản phẩm này sử dụng AI nên có thể hiển thị thông tin không chính xác. Hoạt động trò chuyện của bạn có thể được dùng để cải thiện sản phẩm và việc bạn sử dụng phải tuân thủ Điều khoản, Chính sách sử dụng AI và Chính sách quyền riêng tư của Google.
Tổng quan
Phương thức chat cho phép cả câu hỏi dữ liệu một lượt không theo kế hoạch và phiên trò chuyện nhiều lượt:
- Câu hỏi một lượt: Đặt câu hỏi phân tích ngay lập tức (chẳng hạn như "Những kênh lưu lượng truy cập hàng đầu của chúng tôi trong tuần trước là gì?") và nhận câu trả lời bằng ngôn ngữ tự nhiên cùng với các bảng dữ liệu có cấu trúc.
- Cuộc trò chuyện nhiều lượt: Truyền
sessionIdđể duy trì nhật ký trò chuyện và đặt các câu hỏi chẩn đoán tiếp theo (chẳng hạn như "Tại sao lưu lượng truy cập tự nhiên lại giảm trong khoảng thời gian đó?"). - Phản hồi dữ liệu có cấu trúc: Ngoài nội dung tường thuật bằng văn bản, các phản hồi còn chứa các khối
tablecó cấu trúc với tiêu đề cột và hàng. - Giám sát hạn mức trò chuyện: Kiểm tra hạn mức mã thông báo trò chuyện còn lại mỗi ngày và mỗi giờ bằng cách đặt
returnPropertyQuotathànhtrue.
Xác thực
Các lệnh gọi đến phương thức chat yêu cầu uỷ quyền OAuth 2.0 với phạm vi sau:
Trước khi bắt đầu
Cài đặt và khởi chạy gcloud CLI.
Để tạo Thông tin xác thực mặc định của ứng dụng và cấp cho tài khoản của bạn các phạm vi cần thiết, hãy chạy lệnh sau:
gcloud auth application-default login --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/analytics.chatbot.read"Trong giao diện người dùng Google Analytics, hãy cấp cho tài khoản người dùng của bạn quyền truy cập vào một tài sản Google Analytics.
Định cấu hình các biến môi trường bằng cách nhập nội dung sau. Thay thế
PROJECT_IDbằng mã nhận dạng của dự án vàPROPERTY_IDbằng mã nhận dạng của tài sản Google Analytics.export PROJECT_ID=
PROJECT_IDexport PROPERTY_ID=PROPERTY_ID
Ví dụ 1: Truy vấn một lượt có tính năng theo dõi hạn mức
Để bắt đầu một cuộc trò chuyện mới, hãy tạo một ChatRequest chứa userQuery của bạn.
Đặt returnPropertyQuota thành true để kiểm tra số dư mã thông báo còn lại.
Tình huống: Doanh thu và tỷ lệ chuyển đổi theo thiết bị
Bạn muốn so sánh doanh thu và tỷ lệ chuyển đổi theo phiên trên các thiết bị trong 30 ngày qua.
Yêu cầu 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
}'
Phản hồi HTTP
Phản hồi chứa:
- Một
sessionIdmới được chỉ định mà bạn có thể dùng cho các lượt tiếp theo. - Một danh sách
blockschứa cả nội dung tóm tắt bằng ngôn ngữ tự nhiên (text) và một bảng có cấu trúc (table). Các khối văn bản có thể chứa định dạng Markdown như văn bản in đậm, tiêu đề và đường liên kết. - Thông tin chi tiết về
propertyQuotacủa cơ sở lưu trú.
{
"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
}
}
}
Ví dụ 2: Chẩn đoán đàm thoại nhiều lượt
Để đặt câu hỏi nối tiếp mà vẫn giữ được ngữ cảnh, hãy thêm sessionId do câu trả lời trước trả về vào yêu cầu của bạn.
Tình huống: So sánh với kỳ trước
Tiếp theo yêu cầu so sánh thiết bị trước đó, bạn yêu cầu Advisor so sánh kết quả với kỳ trước.
Yêu cầu 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."
}'
Phản hồi HTTP
Trình cố vấn Analytics sử dụng bộ nhớ phiên để tương quan kết quả với khoảng thời gian trước đó.
{
"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%"
}
]
}
}
}
]
}
Cấu trúc phản hồi và khối dữ liệu
Đối tượng ChatResponse trả về các thành phần có cấu trúc trong mảng blocks:
| Loại khối | Trường | Mô tả |
|---|---|---|
| Văn bản tường thuật | blocks[].text |
Giải thích dễ hiểu và thông tin phân tích tổng quan. |
| Bảng có cấu trúc | blocks[].table |
Bảng phân tích dữ liệu dạng bảng chứa headers (tên và kiểu dữ liệu) và rows (giá trị ô). |
Loại dữ liệu tiêu đề bảng
Các cột trong blocks[].table.headers mô tả loại dữ liệu ngữ nghĩa:
string: Giá trị văn bản theo danh mục (ví dụ:"desktop","/shop/apparel").float: Số dấu phẩy động dạng số.
Quản lý hạn mức trò chuyện
Các yêu cầu của Trợ lý Analytics tiêu thụ mã thông báo trò chuyện dựa trên độ phức tạp của truy vấn. Trạng thái hạn mức hiện tại được trả về trong propertyQuota khi returnPropertyQuota là true:
tokensPerDay: Giới hạn mã thông báo hằng ngày và số dư còn lại.tokensPerHour: Giới hạn tốc độ theo khung thời gian trượt theo giờ và số dư còn lại.
Các ứng dụng tích hợp được đề xuất
Phương thức properties.chat mở ra một số cấu trúc tích hợp giữa các nhóm và công cụ:
Bot trò chuyện và cộng tác dành cho doanh nghiệp
Kết nối không gian làm việc trò chuyện nhóm trực tiếp với Google Analytics.
- Phiên theo luồng: Lưu trữ
sessionIdtheo mã nhận dạng chuỗi trò chuyện để cho phép các thành viên trong nhóm cùng nhau đặt câu hỏi tiếp theo. - Kết xuất thẻ thông tin chi tiết: Định dạng các khối phản hồi
tablethành các tiện ích thẻ tương tác.
Các công cụ Giao thức ngữ cảnh mô hình (MCP) và tác nhân AI tự trị
Trang bị cho các trình điều phối LLM (chẳng hạn như Gemini, LangChain hoặc Claude) một công cụ phân tích GA:
- Thay vì buộc LLM tạo các truy vấn
runReportphức tạp, tác nhân LLM có thể gọi phương thứcchatbằng ý định sử dụng ngôn ngữ tự nhiên. - Trợ lý nhận được các bản tóm tắt có độ chính xác cao và các bảng có cấu trúc để tổng hợp thành các đề xuất tiếp thị đa kênh.
Bản tóm tắt và cảnh báo tự động dành cho cấp quản lý
Tạo các dịch vụ theo lịch để chủ động điều tra các điểm bất thường:
- Một dịch vụ chạy ngầm theo thời gian định trước hằng ngày sẽ truy vấn: "Tóm tắt các chỉ số hiệu suất chính của ngày hôm qua và xác định mọi trường hợp giảm bất thường về lượt chuyển đổi".
- Nếu phát hiện thấy điểm bất thường, tập lệnh sẽ tự động kích hoạt một truy vấn tiếp theo để chẩn đoán nguyên nhân gốc và đăng một bản tóm tắt lên trang tổng quan nội bộ hoặc hệ thống CRM.