תוספים ל-Google Classroom זמינים עכשיו למפתחים! למידע נוסף, יש לעיין במסמכי התיעוד בנושא תוספים.

דף זה תורגם על ידי Cloud Translation API.

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

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

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

המדריך הזה עוסק בנושאים הבאים:

אפשר להשתמש ב-Google Cloud כדי ליצור דף להצגה ב-iframe ב-Classroom.
הוספת כניסה יחידה (SSO) של Google ומתן אפשרות למשתמשים להיכנס.
לבצע קריאות ל-API כדי לצרף את התוסף למטלה.
עליכם לטפל בדרישות העיקריות לשליחת תוספים ובתכונות הנדרשות.

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

הטמעות לדוגמה

דוגמה מלאה זמינה ב-Python. הטמעות חלקיות זמינות גם ב-Java וב-Node.js. ההטמעות האלה הן המקורות לקוד לדוגמה שנמצא בדפים הבאים.

מאיפה להוריד

הדוגמאות של Python ו-Java זמינות במאגרים של GitHub:

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

ארכיון של Node.js

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

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

אישור 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 Client ID בתפריט הנפתח.
בדף הבא:
- מגדירים את 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. אתם יכולים להוריד את קוד המקור המלא מתוך הקישורים שסיפקתם.

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

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

npm install

Java

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

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

אפליקציות Springboo יכולות להשתמש ב-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. שימו לב שהקובץ הזה לא כלול בארכיון לדוגמה. צריך לשנות את השם של קובץ פרטי הכניסה שהורדתם ולהעתיק אותו לכל רמת בסיס של ספרייה.
  
  חשוב: כדי להריץ את הדוגמאות, צריך לספק את הקובץ הסודי של הלקוח מהפרויקט שלכם ב-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 (המטרה של מאגר המפתחות מתוארת בקטע שבהמשך). בהדרכה המפורטת השנייה ואילך, כדאי לכלול גם את הנתיב לקובץ 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, מוסיפים אחת מהאפשרויות הבאות:

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

אבטחת 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)

שרת 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: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.

הפעלת השרת

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