Cấu hình của dự án trên Google Cloud

Trang này cung cấp thông tin bạn cần biết về cách tạo và định cấu hình dự án Google Cloud cho các tiện ích bổ sung của Lớp học. Các dự án Google Cloud được dùng để triển khai tính năng Đăng nhập một lần bằng Google thông qua OAuth 2.0 (Google SSO), để uỷ quyền cho các yêu cầu do tiện ích bổ sung của bạn đưa ra và để quản lý trang thông tin của tiện ích bổ sung trong cửa hàng Google Workspace Marketplace.

Để biết thêm thông tin chung về cách phát hành tiện ích bổ sung lên Marketplace, hãy xem bài viết Phát hành ứng dụng.

Tạo dự án trên Google Cloud

Có hai loại dự án để tạo: dự án riêng tư dùng để phát triển và dự án công khai mà người dùng cuối có thể truy cập. Nhãn "công khai" và "riêng tư" đề cập đến mức độ hiển thị của ứng dụng trong Google Workspace Marketplace; chỉ người dùng trong miền tạo ứng dụng mới có thể cài đặt ứng dụng riêng tư trên Marketplace, còn ứng dụng công khai trên Marketplace thì bất kỳ miền Google Workspace nào cũng có thể sử dụng. Đây phải là hai ứng dụng riêng biệt, vì một dự án không thể vừa công khai vừa riêng tư. Ứng dụng công khai phải được xem xét và phê duyệt trước khi có mặt trên trang web thương mại.

Để biết thông tin chung về cách tạo dự án trên Google Cloud, hãy truy cập vào bài viết Tạo dự án trên Google Cloud.

Tạo dự án công khai trên Google Cloud

Dự án này đại diện cho ứng dụng bổ sung mà quản trị viên, giáo viên và học viên có thể truy cập. Dự án công khai phải được nhóm Google Workspace Marketplace xem xét và phê duyệt thì mới có thể khởi chạy hoặc cài đặt.

  1. Tạo một dự án Google Cloud mới trong miền phát hành chính thức.

    Tạo dự án trên Google Cloud

  2. Bật API Lớp học trong dự án trên Google Cloud.

    Bật API Lớp học

  3. Bật SDK Google Workspace Marketplace trong dự án trên Google Cloud.

    Bật SDK Google Workspace Marketplace

  4. Đặt Cấu hình ứng dụng Mức độ hiển thị ứng dụng của SDK Thị trường thành Công khai và đánh dấu vào hộp Không công khai.

  5. Điền vào các trường bắt buộc trong trang Trang thông tin trên Cửa hàng Play của SDK Marketplace rồi nhấp vào XEM XÉT PHÁT HÀNH.

  6. Nhóm Google Workspace Marketplace sẽ xem xét ứng dụng của bạn. Họ sẽ liên hệ với bạn qua địa chỉ email của nhà phát triển được chỉ định trong SDK Marketplace. Sau khi ứng dụng được phê duyệt, hãy bỏ đánh dấu hộp Không được liệt kê để giáo viên và quản trị viên có thể tìm thấy ứng dụng đó trong Marketplace.

Tạo dự án riêng trên Google Cloud

Dự án riêng tư này đại diện cho ứng dụng bổ sung dùng để phát triển. Người dùng bên ngoài miền tạo ứng dụng này không thể truy cập vào ứng dụng, nhưng không cần phê duyệt trước khi cài đặt. Do đó, Google khuyên bạn nên sử dụng dự án này để phát triển và kiểm thử tiện ích bổ sung trong một môi trường được kiểm soát.

