API báo cáo chính – Uỷ quyền

Hướng dẫn này mô tả cách một ứng dụng cho phép các yêu cầu đến API báo cáo chính.

Uỷ quyền yêu cầu

Trước khi người dùng có thể xem thông tin tài khoản của họ trên trang web Google Analytics, trước tiên họ phải đăng nhập vào Tài khoản Google của mình. Tương tự, khi người dùng truy cập vào ứng dụng của bạn lần đầu tiên, họ cần phải cho phép ứng dụng truy cập vào dữ liệu của họ.

Mọi yêu cầu mà ứng dụng của bạn gửi đến API Analytics phải bao gồm một mã uỷ quyền. Mã này cũng giúp Google xác định ứng dụng của bạn.

Giới thiệu về giao thức cấp phép

Ứng dụng của bạn phải sử dụng OAuth 2.0 để cấp phép các yêu cầu. Chúng tôi không hỗ trợ giao thức cấp phép nào khác. Nếu ứng dụng của bạn sử dụng chức năng Đăng nhập bằng Google, thì Google sẽ giúp bạn xử lý một số bước trong quá trình cấp phép.

Cấp phép cho các yêu cầu bằng OAuth 2.0

Tất cả các yêu cầu đến API Analytics phải được người dùng đã xác thực cho phép.

Các chi tiết của quy trình cấp phép đối với OAuth 2.0 sẽ khác nhau đôi chút tuỳ thuộc vào loại ứng dụng bạn đang viết. Quy trình chung sau đây áp dụng cho tất cả các loại ứng dụng:

  1. Khi tạo ứng dụng của mình, bạn sẽ đăng ký ứng dụng bằng Google API Console. Sau đó, Google cung cấp thông tin bạn sẽ cần sau này, chẳng hạn như mã ứng dụng khách và mật khẩu ứng dụng khách.
  2. Kích hoạt API Analytics trong Google API Console. (Nếu API không được liệt kê trong API Console, thì hãy bỏ qua bước này.)
  3. Khi cần quyền truy cập vào dữ liệu người dùng, ứng dụng sẽ yêu cầu Google cung cấp phạm vi truy cập cụ thể.
  4. Google hiển thị màn hình yêu cầu sự đồng ý cho người dùng để hỏi xem họ có cho phép ứng dụng của bạn yêu cầu một số dữ liệu của họ hay không.
  5. Nếu người dùng đồng ý, thì Google sẽ cấp cho ứng dụng của bạn một mã truy cập ngắn hạn.
  6. Sau đó, ứng dụng yêu cầu dữ liệu người dùng và đính kèm mã truy cập trong yêu cầu.
  7. Nếu xác định rằng yêu cầu của bạn và mã này là hợp lệ, Google sẽ trả về dữ liệu mà ứng dụng yêu cầu.

Một số quy trình cấp phép có các bước bổ sung khác, chẳng hạn như sử dụng mã làm mới để lấy mã truy cập mới. Để biết thông tin chi tiết về quy trình cho các loại ứng dụng khác nhau, hãy xem tài liệu về OAuth 2.0 của Google.

Dưới đây là thông tin về phạm vi của OAuth 2.0 cho API Analytics:

Phạm vi Ý nghĩa
https://www.googleapis.com/auth/analytics.readonly Quyền chỉ có thể đọc đối với Analytics API.

Để yêu cầu quyền truy cập bằng OAuth 2.0, ứng dụng của bạn cần thông tin về mức truy cập, cũng như thông tin mà Google cung cấp khi bạn đăng ký ứng dụng của mình (chẳng hạn như mã ứng dụng khách và mật khẩu ứng dụng khách).

Mẹo: Thư viện ứng dụng API Google có thể xử lý một số bước trong quy trình cấp phép cho bạn. Thư viện này được cung cấp bằng nhiều ngôn ngữ lập trình. Hãy xem trang về các thư viện và mẫu để biết thêm chi tiết.

Các luồng OAuth 2.0 phổ biến

Dưới đây là các trường hợp sử dụng phổ biến cho các quy trình OAuth 2.0 cụ thể:

Máy chủ web

Quy trình này phù hợp cho việc truy cập tự động, ngoại tuyến hoặc theo lịch vào dữ liệu Google Analytics của người dùng.

Ví dụ:

  • Tự động cập nhật trang tổng quan của người dùng bằng dữ liệu mới nhất của Google Analytics.

Phía máy khách

Quy trình này lý tưởng cho những ứng dụng khi người dùng tương tác trực tiếp với ứng dụng để truy cập vào dữ liệu Google Analytics của họ trong trình duyệt. Giải pháp này loại bỏ nhu cầu sử dụng các tính năng phía máy chủ, nhưng khiến cho việc báo cáo tự động, ngoại tuyến hoặc báo cáo theo lịch trở nên không thực tế.

