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 các dự án trên Google Cloud cho tiện ích bổ sung của Lớp học. Các dự án trê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 thực hiện 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 xuất bản một tiện ích bổ sung lên Marketplace, hãy xem phần Xuất bản ứng dụng.
Tạo dự án trên Google Cloud
Có 2 loại dự án cần tạo: dự án riêng tư dùng cho quá trình 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 khả năng hiển thị của ứng dụng trong Google Workspace Marketplace; người dùng chỉ có thể cài đặt ứng dụng Marketplace riêng tư trong miền mà ứng dụng đó được tạo, trong khi ứng dụng Marketplace công khai có sẵn cho mọi miền Google Workspace. Đây phải là 2 ứ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ư. Các ứng dụng công khai phải được xem xét và phê duyệt trước khi xuất hiện 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 trang Tạo dự án trên Google Cloud.
Tạo một dự án công khai trên Google Cloud
Dự án này đại diện cho ứng dụng bổ trợ mà quản trị viên, giáo viên và học viên có thể truy cập. Nhóm Google Workspace Marketplace phải xem xét và phê duyệt một dự án công khai trước khi dự án đó có thể được ra mắt hoặc cài đặt.
Tạo một dự án Google Cloud mới trong miền sản xuất của bạn.
Bật Classroom API trong dự án trên Google Cloud.
Bật Google Workspace Marketplace SDK trong dự án trên Cloud.
Đặt Cấu hình ứng dụng Khả năng hiển thị ứng dụng của Marketplace SDK thành Công khai và đánh dấu vào hộp Không công khai.
Điền các trường bắt buộc trong trang Trang thông tin trên Cửa hàng Play của Marketplace SDK rồi nhấp vào XUẤT BẢN.
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 bằng địa chỉ email của nhà phát triển được chỉ định trong Marketplace SDK. Sau khi ứng dụng được phê duyệt, hãy bỏ chọn hộp Chưa công khai để giáo viên và quản trị viên có thể tìm thấy ứng dụng đó trong Marketplace.
Tạo một dự án riêng tư trên Google Cloud
Dự án riêng tư này đại diện cho ứng dụng tiện ích bổ sung dùng để phát triển. Người dùng bên ngoài miền mà ứng dụng được tạo không thể truy cập vào ứng dụng này, nhưng bạn 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 một 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 một miền dùng thử 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:
- Hoàn tất các bước để nhận miền kiểm thử dành cho nhà phát triển.
Trong khi đăng nhập với tư cách là quản trị viên trong miền minh hoạ, hãy tạo một dự án Google Cloud mới.
Tạo một dự án trên Google Cloud
Nếu bạn không truy cập được vào Google Cloud Console hoặc không tạo được dự án trên Cloud, hãy kiểm tra những mục 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 mục 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 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.
Hoàn tất và gửi biểu mẫu yêu cầu nâng cấp miền dùng thử. Khi bạn gửi biểu mẫu này, Google sẽ nâng cấp miền dùng thử 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 Cloud của bạn sử dụng 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 phần Thư mục > Người dùng, hãy tạo hoặc chọn tài khoản giáo viên kiểm thử. Trong phần Giấy phép của mỗi giáo viên, hãy xác nhận rằng Google Workspace for Education Plus được Chỉ định.
Bật Classroom API trong dự án trên Google Cloud.
Bật Google Workspace Marketplace SDK trong dự án trên Cloud.
Đặt Cấu hình ứng dụng Khả năng hiển thị của ứng dụng trong Marketplace SDK thành riêng tư.
Điền các trường bắt buộc trong trang Trang thông tin trên Cửa hàng Play của Marketplace SDK rồi nhấp vào XUẤT BẢN. 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 của ứng dụng xuất hiện trên trang Thông tin trên Cửa hàng Play.
OAuth 2.0
Để truy cập vào Classroom API, bạn cần có sự đồng ý cho phép truy cập vào dữ liệu người dùng. Các mã thông báo này được lấy bằng cách yêu cầu Google cấp quyền truy cập vào các phạm vi của OAuth cho người dùng đã đăng nhập và nhận mã thông báo có thể dùng để thực hiện các lệnh gọi API sau đó đến Google Lớp học. Bạn phải thiết lập các phạm vi trong trang thông tin trên Google Workspace Marketplace để quản trị viên miền có thể thay mặt người dùng trong miền của họ đưa ra sự đồng ý nếu họ cài đặt tiện ích bổ sung.
Vì các phạm vi của Lớp học là 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 có thể truy cập vào sản phẩm của bạn. Hãy xem phần tổng quan về trình tự đánh giá để biết thêm thông tin về quy trình xác minh.
Hãy xem trang Phạm vi OAuth cho các API của Google để biết danh sách chi tiết về tất cả các phạm vi hiện có và cách sử dụng các phạm vi đó. Hãy xem phần Định cấu hình trang OAuth trong tài liệu 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 số các phạm vi sau:
https://www.googleapis.com/auth/userinfo.email, cho phép một ứ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ư ảnh chân dung, tên và họ, cũng như 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 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 tham 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 tiêu chuẩn mà bạn có thể tuỳ ý truyền cho 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 mượt mà 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 thao tác xác thực khi mở và đọc tệp đính kèm.
Ngay cả khi có mã truy cập OAuth hợp lệ biểu thị thông tin đăng nhập của người dùng, các lệnh gọi API vẫn bị hạn chế bởi 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
courseIdchỉ định trong yêu cầu. - Để tạo, cập nhật, xoá tệp đính kèm và chuyển điểm, người dùng phải là giáo viên.
- Các lệnh gọi đến một bài đăng cụ thể trên Google Lớp học sẽ được kiểm soát bằng các bước kiểm tra sau.
- Khi một tiện ích bổ sung đã có ít nhất một tệp đính kèm trên bài đăng, tiện ích đó có thể đưa ra các yêu cầu sau:
- xác thực khi khởi chạy iframe
- Các thao tác đọc, cập nhật và xoá tệp đính kèm
- Số lần cập nhật điểm trên bài đăng đó
- Khi iframe Khám phá tệp đính kèm được mở lần đầu tiên, tiện ích bổ sung có thể chưa có tệp đính kèm nào trên bài đăng. Một tham số truy vấn
addOnTokenđược cung cấp và có thể dùng để đưa ra yêu cầu cho những nội dung 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)
- Tạo tệp đính kèm trong bài đăng (bắt buộc phải có
- Khi một tiện ích bổ sung đã có ít nhất một tệp đính kèm trên bài đăng, tiện ích đó có thể đưa ra các yêu cầu sau:
Xác minh OAuth
Tiện ích bổ sung Lớp học sử dụng các 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 của Google Workspace Marketplace, hãy truy cập vào phần Bật và định cấu hình SDK của Google Workspace Marketplace và Tạo trang thông tin trên cửa hàng Google Workspace Marketplace.
Những điểm cần cân nhắc khi đăng trang thông tin
Trang thông tin trên Cửa hàng Marketplace SDK của dự án Google Cloud công khai sẽ chỉ định tên và nội dung mô tả ứng dụng của bạn cho người dùng cuối. Bạn có thể cung cấp những thông tin này bằng nhiều ngôn ngữ trong phần Chi tiết về ứng dụng.
Hãy tuân thủ các nguyên tắc sau trong trang thông tin của bạn:
- Trong phần Thông tin chi tiết về ứng dụng:
- Tránh sử dụng dấu chấm 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".
- Mô tả ngắn và Mô tả chi tiết không được chứa nội dung giống hệt nhau.
- Đảm bảo rằng bạn đã chọn một giá trị cho trường Định 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ụ cho giáo viên và quản trị viên có thể là lựa chọn phù hợp cho một tiện ích bổ sung Lớp học.
- Hãy xem các mục được liệt kê trong phần Nội dung mô tả chi tiết về ứng dụng của Marketplace để biết thêm thông tin.
- Trong phần Thành phần đồ hoạ:
- Mọi thành phần đồ hoạ được cung cấp đều không bị mờ và đáp ứng các kích thước được chỉ định trong các tiêu chuẩn của Google Workspace Marketplace
- Mọi ảnh chụp màn hình được cung cấp đều thể hiện chính xác trải nghiệm về tiện ích bổ sung của bạn.
- Trong phần Đường liên kết hỗ trợ:
- Đảm bảo rằng bạn đã cung cấp đường liên kết đến Điều khoản dịch vụ của ứng dụng.
- Đảm bảo rằng bạn tuân thủ Nguyên tắc sử dụng thương hiệu của Google API, trong đó có các tên và nội dung mô tả được phép.
- Nếu bạn đề cập đến bất kỳ sản phẩm nào của Google trong trang thông tin, hãy sử dụng tên của sản phẩm đó theo định dạng được cung cấp trong Danh sách nhãn hiệu. Đảm bảo rằng bạn thêm biểu tượng nhãn hiệu (™) nếu được chỉ định; sử dụng "Google Tài liệu™" chứ không phải "Google Tài liệu".
Tích hợp với các dịch vụ cấp phép và thanh toán của Google
Nếu bạn muốn các ứng dụng 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 API Marketplace.
Chế độ cài đặt khi cài đặt
Ngoài việc cài đặt quản trị viên, tiện ích bổ sung còn cho phép cài đặt riêng lẻ. Trang này nêu bật một số điểm khác biệt giữa hai loại quy trình cài đặt. Trang này không nhằm mục đích quảng bá một loại quy trình cài đặt nào. Bạn có thể chọn cho phép cài đặt riêng lẻ hay không trên trang Cấu hình ứng dụng của Google Workspace Marketplace SDK.
Cài đặt bằng quyền quản trị viên
Quản trị viên cài đặt cho phép quản trị viên thêm một 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 truy cập hoặc đơn vị tổ chức cụ thể. Chỉ quản trị viên miền mới có thể thực hiện quy trình cài đặt của quản trị viên. Quản trị viên có thể tuỳ ý thay mặt cho tất cả người dùng trong miền đồng ý với tất cả các phạm vi truy cập; 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 làm như vậy.
Sau đây là một số điều cần cân nhắc liên quan đến việc cài đặt bằng quyền quản trị viên.
- 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 việc cấp phép. Nếu ứng dụng của bạn yêu cầu có giấy phép, thì việc định hướng các lượt cài đặt thông qua một quản trị viên có thể giúp đảm bảo rằng giấy phép đang được phân phối và sử dụng một cách thích hợp với tổ chức tương ứng.
- Giảm gánh nặng cho người dùng cuối. Việc quản trị viên cài đặt sẽ giảm tải quá trình thiết lập cho giáo viên và học viên. Điều này có thể giúp người dùng có trải nghiệm liền mạch hơn, ít lượt nhấp hơn và ít có khả năng 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 thực hiện quy trình cài đặt bằng quyền quản trị viên và bài viết Cách hoạt động của cơ cấu tổ chức để tìm hiểu thêm về đơn vị tổ chức và nhóm truy cập.
Cài đặt riêng lẻ
Cài đặt riêng lẻ sẽ thêm một tiện ích bổ sung vào tài khoản của người dùng. Người dùng sẽ được nhắc đồng ý với các 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ẻ.
- Tạo điều kiện thuận lợi cho việc áp dụng. Nhiều người dùng có thể xem và cài đặt tiện ích bổ sung của bạn trên 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 áp dụng hoặc ủng hộ sản phẩm của bạn hơn.
- Kiểm thử của 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 cho một nhóm lớn hơn.
Ngoài việc cài đặt tiện ích bổ sung thay cho người dùng, 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 một 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 trong danh sách cho phép để tìm hiểu thêm về hành vi này.
Xem tài liệu về chế độ cài đặt khi cài đặt 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 URI thiết lập tệp đính kèm. URL này được dùng làm giá trị src iframe cho iframe Khám phá tệp đính kèm. Khung hiển thị nội tuyến (iframe) Khám phá tệp đính kèm được giáo viên dùng để tìm nội dung hoặc hoạt động cần đính kèm vào bài tập. Bạn có thể đặt giá trị này trong bảng điều khiển dự án Google Cloud.
Tiền tố URI tệp đính kèm được phép dùng để xác thực các URI được đặt trong AddOnAttachment bằng các phương thức *.addOnAttachments.create và *.addOnAttachments.patch. Quy trình xác thực là một chuỗi tiền tố theo nghĩa đen và không cho phép sử dụng ký tự đại diện.
Bạn cũng phải chỉ định tất cả tiền tố URI mà tiện ích bổ sung của bạn cho phép tệp đính kèm. Tính năng này giúp tăng cường bảo mật bằng cách ngăn chặn tệp đính kèm từ các nguồn không được phép.
Đặt cả hai giá trị này trong trang Cấu hình ứng dụng Marketplace SDK của dự án trên Google Cloud.
Tài khoản kiểm thử
Tạo tài khoản kiểm thử 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ó 2 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 Xem 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@<miền minh hoạ của bạn>
- Sally Student, sally.student@<your demo domain>
Hãy làm theo quy trình này để tạo một tài khoản thử nghiệm mới:
- Đăng nhập vào Bảng điều khiển dành cho quản trị viên.
- Chuyển đến phần Người dùng.
- Nhấp vào Thêm người dùng mới (xem Hình 1).
- Nhập thông tin của người dùng và chỉ định vai trò phù hợp.
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 này để tạo một nhóm kiểm thử mới:
- Đăng nhập vào Bảng điều khiển dành cho quản trị viên.
- Chuyển đến phần Nhóm.
- Nhấp vào Tạo nhóm (xem Hình 2).
- Nhập thành viên và chủ sở hữu của 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.