Hiện tại, các nhà phát triển đã có thể sử dụng rộng rãi tiện ích bổ sung của Google Lớp học! Vui lòng xem tài liệu về tiện ích bổ sung để biết thêm thông tin.

Trang này được dịch bởi Cloud Translation API.

Tạo tiện ích bổ sung dành cho Lớp học

Đây là hướng dẫn từng bước đầu tiên về các tiện ích bổ sung cho Google Lớp học loạt video hướng dẫn từng bước.

Trong hướng dẫn từng bước này, bạn đặt nền tảng cho việc phát triển ứng dụng web và xuất bản ứng dụng dưới dạng tiện ích bổ sung của Lớp học. Các bước hướng dẫn từng bước trong tương lai mở rộng ứng dụng này.

Trong hướng dẫn từng bước này, bạn sẽ hoàn thành các bước sau:

Tạo một dự án mới trên Google Cloud cho tiện ích bổ sung.
Tạo một ứng dụng web skeleton với các nút đăng nhập phần giữ chỗ.
Xuất bản Trang thông tin trên Cửa hàng Play trên Google Workspace Marketplace cho tiện ích bổ sung của bạn.

Sau khi hoàn tất, bạn có thể cài đặt tiện ích bổ sung và tải tiện ích đó trong iframe tiện ích bổ sung dành cho Lớp học.

Điều kiện tiên quyết

Chọn ngôn ngữ để xem các điều kiện tiên quyết phù hợp:

Python

Ví dụ về Python của chúng tôi sử dụng khung Flask. Bạn có thể tải xuống mã nguồn cho tất cả hướng dẫn từng bước trên Trang tổng quan. Mã cho việc này bạn có thể xem hướng dẫn từng bước cụ thể trong thư mục /flask/01-basic-app/.

Nếu cần, hãy cài đặt Python 3.7+ và đảm bảo rằng pip có sẵn.

python -m ensurepip --upgrade

Bạn cũng nên thiết lập và kích hoạt một tài khoản Python ảo mới môi trường.

python3 -m venv .classroom-addon-env
source .classroom-addon-env/bin/activate

Mỗi thư mục con hướng dẫn từng bước trong các ví dụ đã tải xuống đều chứa một requirements.txt. Bạn có thể nhanh chóng cài đặt thư viện cần thiết bằng cách sử dụng pip. Sử dụng mã sau để cài đặt các thư viện cần thiết cho trình phát này hướng dẫn từng bước.

cd flask/01-basic-app
pip install -r requirements.txt

Node.js

Ví dụ Node.js của chúng tôi sử dụng khung Express. Bạn có thể tải hoàn tất mã nguồn cho tất cả hướng dẫn từng bước từ Trang tổng quan.

Nếu cần, hãy cài đặt NodeJS v16.13+.

Cài đặt các mô-đun nút bắt buộc bằng npm.

npm install

Java

Ví dụ Java của chúng tôi sử dụng khung khởi động mùa xuân. Bạn có thể tải xuống mã nguồn hoàn chỉnh cho tất cả hướng dẫn từng bước trên Trang tổng quan.

Cài đặt Java 11 trở lên nếu bạn chưa cài đặt ứng dụng này trên máy.

Các ứng dụng Spring Boot có thể dùng Gradle hoặc Maven để xử lý các bản dựng và quản lý phần phụ thuộc. Ví dụ này bao gồm trình bao bọc Maven giúp đảm bảo bản dựng thành công mà không cần phải cài đặt Maven.

Để có thể chạy ví dụ mà chúng tôi cung cấp, hãy chạy các lệnh sau trong thư mục bạn đã tải dự án xuống để đảm bảo bạn có điều kiện tiên quyết để chạy dự án.

java --version
./mvnw --version

Hoặc trên Windows:

java -version
mvnw.cmd --version

Thiết lập một dự án trên Google Cloud

Quyền truy cập vào API Lớp học và các phương thức xác thực bắt buộc đều do các dự án Google Cloud kiểm soát. Các hướng dẫn sau sẽ hướng dẫn bạn các bước tối thiểu để tạo và định cấu hình dự án mới để sử dụng với tiện ích bổ sung.

Tạo dự án

Tạo một dự án mới trên Google Cloud bằng cách truy cập trang tạo dự án. Bạn có thể cung cấp bất kỳ tên nào cho dự án mới. Nhấp vào Create (Tạo).

