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.

Hướng dẫn từng bước

Loạt hướng dẫn này minh hoạ tất cả các thành phần của một tiện ích bổ sung hoạt động trong Lớp học. Mỗi bước trong hướng dẫn đều đề cập đến các khái niệm cụ thể, triển khai chúng trong một ứng dụng web duy nhất. Mục tiêu là hỗ trợ bạn thiết lập, định cấu hình và chạy một tiện ích bổ sung hoạt động được.

Tiện ích bổ sung của bạn phải tương tác với một dự án trên Google Cloud. Nếu chưa quen với Google Cloud, bạn nên đọc hướng dẫn Bắt đầu. Bạn quản lý thông tin đăng nhập, quyền truy cập API và Google Workspace Marketplace SDK trong bảng điều khiển Google Cloud. Để biết thêm thông tin về Marketplace SDK, hãy truy cập vào trang hướng dẫn về trang thông tin trên Google Workspace Marketplace.

Hướng dẫn này đề cập đến các chủ đề sau:

Sử dụng Google Cloud để tạo một trang hiển thị trong iframe trong Lớp học.
Thêm tính năng đăng nhập một lần (SSO) bằng Google và cho phép người dùng đăng nhập.
Thực hiện lệnh gọi API để đính kèm tiện ích bổ sung vào bài tập.
Đáp ứng các yêu cầu chính khi gửi tiện ích bổ sung và các tính năng bắt buộc.

Hướng dẫn này giả định rằng bạn đã quen thuộc với các khái niệm cơ bản về lập trình và phát triển web. Bạn nên đọc Hướng dẫn định cấu hình dự án trước khi bắt đầu các hướng dẫn từng bước. Trang này chứa các thông tin chi tiết quan trọng về cấu hình mà chưa được đề cập đầy đủ trong hướng dẫn.

Ví dụ về cách triển khai

Bạn có thể xem ví dụ tham chiếu đầy đủ bằng Python. Các phương thức triển khai một phần cũng có trong Java và Node.js. Những cách triển khai này là nguồn của mã ví dụ có trong các trang tiếp theo.

Nơi tải xuống

Các ví dụ về Python và Java có trong kho lưu trữ GitHub:

Bạn có thể tải mẫu Node.js xuống dưới dạng tệp zip:

Kho lưu trữ Node.js

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

Hãy xem các phần sau để chuẩn bị một dự án tiện ích bổ sung mới.

Chứng chỉ HTTPS

Mặc dù bạn có thể lưu trữ ứng dụng của mình trên mọi môi trường phát triển, nhưng tiện ích bổ sung Lớp học chỉ có sẵn thông qua https://. Do đó, bạn cần một máy chủ có tính năng mã hoá SSL để triển khai ứng dụng hoặc kiểm thử ứng dụng trong iframe của tiện ích bổ sung.

Bạn có thể sử dụng localhost với chứng chỉ SSL; hãy cân nhắc sử dụng mkcert nếu bạn cần tạo chứng chỉ cho quá trình phát triển cục bộ.

Dự án Google Cloud

Bạn cần định cấu hình một dự án trên Google Cloud để sử dụng với các ví dụ này. Hãy xem hướng dẫn tạo dự án trên Google Cloud để nắm được thông tin tổng quan về các bước cần thiết để bắt đầu. Phần Thiết lập dự án trên Google Cloud trong hướng dẫn đầu tiên cũng hướng dẫn các hành động định cấu hình cụ thể cần thực hiện.

Khi hoàn tất, hãy tải Mã ứng dụng khách OAuth 2.0 xuống dưới dạng tệp JSON; bạn cần thêm tệp thông tin đăng nhập này vào thư mục ví dụ đã giải nén. Hãy xem phần Tìm hiểu về các tệp để biết vị trí cụ thể.

Thông tin xác thực OAuth

Hãy làm theo các bước sau để tạo thông tin xác thực OAuth mới:

