API Xoá người dùng – Uỷ quyền

Hướng dẫn này mô tả cách ứng dụng cấp quyền cho các yêu cầu gửi đến API Xoá người dùng.

Uỷ quyền cho yêu cầu

Trước khi người dùng có thể xem thông tin tài khoản của mình 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 Analytics API đều phải bao gồm mã thông báo 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 gửi đến Analytics API 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 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.

Các 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 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 của người dùng với 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 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. Loại chiến dịch này không cần 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 theo lịch trở nên không khả thi.

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 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ụ:

  • Một tiện ích 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ể dùng một dự án Bảng điều khiển API cho ứng dụng của mình. Điều này giúp tạo báo cáo tổng hợp và giúp 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 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 trang tổng quan trực tiếp về dữ liệu Google Analytics của riêng bạn và chia sẻ dữ liệu đó 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 trong quy trình 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 hay dưới dạng tệp JSON có thể 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ữ mã này một cách an toàn.

Khắc phục sự cố

Yêu cầu uỷ quyền của bạn không thành công trong các 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 không đúng phạm vi cho API.

  • Bạn sẽ nhận được mã trạng thái 403 nếu người dùng được cấp phép 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 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ả 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 uỷ quyền để hoạt động trong ứng dụng của riêng mình, thì bạn nên cố gắng làm cho ứng dụng hoạt động thông qua sân chơi OAuth 2.0. Sau đó, bạn có thể so sánh các tiêu đề HTTP và yêu cầu từ phần mô phỏng đến 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 của mình đúng cách.

Cấp quyền 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:

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ì sẽ cần một mã thông báo riêng cho mỗi máy. Khi số lượng mã làm mới vượt quá giới hạn, các mã thông báo cũ sẽ trở thành 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ã 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 Khách hàng/Tài khoản, thì sau khi mã thông báo thứ 26 được phát hành, mã làm mới đầu tiên đã được phát hành trước đó sẽ trở nên không hợp lệ. Mã làm mới được yêu cầu thứ 27 sẽ vô hiệu hoá mã thông báo đã phát hành lần thứ 2, v.v.