Hướng dẫn cho nhà phát triển

Tài liệu này mô tả cách sử dụng API Báo cáo theo thời gian thực để lấy dữ liệu Google Analytics.

Giới thiệu

API Báo cáo theo thời gian thực giúp bạn báo cáo hoạt động đang diễn ra trên tài sản của mình ngay bây giờ. Để truy cập dữ liệu theo thời gian thực, bạn hãy tạo một truy vấn chỉ định một chế độ xem (hồ sơ) và ít nhất một chỉ số. Bạn cũng có thể cung cấp thêm tham số truy vấn như phương diện và bộ lọc để tinh chỉnh truy vấn của mình. Truy vấn này được gửi đến API Báo cáo theo thời gian thực. API này sẽ trả về dữ liệu dưới dạng bảng.

Nếu bạn mới sử dụng API này, hãy đọc bài viết Tổng quan về API Báo cáo theo thời gian thực để tìm hiểu về API Báo cáo theo thời gian thực và dữ liệu mà API này cung cấp.

Điều kiện tiên quyết

Trước khi sử dụng API Báo cáo theo thời gian thực để lấy dữ liệu Google Analytics:

  • Hãy đọc trang thư viện ứng dụng để biết danh sách đầy đủ các thư viện ứng dụng cụ thể của ngôn ngữ lập trình hoạt động với API.
  • Đọc Hướng dẫn tham khảo để tìm hiểu cách chỉ sử dụng API (mà không cần sử dụng thư viện ứng dụng) để nhận dữ liệu Google Analytics.

Mỗi thư viện ứng dụng cung cấp một đối tượng dịch vụ phân tích duy nhất để truy cập vào tất cả dữ liệu của API Báo cáo theo thời gian thực. Cách tạo một đối tượng dịch vụ:

  1. Đăng ký ứng dụng của bạn trong Google API Console.
  2. Uỷ quyền truy cập vào dữ liệu Google Analytics.
  3. Tạo một đối tượng dịch vụ Analytics.

Nếu bạn chưa hoàn tất những bước này, vui lòng dừng lại và đọc Xin chào hướng dẫn về API Google Analytics. Đây là tài liệu hướng dẫn bạn về các bước đầu tiên để tạo ứng dụng API Google Analytics. Sau đó, bạn biết cách sử dụng API này để lấy dữ liệu Google Analytics.

Sử dụng API Báo cáo theo thời gian thực

Để sử dụng API Báo cáo theo thời gian thực, ứng dụng sẽ:

  1. Truy vấn API Báo cáo theo thời gian thực.
  2. Xử lý Phản hồi của API.

Truy vấn API Báo cáo theo thời gian thực

Đối tượng dịch vụ phân tích cung cấp phương thức để tạo truy vấn API Báo cáo theo thời gian thực. Để biết thông tin chi tiết về các tham số truy vấn và dữ liệu có sẵn cho API, hãy đọc những nội dung sau:

Sau khi bạn xác định một truy vấn, hãy gọi phương thức execute của truy vấn đó để gửi truy vấn đó đến máy chủ của Google Analytics.

Xử lý Phản hồi của API

Nếu thành công đối với một truy vấn đến API Báo cáo theo thời gian thực, API sẽ trả về dữ liệu được yêu cầu như một phần của tài nguyên dữ liệu theo thời gian thực. Hãy xem Tài liệu tham khảo về API Báo cáo theo thời gian thực để biết thông tin chi tiết về định dạng và cấu trúc phản hồi của API.

Nếu xảy ra lỗi, API sẽ trả về mã trạng thái cụ thể và thông báo mô tả lỗi. Mọi ứng dụng đều phải phát hiện và xử lý lỗi. Hãy xem phần Phản hồi lỗi để biết danh sách chi tiết các lỗi và thử lại các đề xuất.

Mã ví dụ

Phần Ví dụ trên trang Dữ liệu theo thời gian thực: nhận cung cấp mã mẫu bằng nhiều ngôn ngữ lập trình để truy vấn API Báo cáo theo thời gian thực và xử lý phản hồi của API.

Ràng buộc truy vấn

