Phương thức chat của API Dữ liệu cung cấp quyền truy cập có lập trình vào tính năng Hỏi Cố vấn trong Google 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ù Ask Advisor có sẵn dưới dạng tương tác trong giao diện người dùng của Google Analytics, nhưng chat API cho phép nhà phát triển, 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 và 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
sessionIdđể duy trì nhật ký trò chuyện và đặt 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 đó?"). - Câu trả lời có dữ liệu có cấu trúc: Ngoài câu trả lời dạng văn bản, câu trả lờ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 động 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 thông tin 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ả 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 cuộc trò chuyện 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.
Trường hợp: So sánh với kỳ trước
Tiếp nối kết quả so sánh thiết bị trước đó, bạn yêu cầu Cố vấn 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 |
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 Chat
Yêu cầu của tính năng Ask Advisor sẽ tiêu tốn mã thông báo trò chuyện dựa trên độ phức tạp của câu hỏi.
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 trực tiếp không gian làm việc trò chuyện của nhóm với Google Analytics.
- Phiên theo chuỗi: Lưu trữ
sessionIdtheo mã 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 ngôn ngữ tự nhiên. - Tác nhân nhận được các bản tóm tắt có độ chính xác cao và bảng có cấu trúc để tổng hợp thành các đề xuất tiếp thị đa kênh.
Tự động tóm tắt và cảnh báo cho ban điều hành
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 câu lệnh truy vấn hằng ngày cho dịch vụ chạy ngầm theo thời gian định trước: "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 mức giảm bất thường về số 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.
Các bước tiếp theo
- Hãy thử sổ ghi chú Colab Hỏi cố vấn tương tác để chạy các truy vấn một lượt và nhiều lượt bằng thư viện ứng dụng Python.
- Xem tài liệu tham khảo về API REST
properties.chat. - Tìm hiểu thêm về hạn mức và giới hạn của Data API.