Loạt video hướng dẫn từng bước này minh hoạ tất cả các phần di chuyển của một tiện ích bổ sung đang hoạt động của Lớp học. Mỗi bước hướng dẫn từng bước giải quyết các khái niệm cụ thể, triển khai những khái niệm đó 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 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 chưa hiểu rõ về 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 API và SDK GWM trong bảng điều khiển Google Cloud. Để biết thêm thông tin về SDK GWM, hãy truy cập trang hướng dẫn về trang thông tin trên Google Workspace Marketplace.
Hướng dẫn này bao gồm các chủ đề sau:
- Sử dụng Google Cloud để tạo một trang sẽ hiển thị trong iframe của 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 một bài tập.
- Giải quyết 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 với các khái niệm lập trình và phát triển web cơ bản. Bạn nên đọc Hướng dẫ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 chi tiết cấu hình quan trọng không đượ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 ví dụ tham khảo đầy đủ trong JavaScript, Python và Java. Những cách triển khai này là nguồn của mã mẫu có trong các trang tiếp theo.
Nơi tải xuống
Bạn có thể tải xuống các bản lưu trữ đầy đủ các ví dụ của chúng tôi bằng cách sử dụng các liên kết bên dưới.
Điều kiện tiên quyết
Hãy xem các phần sau đây để 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 trên bất kỳ môi trường phát triển nào, nhưng
tiện ích bổ sung dành cho Lớp học chỉ được cung cấp thông qua https://
. Do đó,
bạn cần một máy chủ có lớp 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 mkcertification nếu bạn cần tạo chứng chỉ cho việc 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 giúp bạn bắt đầu. Phần Thiết lập dự án Google Cloud trong hướng dẫn từng bước đầu tiên cũng hướng dẫn các bước thực hiện các thao tác định cấu hình cụ thể.
Khi hoàn tất, hãy tải ID ứ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 phần Tìm hiểu về các tệp 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 xác thực Google Cloud. Hãy đảm bảo rằng bạn đã chọn đúng dự án ở đầu màn hình.
- Nhấp vào TẠO TRUNG TÂM rồi chọn Mã ứng dụng khách OAuth từ 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 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 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 sẽ 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 thêm các tuyến đường khác 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 có thông tin đăng nhập mới được tạo của mình. Chọn tuỳ chọn TẢI 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ữ cụ thể
Xem tệp README trong mỗi bản 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 FLEDGE. Bạn có thể tải mã nguồn đầy đủ xuống từ đường liên kết ở trên.
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
Trong mỗi thư mục con hướng dẫn đã tải xuống, đều có một requirements.txt
. Bạn có thể nhanh chóng cài đặt các thư viện cần thiết bằng pip
. Hãy sử dụng các lệnh sau để cài đặt các 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ụ về Node.js của chúng ta sử dụng Khung Express. Bạn có thể tải mã nguồn đầy đủ xuống từ đường liên kết ở trên.
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 ta sử dụng khung Spring Boot. Bạn có thể tải mã nguồn đầy đủ xuống từ đường liên kết ở trên.
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ý 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 tạo ra một bản dựng thành công mà không yêu cầu bạn phải 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 nhằm đảm bảo bạn đáp ứng 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 tệp 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 hướng dẫn từng bước cụ thể. Mỗi thư mục 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ụ: 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 tiện ích bổ sung.
Nội dung thư mục
Nội dung thư mục 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 của ứ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 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. Các mô-đun này có thể được cài đặt tự động 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 Cloud. Xin lưu ý rằng dữ liệu này không có trong bản 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 từng gốc của thư mục.
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 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/
chứa hình ảnh, CSS và các tệp JavaScript phụ trợ.routes.py
– phương thức của trình xử lý cho các tuyến của ứng dụng web.__init__.py
– trình khởi tạo của mô-đunwebapp
. Trình khởi tạo này sẽ khởi động máy chủ Flask và tải các tuỳ chọn cấu hình được đặt 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 mỗi bước của quy trình đi bộ trong thư mục con <step>
riêng. 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 thư mục
./<step>/public
. - Bạn có thể tìm thấy bộ định tuyến nhanh trong thư mục
./<step>/routes
. - Bạn có thể tìm thấy 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:
- 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: + Thư mụcjava.com.addons.spring
chứa các tệpApplication.java
vàController.java
. 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
chứa các tệp HTML và JavaScript. Thư mục 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ữ tệp này bất cứ khi nào bạn muốn, nhưng hãy nhớ cập nhật tệpapplication.properties
theo đường dẫn tương ứng.pom.xml
chứa thông tin cần thiết để xây dựng 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 nên được tải lên git. Hãy nhớ thêm đường dẫn vào kho khoá của bạn trong.gitignore
này. Trong ví dụ được cung cấp, đó 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 trong hướng dẫn 2 trở đi, bạn cũng nên thêm đường dẫn đến tệpclient_secret.json
để đảm bảo rằng bạn không đưa các khoá bí mật vào 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à nhà máy kho dữ liệu tệp. Bạn có thể tìm 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 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ần lượt là các tệp thực thi trình bao bọc Maven cho Unix và Windows. Ví dụ: việc chạy./mvnw --version
trên Unix sẽ cho 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 tra. Hãy làm theo hướng dẫn bên dưới để 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 của bạn xuống như mô tả ở trên. Đặ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ố tuỳ 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:
localhost
không bảo mật. Xin lưu ý rằng cách này chỉ phù hợp để kiểm thử trực tiếp trong cửa sổ trình duyệt; bạn sẽ không thể tải miền không an toàn trong iframe của tiện ích bổ sung 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ương pháp này phù hợp để triển khai trên đám mây hoặc máy chủ sẵn sàng phát hành công khai. Bạn nên đặt biến môi trường
PORT
để sử dụng cù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 để chạy máy chủ như đã định cấu hình ở 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 một trình duyệt để 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ự dùng để chạy ứng dụng qua HTTPS. Bạn phải lưu các thông tin xác thực 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 phải thêm các khoá này vào chuỗi khoá hệ điều hành để trình duyệt chấp nhận các khoá đó.
Đảm bảo *.pem
có trong tệp .gitignore
vì bạn không muốn xác nhận tệp này 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
cho đúng bước mà bạn muốn chạy dưới dạng máy chủ (ví dụ: step01
cho 01-cơ bản-app và step02
cho đăng nhập 02).
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:3000
.
Bạn có thể kết thúc máy chủ bằng Control + C
trong thiết bị đầu cuối của mì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ự dùng để chạy ứng dụng qua HTTPS.
Hãy cân nhắc sử dụng mkcertification để 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ứ khi nào bạn muốn, nhưng hãy đảm bảo rằng bạn cập nhật tệp 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 *.p12
có trong tệp .gitignore
vì bạn không muốn xác nhận tệp này 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ý của 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 bạn đã chỉ định trong application.properties
.