Zu Cloud Endpoints Frameworks 2.0 für App Engine migrieren

Auf dieser Seite wird beschrieben, wie Sie eine mit Cloud Endpoints 1.0 erstellte Anwendung zu Endpoints Frameworks für App Engine in Java migrieren.

Hinweis: Diese Seite bezieht sich auf Endpoints 1.0 als Endpoints Frameworks Version 1.0 und das neue Endpoints Frameworks für App Engine als Endpoints Frameworks Version 2.0.

Vorteile

Das neue Framework bietet diverse Vorteile, unter anderem:

• Geringere Anfragelatenz
• Bessere Integration von App Engine-Funktionen wie benutzerdefinierten Domains
• Offizieller Support für Guice-Konfigurationen
• Optionale neue Funktionen für die API-Verwaltung

Endpoints Frameworks 2.0 hat keine Auswirkungen auf die Schnittstellen zu Ihrer API. Bestehende Clients arbeiten nach der Migration ohne clientseitige Codeänderungen weiter.

Derzeit ausgeschlossene Funktionen und Tools

Die folgenden Funktionen sind derzeit nicht verfügbar. Wenn Sie eine dieser Funktionen benötigen, senden Sie eine Funktionsanfrage.

• JSON-RPC-Protokoll, das für Legacy-iOS-Clients erforderlich ist. Zum Erstellen von iOS-Clients für Ihre Endpoints Frameworks 2.0 API wird empfohlen, die Google API-Clientbibliothek für Objective-C für REST APIs zu verwenden.
• Automatische ETags
• Automatische Artenfelder
• IDE-Integration
• Teilantworten für fields
• Automatische Erstellung von PATCH-API-Methoden

Android Studio für Endpoints Frameworks 1.0 wird derzeit außerdem nicht in Version 2.0 unterstützt:

Migration zu Endpoints Frameworks Version 2.0

Endpoints Frameworks Version 2.0 wurde in die Maven-Artefakte in der Gruppe com.google.endpoints verschoben. Die benötigte JAR befindet sich im Artefakt endpoints-framework. Wenn Sie die Guice-Konfiguration verwenden möchten, fügen Sie das Artefakt endpoints-framework-guice hinzu.

Die folgende Anleitung beschreibt eine Beispielmigration von Endpoints Frameworks 1.0 zu Endpoints Frameworks 2.0 mit einem Discovery-Dokument:

Hinweis: Wenn Sie Endpoints Frameworks Version 1.0 mit Eclipse verwenden, sollten Sie zuerst Ihr Projekt in ein Maven-Projekt konvertieren und dann die unten angegebene Anleitung für Maven befolgen.

1. Laden Sie die Google Cloud CLI herunter und initialisieren Sie sie.
2. Führen Sie die folgenden Befehle aus:
   1. Prüfen Sie, ob die gcloud CLI für den Zugriff auf Ihre Daten und Dienste in Google Cloud berechtigt ist:

      gcloud auth login

   2. Verwenden Sie die Standardanmeldedaten für Anwendungen:

      gcloud auth application-default login

   3. Installieren Sie die Google Cloud SDK-Komponente app-engine-java:

      gcloud components install app-engine-java

   4. Aktualisieren Sie das Google Cloud SDK und alle Komponenten auf die neueste Version:

      gcloud components update

Migration mithilfe von Maven oder Gradle durchführen:

Maven

1. Entfernen Sie die Legacy-Abhängigkeit, bei dem es sich um das Artefakt appengine-endpoints handelt:

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

2. Fügen Sie die neue Endpoints Frameworks-Abhängigkeit hinzu:

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

3. Fügen Sie das neue Endpoints Frameworks-Plug-in hinzu und definieren Sie den Hostnamen für ein generiertes Discovery-Dokument:

   <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. Fügen Sie das neue Maven-Plug-in für App Engine hinzu:

   <plugin>
       <groupId>com.google.cloud.tools</groupId>
       <artifactId>appengine-maven-plugin</artifactId>
       <version>1.3.2</version>
       <configuration>
           <!-- deploy configuration -->
       </configuration>
   </plugin>

   Hinweis: Das alte App Engine-Maven-Plug-in mit der Gruppe com.google.appengine ist nicht mit dem Endpoints Frameworks-Plug-in kompatibel. Sie müssen die neue Version verwenden.