Hệ thống sẽ mất vài phút để tạo hoàn chỉnh dự án mới. Sau khi hoàn tất, hãy nhớ chọn dự án; bạn có thể chọn nó trong bộ chọn dự án trình đơn thả xuống ở đầu màn hình hoặc nhấp vào CHỌN DỰ ÁN trong trình đơn thông báo ở trên cùng bên phải.

Chọn dự án trong Google Cloud
bảng điều khiển

Đính kèm SDK của Google Workspace Marketplace vào dự án trên Google Cloud

Chuyển đến trình duyệt API Library (Thư viện API). Tìm Google Workspace Marketplace SDK. Bạn sẽ thấy SDK xuất hiện trong danh sách kết quả.

SDK của Google Workspace Marketplace
thẻ bài

Chọn thẻ SDK của Google Workspace Marketplace rồi nhấp vào Bật.

Định cấu hình SDK của Google Workspace Marketplace

Google Workspace Marketplace cung cấp trang thông tin mà người dùng và quản trị viên cài đặt tiện ích bổ sung của bạn. Định cấu hình Cấu hình ứng dụng và Cửa hàng của SDK Marketplace Danh sách và Màn hình đồng ý của OAuth để tiếp tục.

Cấu hình ứng dụng

Chuyển đến trang Cấu hình ứng dụng của SDK Marketplace. Cung cấp các thông tin sau:

Đặt Chế độ hiển thị của ứng dụng thành Public hoặc Private.
- Chế độ cài đặt công khai là dành cho các ứng dụng sẽ được phát hành sau này cho người dùng cuối. Ứng dụng công khai phải trải qua quy trình phê duyệt trước khi được được xuất bản tới người dùng cuối, nhưng bạn có thể chỉ định những người dùng có thể cài đặt và hãy kiểm tra dưới dạng Bản nháp. Đây là trạng thái trước khi phát hành cho phép bạn thử nghiệm và phát triển tiện ích bổ sung của mình trước khi gửi đi để xin được phê duyệt.
- Chế độ cài đặt riêng tư này phù hợp cho hoạt động kiểm thử và phát triển nội bộ. Đáp chỉ người dùng trong cùng miền với dự án đã được tạo. Do đó, bạn nên đặt chế độ hiển thị thành riêng tư chỉ khi dự án được tạo trong một miền có tài khoản Google Workspace for Education , nếu không người dùng thử nghiệm của bạn sẽ không thể chạy Tiện ích bổ sung dành cho Lớp học.
Cảnh báo: Kiểm tra để đảm bảo chế độ cài đặt Chế độ hiển thị của ứng dụng là chính xác trước khi đang lưu. Bạn không thể thay đổi Chế độ hiển thị của ứng dụng sau khi đặt. Bạn phải tạo một dự án mới trên Google Cloud để đặt một Chế độ hiển thị khác của ứng dụng.
Đặt Chế độ cài đặt thành Admin Only install nếu bạn muốn chỉ cho phép quản trị viên miền cài đặt.
Trong phần Tích hợp ứng dụng, hãy chọn Tiện ích bổ sung dành cho Lớp học. Bạn được nhắc đối với URI thiết lập tệp đính kèm bảo mật; đây là URL mà bạn dự kiến sẽ được tải khi người dùng mở tiện ích bổ sung của bạn. Theo mục đích của tài liệu này, hướng dẫn từng bước, giá trị này sẽ là https://<your domain>/addon-discovery.
Tiền tố URI tệp đính kèm được phép được dùng để xác thực các URI được thiết lập trong AddOnAttachment sử dụng courses.*.addOnAttachments.create và courses.*.addOnAttachments.patch. Xác thực là một giá trị cố định khớp với tiền tố chuỗi và không cho phép sử dụng ký tự đại diện tại đoạn mã này bất cứ lúc nào. Thêm ít nhất là miền gốc của máy chủ nội dung, chẳng hạn như https://localhost:5000/ hoặc https://cdn.myedtech.com/.
Thêm cùng Phạm vi OAuth như được cung cấp trong màn hình xin phép bằng OAuth trong bước trước đó.

Lưu ý quan trọng: Danh sách phạm vi OAuth được chỉ định trong Cấu hình ứng dụng phải khớp với những thông tin được liệt kê trong màn hình xin phép bằng OAuth.
Điền vào các trường phù hợp với tổ chức của bạn trong phần Nhà phát triển Đường liên kết.

