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

בסדרת ההדרכות הזו מוסבר על כל החלקים של תוסף Classroom פעיל. כל שלב בהדרכה עוסק במושגים ספציפיים ומיישם אותם באפליקציית אינטרנט אחת. המטרה היא לעזור לכם להגדיר, לקבוע את ההגדרות ולהפעיל תוסף פונקציונלי.

התוסף צריך ליצור אינטראקציה עם פרויקט ב-Google Cloud. אם אתם לא מכירים את Google Cloud, מומלץ לקרוא את מדריכי תחילת העבודה. אתם מנהלים את פרטי הכניסה, את הגישה ל-API ואת Google Workspace Marketplace SDK במסוף 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://. לכן, כדי לפרוס את האפליקציה או לבדוק אותה ב-iframe של התוסף, צריך שרת עם הצפנת SSL.

אפשר להשתמש ב-localhost עם אישור SSL. אם אתם צריכים ליצור אישור לפיתוח מקומי, כדאי להשתמש ב-mkcert.

פרויקט ב-Google Cloud

צריך להגדיר פרויקט ב-Google Cloud כדי להשתמש בדוגמאות האלה. במדריך יצירת פרויקט ב-Google Cloud מוסבר מה צריך לעשות כדי להתחיל. בקטע הגדרת פרויקט ב-Google Cloud במדריך הראשון מוסבר גם איך לבצע את פעולות ההגדרה הספציפיות.

בסיום, מורידים את מזהה הלקוח של OAuth 2.0 כקובץ JSON. צריך להוסיף את קובץ פרטי הכניסה הזה לספריית הדוגמה שחולצה. מידע על מיקומים ספציפיים מופיע במאמר הסבר על הקבצים.

פרטי כניסה של OAuth

כדי ליצור פרטי כניסה חדשים של OAuth:

  • עוברים לדף Google Cloud Credentials. מוודאים שבחרתם את הפרויקט הנכון בחלק העליון של המסך.
  • לוחצים על CREATE CREDENTIALS (יצירת אמצעי אימות) ובוחרים באפשרות OAuth client ID (מזהה לקוח OAuth) מהתפריט הנפתח.
  • בדף הבא:
    • מגדירים את סוג האפליקציה בתור אפליקציית אינטרנט.
    • בקטע Authorized redirect URIs (מזהי URI מורשים להפניה אוטומטית), לוחצים על ADD URI (הוספת URI). מוסיפים את הנתיב המלא של מסלול להחזרת קריאה לאפליקציה. לדוגמה, https://my.domain.com/auth-callback או https://localhost:5000/callback. בהמשך המדריך הזה נסביר איך ליצור את המסלול הזה ולטפל בו. אפשר לערוך או להוסיף מסלולים כאלה בכל שלב.
    • לוחצים על יצירה.
  • לאחר מכן מוצגת תיבת דו-שיח עם פרטי הכניסה החדשים שנוצרו. בוחרים באפשרות DOWNLOAD JSON (הורדת JSON). מעתיקים את קובץ ה-JSON שהורדתם לספרייה של השרת.

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

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

Python

בדוגמה שלנו ב-Python נעשה שימוש ב-framework של 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 framework. אפשר להוריד את קוד המקור המלא מהקישורים שצוינו.

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

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

npm install

Java

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

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

אפליקציות Spring Boot יכולות להשתמש ב-Gradle או ב-Maven כדי לטפל בבנייה ולנהל תלות. הדוגמה הזו כוללת את 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. בדוגמה הזו, קובץ מאגר המפתחות נמצא בספרייה resources. אפשר לאחסן אותו בכל מקום שרוצים, אבל חשוב לעדכן את הנתיב בקובץ application.properties בהתאם.
    • ‫pom.xml מכיל את המידע שנדרש כדי לבנות את הפרויקט ולהגדיר את התלות הנדרשת.
    • ‫.gitignore מכיל שמות של קבצים שאסור להעלות ל-git. חשוב להוסיף את הנתיב למאגר המפתחות ב-.gitignore. בדוגמה שמופיעה למעלה, זהו secrets/*.p12 (הסבר על המטרה של מאגר המפתחות מופיע בקטע הבא). במדריכים 2 ואילך, צריך לכלול גם את הנתיב לקובץ client_secret.json כדי לוודא שלא תכללו את הסודות שלכם במאגר מרוחק. במדריכים 3 ואילך, צריך להוסיף את הנתיב לקובץ מסד הנתונים H2 ואת המפעל של מאגר הנתונים של הקובץ. מידע נוסף על ההגדרה של מאגרי הנתונים האלה זמין במדריך השלישי בנושא טיפול בביקורים חוזרים.
    • ‫mvnw ו-mvnw.cmd הם קובצי ההפעלה של Maven Wrapper ל-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. צריך לציין טאפל של קובצי מפתח 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 כי לא רוצים לבצע commit של הקובץ ל-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 כי לא רוצים לבצע commit של הקובץ ל-git.

הפעלת השרת

מפעילים את השרת על ידי הרצת ה-method‏ 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.