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 trên Google Cloud cho tiện ích bổ sung cho Lớp học. Các dự án trên Google Cloud được dùng để triển khai dịch vụ Đăng nhập một lần của 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 một tiện ích bổ sung trong cửa hàng của 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 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 để 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 chế độ hiển thị của ứng dụng trong Google Workspace Marketplace; chỉ người dùng trong miền mà ứng dụng được tạo mới có thể cài đặt ứng dụng trên Marketplace, còn mọi miền Google Workspace đều có thể cài đặt ứng dụng công khai. Đây phải là hai ứng dụng riêng biệt, vì một dự án không thể vừa ở chế độ công khai vừa riêng tư. Đơn đăng ký công khai phải được xem xét và phê duyệt trước khi cung cấp trên sàn thương mại điện tử.
Để 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 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à bạn tạo ứng dụng sẽ không thể truy cập vào ứng dụng này nhưng không cần được 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à thử nghiệm tiện ích bổ sung của mình 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ạ của Google Workspace for Education, nâng cấp miền lên một giấy phép Plus và cho phép miền đó truy cập vào API tiện ích bổ sung cho Lớp học:
- Hoàn thành các bước để nhận 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 các dự án trên Google Cloud, hãy kiểm tra nội dung 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 rồi chọn Tất cả người dùng trong nhóm hoặc đơn vị tổ chức này 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 tất cả mọi người.
- 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 vào 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 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 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à đưa 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 kiểm thử 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ử của bạn. Trong phần Cấp phép của từng giáo viên, hãy xác nhận rằng Google Workspace for Education Plus đã được Chỉ định.
Bật API Lớp học trong dự án trên Google Cloud.
Bật SDK Google Workspace Marketplace trong dự án trên Google Cloud của bạn.
Đặt Cấu hình ứng dụng của SDK Thị trường thành Chế độ hiển thị của ứng dụng thành 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 phát hành 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 trong trang thông tin trên Cửa hàng Play.
Tạo một dự án công khai trên Google Cloud
Dự án này minh hoạ ứ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.
Tạo một dự án mới trên Google Cloud trong miền phát hành công khai.
Bật API Lớp học trong dự án trên Google Cloud.
Bật SDK Google Workspace Marketplace trong dự án trên Google Cloud của bạn.
Đặ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.
Chia sẻ mã dự án trên Google Cloud hoặc số dự án trên Google Cloud với đối tác Google để thêm dự án vào danh sách cho phép của tiện ích bổ sung. Việc này giúp dự án có quyền truy cập vào các tính năng tiện ích bổ sung mới của API Lớp học.
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 SDK Marketplace. Sau khi ứng dụng được phê duyệt, hãy xoá ô 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 Trang web thương mại.
OAuth 2.0
Để truy cập API Lớp học, bạn cần phải có sự đồng ý của người dùng về việc truy cập vào dữ liệu. Các lớp này có được 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 lệnh gọi API sau đó đến Google Lớp học. Bạn phải thiết lập 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 đồng ý khi họ cài đặt tiện ích bổ sung.
Xem trang Phạm vi OAuth dành cho API 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 đó. Xem phần Định cấu hình trang OAuth trong tài liệu của 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.profilecho phép ứng dụng xem thông tin cá nhân như tên dọc, họ và tên cùng 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ác phạm vi đó sẽ được xác định bằng tham số truy vấn login_hint. Tham số này được chuyển đến bất kỳ URL nào của ứng dụng web khi một iframe mở. Nếu người dùng chưa uỷ quyền một trong các phạm vi này, thì thông số hd ("miền được lưu trữ") sẽ được chuyển đến URL của ứng dụng web.
login_hint và hd là các tham số OpenSL Connect tiêu chuẩn mà bạn có thể tuỳ ý chuyển tới 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. Các bản cập nhật này nhằm mang lại trải nghiệm uỷ quyền mượt mà hơn cho người dùng cuối.
Phạm vi của tiện ích bổ sung dành cho Lớp học
Các phạm vi sau đây 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.studentcho 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 mã truy cập OAuth hợp lệ cho biết thông tin đăng nhập của người dùng, các 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.
- Lệnh gọi đến một bài đăng cụ thể trong Google Lớp học sẽ được kiểm soát bằng các quy trình kiểm tra sau.
- 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 về bài đăng đó
- Khi iframe Khám phá tệp đính kèm được mở lần đầu, tiện ích bổ sung này có thể chưa có tệp đính kèm trên bài đăng. Tham số truy vấn
addOnTokenđược cung cấp có thể dùng để tạo các yêu cầu 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 việc khởi chạy (
addOnTokenđược xác thực nếu được cung cấp và bắt buộc khi tiện ích bổ sung chưa 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 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 bài viết Câu hỏi thường gặp về quy trình xác minh bằng 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
Có một vài điều cần lưu ý khi tạo trang thông tin trên Cửa hàng Play cho các tiện ích bổ sung dành cho Lớp học khi đang tham gia chương trình tiếp cận sớm này.
Để biết thông tin chung về cấu hình SDK trên Google Workspace Marketplace, hãy truy cập vào phần 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 thông tin
Danh sách cửa hàng SDK trên Marketplace của dự án công khai trên Google Cloud 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 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 trên trang thông tin của bạn:
Trong phần Thông tin chi tiết về ứ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 tôi 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, của Công ty của tôi".
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 một giá trị cho trường Pricing (Định giá). Trường này bao gồm các lựa chọn Miễn phí, Có tính phí trong thời gian dùng thử, Có tính phí với 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.
Đả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.
Xem các mục được liệt kê trong Nội dung mô tả chi tiết về ứng dụng của 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 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 mà bạn cung cấp đều là bản thể hiện chính xác về trải nghiệm tiện ích bổ sung.
Trong phần Đường liên kết hỗ trợ:
- Đảm bảo rằng bạn đã cung cấp một đườ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 đã đáp ứng Nguyên tắc sử dụng thương hiệu API của Google, trong đó nêu rõ 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 (TM) nếu được chỉ định; hãy 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ụ cấp phép và thanh toán của Google, hãy truy cập vào API Marketplace.
Chế độ cài đặt
Tiện ích bổ sung có thể cho phép cài đặt riêng lẻ 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 2 loại cài đặt này, chứ không nhằm quảng bá bất kỳ loại cài đặt nào. Bạn có thể chọn cho phép hoặc không cho phép cài đặt riêng lẻ trên trang Cấu hình ứng dụng SDK trên Google Workspace Marketplace.
Cài đặt quản trị viên
Phầ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ả các tài khoản trong một 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 dành cho quản trị viên. Quản trị viên có thể thay mặt cho toàn bộ người dùng trong miền đồng ý 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 làm như vậy.
Sau đây là một số điểm cần cân nhắc liên quan đến 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 đòi hỏi giấy phép, thì việc phân kênh các 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 đang được phân phối và sử dụng phù hợp với tổ chức tương ứng.
- Giảm bớt gánh nặng cho người dùng cuối. Việc cài đặt ứng dụng dành cho quản trị viên sẽ giúp giảm bớt khối lượng 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à giảm khả năng nhầm lẫn.
Vui lòng xem phần Cài đặt các ứng dụng Marketplace trong miền của bạn để biết thêm thông tin về cách cài đặt quản trị viên và Cách hoạt động của cơ cấu tổ chức để tìm hiểu thêm về các đơn vị tổ chức và nhóm truy cập.
Lắp đặt riêng
Các lượt cài đặt riêng lẻ sẽ thêm 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 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 từng bước cài đặt.
- Tạo điều kiện sử dụng. Có thêm nhiều người dùng 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ể khiến nhiều giáo viên khác sử dụng hoặc ủng hộ sản phẩm của bạn.
- Kiểm thử dành cho 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 tra hoặc đánh giá tiện ích bổ sung đó 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. 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 trên danh sách cho phép của bạn để tìm hiểu thêm về hành vi nà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 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 cần đí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à tiện ích bổ sung của bạn cho phé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 tệp đính kèm từ các nguồn không được uỷ quyền.
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 kiểm tra
Tạo tài khoản thử nghiệm trên miền minh hoạ để xác minh hoạt động 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 Bài tập của học viên.
Các tài khoản thử nghiệm được đề xuất:
- Tammy, giáo viên, 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 Birthday, 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 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 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:
- Đă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 liên kết Tạo nhóm trong Bảng điều khiển dành cho quản trị viên.