Danh sách cửa hàng

Chuyển đến trang Trang thông tin trên Cửa hàng Play của SDK Marketplace. Cung cấp các thông tin sau:

Trong phần Chi tiết ứng dụng, hãy thêm ngôn ngữ hoặc mở rộng trình đơn thả xuống bên cạnh ngôn ngữ đã được liệt kê. Cung cấp Tên ứng dụng và nội dung mô tả; chúng xuất hiện trên trang thông tin của tiện ích bổ sung trên Google Workspace Marketplace. Nhấp vào Xong để lưu.
Chọn một Danh mục cho tiện ích bổ sung.
Trong mục Graphics assets (Thành phần đồ hoạ), hãy cung cấp hình ảnh cho các trường bắt buộc. Những URL này có thể thay đổi sau và có thể là phần giữ chỗ.
Trong phần Đường liên kết hỗ trợ, hãy cung cấp các URL được yêu cầu. Đây có thể là phần giữ chỗ nếu bạn đã đặt Chế độ hiển thị của ứng dụng là Riêng tư trong .

Nếu bạn đặt Chế độ hiển thị của ứng dụng thành Riêng tư ở bước trước, hãy nhấp vào PUBLISH; ứng dụng của bạn sẽ có thể cài đặt ngay lập tức. Nếu bạn đặt Chế độ hiển thị của ứng dụng ở chế độ Công khai, thêm địa chỉ email vào khu vực Người kiểm thử bản nháp cho người dùng thử nghiệm bất kỳ rồi nhấp vào Lưu bản nháp.

Màn hình xin phép bằng OAuth

Màn hình đồng ý OAuth xuất hiện khi người dùng cho phép ứng dụng của bạn lần đầu tiên. Thiết bị này sẽ nhắc cho phép ứng dụng của bạn truy cập vào thông tin cá nhân và thông tin tài khoản của họ, như chỉ định bởi phạm vi bạn bật.

Chuyển đến trang tạo màn hình xin phép bằng OAuth. Cung cấp những thông tin sau của bạn:

Đặt User Type (Loại người dùng) thành External (Bên ngoài). Nhấp vào Create (Tạo).
Trong trang tiếp theo, hãy điền thông tin liên hệ và thông tin bắt buộc về ứng dụng. Cung cấp mọi miền lưu trữ ứng dụng của bạn trong Miền được uỷ quyền. Nhấp chuột LƯU VÀ TIẾP TỤC.
Thêm bất kỳ Phạm vi OAuth mà ứng dụng web của bạn yêu cầu. Xem OAuth hướng dẫn cấu hình để thảo luận sâu về phạm vi và mục đích của phạm vi.

Bạn phải yêu cầu ít nhất một trong các phạm vi sau để Google gửi tham số truy vấn login_hint. Giải thích chi tiết hơn về vấn đề này có sẵn trong hướng dẫn cấu hình OAuth của chúng tôi:
- https://www.googleapis.com/auth/userinfo.email (đã được bao gồm)
- https://www.googleapis.com/auth/userinfo.profile (đã được bao gồm)
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
- https://www.googleapis.com/auth/classroom.addons.student
Đồng thời thêm mọi phạm vi API của Google khác mà ứng dụng của bạn yêu cầu từ đầu người dùng.

Nhấp vào LƯU VÀ TIẾP TỤC.
Liệt kê địa chỉ email của bất kỳ tài khoản thử nghiệm nào trên trang Người dùng thử nghiệm. Nhấp vào LƯU VÀ TIẾP TỤC.

Xác nhận rằng các chế độ cài đặt của bạn là chính xác, sau đó quay lại trang tổng quan.

Cài đặt tiện ích bổ sung

Giờ đây, bạn có thể cài đặt tiện ích bổ sung bằng cách sử dụng đường liên kết ở đầu Trang Trang thông tin trên Cửa hàng Play của Marketplace SDK. Nhấp vào biểu tượng Ứng dụng URL ở đầu trang để xem trang thông tin, sau đó chọn Cài đặt.

Tạo một ứng dụng web cơ bản

Thiết lập ứng dụng web skeleton với 2 tuyến. Các bước hướng dẫn từng bước trong tương lai mở rộng ứng dụng này, nên bây giờ chỉ cần tạo trang đích cho tiện ích bổ sung /addon-discovery và một trang chỉ mục mô phỏng / cho "trang web công ty".

