Erste Schritte mit Cloud Endpoints Frameworks für Java

---

Auf dieser Seite wird beschrieben, wie Sie Anfragen an eine Beispiel-API mithilfe von Cloud Endpoints Frameworks für Java konfigurieren, erstellen und senden. Endpoints Frameworks für Java ist in die App Engine-Standardlaufzeitumgebung für Java 8 eingebunden. Endpoints Frameworks besteht aus Tools, Bibliotheken und Funktionen, mit denen Sie APIs und Clientbibliotheken aus einer App Engine-Anwendung generieren können.

Lernziele

Orientieren Sie sich beim Durcharbeiten der Anleitung an der folgenden Aufgabenliste. Alle Aufgaben sind erforderlich, um Anfragen sicher an die API senden zu können.

1. Richten Sie ein Google Cloud-Projekt ein. Siehe Vorbereitung.
2. Erforderliche Software installieren und eine App Engine-Anwendung erstellen. Siehe Erforderliche Software installieren und konfigurieren.
3. Beispielcode herunterladen. Siehe Beispielcode abrufen.
4. OpenAPI-Konfigurationsdatei generieren. Siehe Cloud Endpoints konfigurieren.
5. Endpoints-Konfiguration bereitstellen, um einen Endpoints-Dienst zu erstellen. Siehe Endpoints-Konfiguration bereitstellen.
6. Das Beispiel auf Ihrem Computer ausführen. Siehe Beispiel lokal ausführen.
7. Ein Backend für die API erstellen und die API bereitstellen. Siehe API-Backend bereitstellen.
8. Senden Sie eine Anfrage an die API. Siehe Anfrage an die API senden.
9. API-Aktivitäten verfolgen. Siehe API-Aktivitäten verfolgen.
10. Vermeiden Sie Gebühren, die Ihrem Google Cloud-Konto in Rechnung gestellt werden. Siehe Bereinigen.

Kosten

In diesem Dokument verwenden Sie die folgenden kostenpflichtigen Komponenten von Google Cloud:

• Endpoints
• App Engine

Mit dem Preisrechner können Sie eine Kostenschätzung für Ihre voraussichtliche Nutzung vornehmen. Neuen Google Cloud-Nutzern steht möglicherweise eine kostenlose Testversion zur Verfügung.

Nach Abschluss der in diesem Dokument beschriebenen Aufgaben können Sie weitere Kosten vermeiden, indem Sie die erstellten Ressourcen löschen. Weitere Informationen finden Sie unter Bereinigen.

Hinweise

1. Melden Sie sich bei Ihrem Google Cloud-Konto an. Wenn Sie mit Google Cloud noch nicht vertraut sind, erstellen Sie ein Konto, um die Leistungsfähigkeit unserer Produkte in der Praxis sehen und bewerten zu können. Neukunden erhalten außerdem ein Guthaben von 300 $, um Arbeitslasten auszuführen, zu testen und bereitzustellen.

2. Wählen Sie in der Google Cloud Console auf der Seite der Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.

   Hinweis: Wenn Sie die Ressourcen, die Sie in diesem Verfahren erstellen, nicht behalten möchten, erstellen Sie ein Projekt, anstatt ein vorhandenes Projekt auszuwählen. Wenn Sie fertig sind, können Sie das Projekt löschen und dadurch alle mit dem Projekt verknüpften Ressourcen entfernen.

   Zur Projektauswahl

3. Die Abrechnung für das Google Cloud-Projekt muss aktiviert sein.

4. Wählen Sie in der Google Cloud Console auf der Seite der Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.

   Hinweis: Wenn Sie die Ressourcen, die Sie in diesem Verfahren erstellen, nicht behalten möchten, erstellen Sie ein Projekt, anstatt ein vorhandenes Projekt auszuwählen. Wenn Sie fertig sind, können Sie das Projekt löschen und dadurch alle mit dem Projekt verknüpften Ressourcen entfernen.

   Zur Projektauswahl