Ví dụ:

Ứng dụng đã cài đặt

Quy trình này dành cho các ứng dụng được phân phối dưới dạng gói và do người dùng cài đặt. Quy trình này yêu cầu ứng dụng hoặc người dùng phải có quyền truy cập vào một trình duyệt để hoàn tất quy trình xác thực.

Ví dụ:

  • Tiện ích máy tính để bàn trên PC hoặc Mac.
  • Trình bổ trợ cho hệ thống quản lý nội dung – Lợi ích của quy trình này so với máy chủ web hoặc phía máy khách là bạn có thể sử dụng một dự án Bảng điều khiển API duy nhất cho ứng dụng của mình. Việc này giúp tạo báo cáo tổng hợp và người dùng dễ dàng cài đặt hơn.

Tài khoản dịch vụ

Tài khoản dịch vụ rất hữu ích cho việc truy cập tự động, ngoại tuyến hoặc theo lịch vào dữ liệu Google Analytics cho tài khoản của riêng bạn. Ví dụ: để tạo một trang tổng quan trực tiếp chứa dữ liệu Google Analytics của riêng bạn và chia sẻ trang tổng quan đó với những người dùng khác.

Để bắt đầu sử dụng API Analytics, trước tiên, bạn cần sử dụng công cụ thiết lập. Công cụ này sẽ hướng dẫn bạn cách tạo dự án trong Bảng điều khiển API của Google, bật API và tạo thông tin đăng nhập.

Để thiết lập tài khoản dịch vụ mới, hãy làm như sau:

  1. Nhấp vào Tạo thông tin xác thực > Khoá tài khoản dịch vụ.
  2. Chọn tải khoá công khai/riêng tư của tài khoản dịch vụ xuống dưới dạng tệp P12 tiêu chuẩn hoặc dưới dạng tệp JSON có thể được tải bằng thư viện ứng dụng API của Google.

Cặp khóa công khai/riêng tư mới của bạn sẽ được tạo và tải xuống máy của bạn; đây là bản sao duy nhất của khóa này. Bạn có trách nhiệm lưu trữ an toàn.

Khắc phục sự cố

Bạn không uỷ quyền được trong các trường hợp sau:

  • Bạn sẽ nhận được mã trạng thái 401 nếu access_token đã hết hạn hoặc nếu bạn đang sử dụng sai phạm vi cho API.

  • Bạn sẽ nhận được mã trạng thái 403 nếu người dùng được uỷ quyền không có quyền truy cập vào chế độ xem (hồ sơ). Đảm bảo bạn được uỷ quyền với đúng người dùng và họ thực sự có chế độ xem (hồ sơ) bạn đã chọn.

Nền tảng OAuth 2.0

Công cụ này cho phép bạn xem toàn bộ quy trình uỷ quyền thông qua một giao diện web. Công cụ này cũng hiển thị tất cả tiêu đề của yêu cầu HTTP cần thiết để tạo một truy vấn được uỷ quyền. Nếu không thể nhận được uỷ quyền để hoạt động trong ứng dụng của chính mình, thì bạn nên cố gắng để ứng dụng đó hoạt động thông qua OAuth 2.0 Playground. Sau đó, bạn có thể so sánh tiêu đề HTTP và yêu cầu từ Playground với nội dung mà ứng dụng của bạn đang gửi đến Google Analytics. Bước kiểm tra này là một cách đơn giản để đảm bảo bạn định dạng yêu cầu đúng cách.

Quyền cấp không hợp lệ

Khi cố gắng sử dụng mã làm mới, bạn sẽ gặp lỗi invalid_grant:

Ứng dụng có thể yêu cầu nhiều mã làm mới để truy cập vào một tài khoản Google Analytics.

Ví dụ: nếu người dùng muốn cài đặt một ứng dụng trên nhiều máy và truy cập vào cùng một tài khoản Google Analytics, thì sẽ cần có một mã riêng cho từng máy. Khi số lượng mã thông báo làm mới vượt quá giới hạn, các mã thông báo cũ sẽ trở nên không hợp lệ. Nếu ứng dụng cố gắng dùng mã làm mới không hợp lệ, thì phản hồi lỗi invalid_grant sẽ được trả về.

Giới hạn cho mỗi cặp ứng dụng khách OAuth 2.0 và tài khoản Google Analytics riêng biệt là 25 mã làm mới. Nếu ứng dụng tiếp tục yêu cầu mã làm mới cho cùng một cặp Ứng dụng/Tài khoản, thì sau khi mã làm mới thứ 26 được phát hành, mã làm mới đầu tiên được cấp trước đó sẽ không còn hợp lệ. Mã thông báo làm mới được yêu cầu thứ 27 sẽ vô hiệu hoá mã thông báo được phát hành trước đó thứ hai, v.v.