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

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, שמאפשר לבצע build בהצלחה בלי להתקין את 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 – שיטות הטיפול במסלולים של אפליקציית האינטרנט.

• ‫__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 ואת הפקטורי (factory) של מאגר הנתונים של הקובץ. מידע נוסף על ההגדרה של מאגרי הנתונים האלה זמין במדריך השלישי בנושא טיפול בביקורים חוזרים.
  • ‫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.