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

בסדרת ההדרכות הזו מוסבר איך פועלים כל החלקים בתוסף פעיל ל-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:

• מאגר Python

• מאגר Java

אפשר להוריד את הדוגמה ל-Node.js כקובץ ZIP:

• ארכיון Node.js

דרישות מוקדמות

כדי להכין פרויקט חדש של תוספי Google Workspace, כדאי לעיין בקטעים הבאים.

אישור HTTPS

אתם יכולים לארח את האפליקציה בכל סביבת פיתוח, אבל התוסף ל-Classroom זמין רק דרך https://. לכן, כדי לפרוס את האפליקציה או לבדוק אותה בתוך ה-iframe של התוסף, צריך שרת עם הצפנת SSL.

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

פרויקט ב-Google Cloud

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

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

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

נקודת מפתח: באפליקציית האינטרנט חייבים להשתמש בפרטי כניסה של OAuth 2.0 שמנוהלים ב-Google Cloud.

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

• עוברים לדף Google Cloud Credentials. מוודאים שבחרתם את הפרויקט הנכון בחלק העליון של המסך.
• לוחצים על CREATE CREDENTIALS ובוחרים באפשרות OAuth client ID בתפריט הנפתח.
• בדף הבא:
  • מגדירים את Application type (סוג האפליקציה) ל-Web application (אפליקציית אינטרנט).
  • בקטע URIs מורשים להפניה אוטומטית, לוחצים על הוספת 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. אפשר להוריד את קוד המקור המלא דרך הקישורים שסופקו.

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

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

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

• config.py – אפשרויות הגדרה לשרת Flask.

• הספרייה webapp מכילה את התוכן של אפליקציית האינטרנט. הוא כולל את האפשרויות הבאות:

• הספרייה /templates/ עם תבניות Jinja לדפים שונים.

• הספרייה /static/ עם קובצי תמונות, CSS ו-JavaScript משניים.

• routes.py – שיטות הטיפול (handler) למסלולי אפליקציית האינטרנט.

• __init__.py – הפונקציה להפעלה של המודול webapp. ה-initializer הזה מפעיל את שרת 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.

הפעלת השרת לדוגמה

נקודת מפתח: אפשר לפתוח את אפליקציית האינטרנט ב-Google Classroom רק דרך HTTPS. פרטים נוספים זמינים בקטע אישור HTTPS.

כדי לבדוק את השרת, צריך להפעיל אותו. כדי להפעיל את שרת הדוגמה בשפה הרצויה, פועלים לפי ההוראות הבאות:

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")
   

הפעלת השרת

אזהרה: לפני שמפעילים את השרת, צריך להגדיר פרויקט ב-Google Cloud כדי לגשת ל-Classroom API ולפרטי הכניסה הנדרשים.

מריצים את אפליקציית Python כדי להפעיל את השרת כפי שהוגדר בשלב הקודם.

python main.py

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

Node.js

הגדרת השרת

כדי להפעיל את השרת דרך HTTPS, צריך ליצור אישור עצמי שמשמש להפעלת האפליקציה דרך HTTPS. צריך לשמור את פרטי הכניסה האלה בתור sslcert/cert.pem ו-sslcert/key.pem בתיקיית השורש של המאגר. יכול להיות שתצטרכו להוסיף את המפתחות האלה לאוסף המפתחות של מערכת ההפעלה כדי שהדפדפן יקבל אותם.

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

הפעלת השרת

אזהרה: לפני שמפעילים את השרת, צריך להגדיר פרויקט ב-Google Cloud כדי לגשת ל-Classroom API ולפרטי הכניסה הנדרשים.

אפשר להריץ את האפליקציה באמצעות הפקודה הבאה, ולהחליף את 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.

הפעלת השרת

אזהרה: לפני שמפעילים את השרת, צריך להגדיר פרויקט ב-Google Cloud כדי לגשת ל-Classroom API ולפרטי הכניסה הנדרשים.

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