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

คำแนะนำแบบทีละขั้นชุดนี้จะแสดงให้เห็นการเคลื่อนไหวทั้งหมดของส่วนเสริม Classroom ที่ใช้งานได้ คำแนะนำแบบทีละขั้นแต่ละขั้นตอนกล่าวถึงแนวคิดเฉพาะ โดยนำไปใช้ในเว็บแอปพลิเคชันเดียว โดยมีเป้าหมายเพื่อช่วยคุณในการตั้งค่า กำหนดค่า และเปิดใช้ส่วนเสริมที่ทำงานได้

ส่วนเสริมต้องโต้ตอบกับโปรเจ็กต์ Google Cloud หากคุณไม่คุ้นเคยกับ Google Cloud เราขอแนะนำให้อ่านคู่มือเริ่มต้นใช้งาน คุณจะจัดการข้อมูลเข้าสู่ระบบ การเข้าถึง API และ GWM SDK ได้ในคอนโซล Google Cloud โปรดดูข้อมูลเพิ่มเติมเกี่ยวกับ GWM SDK ที่หน้าคู่มือข้อมูลใน Google Workspace Marketplace

คู่มือนี้ครอบคลุมหัวข้อต่อไปนี้

  • ใช้ Google Cloud เพื่อสร้างหน้าเว็บที่จะแสดงใน iframe ใน Classroom
  • เพิ่มการลงชื่อเพียงครั้งเดียว (SSO) ของ Google และอนุญาตให้ผู้ใช้ลงชื่อเข้าใช้
  • ทำการเรียก API เพื่อแนบส่วนเสริมไปกับงาน
  • ปฏิบัติตามข้อกำหนดสำคัญเกี่ยวกับการส่งส่วนเสริมและฟีเจอร์ที่จำเป็น

คู่มือนี้มีสมมติฐานว่าคุณคุ้นเคยกับแนวคิดการเขียนโปรแกรมและการพัฒนาเว็บขั้นพื้นฐาน เราขอแนะนำให้อ่านคู่มือการกำหนดค่าโปรเจ็กต์ก่อนเริ่มคำแนะนำแบบทีละขั้น หน้านี้มีรายละเอียดการกำหนดค่าที่สำคัญที่ไม่ได้กล่าวถึงในคำแนะนำแบบทีละขั้นทั้งหมด

ตัวอย่างการติดตั้งใช้งาน

ตัวอย่างการอ้างอิงแบบเต็มมีอยู่ใน JavaScript, Python และ Java การติดตั้งเหล่านี้เป็นแหล่งที่มาของโค้ดตัวอย่างที่พบในหน้าต่อๆ ไป

ตำแหน่งที่จะดาวน์โหลด

ดาวน์โหลดที่เก็บถาวรตัวอย่างทั้งหมดได้โดยใช้ลิงก์ด้านล่าง

ข้อกำหนดเบื้องต้น

ตรวจสอบส่วนต่อไปนี้เพื่อเตรียมโปรเจ็กต์ส่วนเสริมใหม่

ใบรับรอง 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 เพิ่มเส้นทางแบบเต็มสำหรับเส้นทางโค้ดเรียกกลับสำหรับแอปพลิเคชัน ตัวอย่างเช่น 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 เพื่อจัดการบิลด์และจัดการทรัพยากร Dependency ได้ ตัวอย่างนี้มี Maven Wrapper ที่ช่วยให้มั่นใจได้ว่าบิลด์จะประสบความสำเร็จโดยที่คุณไม่ต้องติดตั้ง 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 ตัวอย่างนี้มีไฟล์ keystore ในไดเรกทอรี resources คุณจะจัดเก็บไฟล์ไว้ที่ใดก็ได้ที่ต้องการ แต่อย่าลืมอัปเดตไฟล์ application.properties ให้มีเส้นทางสอดคล้องกันด้วย
    • pom.xml มีข้อมูลที่จำเป็นในการสร้างโปรเจ็กต์และกำหนดทรัพยากร Dependency ที่จำเป็น
    • .gitignore มีชื่อไฟล์ที่ไม่ควรอัปโหลดไปยัง Git ตรวจสอบว่าคุณเพิ่มเส้นทางไปยังคีย์สโตร์ใน .gitignore นี้ ในตัวอย่างที่ให้ไว้คือ secrets/*.p12 (เราจะกล่าวถึงวัตถุประสงค์ของคีย์สโตร์ในส่วนด้านล่าง) สำหรับคำแนะนำแบบทีละขั้น 2 และหลังจากนั้น คุณควรใส่เส้นทางไปยังไฟล์ client_secret.json ด้วยเพื่อให้แน่ใจว่าไม่ได้รวมข้อมูลลับไว้ในที่เก็บระยะไกล สำหรับคำแนะนำแบบทีละขั้น 3 และหลังจากนั้น คุณควรเพิ่มเส้นทางไปยังไฟล์ฐานข้อมูล H2 และไฟล์ฐานข้อมูลไฟล์ ดูข้อมูลเพิ่มเติมเกี่ยวกับการตั้งค่าพื้นที่เก็บข้อมูลเหล่านี้ได้ในคำแนะนำแบบทีละขั้น 3 เกี่ยวกับการจัดการการเข้าชมซ้ำ
    • mvnw และ mvnw.cmd เป็นไฟล์ปฏิบัติการของ Maven Wrapper สำหรับ Unix และ Windows ตามลำดับ ตัวอย่างเช่น การเรียกใช้ ./mvnw --version บน Unix จะสร้างเอาต์พุตเวอร์ชัน Apache Maven รวมถึงข้อมูลอื่นๆ
    • ไดเรกทอรี .mvn มีการกำหนดค่าสำหรับ Wrapper ของ Maven

เรียกใช้เซิร์ฟเวอร์ตัวอย่าง

คุณต้องเปิดเซิร์ฟเวอร์เพื่อทดสอบ โปรดทำตามวิธีการด้านล่างเพื่อเรียกใช้เซิร์ฟเวอร์ตัวอย่างในภาษาที่คุณต้องการ

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:3000

คุณสามารถยกเลิกเซิร์ฟเวอร์ด้วย Control + C ในเทอร์มินัลได้

Java

กำหนดค่าเซิร์ฟเวอร์

หากต้องการเรียกใช้เซิร์ฟเวอร์ผ่าน HTTPS คุณต้องสร้างใบรับรองด้วยตนเองที่ใช้เรียกใช้แอปพลิเคชันผ่าน HTTPS

พิจารณาใช้ mkcert สำหรับการพัฒนาในท้องถิ่น เมื่อติดตั้ง mkcert แล้ว คำสั่งต่อไปนี้จะสร้างใบรับรองที่จัดเก็บไว้ในเครื่องเพื่อเรียกใช้ผ่าน HTTPS

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

ตัวอย่างนี้มีไฟล์ keystore ในไดเรกทอรีทรัพยากร คุณจะจัดเก็บไฟล์ดังกล่าวได้ทุกที่ที่ต้องการ แต่อย่าลืมอัปเดตไฟล์ 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