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

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

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

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

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

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

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

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-בסיסית ו-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.

הפעלת השרת

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