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

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

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. ה-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.

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-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.

הפעלת השרת

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