Bạn cần có quyền truy cập vào một miền Google Workspace for Education có giấy phép Teaching & Learning hoặc Plus để tạo dự án riêng tư. Nếu bạn chưa có quyền truy cập vào một miền như vậy, hãy làm theo các bước sau để thiết lập miền minh hoạ Google Workspace for Education, nâng cấp miền đó lên giấy phép Plus và cho phép miền đó truy cập vào API tiện ích bổ sung của Lớp học:

  1. Hoàn tất các bước để lấy miền thử nghiệm cho nhà phát triển.

  2. Khi đăng nhập với tư cách quản trị viên trong miền minh hoạ, hãy tạo một dự án Google Cloud mới.

    Tạo dự án trên Google Cloud

    Nếu bạn không thể truy cập vào Google Cloud Console hoặc tạo dự án trên Google Cloud, hãy kiểm tra những thông tin sau trong Bảng điều khiển dành cho quản trị viên:

    • Truy cập vào trang Cài đặt tài khoản > Cài đặt quyền truy cập theo độ tuổi rồi chọn tuỳ chọn Tất cả người dùng trong nhóm hoặc đơn vị tổ chức này đều từ 18 tuổi trở lên.
    • Trong phần Ứng dụng > Các dịch vụ bổ sung của Google:
    • Google Cloud Platform ĐANG BẬT cho mọi người.
    • Chế độ cài đặt tạo dự án là Cho phép người dùng tạo dự án.
    • Chế độ cài đặt quyền truy cập Cloud Shell là Cho phép truy cập Cloud Shell.

  3. Hoàn tất và gửi biểu mẫu yêu cầu nâng cấp miền minh hoạ. Việc gửi biểu mẫu này yêu cầu Google nâng cấp miền minh hoạ của bạn lên Google Workspace for Education Plus với 10 giấy phép và cho phép dự án trên Google Cloud của bạn truy cập vào API tiện ích bổ sung của Lớp học.

    Bạn sẽ nhận được email khi quá trình nâng cấp và thêm vào danh sách cho phép hoàn tất. Chỉ định giấy phép Plus cho tài khoản giáo viên thử nghiệm trong Bảng điều khiển dành cho quản trị viên. Trong mục Directory > Users (Thư mục > Người dùng), hãy tạo hoặc chọn tài khoản giáo viên thử nghiệm. Trong phần Giấy phép của từng giáo viên, hãy xác nhận rằng Google Workspace for Education Plus đã được Cấp.

  4. Bật API Lớp học trong dự án trên Google Cloud.

    Bật API Lớp học

  5. Bật SDK Google Workspace Marketplace trong dự án trên Google Cloud.

    Bật SDK Google Workspace Marketplace

  6. Đặt Cấu hình ứng dụng Chế độ hiển thị ứng dụng của SDK Marketplace thành riêng tư.

  7. Điền vào các trường bắt buộc trong trang Trang thông tin trên Cửa hàng Play của SDK Marketplace rồi nhấp vào XEM XÉT. Sau khi trang thông tin ứng dụng được xuất bản, người dùng trong miền có thể tìm và cài đặt ứng dụng trong Google Workspace Marketplace hoặc bằng cách truy cập vào URL ứng dụng xuất hiện trên trang Trang thông tin trên Cửa hàng Play.

OAuth 2.0

Để truy cập vào API Lớp học, bạn phải có sự đồng ý truy cập dữ liệu của người dùng. Bạn có thể lấy các mã thông báo này bằng cách yêu cầu Google truy cập vào các phạm vi OAuth cho người dùng đã đăng nhập và nhận một mã thông báo có thể dùng để thực hiện các lệnh gọi API đến Google Lớp học. Bạn phải định cấu hình phạm vi trong trang thông tin trên Cửa hàng Google Workspace Marketplace để quản trị viên miền có thể thay mặt người dùng miền của họ đồng ý nếu họ cài đặt tiện ích bổ sung.

Vì phạm vi của Lớp học là Dữ liệu nhạy cảm, nên bạn phải yêu cầu xác minh OAuth trước khi ra mắt tiện ích bổ sung. Nếu không, người dùng sẽ thấy thông báo cảnh báo rằng ứng dụng chưa được xác minh và chỉ một số ít người dùng mới có thể truy cập vào sản phẩm của bạn. Hãy xem thông tin tổng quan về trình tự xem xét để biết thêm thông tin về quy trình xác minh.

Hãy xem trang Phạm vi OAuth cho API của Google để biết danh sách chi tiết về tất cả phạm vi hiện có và cách sử dụng các phạm vi đó. Xem phần Định cấu hình trang OAuth trong tài liệu về Workspace để biết thông tin chung về cấu hình OAuth.

Quyền của người dùng

