שימוש ב-Apache Maven ובתוסף App Engine (מבוסס Google Cloud CLI)

בדף הזה מוסבר איך לנהל פרויקט App Engine עבור Cloud Endpoints Frameworks API באמצעות Apache Maven. ‫Apache Maven הוא כלי לניהול פרויקטים של תוכנה ולהבנתם, שיכול ליצור קובצי ארכיון אפליקציות אינטרנט (WAR) לצורך פריסה ב-App Engine. ‫Google מספקת פלאגין וארכיטיפים של Maven שנתמכים על ידי Maven 3.3.9 ומעלה.

‫Maven מוריד את ספריות Java מ-App Engine SDK. אתם יכולים להשתמש ב-Maven כדי לבדוק את האפליקציה באופן מקומי ולפרוס אותה ב-App Engine.

לפני שמתחילים

  1. משתמשים במסוף Google Cloud כדי ליצור ולהגדיר את פרויקט Google Cloud :

    מעבר אל App Engine

    1. בוחרים פרויקט קיים או יוצרים פרויקט חדש. Google Cloud
    2. אם צריך ליצור אפליקציית App Engine לפרויקט, פועלים לפי ההנחיות כדי לבחור את האזור שבו רוצים למקם את אפליקציית App Engine.
  2. מורידים ומתקינים את ה-CLI של gcloud, ואז מפעילים את Google Cloud CLI.

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

  3. מתקינים את רכיב app-engine-java של ה-CLI של gcloud: 
    gcloud components install app-engine-java

    הערה: כדי לוודא שמותקנת הגרסה העדכנית של ה-CLI של gcloud ל-Java, מריצים את הפקודה gcloud components update.

  4. אם אין לכם Java, אתם צריכים להוריד, להתקין ולהגדיר אותה.
  5. מגדירים את דגלי מהדר Java בקובץ pom.xml של הפרויקט כדי לציין קוד בייט של Java 8: 
    <properties>
  <maven.compiler.source>1.8</maven.compiler.source>
  <maven.compiler.target>1.8</maven.compiler.target>
</properties>
  6. צריך להתקין את Apache Maven מגרסה 3.3.9 ומעלה. כדי לקבוע את גרסת Maven, מריצים את הפקודה הבאה: 
     mvn -v
  7. אם לא מותקנת אצלכם גרסה מתאימה של Maven:
    1. מורידים את גרסה 3.3.9 של Maven או גרסה חדשה יותר מהאתר של Maven.
    2. מתקינים את Maven במחשב המקומי.

      הערה: משתמשי Linux אולי יצטרכו להוריד את Maven במקום להשתמש ב-apt-get install.

הוספת App Engine Maven Plugin לפרויקט קיים (אופציונלי)

כדי להשתמש ב-App Engine Maven plugin בפרויקט Maven קיים, מוסיפים את הקוד הבא לקטע plugins בקובץ pom.xml של הפרויקט:

<plugin>
   <groupId>com.google.cloud.tools</groupId>
   <artifactId>appengine-maven-plugin</artifactId>
   <version>2.8.1</version>
</plugin>

בחירת ארכיטיפ של App Engine

ארכיטיפים של Maven מאפשרים למשתמשים ליצור פרויקטים של Maven באמצעות תבניות שמכסות תרחישים נפוצים. ‫App Engine משתמש בתכונה הזו של Maven כדי לספק כמה ארכיטיפים שימושיים של App Engine ב-Maven Central. בוחרים ארכיטיפ של App Engine שמתאים לאפליקציה:

סוג האפליקציה פריט מידע שנוצר בתהליך תיאור
מסגרות Endpoints ל-App Engine endpoints-skeleton-archetype יוצר פרויקט חדש וריק של Endpoints Frameworks for App Engine backend API, שמוכן להוספה של מחלקות ומשאבים משלכם, עם הקבצים והספריות הנדרשים.
מסגרות של נקודות קצה ל-App Engine hello-endpoints-archetype יוצר פרויקט API של Endpoints Frameworks עבור App Engine backend, שמוכן לבנייה ולהרצה.

יצירת פרויקט חדש באמצעות Maven

במהלך יצירת הפרויקט, מערכת Maven מבקשת לספק את הערכים groupId, artifactId, version ו-package של הפרויקט.