5. Die Abrechnung für das Google Cloud-Projekt muss aktiviert sein.

6. Notieren Sie sich die Projekt-ID, da sie später benötigt wird.

Erforderliche Software installieren und konfigurieren

1. Wenn Sie Java 8 nicht installiert haben, laden Sie das Java Development Kit (JDK) von der Oracle-Website herunter und installieren Sie es. Da Endpoints Frameworks für Java auf die App Engine-Standardlaufzeitumgebung für Java 8 angewiesen ist, unterstützt Endpoints Frameworks keine anderen Java-Versionen.
2. Wenn Maven 3.3.9 oder höher nicht auf Ihrem System installiert ist, können Sie das Tool hier herunterladen und installieren.

Hinweis für Windows-Nutzer: Das JDK und Maven sollten unter Windows in einem Verzeichnis installiert werden, dessen Pfad keine Leerzeichen enthält. Weitere Informationen finden Sie unter Maven unter Windows.

3. Sie benötigen eine Anwendung, um Anfragen an die Beispiel-API zu senden.

   • Nutzer von Linux und macOS: Diese Anleitung enthält ein Beispiel, bei dem curl verwendet wird. Das Tool ist normalerweise auf Ihrem Betriebssystem vorinstalliert. Wenn curl nicht installiert ist, können Sie es von der Seite Releases und Downloads für curl herunterladen.
   • Nutzer von Windows: Diese Anleitung enthält ein Beispiel, bei dem Invoke-WebRequest verwendet wird. Der Befehl wird in PowerShell ab Version 3.0 unterstützt.
4. Laden Sie die Google Cloud CLI herunter und initialisieren Sie sie.
5. 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

6. Erstellen Sie eine App Engine-Anwendung:
   1. Legen Sie für das Standardprojekt Ihre Projekt-ID fest:

      gcloud config set project YOUR_PROJECT_ID

      Ersetzen Sie YOUR_PROJECT_ID durch Ihre Google Cloud-Projekt-ID. Wenn Sie weitere Google Cloud-Projekte mit gcloud verwalten möchten, lesen Sie gcloud CLI-Konfigurationen verwalten.

   2. Wählen Sie die Region aus, in der Sie Ihre App Engine-Anwendung erstellen möchten. Führen Sie den folgenden Befehl aus, damit eine Liste der Regionen angezeigt wird:

      gcloud app regions list

   3. Erstellen Sie mit dem folgenden Befehl eine App Engine-Anwendung. Ersetzen Sie YOUR_PROJECT_ID durch Ihre Google Cloud-Projekt-ID und YOUR_REGION durch die Region, in der die App Engine-Anwendung erstellt werden soll.

      gcloud app create \
      --project=YOUR_PROJECT_ID \
      --region=YOUR_REGION
      

Beispielcode abrufen

So klonen Sie die Beispiel-API aus GitHub:

1. Klonen Sie das Beispiel-Repository auf Ihrem lokalen Computer:

   git clone https://github.com/GoogleCloudPlatform/java-docs-samples
   

2. Ändern Sie das Verzeichnis, das den Beispielcode enthält:

   cd java-docs-samples/appengine-java8/endpoints-v2-backend
   

Endpoints konfigurieren

Der Beispielcode enthält das Endpoints Frameworks-Tool, das eine OpenAPI-Konfigurationsdatei generiert, in der die REST API des Beispielcodes beschrieben wird. Führen Sie die Schritte in diesem Abschnitt aus, um das Maven-Beispielprojekt zu konfigurieren und zu erstellen. Anschließend können Sie die OpenAPI-Konfigurationsdatei generieren.

Projekt-ID zum API-Beispielcode hinzufügen

Sie müssen die Projekt-ID, die Sie beim Erstellen Ihres Projekts erhalten haben, zur Beispieldatei pom.xml hinzufügen, bevor Sie den Code bereitstellen können.

