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

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ề 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; 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à 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 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 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 một 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 PUBLISH.

  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 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 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 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 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 thành các bước để đăng ký miền thử nghiệm dành 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 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 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.

  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 các 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 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.

  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 trên 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 PUBLISH. 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 có sự đồng ý của người dùng về việc truy cập dữ liệu của họ. 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 Google 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 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 đó. Hãy 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 ứ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 một iframe được mở. Nếu người dùng chưa uỷ quyền 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. 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 các tiện ích bổ sung dành cho 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.
  • 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 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ể thực hiện 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
      • Thông tin 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. 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 lượt 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 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 khi đăng 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 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".

    • 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 (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 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 phần Nội dung mô tả thông tin chi tiết về ứng dụng trên 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ụ 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 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á một trong hai loại cài đặt. 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 dành cho quản trị viên

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ố cân nhắc về việc cài đặt dành 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 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, 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 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.

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ểm 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 riêng một 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 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ề 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 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 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 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

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 Sinh viên, 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 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.