คำแนะนำแบบทีละขั้น

คำแนะนำแบบทีละขั้นชุดนี้จะแสดงให้เห็นส่วนต่างๆ ที่เคลื่อนไหวได้ทั้งหมดของส่วนเสริม 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 ให้เพิ่มรายการต่อไปนี้

  1. 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)

  2. รักษาความปลอดภัยให้ 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)

  3. เซิร์ฟเวอร์ 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