העברה לגרסה 2.0 של Cloud Endpoints Frameworks ל-App Engine

בדף הזה מוסבר איך להעביר אפליקציה קיימת של Cloud Endpoints בגרסה 1.0 אל Endpoints Frameworks for App Engine ב-Java.

יתרונות

למסגרת החדשה יש כמה יתרונות, כולל:

  • זמן האחזור של הבקשות קוצר.
  • שילוב טוב יותר עם תכונות של App Engine, כמו דומיינים בהתאמה אישית.
  • תמיכה רשמית בהגדרות של Guice.
  • אופציונלית, תכונות חדשות לניהול API.

גרסה 2.0 של Endpoints Frameworks לא משפיעה על הממשקים של ה-API. לקוחות קיימים ממשיכים לפעול אחרי ההעברה בלי שנדרשים שינויים בקוד בצד הלקוח.

תכונות וכלים שמוחרגים כרגע

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

  • פרוטוקול JSON-RPC, שנדרש ללקוחות iOS מדור קודם. כדי ליצור לקוחות iOS ל-API של Endpoints Frameworks בגרסה 2.0, מומלץ להשתמש בספריית הלקוח של Google APIs Objective-C ל-REST APIs.
  • תגי ETags אוטומטיים
  • שדות סוג אוטומטיים
  • שילוב עם IDE
  • fields תשובות חלקיות
  • יצירה אוטומטית של שיטת PATCH API

בנוסף, אין כרגע תמיכה ב-Android Studio בנקודות קצה בגרסה 1.0 בגרסה 2.0.

העברה לגרסה 2.0 של Endpoints Frameworks

גרסה 2.0 של Endpoints Frameworks הועברה לארטיפקטים של Maven בקבוצה com.google.endpoints. קובץ ה-JAR הנדרש הבסיסי נמצא בארטיפקט endpoints-framework. אם רוצים להשתמש בהגדרת Guice, מוסיפים את ארטיפקט endpoints-framework-guice.

ההוראות הבאות מספקות דוגמה להעברה מ-Endpoints Frameworks גרסה 1.0 ל-Endpoints Frameworks גרסה 2.0 באמצעות מסמך Discovery:

  1. מורידים ומפעילים את Google Cloud CLI.
  2. מריצים את הפקודות הבאות:
    1. מוודאים של-CLI של gcloud יש הרשאה לגשת לנתונים ולשירותים שלכם ב- Google Cloud: 
      gcloud auth login
    2. שימוש ב-Application Default Credentials: 
      gcloud auth application-default login
    3. מתקינים את רכיב app-engine-java של Google Cloud SDK: 
      gcloud components install app-engine-java
    4. מעדכנים לגרסה האחרונה של ה-SDK של Google Cloud וכל הרכיבים: 
      gcloud components update

העברה באמצעות Maven או Gradle

Maven

  1. מסירים את התלות הקודמת, שהיא פריט המידע appengine-endpoints: 
    <dependency>
      <groupId>com.google.appengine</groupId>
      <artifactId>appengine-endpoints</artifactId>
      <version>1.9.53</version>
</dependency>
  2. מוסיפים את יחסי התלות החדשים של Endpoints Frameworks: 
    <dependency>
    <groupId>com.google.endpoints</groupId>
    <artifactId>endpoints-framework</artifactId>
    <version>2.2.1</version>
</dependency>
  3. מוסיפים את הפלאגין החדש Endpoints Frameworks ומגדירים את שם המארח למסמך Discovery שנוצר: 
    <plugin>
    <groupId>com.google.cloud.tools</groupId>
    <artifactId>endpoints-framework-maven-plugin</artifactId>
    <version>1.0.2</version>
    <configuration>
        <!-- plugin configuration -->
        <hostname>YOUR-PROJECT-ID.appspot.com</hostname>
    </configuration>
</plugin>
  4. מוסיפים את הפלאגין החדש של App Engine Maven: 
    <plugin>
    <groupId>com.google.cloud.tools</groupId>
    <artifactId>appengine-maven-plugin</artifactId>
    <version>1.3.2</version>
    <configuration>
        <!-- deploy configuration -->
    </configuration>