So fügen Sie die Projekt-ID hinzu:

1. Bearbeiten Sie die Datei java-docs-samples/appengine-java8/endpoints-v2-backend/pom.xml.

2. Suchen Sie nach <endpoints.project.id> und ersetzen Sie YOUR_PROJECT_ID durch Ihre Google Cloud-Projekt-ID.

   Beispiel:

   <endpoints.project.id>example-project</endpoints.project.id>
   

3. Speichern Sie die Änderungen.

Beispielprojekt erstellen

So erstellen Sie das Projekt:

1. Prüfen Sie, ob Sie sich im Verzeichnis java-docs-samples/appengine-java8/endpoints-v2-backend befinden.

2. Führen Sie den folgenden Befehl aus:

   mvn clean package
   

3. Warten Sie, bis das Projekt erstellt ist. Wenn das Projekt erstellt wurde, wird eine Meldung angezeigt, die ungefähr so aussieht:

   [INFO] BUILD SUCCESS
   [INFO] ------------------------------------------------------------------------
   [INFO] Total time: 14.846s
   [INFO] Finished at: Wed April 13 09:43:09 PDT 2016
   [INFO] Final Memory: 24M/331M
   

OpenAPI-Konfigurationsdatei generieren

Verwenden Sie danach ein Tool aus der Endpoints Frameworks-Bibliothek, um das OpenAPI-Dokument openapi.json zu generieren. In dieser Datei wird die REST API des Beispielcodes beschrieben.

So generieren Sie die OpenAPI-Konfigurationsdatei:

1. Rufen Sie mit folgendem Befehl das Tool Endpoints Frameworks auf:

   mvn endpoints-framework:openApiDocs
   

2. Warten Sie, bis die Konfigurationsspezifikation erstellt wurde. Nach Abschluss des Vorgangs wird eine Meldung angezeigt, die etwa so aussieht:

   OpenAPI document written to target/openapi-docs/openapi.json
   

   Ignorieren Sie Meldungen über ein fehlgeschlagenes Laden einer statischen Logger-Klasse.

Endpoints-Konfiguration bereitstellen

Für die Bereitstellung der Endpoints-Konfiguration verwenden Sie Service Infrastructure. Dies ist die grundlegende Dienstplattform von Google, die von Endpoints Frameworks und anderen Diensten zum Erstellen und Verwalten von APIs und Diensten genutzt wird.

So stellen Sie die Konfigurationsdatei bereit:

1. Prüfen Sie, ob Sie sich im Verzeichnis java-docs-samples/appengine-java8/endpoints-v2-backend befinden.

2. Stellen Sie die im vorherigen Abschnitt generierte OpenAPI-Konfigurationsdatei bereit:

   gcloud endpoints services deploy target/openapi-docs/openapi.json
   

Dadurch wird ein neuer Endpoints-Dienst mit dem Namen im Format YOUR_PROJECT_ID.appspot.com erstellt. Dieser Name wird in pom.xml und anderen Konfigurationsdateien konfiguriert, die im Beispiel enthalten sind. Wenn Sie die API in App Engine bereitstellen, wird ein DNS-Eintrag mit dem Namensformat YOUR_PROJECT_ID.appspot.com erstellt. Dies ist der vollständig qualifizierte Domainname (FQDN), den Sie beim Senden von Anfragen an die API verwenden.

Beim Erstellen und Konfigurieren des Dienstes gibt Service Management Informationen an das Terminal aus. Warnhinweise, die besagen, dass für die Pfade in openapi.json kein API-Schlüssel erforderlich ist, können Sie bedenkenlos ignorieren. Bei erfolgreichem Abschluss des Vorgangs wird eine Zeile mit der Dienstkonfigurations-ID und dem Dienstnamen angezeigt, die etwa so aussieht:

