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 API Xoá người dùng.
Cấp phép cho yêu cầu
Trước tiên, người dùng phải đăng nhập vào Tài khoản Google của mình thì mới có thể xem thông tin tài khoản trên trang web Google Analytics. 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 uỷ quyền cho ứ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 tới API Analytics đều phải bao gồm 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 do người dùng đã xác thực thực hiện.
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:
- 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.
- 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.)
- 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ể.
- 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.
- 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.
- 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.
- 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 của 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 API Xoá người dùng. |
Để 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.
Quy trình 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 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
Luồng này phù hợp với các ứ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. Phương thức này giúp loại bỏ nhu cầu sử dụng các tính năng phía máy chủ, nhưng lại khiến việc báo cáo tự động, ngoại tuyến hoặc định kỳ không thực tế.
Ví dụ:
- Một công cụ báo cáo dựa trên trình duyệt, chẳng hạn như Trình khám phá truy vấn của Analytics.
Ứ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 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 dành cho máy tính trên máy tính hoặc máy 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. Điều này cho phép báo cáo tổng hợp và cài đặt đơn giản hơn cho người dùng.
Tài khoản dịch vụ
Tài khoản dịch vụ rất hữu ích khi bạn muốn 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 mình. 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 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, bật API và tạo thông tin xác thực.
Để thiết lập tài khoản dịch vụ mới, hãy làm như sau:
- Nhấp vào Tạo thông tin xác thực > Khoá tài khoản dịch vụ.
- 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 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ữ 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
401nếuaccess_tokencủa bạn đã 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
403nếu người dùng được uỷ quyền không có quyền truy cập vào chế độ xem (hồ sơ). Hãy đả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.
OAuth 2.0 playground
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 giao diện web. Công cụ này cũng hiển thị tất cả cá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ể được cấp quyền để hoạt động trong ứng dụng của riêng mình, bạn nên thử làm cho ứng dụng đó hoạt động thông qua OAuth 2.0 Playground. Sau đó, bạn có thể so sánh các tiêu đề HTTP và yêu cầu từ Kotlin Playground với nội dung mà ứ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 các yêu cầu của mình đúng cách.
Quyền cấp không hợp lệ
Khi bạn cố gắng sử dụng mã thông báo làm mới, mã sau đây sẽ trả về lỗi invalid_grant:
- Đồng hồ trên máy chủ của bạn không đồng bộ hoá với giao thức thời gian mạng – NTP.
- Đã vượt quá giới hạn mã làm mới.
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.
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 có 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ã thông báo cũ hơn sẽ trở thành không hợp lệ. Nếu ứng dụng cố gắng sử dụng mã thông báo làm mới không hợp lệ, thì hệ thống sẽ trả về phản hồi lỗi invalid_grant.
Giới hạn cho mỗi cặp ứng dụng OAuth 2.0 và tài khoản Google Analytics 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ã thông báo làm mới cho cùng một cặp Ứng dụng/Tài khoản, thì sau khi mã thông báo thứ 26 được phát hành, mã thông báo làm mới thứ nhất đã phát hành trước đó sẽ trở nên không 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 thứ 2 được phát hành trước đó, v.v.