Ứng dụng web của bạn phải yêu cầu ít nhất một trong các phạm vi sau:

  • https://www.googleapis.com/auth/userinfo.email, cho phép ứng dụng xem địa chỉ email của người dùng.
  • https://www.googleapis.com/auth/userinfo.profile, cho phép một ứng dụng xem thông tin cá nhân như chân dung, tên và họ, cũng như các thông tin cá nhân khác mà người dùng đã công khai.

Sau khi người dùng đã uỷ quyền cho một trong các phạm vi này trong tiện ích bổ sung của bạn, họ sẽ được xác định bằng thông số truy vấn login_hint. Tham số này được truyền đến bất kỳ URL nào của ứng dụng web khi một iframe được mở. Nếu người dùng chưa uỷ quyền cho một trong các phạm vi này, thì login_hint sẽ không được gửi.

login_hint là một thông số OpenID Connect chuẩn mà bạn có thể tuỳ ý truyền đến Google khi sử dụng tính năng Đăng nhập bằng Google hoặc yêu cầu mã thông báo OAuth. Mục đích của việc này là giúp người dùng cuối có trải nghiệm uỷ quyền suôn sẻ hơn.

Phạm vi của tiện ích bổ sung dành cho Lớp học

Sau đây là các phạm vi dành riêng cho tiện ích bổ sung của Lớp học:

  • https://www.googleapis.com/auth/classroom.addons.teacher, cho phép truy cập vào tất cả các phương thức API.
  • https://www.googleapis.com/auth/classroom.addons.student, cho phép truy cập vào các hoạt động xác thực và đọc tệp đính kèm.

Ngay cả khi có mã truy cập OAuth hợp lệ cho biết thông tin xác thực của người dùng, các lệnh gọi API vẫn bị hạn chế theo các yêu cầu bổ sung:

  • Tất cả các phương thức đều yêu cầu người dùng phải là giáo viên hoặc học viên trong khoá học do courseId chỉ định trong yêu cầu.
  • Người dùng phải là giáo viên thì mới có thể tạo, cập nhật, xoá và chuyển điểm bài tập đính kèm.
  • Lệnh gọi đến một bài đăng cụ thể trên Google Lớp học sẽ được kiểm tra theo các bước sau.
    • Khi một tiện ích bổ sung đã có ít nhất một tệp đính kèm trên một bài đăng, tiện ích bổ sung đó có thể đưa ra yêu cầu về:
      • Xác thực việc chạy iframe
      • Thao tác đọc, cập nhật và xoá tệp đính kèm
      • Nội dung cập nhật về điểm của bài đăng đó
    • Khi mở iframe Khám phá tệp đính kèm lần đầu tiên, tiện ích bổ sung có thể chưa có tệp đính kèm trên bài đăng. Chúng tôi cung cấp một tham số truy vấn addOnToken có thể dùng để đưa ra yêu cầu cho những mục sau:
      • Tạo tệp đính kèm trong bài đăng (bắt buộc phải có addOnToken)
      • Xác thực khi khởi chạy (addOnToken được xác thực nếu được cung cấp và là bắt buộc khi tiện ích bổ sung không có tệp đính kèm hiện có trên bài đăng)

Xác minh OAuth

Tiện ích bổ sung của Lớp học sử dụng API của Google để truy cập vào dữ liệu của người dùng Google.

Hãy tham khảo Câu hỏi thường gặp về quy trình xác minh API OAuth để biết thêm thông tin về quy trình xác minh.

Trang thông tin trên Google Workspace Marketplace

Để biết thông tin chung về cấu hình SDK Google Workspace Marketplace, hãy truy cập vào bài viết Bật và định cấu hình SDK Google Workspace Marketplace và Tạo trang thông tin trên Cửa hàng Google Workspace Marketplace.

Những điều cần cân nhắc khi đăng trang thông tin

Trang thông tin trên Cửa hàng SDK của Marketplace trong dự án công khai trên Google Cloud của bạn sẽ chỉ định tên và nội dung mô tả ứng dụng dành cho người dùng cuối. Bạn có thể cung cấp những thông tin chi tiết này bằng nhiều ngôn ngữ trong phần Thông tin chi tiết về ứng dụng.