Ví dụ về ứng dụng web trong iframe

Triển khai 2 điểm cuối sau:

/: hiển thị thông báo chào mừng và nút để đóng cả thẻ hiện tại và iframe của tiện ích bổ sung.
/addon-discovery: hiển thị thông báo chào mừng và hai nút: một nút dùng để đóng iframe tiện ích bổ sung và một iframe để mở trang web trong thẻ mới.

Xin lưu ý rằng chúng ta sẽ thêm các nút để tạo và đóng cửa sổ hoặc iframe. Các minh hoạ phương pháp đưa người dùng vào thẻ mới một cách an toàn trong phần hướng dẫn từng bước tiếp theo.

Tạo tập lệnh tiện ích

Tạo thư mục static/scripts. Tạo tệp mới addon-utils.js. Thêm sau 2 hàm.

/**
 *   Opens a given destination route in a new window. This function uses
 *   window.open() so as to force window.opener to retain a reference to the
 *   iframe from which it was called.
 *   @param {string} destinationURL The endpoint to open, or "/" if none is
 *   provided.
 */
function openWebsiteInNewTab(destinationURL = '/') {
  window.open(destinationURL, '_blank');
}

/**
 *   Close the iframe by calling postMessage() in the host Classroom page. This
 *   function can be called directly when in a Classroom add-on iframe.
 *
 *   Alternatively, it can be used to close an add-on iframe in another window.
 *   For example, if an add-on iframe in Window 1 opens a link in a new Window 2
 *   using the openWebsiteInNewTab function, you can call
 *   window.opener.closeAddonIframe() from Window 2 to close the iframe in Window
 *   1.
 */
function closeAddonIframe() {
  window.parent.postMessage({
    type: 'Classroom',
    action: 'closeIframe',
  }, '*');
};

Tạo tuyến đường

Triển khai các điểm cuối /addon-discovery và /.

Python

Thiết lập thư mục ứng dụng

Trong ví dụ này, hãy cấu trúc logic ứng dụng dưới dạng một Mô-đun Python. Đây là thư mục webapp trong ví dụ mà chúng tôi cung cấp.

Tạo thư mục cho mô-đun máy chủ, chẳng hạn như webapp. Di chuyển static vào thư mục mô-đun. Tạo thư mục template trong thư mục mô-đun; tệp HTML của bạn nằm ở đây.

Xây dựng mô-đun máy chủ*

Tạo tệp __init__.py trong thư mục mô-đun của bạn và thêm đoạn mã sau hoạt động nhập và khai báo.

from flask import Flask
import config

app = Flask(__name__)
app.config.from_object(config.Config)

# Load other module script files. This import statement refers to the
# 'routes.py' file described below.
from webapp import routes

Sau đó, hãy tạo một tệp để xử lý các tuyến của ứng dụng web. Đây là webapp/routes.py trong ví dụ chúng tôi cung cấp. Triển khai 2 tuyến trong này .

from webapp import app
import flask

@app.route("/")
def index():
    return flask.render_template("index.html",
                                message="You've reached the index page.")

@app.route("/classroom-addon")
def classroom_addon():
    return flask.render_template(
        "addon-discovery.html",
        message="You've reached the addon discovery page.")

Lưu ý rằng cả hai tuyến đường của chúng ta đều chuyển biến message đến biến tương ứng Mẫu Jinja. Điều này rất hữu ích khi xác định người dùng đã truy cập trang nào.

Tạo tệp cấu hình và chạy

Trong thư mục gốc của ứng dụng, hãy tạo main.py và config.py tệp. Định cấu hình khoá bí mật của bạn trong config.py.

import os

class Config(object):
    # Note: A secret key is included in the sample so that it works.
    # If you use this code in your application, replace this with a truly secret
    # key. See https://flask.palletsprojects.com/quickstart/#sessions.
    SECRET_KEY = os.environ.get(
        'SECRET_KEY') or "REPLACE ME - this value is here as a placeholder."

Trong tệp main.py, hãy nhập mô-đun và khởi động máy chủ Flask.

from webapp import app

if __name__ == "__main__":
    # Run the application over HTTPs with a locally stored certificate and key.
    # Defaults to https://localhost:5000.
    app.run(
        host="localhost",
        ssl_context=("localhost.pem", "localhost-key.pem"),
        debug=True)