מונח משמעות
groupId מרחב שמות ב-Maven למעקב אחרי הארטיפקטים. כשאנשים משתמשים בפרויקט שלכם בפרויקט Maven משלהם, הוא משמש כמאפיין של התלות שהם מציינים.
artifactId השם של הפרויקט ב-Maven. הוא מצוין גם על ידי צרכנים של הפרויקט שלכם כשהם תלויים בכם בפרויקטים שלהם ב-Maven.
version גרסת Maven הראשונית שרוצים שהפרויקט ייווצר איתה. מומלץ להוסיף את הסיומת -SNAPSHOT ל-version, כי כך יש תמיכה בתוסף Maven release לגרסאות שנמצאות בפיתוח. מידע נוסף על השימוש בתוסף ההפצה מופיע במדריך Maven.
package חבילת Java שנוצרה במהלך היצירה.

יצירת אפליקציה חדשה של Endpoints Frameworks

בקטע הזה מתואר תהליך היצירה של פרויקט חדש ב-Endpoints Frameworks גרסה 2.0.

ב-hello-endpoints-archetype יש דוגמה לשימוש בתוספים, כולל App Engine Maven Plugin ו-Endpoints Frameworks Maven Plugin.

‫hello-endpoints-archetype יוצר דוגמה ל-API של Greetings באמצעות Endpoints Frameworks גרסה 2.0. הוא גם משמש כדוגמה להעברת אפליקציות של Endpoints Frameworks מגרסה 1.0 לגרסה 2.0.

ה-README.md שנוצר עם האב-טיפוס מספק מידע על המקום שבו ההעברה התרחשה.