Hãy làm theo các nguyên tắc sau trong trang thông tin:

  • Trong phần Thông tin chi tiết về ứng dụng:

    • Tránh sử dụng dấu câu trong Tên ứng dụng. Ví dụ: sử dụng "Tiện ích bổ sung của tôi do Công ty của tôi cung cấp" thay vì "Công ty của tôi: Tiện ích bổ sung của tôi" hoặc "Tiện ích bổ sung của tôi, do Công ty của tôi cung cấp".

    • Nội dung mô tả ngắn và Nội dung mô tả chi tiết không được chứa cùng một văn bản.

    + Đảm bảo rằng bạn đã chọn một giá trị cho trường Pricing (Giá). Trường này bao gồm các lựa chọn về giá Miễn phí, Có tính phí, kèm thời gian dùng thử miễn phí, Có tính phí, kèm các tính năng miễn phí và Có tính phí. Bạn không cần chỉ định số tiền chi phí trong trang thông tin trên trang web thương mại.

    • Đảm bảo rằng bạn đã chọn một giá trị cho trường Danh mục. Tài nguyên học thuật hoặc Công cụ dành cho giáo viên và quản trị viên có thể là lựa chọn phù hợp cho tiện ích bổ sung trong Lớp học.

    • Hãy xem các mục được liệt kê trong Mô tả chi tiết về ứng dụng của Marketplace để biết thêm thông tin.

Tích hợp với các dịch vụ thanh toán và cấp phép của Google

Nếu bạn muốn cho phép các ứng dụng của mình trên Google Workspace Marketplace tích hợp với các dịch vụ cấp phép và thanh toán của Google, hãy truy cập vào Marketplace API.

Chế độ cài đặt cài đặt

Tiện ích bổ sung có thể cho phép cài đặt cá nhân ngoài việc cài đặt quản trị viên. Trang này nêu bật một số điểm khác biệt giữa hai loại cài đặt. Trang này không nhằm mục đích quảng bá bất kỳ loại cài đặt nào. Bạn có thể chọn cho phép cài đặt riêng lẻ trong trang Cấu hình ứng dụng SDK Google Workspace Marketplace.

Cài đặt bằng quyền quản trị

Tính năng Cài đặt của quản trị viên cho phép quản trị viên thêm tiện ích bổ sung vào tất cả tài khoản trong một miền hoặc vào các nhóm quyền truy cập hoặc đơn vị tổ chức cụ thể. Chỉ quản trị viên miền mới có thể cài đặt dưới quyền quản trị viên. Quản trị viên có thể đồng ý thay mặt tất cả người dùng trong miền đối với mọi phạm vi truy cập (không bắt buộc); người dùng sẽ không được nhắc đồng ý với bất kỳ phạm vi truy cập nào nếu quản trị viên chọn đồng ý.

Sau đây là một số điều cần cân nhắc liên quan đến việc cài đặt cho quản trị viên.

  • Các chế độ kiểm soát chặt chẽ hơn. Quản trị viên có thể hạn chế những người dùng có thể truy cập vào một tiện ích bổ sung.
  • Khả năng tương thích với giấy phép. Nếu ứng dụng của bạn yêu cầu giấy phép, việc chuyển hướng lượt cài đặt thông qua quản trị viên có thể giúp đảm bảo rằng giấy phép được phân phối và sử dụng đúng cách với tổ chức tương ứng.
  • Giảm gánh nặng cho người dùng cuối. Việc cài đặt bằng quản trị viên sẽ giảm tải thiết lập cho giáo viên và học viên. Điều này có thể mang lại trải nghiệm liền mạch hơn cho người dùng với ít lượt nhấp hơn và ít cơ hội gây nhầm lẫn hơn.

Hãy xem bài viết Cài đặt các ứng dụng trên Marketplace trong miền của bạn để biết thêm thông tin về cách cài đặt bằng quyền quản trị viên và bài viết Cơ cấu tổ chức hoạt động như thế nào để tìm hiểu thêm về đơn vị tổ chức và nhóm quyền truy cập.

Cài đặt riêng lẻ

