Uỷ quyền API Trình quản lý thẻ

Tài liệu này mô tả cách một ứng dụng có thể được uỷ quyền để gửi yêu cầu đến API Trình quản lý thẻ.

Uỷ quyền yêu cầu

Để người dùng có thể xem thông tin tài khoản của mình trên bất kỳ trang web nào của Google, trước tiên, họ phải đăng nhập bằng Tài khoản Google. Tương tự như vậy, 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 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 tới API Trình quản lý thẻ 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 đối với API Trình quản lý thẻ phải do một người dùng đã xác thực ủy quyề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:

  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 Trình quản lý thẻ trong Bảng điều khiển API của Google. (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 Trình quản lý thẻ:

Phạm vi Ý nghĩa
https://www.googleapis.com/auth/tagmanager.readonly Xem vùng chứa Trình quản lý thẻ của Google.
https://www.googleapis.com/auth/tagmanager.edit.containers Quản lý vùng chứa Trình quản lý thẻ của Google.
https://www.googleapis.com/auth/tagmanager.delete.containers Xoá vùng chứa Trình quản lý thẻ của Google.
https://www.googleapis.com/auth/tagmanager.edit.containerversions Quản lý phiên bản vùng chứa Trình quản lý thẻ của Google.
https://www.googleapis.com/auth/tagmanager.publish Xuất bản vùng chứa Trình quản lý thẻ của Google.
https://www.googleapis.com/auth/tagmanager.manage.users Quản lý quyền của người dùng đối với dữ liệu Trình quản lý thẻ của Google.
https://www.googleapis.com/auth/tagmanager.manage.accounts Quản lý tài khoản Trình quản lý thẻ của Google.

Để 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).

Bắt đầu

Để bắt đầu sử dụng API Trình quản lý thẻ, 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 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ữ thông tin một cách an toàn.

Luồng OAuth 2.0 phổ biến

Các nguyên tắc sau đây trình bày 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 với hoạt động truy cập tự động/ngoại tuyến/theo lịch vào tài khoản Trình quản lý thẻ của Google của người dùng.

Ví dụ:
  • Tự động cập nhật thông tin trên Trình quản lý thẻ từ một máy chủ.

Phía máy khách

Rất phù hợp khi người dùng tương tác trực tiếp với ứng dụng để truy cập vào Tài khoản Trình quản lý thẻ của Google trong trình duyệt. Quy trình này giúp loại bỏ nhu cầu về khả năng phía máy chủ, nhưng cũng khiến việc báo cáo tự động/ngoại tuyến/theo lịch không thực sự hiệu quả.

Ví dụ:
  • Công cụ định cấu hình dựa trên trình duyệt tuỳ chỉnh.

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

Đối với 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. Phương thức 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 dành cho máy tính 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 trên Bảng điều khiển API duy nhất cho ứng dụng của mình. Điều này giúp người dùng cài đặt đơn giản hơn.

Tài khoản dịch vụ

Hữu ích khi truy cập tự động/ngoại tuyến/theo lịch vào tài khoản Trình quản lý thẻ của Google của riêng bạn. Ví dụ: để tạo một công cụ tuỳ chỉnh giúp bạn giám sát tài khoản Trình quản lý thẻ của Google của riêng mình và chia sẻ công cụ đó với những người dùng khác.

Khắc phục sự cố

Nếu access_token đã hết hạn hoặc bạn sử dụng sai phạm vi cho một lệnh gọi API cụ thể, thì bạn sẽ nhận được mã trạng thái 401 trong phản hồi.

Nếu người dùng được uỷ quyền không có quyền truy cập vào tài khoản hoặc vùng chứa Trình quản lý thẻ của Google hoặc vùng chứa, thì bạn sẽ nhận được mã trạng thái 403 trong phản hồi. Hãy đảm bảo bạn được cấp quyền cho đúng người dùng và bạn đã được cấp quyền để truy cập vào tài khoản hoặc vùng chứa Trình quản lý thẻ.

Playground OAuth 2.0

Ứng dụng OAuth 2.0 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 đề của yêu cầu HTTP cần thiết để tạo truy vấn được uỷ quyền. Nếu không được phép hoạt động trong ứng dụng của riêng bạn, 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 các 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. Bước kiểm tra này là một cách đơn giản để đảm bảo bạn đang định dạng các yêu cầu của mình đúng cách.

Cấp không hợp lệ

Nếu bạn nhận được phản hồi lỗi invalid_grant khi cố gắng sử dụng mã làm mới, thì lỗi đó có thể do một hoặc cả hai nguyên nhân sau:

  1. Đồng hồ trên máy chủ của bạn không đồng bộ hoá với NTP.
  2. Bạn đã vượt quá giới hạn mã thông báo 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 Trình quản lý thẻ của Google. Ví dụ: tính năng này hữu ích trong trường hợp 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 Trình quản lý thẻ của Google. Trong trường hợp này, cần có 2 mã làm mới, mỗi mã cho một lượt cài đặt. 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ẽ không hợp lệ. Nếu ứng dụng cố gắng dùng mã làm mới đã hết hiệu lực, thì phản hồi lỗi invalid_grant sẽ được trả về. Mỗi tổ hợp mã ứng dụng khách/tài khoản riêng biệt có thể có tối đa 25 mã làm mới. (Xin lưu ý rằng giới hạn này có thể thay đổi.) Nếu ứng dụng tiếp tục yêu cầu mã làm mới cho cùng một tổ hợp Client-ID/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 sẽ không hợp lệ. Mã thông báo làm mới được yêu cầu thứ 27 sẽ làm mất hiệu lực của mã thông báo phát hành thứ 2, v.v.