Phương thức chat của Data API cung cấp quyền truy cập theo lập trình vào Ask Advisor trong Google Analytics – một Trợ lý Analytics sử dụng 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ù Ask Advisor 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 nhà phát triển, các tác nhân AI tự động và các công cụ nội bộ tương tác với Ask Advisor theo phương thức 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 và phiên trò chuyện nhiều lượt:
- Truy vấn 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 một
sessionIdđể duy trì nhật ký trò chuyện và đặt các câu hỏi chẩn đoán nối tiếp (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 theo ngày và theo 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 CLI gcloud.
Để 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
Câu trả lờ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ả bản 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
Ask Advisor 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 con người có thể đọc được và thông tin phân tích tổng quan cấp cao. |
| Bảng có cấu trúc | blocks[].table |
Thông tin chi tiết về 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.
Quản lý hạn mức trò chuyện
Các yêu cầu của Ask Advisor tiêu thụ mã thông báo trò chuyện dựa trên độ phức tạp của cụm từ tìm kiếm.
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 hằng 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 trên 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 của bạn trực tiếp với Google Analytics.
- Phiên theo chuỗi: 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.
Cảnh báo và tóm tắt tự động 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 lượt chuyển đổi giảm bất thường".
- 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.