Ủy quyền

Hướng dẫn này mô tả cách một ứng dụng uỷ quyền cho các yêu cầu gửi đến User Deletion API.

Cấp phép cho yêu cầu

Trước khi xem thông tin tài khoản trên trang web Google Analytics, trước tiên, người dùng phải đăng nhập vào Tài khoản Google của họ. Tương tự, khi truy cập vào ứng dụng của bạn lần đầu tiên, người dùng cần uỷ quyền cho ứng dụng của bạn 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 Analytics API đều phải có 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 đối với API Analytics đều phải được người dùng đã xác thực cấp 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 Analytics API 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 truy cập OAuth 2.0 cho API Analytics:

Phạm vi Ý nghĩa
https://www.googleapis.com/auth/analytics.user.deletion Xoá dữ liệu bằng User Deletion 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

Sau đây là danh sách các trường hợp sử dụng phổ biến cho các luồng OAuth 2.0 cụ thể:

Máy chủ web

Quy trình này phù hợp với quyền 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 người dùng bằng dữ liệu mới nhất của Google Analytics.

Phía máy khách

Luồng này phù hợp với những ứng dụng mà người dùng tương tác trực tiếp để truy cập vào dữ liệu Google Analytics của họ trong một trình duyệt. Điều này giúp bạn không cần đến các chức năng phía máy chủ, nhưng khiến việc báo cáo tự động, ngoại tuyến hoặc 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 những ứng dụng được phân phối dưới dạng một 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 có quyền truy cập vào trình duyệt để hoàn tất quy trình xác thực.

Ví dụ:

  • Một tiện ích trên máy tính để bàn chạy Windows hoặc macOS.
  • Một 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 API Console duy nhất cho ứng dụng của mình. Điều này giúp người dùng có thể xem báo cáo tổng hợp và cài đặt dễ dàng 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 về 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 Analytics API, 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 quy trình tạo dự án trong Google API Console và bật API.

Để thiết lập một 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/khoá 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 mà thư viện ứng dụng API của Google có thể tải.

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ữ cặp khoá một cách an toàn.

Khắc phục sự cố

Yêu cầu uỷ quyền của bạn sẽ không thành công trong những trường hợp sau:

  • Bạn sẽ nhận được mã trạng thái 401 nếu access_token của bạn đã hết hạn hoặc nếu bạn đang sử dụng phạm vi không chính xác 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 bằng đúng người dùng và người dùng đó thực sự có chế độ xem (hồ sơ) mà bạn đã chọn.

Sân chơi OAuth 2.0

Công cụ này cho phép bạn thực hiện 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 đề yêu cầu HTTP cần thiết để thực hiện một truy vấn được uỷ quyền. Nếu không thể cấp phép để hoạt động trong ứng dụng của riêng mình, bạn nên thử cấp phép thông qua OAuth 2.0 Playground. Sau đó, bạn có thể so sánh tiêu đề và yêu cầu HTTP từ sân chơi với những gì ứng dụng của bạn đang gửi đến Google Analytics. Đây là một cách đơn giản để đảm bảo bạn định dạng yêu cầu đúng cách.

Khoản cấp không hợp lệ

Khi bạn cố gắng sử dụng mã làm mới, thao tác này sẽ trả về cho bạn lỗi invalid_grant:

Các ứ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 duy nhất.

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ì mỗi máy sẽ cần một mã thông báo riêng. Khi số lượng mã làm mới vượt quá giới hạn, các mã cũ hơn sẽ trở nên không hợp lệ. Nếu ứng dụng cố gắng sử 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 OAuth 2.0 và tài khoản Google Analytics riêng biệt là 25 mã thông báo 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 Client/Account, thì sau khi mã thông báo thứ 26 được phát hành, mã làm mới thứ nhất đã được phát hành trước đó sẽ trở nên không hợp lệ. Mã thông báo làm mới thứ 27 được yêu cầu sẽ làm mất hiệu lực mã thông báo thứ 2 đã được phát hành trước đó, v.v.