Service Configuration [2017-02-13-r2] uploaded for service [example-project-12345.appspot.com]

Im obigen Beispiel ist 2017-02-13-r2 die Dienstkonfigurations-ID und example-project-12345.appspot.com der Dienstname.

Weitere Informationen finden Sie unter gcloud-Endpoints-Dienste bereitstellen.

Erforderliche Dienste prüfen

Für die API-Verwaltung erfordert Endpoints Frameworks folgende Dienste:

Name	Titel
servicemanagement.googleapis.com	Service Management API
servicecontrol.googleapis.com	Service Control API
endpoints.googleapis.com	Google Cloud Endpoints

In der Regel werden die erforderlichen Dienste mit dem Befehl gcloud endpoints services deploy aktiviert. Unter folgenden Umständen kann es vorkommen, dass der Befehl gcloud erfolgreich ausgeführt wird, die erforderlichen Dienste jedoch nicht aktiviert werden:

• Wenn Sie eine Drittanbieteranwendung wie Terraform verwendet haben und Sie diese Dienste nicht hinzufügen.

• Wenn Sie die Endpoints-Konfiguration für ein vorhandenes Google Cloud-Projekt bereitgestellt haben, in dem diese Dienste explizit deaktiviert wurden.

Prüfen Sie mit dem folgenden Befehl, ob die erforderlichen Dienste aktiviert sind:

gcloud services list

Wenn die erforderlichen Dienste nicht aufgeführt sind, müssen Sie sie aktivieren:

gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com
gcloud services enable endpoints.googleapis.com

Aktivieren Sie auch Ihren Endpoints-Dienst:

gcloud services enable ENDPOINTS_SERVICE_NAME

Zum Ermitteln des ENDPOINTS_SERVICE_NAME haben Sie folgende Möglichkeiten:

• Rufen Sie nach der Bereitstellung der Endpoints-Konfiguration die Seite Endpunkte in der Cloud Console auf. Die Liste der möglichen ENDPOINTS_SERVICE_NAME wird in der Spalte Dienstname angezeigt.

• Bei OpenAPI ist ENDPOINTS_SERVICE_NAME der Wert, den Sie im Feld host Ihrer OpenAPI-Spezifikation angegeben haben. Bei gRPC ist der ENDPOINTS_SERVICE_NAME das, was Sie im Feld name Ihrer gRPC-Endpoints-Konfiguration angegeben haben.

Weitere Informationen zu den gcloud-Befehlen finden Sie unter gcloud-Dienste.

Beispiel lokal ausführen

Nachdem Sie die Endpoints-Konfiguration bereitgestellt haben, kann das Beispiel lokal ausgeführt werden.

1. Erstellen Sie eine Umgebungsvariable namens ENDPOINTS_SERVICE_NAME, mit der in der Datei appengine-web.xml des Beispiels der Hostname festgelegt wird. Ersetzen Sie im Folgenden YOUR_PROJECT_ID durch Ihre Google Cloud-Projekt-ID.

   In Linux oder macOS:

   export ENDPOINTS_SERVICE_NAME=YOUR_PROJECT_ID.appspot.com
   

   In Windows PowerShell:

   $Env:ENDPOINTS_SERVICE_NAME="YOUR_PROJECT_ID.appspot.com"
   

2. Rufen Sie neue Nutzeranmeldedaten ab, die Sie als Standardanmeldedaten für Anwendungen verwenden.

   gcloud auth application-default login
   

3. Führen Sie den Entwicklungsserver aus.

   mvn appengine:run
   

   Die lokale Instanz kann unter http://localhost:8080 erreicht werden, wie den Logs zu entnehmen ist, die von dem Befehl mvn appengine:run zurückgegeben wurden:

   [INFO] GCLOUD: INFO: Module instance default is running at http://localhost:8080/
   

4. Senden Sie eine Anfrage an die lokale Instanz:

Linux oder macOS