Chuyển đến trang Thông tin đăng nhập Google Cloud. Đảm bảo rằng bạn đã chọn đúng dự án ở đầu màn hình.
Nhấp vào TẠO THÔNG TIN XÁC THỰC rồi chọn Mã ứng dụng OAuth trong trình đơn thả xuống.
Trên trang tiếp theo:
- Đặt Loại ứng dụng thành Ứng dụng web.
- Trong mục URI chuyển hướng được uỷ quyền, hãy nhấp vào THÊM URI. Thêm đường dẫn đầy đủ cho một tuyến đường gọi lại cho ứng dụng của bạn. Ví dụ: https://my.domain.com/auth-callback hoặc https://localhost:5000/callback. Bạn sẽ tạo và xử lý tuyến đường này sau trong hướng dẫn này. Bạn có thể chỉnh sửa hoặc thêm các tuyến đường như vậy bất cứ lúc nào.
- Nhấp vào TẠO.
Sau đó, bạn sẽ nhận được một hộp thoại chứa thông tin đăng nhập mà bạn vừa tạo. Chọn mục TẢI TỆP JSON XUỐNG. Sao chép tệp JSON đã tải xuống vào thư mục máy chủ.

Điều kiện tiên quyết theo ngôn ngữ

Xem tệp README trong mỗi kho lưu trữ để biết danh sách các điều kiện tiên quyết mới nhất.

Python

Ví dụ về Python của chúng tôi sử dụng khung Flask. Bạn có thể tải mã nguồn hoàn chỉnh xuống từ các đường liên kết được cung cấp.

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

python3 -m ensurepip --upgrade

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

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

Có một requirements.txt trong mỗi thư mục con hướng dẫn từng bước trong các ví dụ đã tải xuống. Bạn có thể nhanh chóng cài đặt các thư viện cần thiết bằng cách sử dụng pip. Hãy dùng các lệnh sau để cài đặt các thư viện bắt buộc cho hướng dẫn đầu tiên.

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

Node.js

Ví dụ về Node.js của chúng tôi sử dụng khung Express. Bạn có thể tải mã nguồn đầy đủ xuống từ các đường liên kết được cung cấp.

Ví dụ này yêu cầu Node.js phiên bản 16.13 trở lên.

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

npm install

Java

Ví dụ về Java của chúng tôi sử dụng khung Spring Boot. Bạn có thể tải mã nguồn đầy đủ xuống từ các đường liên kết được cung cấp.

Cài đặt Java 11 trở lên nếu bạn chưa cài đặt trên máy của mình.

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

Trong thư mục mà bạn đã tải xuống hoặc sao chép dự án, hãy chạy các lệnh sau để đảm bảo bạn có cá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

Tìm hiểu về các tệp

Các phần sau đây mô tả bố cục của các thư mục mẫu.

Tên thư mục

Mỗi kho lưu trữ chứa một số thư mục có tên bắt đầu bằng một số, chẳng hạn như /01-basic-app/. Các con số này tương ứng với các bước cụ thể trong hướng dẫn. Mỗi thư mục chứa một ứng dụng web có đầy đủ chức năng, triển khai các tính năng được mô tả trong một hướng dẫn cụ thể. Ví dụ: thư mục /01-basic-app/ chứa phương thức triển khai cuối cùng cho hướng dẫn Tạo một tiện ích bổ sung.

Nội dung trong thư mục

Nội dung thư mục sẽ khác nhau tuỳ thuộc vào ngôn ngữ triển khai:

Python

Thư mục gốc chứa các tệp sau:
- main.py – điểm truy cập vào ứng dụng Python. Chỉ định cấu hình máy chủ mà bạn muốn sử dụng trong tệp này, sau đó chạy tệp để khởi động máy chủ.
- requirements.txt – các mô-đun Python cần thiết để chạy ứng dụng web. Bạn có thể tự động cài đặt các mô-đun này bằng cách sử dụng pip install -r requirements.txt.
- client_secret.json – tệp mật khẩu ứng dụng khách được tải xuống từ Google Cloud. Xin lưu ý rằng thông tin này không có trong tệp lưu trữ mẫu; bạn nên đổi tên và sao chép tệp thông tin đăng nhập đã tải xuống vào từng thư mục gốc.
  
  Lưu ý quan trọng: Bạn phải cung cấp tệp khoá bí mật của ứng dụng từ dự án Google Cloud thì mới có thể chạy các ví dụ.
config.py – các lựa chọn cấu hình cho máy chủ Flask.
Thư mục webapp chứa nội dung cho ứng dụng web. Gói này bao gồm những công cụ sau:
Thư mục /templates/ có các mẫu Jinja cho nhiều trang.
Thư mục /static/ có hình ảnh, CSS và các tệp JavaScript phụ.
routes.py – các phương thức trình xử lý cho các tuyến của ứng dụng web.
__init__.py – trình khởi tạo cho mô-đun webapp. Trình khởi tạo này sẽ khởi động máy chủ Flask và tải các lựa chọn cấu hình được đặt trong config.py.
Các tệp bổ sung theo yêu cầu của một bước cụ thể trong hướng dẫn.