5. Aktualisieren Sie den API-Einstiegspunkt in der web.xml-Projektdatei:
   • Benennen Sie alle Vorkommen von SystemServiceServlet in EndpointsServlet um
   • Ersetzen Sie alle Vorkommen des Pfads /_ah/spi/ durch den neuen erforderlichen Pfad /_ah/api/
     

   Im Folgenden wird der Inhalt von web.xml vor und nach der Migration gezeigt:

   Vor der Migration

   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>

   Nach der Migration

   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. Nachdem Sie die Abhängigkeiten geändert haben, bereinigen Sie das Projekt:

   mvn clean

7. Sie können ein Discovery-Dokument generieren:

   mvn endpoints-framework:discoveryDocs

   Weitere Informationen zu Maven-Plug-in-Zielvorhaben für Endpoints Frameworks
8. Sie können ein Projekt bereitstellen:

   mvn appengine:deploy

   Weitere Informationen zu Maven-Plug-in-Zielvorhaben für App Engine

   Hinweis: Bei der Migration muss die Bereitstellung in einer neuen App Engine-Version erfolgen. Das geschieht automatisch, wenn Sie keine Version angeben. Siehe Bekannte Probleme.

Gradle

1. Entfernen Sie die Legacy-Abhängigkeit, bei dem es sich um das Artefakt appengine-endpoints handelt:

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

2. Fügen Sie die neue Endpoints Frameworks-Abhängigkeit hinzu:

   compile group: 'com.google.endpoints', name: 'endpoints-framework', version: '2.0.8'

3. Fügen Sie die neuen App Engine- und Endpoints Frameworks-Plug-ins hinzu:

   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. Wenden Sie die neuen App Engine- und Endpoints Frameworks-Plug-ins an:

   apply plugin: 'com.google.cloud.tools.appengine'
   apply plugin: 'com.google.cloud.tools.endpoints-framework-server'

5. Definieren Sie den Hostnamenendpunkt für generierte Discovery-Dokumente:

   endpointsServer {
     // Endpoints Framework Plugin server-side configuration
     hostname = "YOUR-PROJECT-ID.appspot.com"
   }

6. Aktualisieren Sie den API-Einstiegspunkt in der web.xml-Projektdatei:
   • Benennen Sie alle Vorkommen von SystemServiceServlet in EndpointsServlet um
   • Ersetzen Sie alle Vorkommen des Pfads /_ah/spi/ durch den neuen erforderlichen Pfad /_ah/api/
     

   Im Folgenden wird der Inhalt von web.xml vor und nach der Migration gezeigt:

   Vor der Migration

   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>

   Nach der Migration

   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. Nachdem Sie die Abhängigkeiten geändert haben, bereinigen Sie das Projekt mit folgendem Befehl:

   gradle clean

8. Zum Generieren eines Discovery-Dokuments verwenden Sie folgenden Befehl:

   gradle endpointsDiscoveryDocs

   Weitere Informationen zu den Plug-in-Aufgaben für Gradle Endpoints Frameworks
9. Sie können ein Projekt mit folgendem Befehl bereitstellen:

   gradle appengineDeploy

   Weitere Informationen zu den Plug-in-Aufgaben für Gradle App Engine

   Hinweis: Bei der Migration muss die Bereitstellung in einer neuen App Engine-Version erfolgen. Das geschieht automatisch, wenn Sie keine Version angeben. Siehe Bekannte Probleme.

Guice für die Konfiguration von Endpoints Frameworks für Java verwenden

Wenn Sie Guice verwenden möchten:

1. Fügen Sie die neue Endpoints Frameworks Guice-Abhängigkeit hinzu:

   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. Deklarieren Sie ein neues Modul, das EndpointsModule erweitert, und konfigurieren Sie es so:

   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));
     }
   }

Neue Bereitstellung verifizieren

Sie können überprüfen, ob das neue Framework Traffic bereitstellt:

1. Senden Sie einige Anfragen an die neue Bereitstellung.

2. Rufen Sie in der Google Cloud Console die Seite Logging > Log-Explorer auf.

   Zur Seite „Log-Explorer“

