Zu Cloud Endpoints Frameworks 2.0 für App Engine migrieren

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

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 Version 2.0 hat keine Auswirkungen auf die Schnittstellen zu Ihrer API. Bereits bestehende Clients können nach der Migration ohne clientseitige Änderungen des Codes weiter verwendet werden.

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 Version 1.0 zu Endpoints Frameworks Version 2.0 unter Verwendung eines Discovery-Dokuments:

  • Laden Sie das Cloud SDK herunter und initialisieren Sie es.
  • Führen Sie die folgenden Befehle aus:
    1. Das Cloud SDK muss berechtigt sein, auf Ihre Daten und Dienste auf Google Cloud zuzugreifen:
      gcloud auth login
    2. Verwenden Sie die Standardanmeldedaten für Anwendungen:
      gcloud auth application-default login
    3. Installieren Sie die Cloud SDK-Komponente app-engine-java:
      gcloud components install app-engine-java
    4. Aktualisieren Sie das 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 alte Abhängigkeit, also das Artefakt appengine-endpoints:
      <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>
    5. Aktualisieren Sie den API-Einstiegspunkt in der Projektdatei web.xml:
      • 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 Beispiel wird der Inhalt der Datei web.xml vor und nach der Migration gezeigt:

      Vor der Migration

      Endpoints Frameworks Version 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 Version 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-Zielen für App Engine.

    Gradle

    1. Entfernen Sie die alte Abhängigkeit, also das Artefakt appengine-endpoints:
      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. Legen Sie den Hostnamen-Endpunkt für generierte Discovery-Dokumente fest:
      endpointsServer {
        // Endpoints Framework Plugin server-side configuration
        hostname = "YOUR-PROJECT-ID.appspot.com"
      }
    6. Aktualisieren Sie den API-Einstiegspunkt in Ihrer Projektdatei web.xml:
      • 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 Beispiel wird der Inhalt der Datei web.xml vor und nach der Migration gezeigt:

      Vor der Migration

      Endpoints Frameworks Version 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 Version 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 können Sie den folgenden Befehl verwenden:
      gradle endpointsDiscoveryDocs
      Weitere Informationen zu den Plug-in-Aufgaben für Gradle Endpoints Frameworks
    9. Sie können ein Projekt mit dem folgenden Befehl bereitstellen:
      gradle appengineDeploy

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

    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. Geben Sie ein neues Modul zur Erweiterung von EndpointsModule an 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 Cloud Console die Seite Stackdriver Logging > Logs (Logbetrachter) auf:

      Zur Seite "Loganzeige"

    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 Cloud SDK-basierten App Engine-Maven-Plug-in 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:

    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 Cloud SDK-basierten Gradle-Plug-in manuell konfigurieren. Siehe ein Beispiel aus StackOverflow.