Lượt cài đặt riêng lẻ sẽ thêm một tiện ích bổ sung vào tài khoản của riêng người dùng. Người dùng sẽ được nhắc đồng ý với phạm vi truy cập của tiện ích bổ sung trong quá trình cài đặt.

Sau đây là một số điều cần cân nhắc liên quan đến việc cài đặt riêng lẻ.

  • Hỗ trợ việc sử dụng. Nhiều người dùng hơn có thể xem và cài đặt tiện ích bổ sung của bạn từ Google Workspace Marketplace. Việc cho phép cài đặt riêng lẻ có thể khuyến khích nhiều giáo viên sử dụng hoặc ủng hộ sản phẩm của bạn hơn.
  • Kiểm thử quản trị viên. Quản trị viên có thể cài đặt từng tiện ích bổ sung để kiểm thử hoặc đánh giá trước khi phê duyệt hoặc cài đặt tiện ích bổ sung đó cho một nhóm lớn hơn.

Ngoài việc thay mặt người dùng cài đặt tiện ích bổ sung, quản trị viên cũng có thể duy trì danh sách cho phép để cho phép người dùng cài đặt các tiện ích bổ sung cho phép cài đặt riêng lẻ. Nếu một tiện ích bổ sung không có trong danh sách cho phép, người dùng vẫn có thể thấy trang thông tin của tiện ích bổ sung đó trong Google Workspace Marketplace nhưng không thể cài đặt tiện ích bổ sung đó; thay vào đó, họ sẽ thấy thông báo giải thích rằng quản trị viên miền chưa cho phép cài đặt tiện ích bổ sung đó. Hãy xem bài viết Quản lý các ứng dụng Google Workspace Marketplace trên danh sách cho phép của bạn để tìm hiểu thêm về hành vi này.

Hãy xem tài liệu về chế độ cài đặt của Google Workspace Marketplace để biết thêm thông tin.

Tích hợp ứng dụng

Bạn phải cung cấp URL iframe khởi chạy trong trường Attachment Setup URI (URI thiết lập tệp đính kèm). URL này được dùng làm giá trị src của iframe cho iframe Khám phá tệp đính kèm. Giáo viên sử dụng iframe Khám phá tệp đính kèm để tìm nội dung hoặc hoạt động đính kèm vào bài tập.

Bạn cũng phải chỉ định tất cả tiền tố URI mà tệp đính kèm được phép từ tiện ích bổ sung của bạn. Tính năng này tăng cường bảo mật bằng cách ngăn chặn các tệp đính kèm từ nguồn trái phép.

Hãy xem trang hướng dẫn về iframe để biết thêm thông tin chi tiết về các trường này.

Tài khoản thử nghiệm

Tạo tài khoản thử nghiệm trên miền minh hoạ để xác minh hành vi chính xác của tiện ích bổ sung riêng tư. Bạn cần có hai tài khoản học viên để kiểm thử việc chuyển đổi giữa các học viên trong iframe Bài tập của học viên.

Tài khoản thử nghiệm được đề xuất:

  • Cô Tammy, tammy.teacher@<your demo domain>
  • Sam Student, sam.student@<your demo domain>
  • Sally Student, sally.student@<your demo domain>

Hãy làm theo quy trình sau để tạo một tài khoản thử nghiệm mới:

  1. Đăng nhập vào Bảng điều khiển dành cho quản trị viên.
  2. Chuyển đến phần Người dùng.
  3. Nhấp vào Thêm người dùng mới (xem Hình 1).
  4. Nhập thông tin của người dùng rồi chỉ định vai trò thích hợp.

Nhấp vào Thêm người dùng mới Hình 1. Vị trí của đường liên kết Thêm người dùng mới trong Bảng điều khiển dành cho quản trị viên.

Hãy làm theo quy trình sau để tạo một nhóm thử nghiệm mới:

  1. Đăng nhập vào Bảng điều khiển dành cho quản trị viên.
  2. Chuyển đến phần Nhóm.
  3. Nhấp vào Tạo nhóm (xem Hình 2).
  4. Nhập thành viên và chủ sở hữu của nhóm.

Nhấp vào Tạo nhóm Hình 2. Vị trí của đường liên kết Tạo nhóm trong Bảng điều khiển dành cho quản trị viên.