3. Wenn Anfragen mit Pfaden angezeigt werden, die mit /_ah/api beginnen, stellt Endpoints Frameworks Version 2.0 jetzt Traffic an Ihre API bereit. Die Logs sollten keine Anfragen mit Pfaden enthalten, die mit /_ah/spi beginnen. Diese Anfragen weisen darauf hin, dass der Endpoints Version 1.0-Proxy weiterhin Anfragen bedient.

Endpoints-API-Verwaltung hinzufügen

Mit Endpoints Frameworks 2.0 können Sie auch Funktionen für die API-Verwaltung aktivieren:

• Verwalten von API-Schlüsseln
• Teilen von APIs
• Nutzerauthentifizierung
• API-Messwerte
• API-Logs

Weitere Informationen zu diesen Funktionen finden Sie unter API-Verwaltung hinzufügen.

Fehlerbehebung

In diesem Abschnitt werden häufige Fehler beschrieben, die bei der Migration zu Endpoints Frameworks Version 2.0 auftreten können, und entsprechende Lösungen vorgeschlagen.

API gibt 404-Fehler zurück, API Explorer listet APIs jedoch weiterhin korrekt auf

Bei der Migration zu Endpoints Frameworks Version 2.0 müssen Sie die alte Konfiguration von Endpoints Frameworks Version 1.0 entfernen. Wenn die alte Konfiguration noch in der Anwendungskonfiguration vorhanden ist, behandelt der Endpoints-Dienst die Anwendung weiterhin als Anwendung der Version 1.0. Unter Umständen sehen Sie in den App Engine-Logs Anfragen, die an /_ah/spi gesendet werden. Dies hat zur Folge, dass HTTP 404-Fehler an den Client gesendet werden.

1. Entfernen Sie die folgenden Zeilen aus der Datei web.xml, falls sie vorhanden sind:

   <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. Überprüfen Sie, dass die Datei web.xml Folgendes enthält:

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

API löst Reflexionsfehler aus

Nehmen Sie nur das Artefakt endpoints-framework in das Anwendungspaket auf. Lassen Sie das alte JAR appengine-endpoints weg. Wenn Sie eine Anwendung mit beiden JARs bereitstellen, können Reflexions- oder Laufzeitfehler vom Typ NoClassDefFoundError, NoSuchMethodError und ClassCastException auftreten. Entfernen Sie folgende Zeilen aus Ihrer Build-Datei, sofern diese vorhanden sind:

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: '+'

Darüber hinaus können andere Abhängigkeiten, die ältere Guava-Versionen voraussetzen, als fehlende Methode TypeToken erkannt werden. Verwenden Sie unbedingt Guava Version 19 oder das Artefakt endpoints-framework-all, das Abhängigkeiten per Shadowing einbindet.

Quellen der Clientbibliothek werden nicht kompiliert

Wenn Sie einen Fehler wie method does not override or implement a method from a supertype oder cannot find symbol method setBatchPath(String) erhalten, setzt Ihre Clientanwendung wahrscheinlich eine ältere Version der Google Java-Clientbibliothek voraus. Sorgen Sie unbedingt dafür, dass das Artefakt google-api-client mindestens die Version 1.23.0 hat.

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'

Probleme mit JPA-/JDO-DataNucleus-Erweiterung

Maven

DataNucleus-Erweiterungen werden im neuen Maven-Plug-in für App Engine, das auf der Google Cloud CLI basiert, nicht unterstützt. Wenn Ihr Projekt die Unterstützung für die DataNucleus JDO- oder JPA-Erweiterungen aus dem alten Plug-in verwendet, müssen Sie das Drittanbieter-DataNucleus-Plug-in für Maven bei der Migration separat konfigurieren. Weitere Informationen finden Sie hier:

• Anleitung für JDO
• Anleitung für JPA

Gradle

Wenn in Ihrem Projekt die JPA/JDO-DataNucleus-Erweiterung gradle-appengine-plugin verwendet wird, müssen Sie die DataNucleus-Erweiterung nach dem Wechsel zum neuen gcloud CLI-basierten Gradle-Plug-in manuell konfigurieren. Siehe ein Beispiel aus StackOverflow.