คำแนะนำแบบทีละขั้นชุดนี้จะแสดงให้เห็นส่วนต่างๆ ที่เคลื่อนไหวได้ทั้งหมดของส่วนเสริม Classroom ที่ใช้งานได้ คำแนะนำแบบทีละขั้นแต่ละขั้นตอนจะแสดงแนวคิดที่เจาะจง และนำไปใช้ในเว็บแอปพลิเคชันเดียว เป้าหมายคือเพื่อช่วยในการตั้งค่า กำหนดค่า และเปิดใช้งานส่วนเสริมที่ทำงานได้
ส่วนเสริมต้องโต้ตอบกับโปรเจ็กต์ Google Cloud หากคุณไม่คุ้นเคยกับ Google Cloud ขอแนะนำให้อ่านคู่มือเริ่มต้นใช้งาน คุณจะจัดการข้อมูลเข้าสู่ระบบ, การเข้าถึง API และ SDK ของ Google Workspace Marketplace ได้ในคอนโซล Google Cloud โปรดดูข้อมูลเพิ่มเติมเกี่ยวกับ SDK ของ Marketplace ที่หน้าคู่มือข้อมูลผลิตภัณฑ์ใน Google Workspace Marketplace
คู่มือนี้ครอบคลุมหัวข้อต่อไปนี้
- ใช้ Google Cloud เพื่อสร้างหน้าที่จะแสดงใน iframe ใน Classroom
- เพิ่มการลงชื่อเพียงครั้งเดียว (SSO) ของ Google และอนุญาตให้ผู้ใช้ลงชื่อเข้าใช้
- เรียกใช้ API เพื่อแนบส่วนเสริมไปกับงาน
- ปฏิบัติตามข้อกำหนดการส่งส่วนเสริมที่สำคัญและฟีเจอร์ที่จำเป็น
คู่มือนี้จะถือว่าคุณคุ้นเคยกับการเขียนโปรแกรมและแนวคิดพื้นฐานในการพัฒนาเว็บ ขอแนะนำให้อ่านคู่มือการกำหนดค่าโปรเจ็กต์ก่อนเริ่มคำแนะนำแบบทีละขั้น หน้านี้ประกอบด้วยรายละเอียดการกำหนดค่าที่สำคัญในคำแนะนำแบบทีละขั้นไม่ครบ
ตัวอย่างการติดตั้งใช้งาน
มีตัวอย่างการอ้างอิงที่สมบูรณ์ใน Python การติดตั้งใช้งานบางส่วนยังพร้อมใช้งานใน Java และ Node.js อีกด้วย การติดตั้งใช้งานเหล่านี้เป็นแหล่งที่มาของโค้ดตัวอย่างที่พบในหน้าต่อๆ ไป
ดาวน์โหลดได้ที่ไหน
ตัวอย่าง Python และ Java มีอยู่ในที่เก็บ GitHub ดังนี้
ตัวอย่าง Node.js สามารถดาวน์โหลดเป็นไฟล์ ZIP ได้ ดังนี้
สิ่งที่ต้องดำเนินการก่อน
ตรวจสอบส่วนต่อไปนี้เพื่อเตรียมโปรเจ็กต์ส่วนเสริมใหม่
ใบรับรอง HTTPS
แม้ว่าคุณจะโฮสต์แอปในสภาพแวดล้อมการพัฒนาใดก็ได้ แต่ส่วนเสริมของ Classroom จะใช้งานได้ผ่าน https://
เท่านั้น คุณจึงต้องมีเซิร์ฟเวอร์ที่มีการเข้ารหัส SSL เพื่อทำให้แอปใช้งานได้หรือเพื่อทดสอบภายใน iframe ของส่วนเสริม
คุณอาจใช้ localhost
กับใบรับรอง SSL ลองใช้ mkcert หากจำเป็นต้องสร้างใบรับรองสำหรับการพัฒนาในเครื่อง
โปรเจ็กต์ Google Cloud
คุณต้องกำหนดค่าโปรเจ็กต์ Google Cloud เพื่อใช้กับตัวอย่างเหล่านี้ โปรดดูภาพรวมของขั้นตอนที่จำเป็นในการเริ่มต้นใช้งานในคู่มือการ สร้างโปรเจ็กต์ Google Cloud ส่วนตั้งค่าโปรเจ็กต์ Google Cloud ในคำแนะนำแบบทีละขั้นแรกก็มีขั้นตอนการดำเนินการกำหนดค่าเฉพาะที่ต้องทำด้วย
เมื่อเสร็จแล้ว ให้ดาวน์โหลดรหัสไคลเอ็นต์ OAuth 2.0 เป็นไฟล์ JSON คุณต้องเพิ่มไฟล์ข้อมูลเข้าสู่ระบบนี้ลงในไดเรกทอรีตัวอย่างที่คลายการบีบอัดแล้ว โปรดดูทำความเข้าใจเกี่ยวกับไฟล์สำหรับสถานที่ที่ระบุ
ข้อมูลเข้าสู่ระบบ OAuth
ทําตามขั้นตอนต่อไปนี้เพื่อสร้างข้อมูลเข้าสู่ระบบ OAuth ใหม่
- ไปที่หน้าข้อมูลเข้าสู่ระบบ Google Cloud ตรวจสอบว่าได้เลือกโปรเจ็กต์ที่ถูกต้องที่ด้านบนของหน้าจอ
- คลิกสร้างข้อมูลรับรอง แล้วเลือกรหัสไคลเอ็นต์ OAuth จากเมนูแบบเลื่อนลง
- ในหน้าถัดไป
- ตั้งค่าประเภทแอปพลิเคชันเป็นเว็บแอปพลิเคชัน
- ในส่วน URI การเปลี่ยนเส้นทางที่ได้รับอนุญาต ให้คลิกเพิ่ม URI เพิ่มเส้นทางแบบเต็มสำหรับเส้นทาง Callback ของแอปพลิเคชัน เช่น
https://my.domain.com/auth-callback
หรือhttps://localhost:5000/callback
คุณจะสร้างและจัดการเส้นทางนี้ ภายหลังในคำแนะนำแบบทีละขั้นนี้ คุณสามารถแก้ไขหรือเพิ่มเส้นทางดังกล่าวได้ทุกเมื่อ - คลิกสร้าง
- จากนั้นคุณจะได้รับกล่องโต้ตอบที่มีข้อมูลเข้าสู่ระบบที่สร้างขึ้นใหม่ เลือกตัวเลือกดาวน์โหลด JSON คัดลอกไฟล์ JSON ที่ดาวน์โหลดลงในไดเรกทอรีเซิร์ฟเวอร์
ข้อกำหนดเบื้องต้นเฉพาะภาษา
ดูไฟล์ README ในแต่ละที่เก็บเพื่อดูรายการข้อกำหนดเบื้องต้นล่าสุด
Python
ตัวอย่าง Python ของเราใช้เฟรมเวิร์ก Flask คุณสามารถดาวน์โหลดซอร์สโค้ดที่สมบูรณ์ได้จากลิงก์ที่ให้ไว้
หากจำเป็น ให้ติดตั้ง Python 3.7+ และตรวจสอบว่ามี pip
ให้ใช้งาน
python3 -m ensurepip --upgrade
นอกจากนี้ เราขอแนะนำให้คุณตั้งค่าและเปิดใช้งานสภาพแวดล้อมเสมือนของ Python ใหม่
python3 -m venv .classroom-addon-env
source .classroom-addon-env/bin/activate
มี requirements.txt
ในไดเรกทอรีย่อยคำแนะนำแบบทีละขั้นแต่ละรายการในตัวอย่างที่ดาวน์โหลดมา คุณติดตั้งไลบรารีที่จำเป็นได้อย่างรวดเร็วโดยใช้ pip
ใช้คำสั่งต่อไปนี้เพื่อติดตั้งไลบรารีที่จำเป็นสำหรับคำแนะนำแบบทีละขั้นครั้งแรก
cd flask/01-basic-app
pip install -r requirements.txt
Node.js
ตัวอย่าง Node.js ของเราใช้เฟรมเวิร์ก Express คุณสามารถดาวน์โหลดซอร์สโค้ดที่สมบูรณ์ได้จากลิงก์ที่ให้ไว้
ตัวอย่างนี้ต้องใช้ Node.js v16.13 ขึ้นไป
ติดตั้งโมดูลโหนดที่จำเป็นโดยใช้ npm
npm install
Java
ตัวอย่าง Java ของเราใช้เฟรมเวิร์ก Spring Boot คุณสามารถดาวน์โหลดซอร์สโค้ดที่สมบูรณ์ได้จากลิงก์ที่ให้ไว้
ติดตั้ง Java 11+ หากยังไม่ได้ติดตั้งในเครื่อง
แอปพลิเคชัน Spring Boot สามารถใช้ Gradle หรือ Maven เพื่อจัดการบิลด์และจัดการการขึ้นต่อกันได้ ตัวอย่างนี้มี Wrapper ของ Maven ที่ช่วยให้สามารถสร้างบิลด์ได้สำเร็จโดยที่คุณไม่ต้องติดตั้ง Maven เอง
ในไดเรกทอรีที่คุณดาวน์โหลดหรือโคลนโปรเจ็กต์ ให้เรียกใช้คำสั่งต่อไปนี้เพื่อให้แน่ใจว่าคุณมีข้อกำหนดเบื้องต้นเพื่อเรียกใช้โปรเจ็กต์
java --version
./mvnw --version
หรือบน Windows:
java -version
mvnw.cmd --version
ทำความเข้าใจไฟล์
ส่วนต่อไปนี้จะอธิบายเลย์เอาต์ไดเรกทอรีตัวอย่าง
ชื่อไดเรกทอรี
ที่เก็บแต่ละรายการจะมีไดเรกทอรีหลายรายการที่ชื่อขึ้นต้นด้วยตัวเลข เช่น /01-basic-app/
ตัวเลขจะสอดคล้องกับขั้นตอนคำแนะนำแบบทีละขั้นที่เฉพาะเจาะจง
แต่ละไดเรกทอรีจะมีเว็บแอปที่ทำงานได้เต็มรูปแบบซึ่งใช้ฟีเจอร์ที่อธิบายไว้ในคำแนะนำแบบทีละขั้นโดยเฉพาะ เช่น ไดเรกทอรี /01-basic-app/
มีลักษณะการใช้งานสุดท้ายสำหรับคำแนะนำการสร้างส่วนเสริม
เนื้อหาไดเรกทอรี
เนื้อหาไดเรกทอรีจะแตกต่างกันไปตามภาษาที่ใช้งาน ดังนี้
Python
ไดเรกทอรีรากมีไฟล์ต่อไปนี้
main.py
- จุดแรกเข้าของแอปพลิเคชัน Python ระบุการกำหนดค่าเซิร์ฟเวอร์ที่คุณต้องการใช้ในไฟล์นี้ จากนั้นเรียกใช้เพื่อเริ่มต้นเซิร์ฟเวอร์requirements.txt
- โมดูล Python ที่ต้องใช้เพื่อเรียกใช้เว็บแอป ซึ่งติดตั้งได้โดยอัตโนมัติโดยใช้pip install -r requirements.txt
client_secret.json
- ไฟล์รหัสลับไคลเอ็นต์ที่ดาวน์โหลดจาก Google Cloud โปรดทราบว่าข้อมูลนี้ไม่ได้รวมอยู่ในที่เก็บถาวรตัวอย่าง คุณควรเปลี่ยนชื่อและคัดลอกไฟล์ข้อมูลเข้าสู่ระบบที่ดาวน์โหลดมาไปยังรากของไดเรกทอรีแต่ละรายการ
config.py
- ตัวเลือกการกำหนดค่าสำหรับเซิร์ฟเวอร์ Flaskไดเรกทอรี
webapp
มีเนื้อหาสำหรับเว็บแอปพลิเคชัน ซึ่งรวมถึงสิ่งต่อไปนี้ไดเรกทอรี
/templates/
ที่มีเทมเพลต Jinja สำหรับหน้าต่างๆไดเรกทอรี
/static/
ที่มีรูปภาพ, CSS และไฟล์ JavaScript เสริมroutes.py
- เมธอดของเครื่องจัดการสำหรับเส้นทางของเว็บแอปพลิเคชัน__init__.py
- ค่าเริ่มต้นสำหรับโมดูลwebapp
เครื่องมือเริ่มต้นนี้จะเริ่มเซิร์ฟเวอร์ Flask และโหลดตัวเลือกการกำหนดค่าที่กำหนดไว้ในconfig.py
ไฟล์เพิ่มเติมตามที่ขั้นตอนคำแนะนำแบบทีละขั้นกำหนดไว้
Node.js
แต่ละขั้นตอนของคำแนะนำแบบทีละขั้นจะอยู่ในโฟลเดอร์ย่อย <step>
ของตัวเอง แต่ละขั้นตอนประกอบด้วยข้อมูลต่อไปนี้
- ไฟล์แบบคงที่ เช่น JavaScript, CSS และรูปภาพจะอยู่ในโฟลเดอร์
./<step>/public
- พบเราเตอร์ Express ในโฟลเดอร์
./<step>/routes
- เทมเพลต HTML จะอยู่ในโฟลเดอร์
./<step>/views
- แอปพลิเคชันเซิร์ฟเวอร์คือ
./<step>/app.js
Java
ไดเรกทอรีโปรเจ็กต์จะมีข้อมูลต่อไปนี้
- ไดเรกทอรี
src.main
มีซอร์สโค้ดและการกำหนดค่าเพื่อให้เรียกใช้แอปพลิเคชันได้สำเร็จ ไดเรกทอรีนี้ประกอบด้วยไฟล์ต่อไปนี้ + ไดเรกทอรีjava.com.addons.spring
ประกอบด้วยไฟล์Application.java
และController.java
ไฟล์Application.java
มีหน้าที่ในการเรียกใช้แอปพลิเคชันเซิร์ฟเวอร์ในขณะที่ไฟล์Controller.java
จัดการตรรกะปลายทาง ไดเรกทอรีอีกresources
รายการมีไดเรกทอรีtemplates
ที่มีไฟล์ HTML และ JavaScript นอกจากนี้ยังมีไฟล์application.properties
ที่ระบุพอร์ตที่จะเรียกใช้เซิร์ฟเวอร์ เส้นทางไปยังไฟล์คีย์สโตร์ และเส้นทางไปยังไดเรกทอรีtemplates
ตัวอย่างนี้มีไฟล์คีย์สโตร์ในไดเรกทอรีresources
คุณจะจัดเก็บไฟล์ไว้ที่ใดก็ได้ที่ต้องการ แต่โปรดตรวจสอบว่าได้อัปเดตไฟล์application.properties
ด้วยเส้นทางแล้วpom.xml
มีข้อมูลที่จำเป็นในการสร้างโปรเจ็กต์และระบุทรัพยากร Dependency ที่จำเป็น.gitignore
มีชื่อไฟล์ที่ไม่ควรอัปโหลดไปยัง Git ตรวจสอบว่าคุณเพิ่มเส้นทางไปยังคีย์สโตร์ใน.gitignore
นี้ ในตัวอย่างที่ระบุ นี่คือsecrets/*.p12
(วัตถุประสงค์ของคีย์สโตร์จะอธิบายอยู่ในส่วนด้านล่าง) สำหรับคำแนะนำแบบทีละขั้น 2 และนอกเหนือจากนั้น คุณควรใส่เส้นทางไปยังไฟล์client_secret.json
ด้วยเพื่อให้แน่ใจว่าไม่ได้รวมข้อมูลลับไว้ในที่เก็บระยะไกล สำหรับคำแนะนำแบบทีละขั้นที่ 3 ขึ้นไป คุณควรเพิ่มเส้นทางไปยังไฟล์ฐานข้อมูล H2 และแฟ้มฐานข้อมูลไฟล์จากโรงงาน ดูข้อมูลเพิ่มเติมเกี่ยวกับการตั้งค่าพื้นที่เก็บข้อมูลเหล่านี้ได้ในคำแนะนำที่ 3 เกี่ยวกับการจัดการการเข้าชมซ้ำmvnw
และmvnw.cmd
เป็นไฟล์ปฏิบัติการ Wrapper ของ Maven สำหรับ Unix และ Windows ตามลำดับ เช่น การเรียกใช้./mvnw --version
ใน Unix จะแสดงเวอร์ชัน Apache Maven รวมถึงข้อมูลอื่นๆ- ไดเรกทอรี
.mvn
มีการกำหนดค่าสำหรับ Maven Wrapper
เรียกใช้เซิร์ฟเวอร์ตัวอย่าง
คุณต้องเปิดเซิร์ฟเวอร์เพื่อทดสอบ โปรดทำตามวิธีการต่อไปนี้เพื่อเรียกใช้เซิร์ฟเวอร์ตัวอย่างในภาษาที่คุณต้องการ
Python
ข้อมูลเข้าสู่ระบบ OAuth
สร้างและดาวน์โหลดข้อมูลเข้าสู่ระบบ OAuth ตามที่อธิบายไว้ก่อนหน้านี้ วางไฟล์ JSON ในไดเรกทอรีรากควบคู่ไปกับไฟล์การเรียกใช้ของเซิร์ฟเวอร์ของแอปพลิเคชัน
กำหนดค่าเซิร์ฟเวอร์
คุณมีตัวเลือกมากมายในการเรียกใช้เว็บเซิร์ฟเวอร์ ในตอนท้ายของไฟล์ Python ให้เพิ่มรายการต่อไปนี้
localhost
ไม่ปลอดภัย โปรดทราบว่าวิธีนี้เหมาะสำหรับการทดสอบโดยตรงในหน้าต่างเบราว์เซอร์เท่านั้น เนื่องจากโดเมนที่ไม่ปลอดภัยจะโหลดใน iframe ของส่วนเสริมของ Classroom ไม่ได้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)
รักษาความปลอดภัยให้
localhost
คุณต้องระบุ Tuple ของไฟล์คีย์ SSL สำหรับอาร์กิวเมนต์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 ซึ่งเหมาะกับการทำให้เซิร์ฟเวอร์ที่พร้อมสำหรับการใช้งานจริงหรือการทำให้ระบบคลาวด์ใช้งานได้ เราขอแนะนำให้ตั้งค่าตัวแปรสภาพแวดล้อม
PORT
เพื่อใช้กับตัวเลือกการเปิดตัวนี้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")
เปิดเซิร์ฟเวอร์
เรียกใช้แอปพลิเคชัน Python เพื่อเปิดใช้เซิร์ฟเวอร์ตามที่กำหนดค่าไว้ในขั้นตอนก่อนหน้า
python main.py
คลิก URL ที่ปรากฏเพื่อดูเว็บแอปในเบราว์เซอร์เพื่อยืนยันว่าแอปทำงานได้อย่างถูกต้อง
Node.js
กำหนดค่าเซิร์ฟเวอร์
หากต้องการเรียกใช้เซิร์ฟเวอร์ผ่าน HTTPS คุณต้องสร้างใบรับรองตนเองที่ใช้เรียกใช้แอปพลิเคชันผ่าน HTTPS ข้อมูลเข้าสู่ระบบเหล่านี้ควรบันทึกเป็น sslcert/cert.pem
และ sslcert/key.pem
ในโฟลเดอร์รูทของที่เก็บ คุณอาจต้องเพิ่มคีย์เหล่านี้ลงในคีย์เชนระบบปฏิบัติการเพื่อให้เบราว์เซอร์ยอมรับคีย์
ตรวจสอบว่า *.pem
อยู่ในไฟล์ .gitignore
เพราะไม่ต้องการคอมมิตไฟล์ไปยัง git
เปิดเซิร์ฟเวอร์
เรียกใช้แอปพลิเคชันด้วยคำสั่งต่อไปนี้แทน step01
สำหรับขั้นตอนที่ถูกต้องที่ต้องการเรียกใช้ในฐานะเซิร์ฟเวอร์ (เช่น step01
สำหรับ 01-basic-app และ step02
สำหรับ 02-sign-in)
npm run step01
หรือ
npm run step02
การดำเนินการนี้จะเปิดเว็บเซิร์ฟเวอร์เวลา https://localhost:5000
คุณอาจยุติเซิร์ฟเวอร์โดยมี Control + C
อยู่ในเครื่องชำระเงินของคุณ
Java
กำหนดค่าเซิร์ฟเวอร์
หากต้องการเรียกใช้เซิร์ฟเวอร์ผ่าน HTTPS คุณต้องสร้างใบรับรองตนเองที่ใช้เรียกใช้แอปพลิเคชันผ่าน HTTPS
ลองใช้ mkcert สำหรับการพัฒนาในเครื่อง เมื่อติดตั้ง mkcert
แล้ว คำสั่งต่อไปนี้จะสร้างใบรับรองที่เก็บไว้ภายในเครื่องเพื่อเรียกใช้ผ่าน HTTPS
mkcert -install
mkcert -pkcs12 -p12-file <path_to_keystore> <domain_name>
ตัวอย่างนี้มีไฟล์คีย์สโตร์ในไดเรกทอรีทรัพยากร คุณจะจัดเก็บไฟล์ไว้ที่ใดก็ได้ที่ต้องการ แต่โปรดตรวจสอบว่าได้อัปเดตไฟล์ application.properties
ด้วยเส้นทางแล้ว ชื่อโดเมนคือโดเมนที่คุณเรียกใช้โปรเจ็กต์ (เช่น localhost
)
ตรวจสอบว่า *.p12
อยู่ในไฟล์ .gitignore
เพราะไม่ต้องการคอมมิตไฟล์ไปยัง git
เปิดเซิร์ฟเวอร์
เปิดใช้เซิร์ฟเวอร์โดยเรียกใช้เมธอด main
ในไฟล์ Application.java
ตัวอย่างเช่น ใน IntelliJ คุณจะคลิกขวาที่
Application.java
> Run 'Application'
ในไดเรกทอรี src/main/java/com/addons/spring
หรือเปิดไฟล์ Application.java
เพื่อคลิกลูกศรสีเขียวทางด้านซ้ายของลายเซ็นเมธอด main(String[] args)
ก็ได้ หรือเรียกใช้โปรเจ็กต์ในหน้าต่างเทอร์มินัลก็ได้ โดยทำดังนี้
./mvnw spring-boot:run
หรือใน Windows
mvnw.cmd spring-boot:run
การดำเนินการนี้จะเปิดใช้เซิร์ฟเวอร์ที่ https://localhost:5000
หรือที่พอร์ตที่คุณระบุใน application.properties