Dưới đây là những quy định hạn chế đối với truy vấn API thời gian thực:

  • Nếu chỉ số rt:activeUsers được đưa vào một truy vấn có các bộ lọc phương diện sau đây, thì chỉ toán tử AND và kiểu khớp bằng nhau (==) mới được hỗ trợ.
    • rt:goalId
    • rt:eventAction
    • rt:eventCategory
    • rt:eventLabel

    Vì chỉ số rt:activeUsers chỉ truy xuất số lượng người dùng đang hoạt động trên trang web, vì vậy, đừng sử dụng rt:minutesAgo với rt:activeUsers. Điều này nghĩa là rt:activeUsers ngụ ý rằng rt:minutesAgo bằng 0.

  • Không hỗ trợ bộ lọc chỉ số.
  • Không hỗ trợ tham số fields.

Quản lý hạn mức

Như được mô tả trong phần Giới hạn và hạn mức, hạn mức hằng ngày cho API Báo cáo theo thời gian thực được chia sẻ với các API Google Analytics khác. Nếu bạn thăm dò API Báo cáo theo thời gian thực trong những khoảng thời gian ngắn, thì bạn sẽ nhanh chóng đạt đến giới hạn hạn mức hằng ngày. Khi điều đó xảy ra, các yêu cầu từ các API Google Analytics khác cũng sẽ ngừng hoạt động cho đến khi hạn mức được làm mới.

Dưới đây là một số ví dụ về cách triển khai có thể sử dụng hết hạn mức rất nhanh chóng:

  • Bạn có nhiều trang tổng quan theo thời gian thực đang truy vấn dữ liệu cho một chế độ xem Google Analytics (hồ sơ) duy nhất trong những khoảng thời gian rất ngắn hằng ngày.
  • Bạn có một tài sản có rất nhiều người dùng và đã triển khai một tiện ích theo thời gian thực. Mỗi lần tiện ích này hiển thị với người dùng, bạn đang truy vấn trực tiếp Google Analytics thay vì sử dụng bộ nhớ đệm.

Cách giảm thiểu việc sử dụng hạn mức và quản lý hiệu quả:

  • Triển khai tính năng lưu vào bộ nhớ đệm phía máy chủ. Khi nhiều người dùng đưa ra yêu cầu về cùng một dữ liệu theo thời gian thực, bạn nên trả về phản hồi được lưu vào bộ nhớ đệm thay vì truy vấn trực tiếp API Báo cáo theo thời gian thực cho yêu cầu của từng người dùng. Sau đó, định kỳ làm mới bộ nhớ đệm bằng dữ liệu mới nhất theo thời gian thực tại một khoảng thời gian làm mới hợp lý để tránh vượt quá hạn mức hằng ngày.
  • Kết hợp nhiều truy vấn bằng cách chỉ định kích thước bổ sung và phân tích cú pháp phản hồi ở phía máy chủ hoặc máy khách.
  • Tăng khoảng thời gian mà bạn yêu cầu dữ liệu theo thời gian thực.

Ví dụ: Tính khoảng thời gian làm mới

Nếu định thường xuyên đưa ra các yêu cầu về dữ liệu theo thời gian thực, thì bạn nên chọn khoảng thời gian làm mới hợp lý dựa trên mức sử dụng dự kiến.

Ví dụ: một chế độ xem (hồ sơ) Google Analytics có giới hạn hằng ngày là 10.000 yêu cầu mỗi ngày. Trong một ngày, nếu bạn dự kiến thực hiện 6.000 truy vấn đối với API Báo cáo chính cho một chế độ xem (hồ sơ), thì bạn sẽ còn hạn mức 4.000 yêu cầu cho chế độ xem đó (hồ sơ).

Giả sử bạn quyết định sử dụng API Báo cáo theo thời gian thực để triển khai 3 trang tổng quan theo thời gian thực. Trang tổng quan này chạy truy vấn cả ngày cho dữ liệu theo thời gian thực từ cùng một chế độ xem (hồ sơ). Mỗi trang tổng quan có thể thực hiện khoảng 1.333 truy vấn mỗi ngày (4.000 truy vấn / 3 trang tổng quan). Một ngày có 86.400 giây. Do đó, khoảng thời gian làm mới cho mỗi trang tổng quan phải lớn hơn 65 giây (86.400 / 1.333) để tổng số yêu cầu hằng ngày cho chế độ xem (hồ sơ) thấp hơn giới hạn 4.000 hằng ngày.