Auf dieser Seite wird die Migration einer vorhandenen Cloud Endpoints-Version 1.0 beschrieben. Anwendung für Endpoints Frameworks für App Engine in Java.
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 1.0 zu Endpoints Frameworks 2.0 mit einem Discovery-Dokument:
- Laden Sie die Google Cloud CLI herunter und initialisieren Sie sie.
- Führen Sie die folgenden Befehle aus:
- Prüfen Sie, ob die gcloud CLI für den Zugriff auf Ihre Daten und Dienste in Google Cloud berechtigt ist:
gcloud auth login
- Verwenden Sie die Standardanmeldedaten für Anwendungen:
gcloud auth application-default login
- Installieren Sie die Google Cloud SDK-Komponente
app-engine-java
:gcloud components install app-engine-java
- Aktualisieren Sie das Google Cloud SDK und alle Komponenten auf die neueste Version:
gcloud components update
- Prüfen Sie, ob die gcloud CLI für den Zugriff auf Ihre Daten und Dienste in Google Cloud berechtigt ist:
Migration mithilfe von Maven oder Gradle durchführen:
Maven
- Entfernen Sie die alte Abhängigkeit, also das Artefakt
appengine-endpoints
: - Fügen Sie die neue Endpoints Frameworks-Abhängigkeit hinzu:
- Fügen Sie das neue Endpoints Frameworks-Plug-in hinzu und definieren Sie die Hostname für Ein generiertes Discovery-Dokument:
- Fügen Sie das neue Maven-Plug-in für App Engine hinzu:
- API-Einstiegspunkt in Ihrem Projekt
web.xml
aktualisieren Datei:- Benennen Sie alle Vorkommen von
SystemServiceServlet
inEndpointsServlet
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.0web.xml
:Nach der Migration
Endpoints Frameworks Version 2.0web.xml
: - Benennen Sie alle Vorkommen von
- Nachdem Sie die Abhängigkeiten geändert haben, bereinigen Sie das Projekt:
mvn clean
- Sie können ein Discovery-Dokument generieren:
Weitere Informationen zu Maven Endpoints Frameworks Plug-in-Zielvorhaben.mvn endpoints-framework:discoveryDocs
- Sie können ein Projekt bereitstellen:
mvn appengine:deploy
Weitere Informationen zu Maven-Plug-in-Zielvorhaben für App Engine
Gradle
- Entfernen Sie die alte Abhängigkeit, also das Artefakt
appengine-endpoints
:compile group: 'com.google.appengine', name: 'appengine-endpoints', version: '+'
- Fügen Sie die neue Endpoints Frameworks-Abhängigkeit hinzu:
- Fügen Sie die neuen App Engine- und Endpoints Frameworks-Plug-ins hinzu:
- Wenden Sie die neuen App Engine- und Endpoints Frameworks-Plug-ins an:
- Definieren Sie den Hostnamen-Endpunkt für generierte Discovery-Dokumente:
- Aktualisieren Sie den API-Einstiegspunkt in Ihrer Projektdatei
web.xml
:- Benennen Sie alle Vorkommen von
SystemServiceServlet
inEndpointsServlet
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.0web.xml
:Nach der Migration
Endpoints Frameworks Version 2.0web.xml
: - Benennen Sie alle Vorkommen von
- Nachdem Sie die Abhängigkeiten geändert haben, bereinigen Sie das Projekt mit folgendem Befehl:
gradle clean
- Zum Generieren eines Discovery-Dokuments können Sie den folgenden Befehl verwenden:
Weitere Informationen zu Gradle Endpoints Frameworks Plug-in-Aufgabengradle endpointsDiscoveryDocs
- Sie können ein Projekt mit dem folgenden Befehl bereitstellen:
gradle appengineDeploy
Weitere Informationen zu den Plug-in-Aufgaben für Gradle App Engine
Guice für die Konfiguration von Endpoints Frameworks für Java verwenden
Wenn Sie Guice verwenden möchten:
- Fügen Sie die neue Endpoints Frameworks Guice-Abhängigkeit hinzu:
Maven
Gradle
- Geben Sie ein neues Modul zur Erweiterung von
EndpointsModule
an und konfigurieren Sie es so:
Neue Bereitstellung verifizieren
Sie können überprüfen, ob das neue Framework Traffic bereitstellt:
- Senden Sie einige Anfragen an die neue Bereitstellung.
Rufen Sie in der Google Cloud Console die Seite Logging > Log-Explorer auf.
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.
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>
Ü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
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
Das neue Google Cloud CLI-basierte Maven-Plug-in für App Engine unterstützen DataNucleus-Erweiterungen jeglicher Art. 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 Ihr Projekt das gradle-appengine-plugin
JPA/JDO verwendet
DataNucleus-Erweiterung, Sie müssen DataNucleus manuell konfigurieren
Verbesserungen nach dem Wechsel zum neuen gcloud CLI-basierten Gradle-Plug-in
.
Siehe ein Beispiel aus StackOverflow.