curl \
    --request POST \
    --header "Content-Type: application/json" \
    --data '{"message":"hello world"}' \
    http://localhost:8080/_ah/api/echo/v1/echo

Im vorherigen curl:

• Durch die Option --data werden die an die API zu übertragenden Daten festgelegt.
• Durch die Option --header wird angegeben, dass die Daten im JSON-Format vorliegen.

PowerShell

(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
    -Headers @{"content-type"="application/json"} `
    -URI "http://localhost:8080/_ah/api/echo/v1/echo").Content

In diesem Beispiel enden die ersten beiden Zeilen mit einem Graviszeichen. Achten Sie beim Einfügen des Beispiels in PowerShell darauf, dass nach dem Graviszeichen kein Leerzeichen folgt. Informationen zu den in der Beispielanfrage verwendeten Optionen finden Sie in der Microsoft-Dokumentation unter Invoke-WebRequest.

Die API gibt die von Ihnen gesendete Meldung zurück und reagiert mit folgender Zeile:

{
 "message": "hello world"
}

API-Back-End bereitstellen

Bisher haben Sie die OpenAPI-Konfiguration für Service Management, aber noch nicht den Code für das API-Back-End bereitgestellt. In diesem Abschnitt wird die Bereitstellung der Beispiel-API für App Engine beschrieben.

So stellen Sie das API-Back-End bereit:

1. Prüfen Sie, ob Sie sich im Verzeichnis java-docs-samples/appengine-java8/endpoints-v2-backend befinden.

2. Stellen Sie den API-Implementierungscode mithilfe von Maven bereit:

    mvn appengine:deploy
   

   Das erste Mal, wenn Sie eine Beispielanwendung hochladen, werden Sie möglicherweise dazu aufgefordert, die Bereitstellung zu autorisieren. Führen Sie dazu die angezeigten Schritte aus. Wenn ein Browserfenster mit einem Code angezeigt wird, kopieren Sie diesen in das Terminalfenster.

3. Warten Sie, bis das Hochladen abgeschlossen ist.

   Warten Sie einige Minuten, bevor Sie Anfragen an Ihre API senden, damit App Engine die Initialisierung abschließen kann.

Anfrage an die API senden

Nachdem Sie die API und deren Konfigurationsdatei bereitgestellt haben, können Sie Anfragen an die API senden.

Linux oder macOS

Senden Sie eine HTTP-Anfrage mithilfe von curl. Ersetzen Sie [YOUR_PROJECT_ID] durch Ihre Google Cloud-Projekt-ID.

curl \
    --request POST \
    --header "Content-Type: application/json" \
    --data '{"message":"hello world"}' \
    https://[YOUR_PROJECT_ID].appspot.com/_ah/api/echo/v1/echo

Im vorherigen curl:

• Durch die Option --data werden die an die API zu übertragenden Daten festgelegt.
• Durch die Option --header wird angegeben, dass die Daten im JSON-Format vorliegen.

PowerShell

Senden Sie eine HTTP-Anfrage mithilfe von Invoke-WebRequest. Ersetzen Sie [YOUR_PROJECT_ID] durch Ihre Google Cloud-Projekt-ID:

(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
    -Headers @{"content-type"="application/json"} -URI `
     "https://[YOUR_PROJECT_ID].appspot.com/_ah/api/echo/v1/echo").Content

In diesem Beispiel enden die ersten beiden Zeilen mit einem Graviszeichen. Achten Sie beim Einfügen des Beispiels in PowerShell darauf, dass nach dem Graviszeichen kein Leerzeichen folgt. Informationen zu den in der Beispielanfrage verwendeten Optionen finden Sie in der Microsoft-Dokumentation unter Invoke-WebRequest.

Drittanbieteranwendung

Sie können eine Drittanbieteranwendung wie die Chrome-Browsererweiterung Postman zum Senden der Anfrage verwenden:

• Wählen Sie POST als HTTP-Verb aus.
• Wählen Sie für den Header den Schlüssel content-type und den Wert application/json aus.
• Geben Sie als Text Folgendes ein:
  {"message":"hello world"}
• Geben Sie die URL zur Beispielanwendung ein. Beispiel:
  https://example-project-12345.appspot.com/_ah/api/echo/v1/echo

Die API gibt die von Ihnen gesendete Meldung zurück und reagiert mit folgender Zeile:

{
 "message": "hello world"
}

Wenn Sie als Antwort einen Fehler erhalten haben, lesen Sie die Informationen unter Fehlerbehebung bei Antwortfehlern.

Sie haben gerade eine API in Endpoints Frameworks bereitgestellt und getestet!

Hinweis: Wenn Sie uns mitteilen möchten, was Ihnen an dieser Anleitung gefallen hat, können Sie uns gerne Feedback geben. Ihr Feedback hilft uns bei der Verbesserung dieser Anleitungen.
Wenn Sie eine Fehlermeldung erhalten, können Sie der Google-Gruppe google-cloud-endpoints beitreten und uns mitteilen, was schiefgegangen ist. Sie erhalten in dieser Gruppe Antworten von anderen Endpoints-Nutzern und Google-Entwicklern, die die Diskussion in der Gruppe verfolgen.

API-Aktivität verfolgen

1. Sehen Sie sich in der Google Cloud Console auf der Seite Endpunkte > Dienste die Aktivitätsgrafiken für Ihre API an.

   Endpoints-Dienste aufrufen

   Es kann einige Momente dauern, bis die Anfrage in den Grafiken angezeigt wird.

2. Sehen Sie sich auf der Seite "Log Explorer" die Anfragelogs an.

   Zur Seite „Log-Explorer“

Entwicklerportal für die API erstellen

Sie können mit dem Cloud Endpoints-Portal ein Entwicklerportal erstellen. Das ist eine Website zur Interaktion mit der Beispiel-API. Weitere Informationen finden Sie unter Übersicht über das Cloud Endpoints-Portal.

Bereinigen

Damit Ihrem Google Cloud-Konto die in dieser Anleitung verwendeten Ressourcen nicht in Rechnung gestellt werden, löschen Sie entweder das Projekt, das die Ressourcen enthält, oder Sie behalten das Projekt und löschen die einzelnen Ressourcen.

Achtung: Das Löschen von Projekten hat folgende Auswirkungen:
• Alle Inhalte des Projekts werden gelöscht. Wenn Sie für die Aufgaben in diesem Dokument ein bereits bestehendes Projekt verwendet haben und dieses löschen, werden auch alle anderen im Rahmen des Projekts erstellten Daten gelöscht.
• Benutzerdefinierte Projekt-IDs gehen verloren. Beim Erstellen dieses Projekts haben Sie möglicherweise eine benutzerdefinierte Projekt-ID erstellt, die Sie weiterhin verwenden möchten. Damit die URLs, die die Projekt-ID nutzen, z. B. eine appspot.com-URL, erhalten bleiben, sollten Sie ausgewählte Ressourcen innerhalb des Projekts löschen, statt das gesamte Projekt.
1. Wechseln Sie in der Google Cloud Console zur Seite Ressourcen verwalten.

   Zur Seite „Ressourcen verwalten“

2. Wählen Sie in der Projektliste das Projekt aus, das Sie löschen möchten, und klicken Sie dann auf Löschen.
3. Geben Sie im Dialogfeld die Projekt-ID ein und klicken Sie auf Shut down (Beenden), um das Projekt zu löschen.

Nächste Schritte

• Endpoints Frameworks-Architektur
• Verfügbare API-Annotationen
• API über anderen Pfad bereitstellen
• API überwachen
• API-Zugriff mit API-Schlüsseln einschränken
• API-Versionierung handhaben
• Google Cloud Endpoints-Community