Node.js

Bạn có thể tìm thấy từng bước của hướng dẫn trong thư mục con <step>riêng. Mỗi bước chứa:

Các tệp tĩnh như JavaScript, CSS và hình ảnh nằm trong thư mục ./<step>/public.
Các bộ định tuyến Express nằm trong thư mục ./<step>/routes.
Bạn có thể tìm thấy các mẫu HTML trong thư mục ./<step>/views.
Ứng dụng máy chủ là ./<step>/app.js.

Java

Thư mục dự án bao gồm những nội dung sau:

Thư mục src.main chứa mã nguồn và cấu hình để chạy ứng dụng thành công. Thư mục này bao gồm những nội dung sau: + Thư mục java.com.addons.spring chứa các tệp Application.java và Controller.java. Tệp Application.java chịu trách nhiệm chạy máy chủ ứng dụng trong khi tệp Controller.java xử lý logic điểm cuối. + Thư mục resources chứa thư mục templates có các tệp HTML và JavaScript. Tệp này cũng chứa tệp application.properties chỉ định cổng để chạy máy chủ, đường dẫn đến tệp kho khoá và đường dẫn đến thư mục templates. Ví dụ này bao gồm tệp kho khoá trong thư mục resources. Bạn có thể lưu trữ tệp này ở bất cứ đâu bạn muốn, nhưng hãy nhớ cập nhật tệp application.properties bằng đường dẫn tương ứng.
- pom.xml chứa thông tin cần thiết để tạo dự án và xác định các phần phụ thuộc bắt buộc.
- .gitignore chứa tên tệp không được tải lên git. Đảm bảo rằng bạn thêm đường dẫn đến kho khoá của mình trong .gitignore này. Trong ví dụ được cung cấp, đây là secrets/*.p12 (mục đích của kho khoá sẽ được thảo luận trong phần bên dưới). Đối với hướng dẫn 2 trở lên, bạn cũng nên thêm đường dẫn đến tệp client_secret.json để đảm bảo rằng bạn không đưa các khoá bí mật vào một kho lưu trữ từ xa. Đối với quy trình từng bước 3 trở đi, bạn nên thêm đường dẫn đến tệp cơ sở dữ liệu H2 và nhà máy kho lưu trữ dữ liệu tệp. Bạn có thể xem thêm thông tin về cách thiết lập các kho dữ liệu này trong hướng dẫn thứ ba về xử lý các lượt truy cập lặp lại.
- mvnw và mvnw.cmd lần lượt là các tệp thực thi trình bao bọc Maven cho Unix và Windows. Ví dụ: khi chạy ./mvnw --version trên Unix, hệ thống sẽ xuất phiên bản Apache Maven, cùng với các thông tin khác.
- Thư mục .mvn chứa cấu hình cho trình bao bọc Maven.

Chạy máy chủ mẫu

Bạn cần khởi chạy máy chủ để kiểm thử. Hãy làm theo các hướng dẫn sau để chạy máy chủ mẫu bằng ngôn ngữ bạn chọn:

Python

Thông tin đăng nhập OAuth

Tạo và tải thông tin đăng nhập OAuth xuống như đã mô tả trước đó. Đặt tệp JSON vào thư mục gốc cùng với tệp khởi chạy máy chủ của ứng dụng.

Định cấu hình máy chủ

Bạn có một số lựa chọn để chạy máy chủ web. Ở cuối tệp Python, hãy thêm một trong những nội dung sau:

Không được bảo mật localhost. Xin lưu ý rằng điều này chỉ phù hợp để kiểm thử trực tiếp trong cửa sổ trình duyệt; bạn không thể tải các miền không bảo mật trong iframe tiện ích bổ sung Lớp học.
```
if __name__ == "__main__":
  # Disable OAuthlib's HTTPs verification.
  os.environ["OAUTHLIB_INSECURE_TRANSPORT"] = "1"

  # Run the web app at http://localhost:5000.
  app.run(debug=True)
```

Bảo mật localhost. Bạn phải chỉ định một bộ gồm các tệp khoá SSL cho đối số ssl_context.

if __name__ == "__main__":
  # Run the web app at https://localhost:5000.
  app.run(host="localhost",
          ssl_context=("localhost.pem", "localhost-key.pem"),
          debug=True)

Máy chủ Gunicorn. Điều này phù hợp với việc triển khai máy chủ hoặc đám mây sẵn sàng cho hoạt động sản xuất. Bạn nên đặt biến môi trường PORT để sử dụng với lựa chọn khởi chạy này.

if __name__ == "__main__":
  # Run the web app at https://<your domain>:<server_port>.
  # Defaults to https://<your domain>:8080.
  server_port = os.environ.get("PORT", "8080")
  app.run(debug=True, port=server_port, host="0.0.0.0")

Khởi chạy máy chủ

Chạy ứng dụng Python để khởi chạy máy chủ như đã định cấu hình trong bước trước.

python main.py

Nhấp vào URL xuất hiện để xem ứng dụng web của bạn trong trình duyệt nhằm xác nhận rằng ứng dụng đang chạy đúng cách.

Node.js

Định cấu hình máy chủ

Để chạy máy chủ qua HTTPS, bạn cần tạo một chứng chỉ tự ký dùng để chạy ứng dụng qua HTTPS. Bạn nên lưu các thông tin đăng nhập này dưới dạng sslcert/cert.pem và sslcert/key.pem trong thư mục gốc của kho lưu trữ. Bạn có thể cần thêm các khoá này vào chuỗi khoá của hệ điều hành để trình duyệt chấp nhận chúng.

Đảm bảo rằng *.pem nằm trong tệp .gitignore vì bạn không muốn xác nhận tệp với git.

Khởi chạy máy chủ

Bạn có thể chạy ứng dụng bằng lệnh sau đây, thay thế step01 bằng bước chính xác mà bạn muốn chạy dưới dạng máy chủ (ví dụ: step01 cho 01-basic-app và step02 cho 02-sign-in).

npm run step01

hoặc

npm run step02

Thao tác này sẽ khởi chạy máy chủ web tại https://localhost:5000.

Bạn có thể chấm dứt máy chủ bằng Control + C trong thiết bị đầu cuối.

Java

Định cấu hình máy chủ

Để chạy máy chủ qua HTTPS, bạn cần tạo một chứng chỉ tự ký dùng để chạy ứng dụng qua HTTPS.

Cân nhắc sử dụng mkcert để phát triển cục bộ. Sau khi bạn cài đặt mkcert, các lệnh sau sẽ tạo một chứng chỉ được lưu trữ cục bộ để chạy qua HTTPS.

mkcert -install
mkcert -pkcs12 -p12-file <path_to_keystore> <domain_name>

Ví dụ này bao gồm tệp kho khoá trong thư mục tài nguyên. Bạn có thể lưu trữ tệp này ở bất cứ đâu bạn muốn, nhưng hãy nhớ cập nhật tệp application.properties bằng đường dẫn tương ứng. Tên miền là miền mà bạn chạy dự án trên đó (ví dụ: localhost).

Đảm bảo rằng *.p12 nằm trong tệp .gitignore vì bạn không muốn xác nhận tệp với git.

Khởi chạy máy chủ

Khởi chạy máy chủ bằng cách chạy phương thức main trong tệp Application.java. Ví dụ: trong IntelliJ, bạn có thể nhấp chuột phải vào Application.java > Run 'Application' trong thư mục src/main/java/com/addons/spring hoặc mở tệp Application.java để nhấp vào mũi tên màu xanh lục ở bên trái chữ ký phương thức main(String[] args). Ngoài ra, bạn có thể chạy dự án trong cửa sổ dòng lệnh:

./mvnw spring-boot:run

hoặc trên Windows:

mvnw.cmd spring-boot:run

Thao tác này sẽ khởi chạy máy chủ tại https://localhost:5000 hoặc tại cổng mà bạn đã chỉ định trong application.properties.

Hướng dẫn từng bước Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Ví dụ về cách triển khai

Nơi tải xuống

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

Chứng chỉ HTTPS

Dự án Google Cloud

Thông tin xác thực OAuth

Điều kiện tiên quyết theo ngôn ngữ

Python

Node.js

Java

Tìm hiểu về các tệp

Tên thư mục

Nội dung trong thư mục

Python

Node.js

Java

Chạy máy chủ mẫu

Python

Node.js

Java

Hướng dẫn từng bước