Node.js

Các tuyến được đăng ký trong tệp app.js bằng các dòng sau.

const websiteRouter = require('./routes/index');
const addonRouter = require('./routes/classroom-addon');

app.use('/', websiteRouter);
app.use('/addon-discovery', addonRouter);

Mở /01-basic-app/routes/index.js và xem lại mã. Tuyến đường này là được tiếp cận khi người dùng cuối truy cập vào trang web của công ty. Tuyến kết xuất một bằng cách sử dụng mẫu Tay điều khiển index và truyền mẫu đối tượng dữ liệu chứa các biến title và message.

router.get('/', function (req, res, next) {
  res.render('index', {
    title: 'Education Technology',
    message: 'Welcome to our website!'
  });
});

Mở tuyến đường thứ hai /01-basic-app/routes/classroom-addon.js và xem lại mã. Tuyến này sẽ đạt đến khi tiện ích bổ sung của người dùng cuối truy cập. Lưu ý tuyến này sử dụng mẫu Tay cầm discovery và bố cục addon.hbs để hiển thị trang khác với trang web của công ty của bạn.

router.get('/', function (req, res, next) {
  res.render('discovery', {
    layout: 'addon.hbs',
    title: 'Education Technology Classroom add-on',
    message: `Welcome.`
  });
});

Java

Ví dụ về mã Java sử dụng các mô-đun để đóng gói hướng dẫn từng bước tuần tự bước. Vì đây là hướng dẫn từng bước đầu tiên, nên mã nằm trong phần Mô-đun step_01_basic_app. dự kiến bạn sẽ không triển khai dự án sử dụng các mô-đun; Thay vào đó, bạn nên tạo dựa trên một dự án khi bạn làm theo từng bước trong hướng dẫn từng bước.

Tạo một lớp tay điều khiển, Controller.java trong dự án mẫu này, để xác định các điểm cuối. Trong tệp này, hãy nhập chú thích @GetMapping từ phần phụ thuộc spring-boot-starter-web.

import org.springframework.web.bind.annotation.GetMapping;

Thêm chú thích trình điều khiển khung Spring vào phía trên lớp định nghĩa để cho biết mục đích của lớp.

@org.springframework.stereotype.Controller
public class Controller {

Sau đó, hãy triển khai 2 tuyến này và 1 tuyến bổ sung để xử lý lỗi.

/** Returns the index page that will be displayed when the add-on opens in a
*   new tab.
*   @param model the Model interface to pass error information that's
*   displayed on the error page.
*   @return the index page template if successful, or the onError method to
*   handle and display the error message.
*/
@GetMapping(value = {"/"})
public String index(Model model) {
  try {
    return "index";
  } catch (Exception e) {
    return onError(e.getMessage(), model);
  }
}

/** Returns the add-on discovery page that will be displayed when the iframe
*   is first opened in Classroom.
*   @param model the Model interface to pass error information that's
*   displayed on the error page.
*   @return the addon-discovery page.
*/
@GetMapping(value = {"/addon-discovery"})
public String addon_discovery(Model model) {
  try {
    return "addon-discovery";
  } catch (Exception e) {
    return onError(e.getMessage(), model);
  }
}

/** Handles application errors.
*   @param errorMessage message to be displayed on the error page.
*   @param model the Model interface to pass error information to display on
*   the error page.
*   @return the error page.
*/
@GetMapping(value = {"/error"})
public String onError(String errorMessage, Model model) {
  model.addAttribute("error", errorMessage);
  return "error";
}

Kiểm thử tiện ích bổ sung

Khởi chạy máy chủ của bạn. Sau đó, đăng nhập vào Google Lớp học bằng tài khoản của Người dùng thử nghiệm với Giáo viên. Chuyển đến thẻ Bài tập trên lớp và tạo tài liệu mới Sự chuyển nhượng. Chọn tiện ích bổ sung của bạn trong bộ chọn Tiện ích bổ sung. iframe mở và tiện ích bổ sung sẽ tải URI thiết lập tệp đính kèm mà bạn đã chỉ định trong Trang Cấu hình ứng dụng của SDK Marketplace.

Xin chúc mừng! Bạn có thể chuyển sang bước tiếp theo: đăng nhập cho người dùng bằng dịch vụ SSO của Google.