הדרכות מפורטות

סדרת ההדרכות הזו ממחישה את כל החלקים הנעים של תוסף 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 Credentials. מוודאים שבחרתם את הפרויקט הנכון בחלק העליון של המסך.
  • לוחצים על CREATE CREDENTIALS ובחרו מזהה לקוח ב-OAuth מהתפריט הנפתח.
  • בדף הבא:
    • מגדירים את Application type (סוג האפליקציה) לערך Web application.
    • בקטע URI מורשים להפניה אוטומטית, לוחצים על הוספת URI. מוסיפים את הנתיב המלא של מסלול ההתקשרות חזרה לאפליקציה. לדוגמה, https://my.domain.com/auth-callback או https://localhost:5000/callback. תוכלו ליצור את המסלול הזה ותטפלו בו מאוחר יותר בהדרכה המפורטת הזאת. תמיד אפשר לערוך או להוסיף עוד מסלולים.
    • לוחצים על יצירה.
  • לאחר מכן תופיע תיבת דו-שיח עם פרטי הכניסה החדשים. בוחרים באפשרות Download JSON. מעתיקים את קובץ .json שהורדתם לספריית השרת.

דרישות מוקדמות ספציפיות לשפה

כדאי לצפות בקובץ ה-README בכל ארכיון, כדי לראות את הרשימה העדכנית ביותר של דרישות הסף.

Python

בדוגמה של Python אנחנו משתמשים ב-Flask framework. תוכלו להוריד את קוד המקור המלא מהקישור שלמעלה.

אם צריך, מתקינים את 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 framework. תוכלו להוריד את קוד המקור המלא מהקישור שלמעלה.

הדוגמה הזו מחייבת Node.js v16.13 ואילך.

צריך להתקין את המודולים של הצמתים הנדרשים באמצעות npm.

npm install

Java

הדוגמה ב-Java משתמשת ב-Spring Boot framework. תוכלו להוריד את קוד המקור המלא מהקישור שלמעלה.

מתקינים את Java 11 ואילך אם היא עדיין לא מותקנת במחשב.

אפליקציות Spring Boot יכולות להשתמש ב-Gradle או ב-Maven כדי לטפל בגרסאות build ולנהל יחסי תלות. בדוגמה הזו נכלל wrapper של Maven שמבטיח גרסת build מוצלחת בלי שתצטרכו להתקין את 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 – שיטות ה-handler של הנתיבים באפליקציית האינטרנט.

  • __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 מכיל את המידע הדרוש כדי ליצור את הפרויקט ולהגדיר את יחסי התלות הנדרשים.
    • .gitignore מכיל שמות קבצים שלא צריך להעלות ל-Git. חשוב להוסיף את הנתיב למאגר המפתחות ב.gitignore. בדוגמה שסופקה, השדה secrets/*.p12 (מטרת מאגר המפתחות מתוארת בקטע בהמשך). בהדרכה מפורטת 2 ואילך, כדאי לכלול גם את הנתיב לקובץ client_secret.json כדי לוודא שאתם לא כוללים את הסודות במאגר מרוחק. בהדרכה מפורטת בגרסה 3 ואילך, יש להוסיף את הנתיב לקובץ מסד הנתונים H2 ולמפעל מאגר הנתונים של הקבצים. למידע נוסף על ההגדרה של מאגרי הנתונים האלה, אפשר לעיין בהדרכה השלישית בנושא טיפול בביקורים חוזרים.
    • mvnw ו-mvnw.cmd הם קובצי ההפעלה של wrapper של Maven ל-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. עליכם לציין שני קבצים של מפתחות 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 ו-step02 לכניסה מסוג 02).

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>

הדוגמה הזו כוללת את קובץ מאגר המפתחות בספריית המשאבים. אפשר לאחסן אותו בכל מקום, אבל חשוב לעדכן את הנתיב בקובץ application.properties בהתאם. שם הדומיין הוא הדומיין שבו מריצים את הפרויקט (לדוגמה, localhost).

חשוב לוודא שה-*.p12 נמצא בקובץ .gitignore כי אתם לא רוצים לשמור אותו כ-Git.

הפעלת השרת

כדי להפעיל את השרת, מריצים את השיטה main בקובץ Application.java. ב-IntelliJ, לדוגמה, אפשר ללחוץ לחיצה ימנית על Application.java > Run 'Application' בספרייה src/main/java/com/addons/spring או לפתוח את הקובץ Application.java כדי ללחוץ על החץ הירוק שמשמאל לחתימת method main(String[] args). לחלופין, אפשר להריץ את הפרויקט בחלון טרמינל:

./mvnw spring-boot:run

או ב-Windows:

mvnw.cmd spring-boot:run

הפעולה הזו מפעילה את השרת ב-https://localhost:5000 או ביציאה שציינתם ב-application.properties.