Sử dụng Ask Advisor trong Google Analytics theo phương thức lập trình để truy vấn và phân tích dữ liệu của bạn

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:

  1. 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.
  2. 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 đó?").
  3. 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 table có cấu trúc với tiêu đề cột và hàng.
  4. 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 returnPropertyQuota thành true.

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

  1. Cài đặt và khởi chạy CLI gcloud.

  2. Để 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"
    
  3. 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.

  4. Đị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_ID bằng mã nhận dạng của dự án và PROPERTY_ID bằng mã nhận dạng của tài sản Google Analytics.

      export PROJECT_ID=PROJECT_ID
      export 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 sessionId mới được chỉ định mà bạn có thể dùng cho các lượt tiếp theo.
  • Một danh sách blocks chứ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ề propertyQuota củ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ữ sessionId theo 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 table thà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 runReport phức tạp, tác nhân LLM có thể gọi phương thức chat bằ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.