כדי ליצור פרויקט ארכיטיפ של Endpoints Frameworks עבור API של קצה עורפי ב-App Engine:

  1. משנים את הספרייה לספרייה שבה רוצים לבנות את הפרויקט.

  2. מריצים את פקודת Maven הבאה:

    mvn archetype:generate -Dgoogle-cloud-project=[YOUR-PROJECT-ID] -Dappengine-plugin=2.8.1 -Dendpoints-frameworks=2.1.0 -Dendpoints-plugin=1.0.2 -Dappengine-sdk=1.9.98 -Dfilter=com.google.appengine.archetypes:

    כאשר:

    • ‫-Dgoogle-cloud-project מוגדר למזהה הפרויקט.
    • ‫-Dappengine-plugin מוגדר לגרסה העדכנית ביותר של התוסף App Engine Maven.
    • ‫-Dendpoints-frameworks מוגדר לגרסה העדכנית ביותר של Endpoints Frameworks for App Engine עבור תלות ב-Maven.
    • ‫-Dendpoints-plugin מוגדר לגרסה העדכנית ביותר של Endpoints Frameworks for App Engine Maven Plugin.

  3. צריך להזין את המספר שמתאים ל-hello-endpoints-archetype.

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

  5. כשמוצגת ההודעה Define value for property 'groupId', מציינים את מרחב השמות של האפליקציה. לדוגמה, מציינים את הערך com.example.helloendpoints.

  6. כשמוצגת ההודעה Define value for property 'artifactId', מציינים את שם הפרויקט. לדוגמה, מציינים את הערך helloendpoints.

  7. כשמוצגת הבקשה Define value for property 'version', מאשרים את ערך ברירת המחדל.

  8. כשמוצגת הבקשה Define value for property 'package', מאשרים את ערך ברירת המחדל.

  9. כשמופיעה בקשה לאשר את הבחירות, מקבלים את ערך ברירת המחדל על ידי הקלדת Y.

  10. מחכים שהפרויקט יסיים את היצירה. ואז משנים את הספרייה לספריית הפרויקט החדשה, לדוגמה helloendpoints/.

  11. יוצרים את הפרויקט.

    mvn clean package

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

    [INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 4.062 s
[INFO] Finished at: 2017-02-28T00:28:03-08:00
[INFO] Final Memory: 27M/485M
[INFO] ------------------------------------------------------------------------

  13. כדי לבדוק באופן מקומי ולפרוס את הפרויקט בסביבה הרגילה של App Engine, כדאי לעיין במאמר ניהול, בדיקה ופריסה של פרויקט Maven.

  14. בנוסף, אפשר ליצור ספריות לקוח Java ל-Greeting API באמצעות Endpoints Frameworks Maven Plugin:

    mvn endpoints-framework:clientLibs

התרשים הבא מציג את פריסת הפרויקט הבסיסית של Greetings API:

פריסת פרויקט Maven

  • השדה README.md מכיל מידע על הדוגמה שנוצרה.
  • ‫Greetings.java מכיל הגדרת API לדוגמה של Greetings API.
  • ‫Constants.java מכיל קבועים שמשמשים בדוגמה Greetings API.
  • ‫HelloGreeting.java מכיל מאגר להודעות שהתקבלו ונשלחו מ-Greetings API לדוגמה.
  • ‫index.html מכיל ממשק משתמש פשוט לקריאה ל-Greetings API בקצה העורפי.
  • ‫base.js מכיל JavaScript שנדרש לממשק המשתמש כדי לבצע בקשות לשרת.
  • build.gradle אחרי שהדוגמה נוצרת, היא תומכת גם ב-Gradle. מידע נוסף על הפונקציונליות הזו זמין בREADME.md.

קומפילציה ו-build של האפליקציה

כדי לפתח אפליקציה שנוצרה באמצעות ארכיטיפים של Maven App Engine:

  1. עוברים לספרייה הראשית של הפרויקט, לדוגמה, guestbook/.

  2. מריצים את Maven:

    mvn clean package

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

    BUILD SUCCESS
 Total time: 10.724s
 Finished at: 2016-08-04T16:18:24-07:00
 Final Memory: 24M/213M

בדיקת האפליקציה באמצעות שרת הפיתוח

במהלך שלב הפיתוח, אתם יכולים להריץ ולבדוק את האפליקציה בכל שלב בשרת הפיתוח על ידי הרצת התוסף App Engine Maven.

כדי לבדוק את מסגרות Endpoints עבור אפליקציית App Engine:

  1. אם עדיין לא עשיתם זאת, אתם צריכים לבנות את האפליקציה:

    mvn clean package

  2. מריצים את הדוגמה באופן מקומי:

    mvn appengine:run

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

    [INFO] GCLOUD: INFO ### devappserver2.py:764] Skipping SDK update check.
[INFO] GCLOUD: INFO ### api_server.py:268] Starting API server at: http://localhost:34199
[INFO] GCLOUD: INFO ### dispatcher.py:199] Starting module "default" running at: http://localhost:8080
[INFO] GCLOUD: INFO ### admin_server.py:116] Starting admin server at: http://localhost:8000
[INFO] GCLOUD: ### com.google.appengine.tools.development.SystemPropertiesManager setSystemProperties

  3. כדי לגשת לאפליקציה, נכנסים לכתובת http://localhost:8080/ בדפדפן.

  4. מכבים את האפליקציה ואת שרת הפיתוח על ידי לחיצה על Control+C.

ציון יציאה לבדיקה מקומית

כשמריצים את האפליקציה בשרת הפיתוח המקומי, יציאת ברירת המחדל היא 8080. אפשר לשנות את ברירת המחדל הזו על ידי שינוי של רשומת הפלאגין עבור appengine-maven-plugin. לדוגמה, אפשר לציין את היציאה והכתובת בקובץ pom.xml של ספריית האפליקציה:

<plugins>
   <plugin>
     <groupId>com.google.cloud.tools</groupId>
     <artifactId>appengine-maven-plugin</artifactId>
     <version>2.8.1</version>
     <configuration>
       <devserver.host>0.0.0.0</devserver.host>
       <devserver.port>8181</devserver.port>
     </configuration>
  </plugin>
</plugins>

בדוגמה הזו, <devserver.port> מגדיר את היציאה ל-8181 במקום ברירת המחדל, וכתובת 0.0.0.0 מצוינת, מה שאומר ששרת הפיתוח מאזין לבקשות שמגיעות מהרשת המקומית.

הקידומת devserver היא אופציונלית. אפשר להשתמש במקומה ב-<port>8181</port>.

ניפוי באגים בשרת הפיתוח

כדי לנפות באגים באפליקציה שפועלת באופן מקומי, מגדירים את jvmFlags בהגדרות הפלאגין כדי להפעיל ניפוי באגים ב-JVM הבסיסי, לדוגמה:

<configuration>
  <jvmFlags>
    <jvmFlag>-Xdebug</jvmFlag>
    <jvmFlag>-Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005</jvmFlag>
  </jvmFlags>
</configuration>

פריסת האפליקציה

כדי לפרוס את האפליקציה:

mvn appengine:deploy

לappengine:deployיעד ולכל היעדים האחרים בתוסף App Engine Maven יש פרמטרים משויכים שאפשר להשתמש בהם. רשימה מלאה של המטרות והפרמטרים מופיעה במאמר App Engine Maven plugin goals and parameters.

המאמרים הבאים

  • אפשר לעיין בקוד של התוסף App Engine Maven ולדווח על בעיות ב-GitHub.
  • כדי ללמוד איך מציינים פרמטרים ליעדים, אפשר לעיין במאמר App Engine Maven Goals and Parameters.
  • אפשר לעיין בקוד של התוסף Endpoints Frameworks Maven ולדווח על בעיות ב-GitHub.
  • כדי ללמוד איך מציינים פרמטרים ליעדים, אפשר לעיין בתוסף Cloud Endpoints Frameworks Maven.