Loạt hướng dẫn từng bước này minh hoạ tất cả các phần chuyển động của một hành động Tiện ích bổ sung dành cho Lớp học. Mỗi bước hướng dẫn từng bước giải quyết cụ thể các khái niệm khác, triển khai chúng trong một ứng dụng web đơn lẻ. Mục tiêu là hỗ trợ bạn trong việc thiết lập, định cấu hình và khởi chạy một tiện ích bổ sung chức năng.
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 bạn không quen với Google Cloud, bạn nên đọc Hướng dẫn bắt đầu sử dụng. Bạn quản lý thông tin xác thực, quyền truy cập vào API và SDK của Google Workspace Marketplace trong bảng điều khiển Google Cloud. Để biết thêm thông tin về chính sách SDK Marketplace, truy cập vào Google Workspace Marketplace trang thông tin.
Hướng dẫn này bao gồm các chủ đề sau:
- Sử dụng Google Cloud để tạo một trang nhằm hiển thị trong iframe trong Lớp học.
- Thêm dịch vụ đăng nhập một lần (SSO) của 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ông việc lập trình và kiến thức web cơ bản các khái niệm cơ bản về phát triển ứng dụng. Bạn nên đọc phần Cấu hình dự án trước khi bắt đầu hướng dẫn từng bước. Trang này chứa các thông tin quan trọng chưa được đề cập đầy đủ trong hướng dẫn từng bước.
Ví dụ về cách triển khai
Bạn có thể xem một ví dụ tham chiếu hoàn chỉnh trong Python. Triển khai một phần cũng có bằng Java và Node.js. Những cách triển khai này là nguồn của mã ví dụ được tìm thấy 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:
Điều kiện tiên quyết
Hãy xem các mục sau để chuẩn bị cho một dự án mới về tiện ích bổ sung.
Chứng chỉ HTTPS
Mặc dù bạn có thể lưu trữ ứng dụng trên bất kỳ môi trường phát triển nào,
Tiện ích bổ sung dành cho Lớp học chỉ được cung cấp cho đến hết ngày https://
. Do đó,
bạn cần một máy chủ được mã hoá SSL để triển khai ứng dụng hoặc kiểm tra ứ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ỉ để 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 để biết thông tin tổng quan về những yêu cầu cần thiết bước đầu tiên để bắt đầu. Bài viết Thiết lập dự án Google Cloud trong hướng dẫn từng bước đầu tiên cũng là các bước thông qua 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 xác thực này vào thư mục mẫu đã giải nén. Hãy xem bài viết Tìm hiểu cho các vị trí cụ thể.
Thông tin đăng nhập OAuth
Hãy làm theo các bước sau để tạo thông tin đăng nhập OAuth mới:
- Chuyển đến trang Thông tin đăng nhập Google Cloud. Đảm bảo bạn đã chọn đúng dự án ở đầu màn hình.
- Nhấp vào TẠO XÁC THỰC và chọn ID ứng dụng khách OAuth từ trình đơn thả xuống.
- Trên trang tiếp theo:
- Đặt Application type (Loại ứng dụng) thành Web application (Ứ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 toàn bộ
path cho tuyến gọi lại cho ứng dụng của bạn. Ví dụ:
https://my.domain.com/auth-callback
hoặchttps://localhost:5000/callback
. Bạn tạo và xử lý tuyến này ở phần sau của hướng dẫn từng bước này. Bạn có thể chỉnh sửa hoặc bổ sung 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 hộp thoại có thông tin đăng nhập mới tạo. Chọn Tuỳ chọn TẢI JSON XUỐNG. Sao chép tệp JSON đã tải xuống vào máy chủ của bạn thư mục.
Điều kiện tiên quyết theo ngôn ngữ cụ thể
Xem tệp README trong mỗi kho lưu trữ để biết danh sách mới nhất các điều kiện tiên quyế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 từ đường liên kết được cung cấp.
Nếu cần, hãy cài đặt Python 3.7+ 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 tài khoản Python ảo mới môi trường.
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
tải các ví dụ xuống. 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
. Dùng những lệnh sau để cài đặt thư viện cần thiết cho
hướng dẫn từng bước đầu tiên.
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 xuống mã nguồn hoàn chỉnh từ đường liên kết được cung cấp.
Ví dụ này yêu cầu phiên bản Node.js v16.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ụ 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 từ đườ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 ứ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.
Trong thư mục mà bạn đã tải xuống hoặc sao chép dự án, hãy chạy lệnh sau đây để đả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ề tệp
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/
. Những con số này tương ứng với các bước hướng dẫn từng bước cụ thể.
Mỗi thư mục đều chứa một ứng dụng web có đầy đủ chức năng giúp triển khai các tính năng
được mô tả trong một hướng dẫn từng bước cụ thể. Ví dụ: /01-basic-app/
Thư mục chứa phần triển khai cuối cùng cho phần Tạo tiện ích bổ sung
hướng dẫn từng bước.
Nội dung 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 máy chủ mà bạn muốn sử dụng trong tệp này, sau đó chạy cấu hình khởi động máy chủ.requirements.txt
– các mô-đun Python cần có để chạy ứng dụng web. Bạn có thể tự động cài đặt các ứng dụng này bằngpip 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 Đám mây. Xin lưu ý rằng nội dung này không được đưa vào kho lưu trữ mẫu; bạn nên đổi tên và sao chép tệp thông tin xác thực đã tải xuống vào mỗi gốc của thư mục.
config.py
– tuỳ chọn cấu hình cho máy chủ Flask.Thư mục
webapp
chứa nội dung dành 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à JavaScript phụ trợ tệp.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ô-đunwebapp
. Chiến dịch này trình khởi tạo khởi động máy chủ Flask và tải các tuỳ chọn cấu hình được thiết lập trongconfig.py
.Các tệp bổ sung theo yêu cầu của một bước hướng dẫn cụ thể.
Node.js
Bạn có thể tìm thấy từng bước của hướng dẫn trong <step>
riêng
thư mục con. Mỗi bước bao gồm:
- Bạn có thể tìm thấy các tệp tĩnh như JavaScript, CSS và hình ảnh trong
./<step>/public
thư mục. - Bạn có thể tìm thấy bộ định tuyến Express trong các thư mục
./<step>/routes
. - Bạn có thể tìm thấy mẫu HTML trong các thư mục
./<step>/views
. - Ứng dụng máy chủ là
./<step>/app.js
.
Java
Thư mục dự án bao gồm:
- Thư mục
src.main
chứa mã nguồn và cấu hình cần chạy ứng dụng thành công. Thư mục này bao gồm: + Thư mụcjava.com.addons.spring
chứa phần tử TệpApplication.java
vàController.java
. Chiến lược phát hành đĩa đơn TệpApplication.java
chịu trách nhiệm chạy máy chủ ứng dụng trong khi tệpController.java
xử lý logic điểm cuối. + Thư mụcresources
chứa thư mụctemplates
có Tệp HTML và JavaScript. Thẻ này cũng chứa Tệpapplication.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ụctemplates
. Ví dụ này bao gồm tệp kho khoá trong thư mụcresources
. Bạn có thể lưu trữ khoá này ở bất cứ đâu thích, nhưng hãy nhớ cập nhậtapplication.properties
với đườ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. Hãy đảm bảo rằng bạn thêm đường dẫn vào 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 dưới đây). Đối với hướng dẫn từng bước 2 và ngoài ra, bạn cũng nên bao gồm cả đường dẫn đếnclient_secret.json
để đảm bảo rằng bạn không bao gồm bí mật trong một kho lưu trữ từ xa. Đối với hướng dẫn từng bước 3 trở lên, bạn nên thêm đường dẫn vào tệp cơ sở dữ liệu H2 và kho dữ liệu của tệp nhà máy. Bạn có thể cung cấp thêm thông tin về việc thiết lập các kho dữ liệu này bạn có thể tìm thấy trong hướng dẫn từng bước thứ ba về cách xử lý các lượt truy cập lặp lại.mvnw
vàmvnw.cmd
là các tệp thực thi trình bao bọc Maven dành cho Unix và Windows. Ví dụ: chạy./mvnw --version
trên Unix sẽ xuất ra phiên bản Apache Maven cùng nhiều 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ủ của mình để 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 đó. Địa điểm tệp JSON trong thư mục gốc cùng với máy chủ của ứng dụng khởi chạy tệp.
Đị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 Python, hãy thêm một trong các đoạn mã sau:
localhost
không an toàn. Lưu ý rằng cách này phù hợp để kiểm thử trực tiếp chỉ hiển thị trong cửa sổ trình duyệt; bạn không thể tải các miền không an toàn trong iframe tiện ích bổ sung dành cho 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ộ 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)
Gunicorn. Phù hợp với máy chủ sẵn sàng phát hành công khai hoặc đám mây. Bạn nên đặt biến môi trường
PORT
cho sử dụng với tuỳ 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 của bạn để 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 để xác nhận rằng nó đ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ự xác nhận
được dùng để chạy ứng dụng qua HTTPS. Các thông tin đăng nhập này phải
được lưu 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ể phải thêm những khoá này vào chuỗi khoá hệ điều hành để
trình duyệt của bạn để chấp nhận chúng.
Đảm bảo rằng *.pem
nằm trong tệp .gitignore
của bạn vì bạn không muốn
xác nhận tệp vào git.
Khởi chạy máy chủ
Bạn có thể chạy ứng dụng bằng lệnh sau đây thay cho step01
cho 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-đăng nhập).
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 dòng lệnh.
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ự xác nhận được dùng để chạy ứng dụng qua HTTPS.
Hãy cân nhắc sử dụng mkcert để phát triển cục bộ. Sau khi cài đặt mkcert
,
các lệnh sau tạo một chứng chỉ được lưu trữ cục bộ để chạy trên
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ữ dữ liệu đó ở bất cứ nơi nào bạn muốn, nhưng hãy đảm bảo rằng bạn cập nhật
application.properties
với đường dẫn tương ứng. Tên miền là
miền mà bạn chạy dự án (ví dụ: localhost
).
Đảm bảo rằng *.p12
nằm trong tệp .gitignore
của bạn vì bạn không muốn
xác nhận tệp vào git.
Khởi chạy máy chủ
Chạy máy chủ bằng cách chạy phương thức main
trong Application.java
. Chẳng hạn như trong IntelliJ, bạn có thể nhấp chuột phải
Application.java
> Run 'Application'
trong
Thư mục src/main/java/com/addons/spring
hoặc mở Application.java
hãy nhấp vào mũi tên màu xanh lục ở bên trái main(String[] args)
của phương thức. Ngoài ra, bạn có thể chạy dự án trong một thiết bị đầu cuối
thời lượng:
./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
được chỉ định trong application.properties
.