Trang này trình bày những 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 các 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 của Google thông qua OAuth 2.0 (SSO của Google), để cho phép 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ề việc xuất bản tiện ích bổ sung lên Marketplace, hãy xem bài viết Xuất bản ứng dụng.
Tạo dự án trên Google Cloud
Có hai loại dự án cần tạo: một dự án riêng tư dùng để phát triển và một dự án công khai mà người dùng cuối có thể truy cập. Các nhãn "công khai" và "riêng tư" đề cập đến chế độ hiển thị của ứng dụng trong Google Workspace Marketplace; một ứng dụng Marketplace riêng tư chỉ có thể được cài đặt bởi người dùng trong miền nơi ứng dụng được tạo, trong khi bất kỳ miền Google Workspace nào cũng có thể cài đặt ứng dụng Marketplace công khai. Đâ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ư. Ứng dụng công khai phải được xem xét và phê duyệt trước khi ra mắt trên Marketplace.
Để biết thông tin chung về việc 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 một dự án công khai trên Google Cloud
Dự án này đại diện cho ứng dụng tiện ích 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 trước khi có thể ra mắt hoặc cài đặt.
Tạo một dự án mới trên Google Cloud trong miền phát hành chính thức của bạn.
Bật API Lớp học trong dự án trên Google Cloud.
Bật SDK của Google Workspace Marketplace trong dự án trên Cloud.
Đặt Cấu hình ứng dụng Chế độ hiển thị của ứng dụng của SDK Marketplace thành Công khai rồi đánh dấu vào hộp Không công khai.
Hoàn tất các trường bắt buộc trên trang Trang thông tin trên Cửa hàng Play của SDK Marketplace 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ỏ đánh dấu ô Không công khai để giáo viên và quản trị viên có thể tìm thấy ứng dụng đó trong Thị trường.
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 đã tạo ứng dụng này sẽ không truy cập được, nhưng không cần phê duyệt trước khi cài đặt. Do đó, 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 đó, hãy làm theo các bước sau để thiết lập miền minh hoạ của Google Workspace for Education, nâng cấp lên một giấy phép Plus và cho phép miền này truy cập vào API tiện ích bổ sung của Lớp học:
- Hoàn thành các bước để đăng ký miền thử nghiệm dành cho nhà phát triển.
Sau 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 một dự án trên Google Cloud
Nếu bạn không thể truy cập vào bảng điều khiển Google Cloud hoặc tạo dự án trên Google Cloud, hãy xem những mục sau trong Bảng điều khiển dành cho quản trị viên:
- Truy cập trang Cài đặt tài khoản > Cài đặt quyền truy cập theo độ tuổi và 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 Ứ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 của Cloud Shell là Cho phép truy cập vào Cloud Shell.
Hoàn thành và gửi biểu mẫu yêu cầu nâng cấp miền minh hoạ. Khi gửi biểu mẫu này, bạn sẽ được 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, đồng thời cho phép dự án trên đám mây của bạn sử dụng API tiện ích bổ sung dành cho Lớp học.
Bạn sẽ nhận được email khi các quy trình nâng cấp và danh sách cho phép hoàn tất. Cấp giấy phép Plus cho tài khoản giáo viên kiểm tra trong Bảng điều khiển dành cho quản trị viên. Trong 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 từng giáo viên, hãy xác nhận rằng Google Workspace for Education Plus đã được Cấp.
Bật API Lớp học trong dự án trên Google Cloud.
Bật SDK của Google Workspace Marketplace trong dự án trên Cloud.
Đặt Cấu hình ứng dụng Chế độ hiển thị của ứng dụng của SDK Marketplace ở chế độ riêng tư.
Hoàn tất các trường bắt buộc trên trang Trang thông tin trên Cửa hàng Play của SDK Marketplace rồi nhấp vào XUẤT BẢN. Sau khi xuất bản trang thông tin ứng dụng, 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 đồng ý với quyền truy cập vào dữ liệu của người dùng. Bạn có thể lấy các mã 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ã thông báo có thể dùng để thực hiện lệnh gọi API đến Google Lớp học sau đó. Bạn phải định cấu hình các phạm vi trong trang thông tin trên Cửa hàng Play của Google Workspace Marketplace để quản trị viên miền có thể thay mặt người dùng của miền đưa ra sự đồng ý nếu họ cài đặt tiện ích bổ sung.
Hãy xem trang Các phạm vi của OAuth cho API Google để biết danh sách chi tiết về tất cả các phạm vi có sẵn 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 nên yêu cầu ít nhất một trong các phạm vi sau:
https://www.googleapis.com/auth/userinfo.emailcho phép ứng dụng xem địa chỉ email của người dùng.https://www.googleapis.com/auth/userinfo.profilecho phép ứng dụng xem thông tin cá nhân như ảnh dọc, họ và tên cũng như các thông tin cá nhân khác mà người dùng đã cung cấp 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, các phạm vi đó 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 iframe được mở. Nếu người dùng chưa cấp 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ố SSO Connect chuẩn mà bạn có thể tuỳ ý chuyển cho Google khi sử dụng chức năng Đăng nhập bằng Google hoặc yêu cầu mã thông báo OAuth. Tính năng này nhằm giúp người dùng cuối có được trải nghiệm uỷ quyền suôn sẻ hơn.
Phạm vi 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 các tiện ích bổ sung dành cho Lớp học:
https://www.googleapis.com/auth/classroom.addons.teachercho 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 để khởi chạy các thao tác 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 đăng nhập của người dùng, lệnh gọi API vẫn được kiểm soát 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
courseIdchỉ định trong yêu cầu. - Việc tạo tệp đính kèm, cập nhật, xoá và trả điểm về yêu cầu 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 đây.
- Khi đã có ít nhất một tệp đính kèm trên bài đăng, tiện ích bổ sung có thể yêu cầu:
- xác thực khởi chạy iframe
- Thao tác đọc, cập nhật và xoá tệp đính kèm
- 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 trong bài đăng. Tham số truy vấn
addOnTokenđược cung cấp có thể dùng để yêu cầu những nội dung sau:- Tạo tệp đính kèm dưới bài đăng (bắt buộc phải có
addOnToken) - Xác thực quá trình 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 dưới bài đăng (bắt buộc phải có
- Khi đã có ít nhất một tệp đính kèm trên bài đăng, tiện ích bổ sung có thể yêu cầu:
Xác minh OAuth
Tiện ích bổ sung dành cho 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 bài viết Câu hỏi thường gặp về việc xác minh ứng dụng để dùng API qua 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 xem bài viết 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 Play trên Google Workspace Marketplace.
Những điều cần cân nhắc về trang thông tin
Danh sách cửa hàng SDK Marketplace công khai của dự án Google Cloud chỉ định tên và nội dung mô tả ứng dụng của bạn 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 Chi tiết ứng dụng.
Hãy làm theo các nguyên tắc sau trên trang thông tin của bạn:
Trong phần Chi tiết ứng dụng:
Tránh dùng dấu câu trong Tên ứng dụng. Ví dụ: sử dụng "Tiện ích bổ sung của công ty của tôi" 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 cùng một văn bản.
+ Đảm bảo rằng bạn đã chọn giá trị cho trường Pricing (Định giá). Trường này bao gồm các lựa chọn về giá Miễn phí, Có tính phí khi dùng thử miễn phí, Có tính phí bằng các tính năng miễn phí và giá Có tính phí. Bạn không cần chỉ định số tiền chi phí trong trang thông tin trên Marketplace.
Hãy đảm bảo rằng bạn đã chọn giá trị cho trường Danh mục. Tài nguyên học tập hoặc Công cụ dành cho giáo viên và quản trị viên có thể là những lựa chọn phù hợp cho tiện ích bổ sung của Lớp học.
Hãy xem các mục được liệt kê trong phần Mô tả thông tin chi tiết về ứng dụng trên Marketplace để biết thêm thông tin.
Trong mục Thành phần đồ hoạ:
Mọi thành phần đồ hoạ được cung cấp đều không bị mờ và đáp ứng kích thước quy đị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 tiện ích bổ sung của bạn.
Trong Đường liên kết hỗ trợ:
- Hãy đả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 API của Google, 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 trên trang thông tin của mình, hãy sử dụng tên của sản phẩm đó ở định dạng được cung cấp trong Danh sách nhãn hiệu. Đảm bảo bạn thêm biểu tượng nhãn hiệu (TM) nếu được chỉ định; sử dụng "Google Tài liệuTM", 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 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ụ thanh toán và cấp phép của Google, hãy truy cập vào API Marketplace.
Cài đặt
Tiện ích bổ sung có thể cho phép cài đặt riêng lẻ ngoài 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 2 loại chế độ cài đặt và không quảng bá loại cài đặt nào. Bạn có thể chọn có cho phép cài đặt riêng lẻ hay không trên trang Cấu hình ứng dụng SDK của Google Workspace Marketplace.
Cài đặt dành cho quản trị viên
Cài đặt dành cho 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 miền hoặc vào các nhóm truy cập hay đơn vị tổ chức cụ thể. Chỉ quản trị viên miền mới có thể thực hiện cài đặt quản trị viên. Quản trị viên có thể tuỳ ý đồng ý với tất cả phạm vi truy cập thay mặt cho tất cả người dùng trong miền; 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ố cân nhắc về việc cài đặt dành cho 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 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 giấy phép, các bản cài đặt phân kênh thông qua một quản trị viên có thể giúp đảm bảo rằng các giấy phép đang được phân phối và sử dụng phù 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 cài đặt cho quản trị viên sẽ giúp giảm tải khi 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 người dùng liền mạch hơn với ít lượt nhấp hơn và ít khả năng gây nhầm lẫn hơn.
Xem phần 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 các ứng dụng dành cho quản trị viên và Cách cơ cấu tổ chức hoạt động để tìm hiểu thêm về các đơn vị tổ chức và nhóm quản lý quyền truy cập.
Cài đặt riêng lẻ
Cài đặt riêng lẻ sẽ thêm tiện ích bổ sung vào tài khoản riêng của người dùng. Người dùng đượ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ểm cần cân nhắc liên quan đến việc cài đặt riêng lẻ.
- Hỗ trợ áp 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 từng giáo viên cài đặt có thể nhắc thêm nhiều giáo viên áp dụng hoặc ủng hộ sản phẩm của bạn.
- Kiểm thử với quản trị viên. Quản trị viên có thể cài đặt riêng một tiện ích bổ sung để kiểm thử hoặc đánh giá tiện ích bổ sung đó trước khi phê duyệt hoặc cài đặt 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 phần Quản lý các ứng dụng trên Google Workspace Marketplace trên danh sách cho phép của bạn để tìm hiểu thêm về hoạt động này.
Hãy xem tài liệu về cách 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 của tính năng Khám phá tệp đính kèm. Giáo viên sử dụng iframe của tính năng Khám phá tệp đính kèm để tìm nội dung hoặc hoạt động cần đính kèm vào bài tập.
Bạn cũng phải chỉ định tất cả các tiền tố URI mà tiện ích bổ sung của bạn cho phép đính kèm tệp. Tính năng này giúp tăng tính bảo mật bằng cách ngăn chặn tệp đính kèm từ các 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
Hãy 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ư. 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 Đánh giá bài tập của học viên.
Tài khoản thử nghiệm được đề xuất:
- Giáo viên Tammy, tammy.teacher@<miền minh hoạ của bạn>
- Sam Sinh viên, sam.student@<miền minh hoạ của bạn>
- Sally Sinh viên, sally.student@<miền minh hoạ của bạn>
Hãy làm theo quy trình sau để 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 mục 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ò thích 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.
Làm theo quy trình sau để 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 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.