</plugin>
  5. מעדכנים את נקודת הכניסה ל-API בקובץ web.xml של הפרויקט:
    • שינוי השם של כל המופעים של SystemServiceServlet לEndpointsServlet
    • מחליפים את כל המופעים של הנתיב /_ah/spi/ בנתיב החדש הנדרש /_ah/api/

    בהמשך מוצג התוכן של web.xml לפני ואחרי ההעברה:

    לפני ההעברה

    ‫Endpoints Frameworks גרסה 1.0 web.xml: 
    <servlet>
    <servlet-name>SystemServiceServlet</servlet-name>
    <servlet-class>com.google.api.server.spi.SystemServiceServlet</servlet-class>
    <init-param>
        <param-name>services</param-name>
        <param-value>com.example.helloendpoints.Greetings</param-value>
    </init-param>
    <init-param>
        <param-name>restricted</param-name>
        <param-value>false</param-value>
    </init-param>
</servlet>
<servlet-mapping>
    <servlet-name>SystemServiceServlet</servlet-name>
    <url-pattern>/_ah/spi/*</url-pattern>
</servlet-mapping>

    אחרי המיגרציה

    ‫Endpoints Frameworks גרסה 2.0 web.xml: 
    <servlet>
    <servlet-name>EndpointsServlet</servlet-name>
    <servlet-class>com.google.api.server.spi.EndpointsServlet</servlet-class>
    <init-param>
        <param-name>services</param-name>
        <param-value>com.example.helloendpoints.Greetings</param-value>
    </init-param>
    <init-param>
        <param-name>restricted</param-name>
        <param-value>false</param-value>
    </init-param>
</servlet>
<servlet-mapping>
    <servlet-name>EndpointsServlet</servlet-name>
    <url-pattern>/_ah/api/*</url-pattern>
</servlet-mapping>

  6. אחרי שינוי התלויות, מנקים את הפרויקט: 
    mvn clean
  7. אפשר ליצור מסמך Discovery: 
    mvn endpoints-framework:discoveryDocs
     מידע נוסף על יעדי הפלאגין של Maven Endpoints Frameworks
  8. אפשר לפרוס פרויקט: 
    mvn appengine:deploy

    מידע נוסף על מטרות הפלאגין Maven App Engine

Gradle

  1. מסירים את התלות הקודמת, שהיא פריט המידע appengine-endpoints: 
    compile group: 'com.google.appengine', name: 'appengine-endpoints', version: '+'
  2. מוסיפים את יחסי התלות החדשים של Endpoints Frameworks: 
    compile group: 'com.google.endpoints', name: 'endpoints-framework', version: '2.0.8'
  3. מוסיפים את הפלאגינים החדשים של App Engine ו-Endpoints Frameworks: 
    buildscript {    // Configuration for building
  repositories {
    mavenCentral()
    jcenter()    // Bintray's repository - a fast Maven Central mirror & more
  }
  dependencies {
    // App Engine Gradle plugin
    classpath 'com.google.cloud.tools:appengine-gradle-plugin:1.3.3'

    // Endpoints Frameworks Gradle plugin
    classpath 'com.google.cloud.tools:endpoints-framework-gradle-plugin:1.0.2'
  }
}
  4. החלת התוספים החדשים של App Engine ו-Endpoints Frameworks: 
    apply plugin: 'com.google.cloud.tools.appengine'
apply plugin: 'com.google.cloud.tools.endpoints-framework-server'
  5. הגדרת נקודת הקצה של שם המארח למסמכי Discovery שנוצרו: 
    endpointsServer {
  // Endpoints Framework Plugin server-side configuration
  hostname = "YOUR-PROJECT-ID.appspot.com"
}
  6. מעדכנים את נקודת הכניסה ל-API בקובץ web.xml של הפרויקט:
    • שינוי השם של כל המופעים של SystemServiceServlet לEndpointsServlet
    • מחליפים את כל המופעים של הנתיב /_ah/spi/ בנתיב החדש הנדרש /_ah/api/

    בהמשך מוצג התוכן של web.xml לפני ואחרי ההעברה:

    לפני ההעברה

    ‫Endpoints Frameworks גרסה 1.0 web.xml: 
    <servlet>
    <servlet-name>SystemServiceServlet</servlet-name>
    <servlet-class>com.google.api.server.spi.SystemServiceServlet</servlet-class>
    <init-param>
        <param-name>services</param-name>
        <param-value>com.example.helloendpoints.Greetings</param-value>
    </init-param>
    <init-param>
        <param-name>restricted</param-name>
        <param-value>false</param-value>
    </init-param>
</servlet>
<servlet-mapping>
    <servlet-name>SystemServiceServlet</servlet-name>
    <url-pattern>/_ah/spi/*</url-pattern>
</servlet-mapping>

    אחרי המיגרציה

    ‫Endpoints Frameworks גרסה 2.0 web.xml: 
    <servlet>
    <servlet-name>EndpointsServlet</servlet-name>
    <servlet-class>com.google.api.server.spi.EndpointsServlet</servlet-class>
    <init-param>
        <param-name>services</param-name>
        <param-value>com.example.helloendpoints.Greetings</param-value>
    </init-param>
    <init-param>
        <param-name>restricted</param-name>
        <param-value>false</param-value>
    </init-param>
</servlet>
<servlet-mapping>
    <servlet-name>EndpointsServlet</servlet-name>
    <url-pattern>/_ah/api/*</url-pattern>
</servlet-mapping>

  7. אחרי שינוי התלויות, מנקים את הפרויקט באמצעות: 
    gradle clean
  8. אפשר ליצור מסמך Discovery באמצעות: 
    gradle endpointsDiscoveryDocs
     מידע נוסף על משימות הפלאגין של Gradle Endpoints Frameworks
  9. אפשר לפרוס פרויקט באמצעות: 
    gradle appengineDeploy

    מידע נוסף על משימות הפלאגין של Gradle App Engine

שימוש ב-Guice להגדרת Endpoints Frameworks for Java

אם רוצים להשתמש ב-Guice:

  1. מוסיפים את התלות החדשה ב-Guice של Endpoints Frameworks:

    Maven

    <dependency>
    <groupId>com.google.endpoints</groupId>
    <artifactId>endpoints-framework-guice</artifactId>
    <version>2.2.1</version>
</dependency>

    Gradle

    compile 'com.google.endpoints:endpoints-framework-guice:2.0.9'
  2. מצהירים על מודול חדש שמרחיב את EndpointsModule ומגדירים אותו באופן הבא: 
    public class EchoEndpointModule extends EndpointsModule {
  @Override
  public void configureServlets() {
    super.configureServlets();

    bind(ServiceManagementConfigFilter.class).in(Singleton.class);
    filter("/_ah/api/*").through(ServiceManagementConfigFilter.class);

    Map<String, String> apiController = new HashMap<String, String>();
    apiController.put("endpoints.projectId", "YOUR-PROJECT-ID");
    apiController.put("endpoints.serviceName", "YOUR-PROJECT-ID.appspot.com");

    bind(GoogleAppEngineControlFilter.class).in(Singleton.class);
    filter("/_ah/api/*").through(GoogleAppEngineControlFilter.class, apiController);

    bind(Echo.class).toInstance(new Echo());
    configureEndpoints("/_ah/api/*", ImmutableList.of(Echo.class));
  }
}

אימות פריסה חדשה

כדי לוודא שהמסגרת החדשה מציגה תנועה:

  1. שליחת בקשות לפריסה החדשה.

  2. במסוף Google Cloud , נכנסים לדף Logging > Logs Explorer.

    כניסה לדף Logs Explorer

  3. אם הבקשות מוצגות עם נתיבים שמתחילים ב-/_ah/api, סימן שהגרסה 2.0 של Endpoints Frameworks משרתת עכשיו את ה-API שלכם. בלוגים לא אמורות להופיע בקשות עם נתיבים שמתחילים ב-/_ah/spi. הבקשות האלה מצביעות על כך שהפרוקסי של גרסה 1.0 של Endpoints Frameworks עדיין משרת בקשות.

הוספת ניהול של Endpoints API

גרסה 2.0 של Endpoints Frameworks מאפשרת גם להפעיל תכונות של ניהול API, כולל:

  • ניהול מפתחות API
  • שיתוף API
  • אימות משתמשים
  • מדדי API
  • יומני API

כדי להתחיל להשתמש בתכונות האלה, אפשר לעיין במאמר בנושא הוספת ניהול API.

פתרון בעיות

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

ה-API מחזיר שגיאות 404, אבל ב-API Explorer עדיין מופיעים ממשקי ה-API בצורה תקינה

כשמבצעים מיגרציה מ-Endpoints Frameworks גרסה 1.0 לגרסה 2.0, צריך להסיר את ההגדרה של גרסה 1.0. אם ההגדרה הישנה עדיין קיימת בהגדרות האפליקציה, שירות ה-Endpoints ימשיך להתייחס לאפליקציה כאפליקציה בגרסה 1.0. יכול להיות שתראו ביומנים של App Engine בקשות שנשלחות אל /_ah/spi, שמובילות לשגיאות HTTP 404 שנשלחות ללקוח.

  1. מסירים את השורות הבאות מקובץ web.xml, אם הן מופיעות בו:

    <servlet>
    <servlet-name>SystemServiceServlet</servlet-name>
    <servlet-class>com.google.api.server.spi.SystemServiceServlet</servlet-class>
    <init-param>
        <param-name>services</param-name>
        <param-value>...</param-value>
    </init-param>
</servlet>
<servlet-mapping>
    <servlet-name>SystemServiceServlet</servlet-name>
    <url-pattern>/_ah/spi/*</url-pattern>
</servlet-mapping>

  2. חשוב לוודא שהקובץ web.xml מכיל את הפרטים הבאים:

    <servlet-mapping>
    <servlet-name>EndpointsServlet</servlet-name>
    <url-pattern>/_ah/api/*</url-pattern>
</servlet-mapping>

ה-API מחזיר שגיאות שקשורות להשתקפות

אתם צריכים לארוז באפליקציה רק את ארטיפקט endpoints-framework, ולא את קובץ ה-JAR הישן appengine-endpoints. אם פורסים אפליקציה עם קובצי JAR משני הסוגים, יכול להיות שתיתקלו בשגיאות רפלקציה או בשגיאות של סוג בזמן ריצה, כמו NoClassDefFoundError,‏ NoSuchMethodError ו-ClassCastException. מסירים את השורות הבאות מקובץ ה-build, אם הן מופיעות בו:

Maven

<dependency>
      <groupId>com.google.appengine</groupId>
      <artifactId>appengine-endpoints</artifactId>
      <version>1.9.53</version>
</dependency>

Gradle

compile group: 'com.google.appengine', name: 'appengine-endpoints', version: '+'

בנוסף, אם אחד מהתלויות האחרות שלכם תלוי בגרסאות ישנות יותר של Guava, יכול להיות שזה יתבטא גם כשיטה חסרה של TypeToken. צריך לוודא שמשתמשים ב-Guava גרסה 19 או בפריט endpoints-framework-all, שמסתיר את התלות.

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

אם מופיעה שגיאה כמו method does not override or implement a method from a supertype או cannot find symbol method setBatchPath(String), סביר להניח שאפליקציית הלקוח שלכם תלויה בגרסה ישנה של ספריית הלקוח של Google Java. צריך לוודא שפריט ה-google-api-client הוא מגרסה 1.23.0 ומעלה.

Maven

<dependency>
    <groupId>com.google.api-client</groupId>
    <artifactId>google-api-client</artifactId>
    <version>1.23.0</version>
</dependency>

Gradle

compile group: 'com.google.api-client', name: 'google-api-client', version: '1.23.0'

בעיות בשיפור של JPA/JDO Datanucleus

Maven

התוסף החדש של App Engine Maven שמבוסס על Google Cloud CLI לא תומך בשיפור Datanucleus מכל סוג שהוא. אם הפרויקט שלכם משתמש בתמיכה בשיפור של Datanucleus JDO או JPA מהפלאגין הישן, אתם צריכים להגדיר בנפרד את פלאגין Datanucleus Maven של צד שלישי כשאתם מבצעים העברה. מידע נוסף מפורט במאמרים הבאים:

Gradle

אם הפרויקט שלכם משתמש בשיפור של gradle-appengine-plugin JPA/JDO Datanucleus, תצטרכו להגדיר ידנית את השיפור של Datanucleus אחרי שתעברו לתוסף החדש של Gradle שמבוסס על gcloud CLI. דוגמה מ-Stackoverflow