Erste Schritte mit Cloud Endpoints in der flexiblen App Engine-Umgebung (.NET) mit ESP

---

In dieser Anleitung wird erklärt, wie Sie eine .NET Core-Beispiel-API und den Extensible Service Proxy (ESP) konfigurieren und bereitstellen, der auf einer Instanz in der flexiblen App Engine-Umgebung ausgeführt wird. Die REST API des Beispielcodes wird in der OpenAPI-Spezifikation beschrieben. Sie erfahren in dieser Anleitung auch, wie Sie einen API-Schlüssel erstellen und in Anfragen an die API verwenden.

Eine Übersicht über Cloud Endpoints finden Sie in den Abschnitten Über Cloud Endpoints und Endpoints-Architektur.

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, installieren Sie die erforderliche Software und erstellen Sie eine App Engine-Anwendung. Siehe Vorbereitung.
2. Beispielcode herunterladen: Siehe Beispielcode abrufen.
3. Konfigurieren Sie die Datei openapi-appengine.yaml, mit der Endpoints konfiguriert wird. Siehe Endpoints konfigurieren.
4. Die Endpoints-Konfiguration bereitstellen, um einen Endpoints-Dienst zu erstellen. Siehe Endpoints-Konfiguration bereitstellen.
5. Die Beispiel-API und den ESP in App Engine bereitstellen. Siehe API-Backend bereitstellen.
6. Senden Sie eine Anfrage an die API. Siehe Anfrage an die API senden.
7. API-Aktivitäten verfolgen. Siehe API-Aktivitäten verfolgen.
8. 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:

• App Engine
• Endpoints

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.
7. Für diese Anleitung ist das .NET Core 2.x SDK erforderlich, das Sie mit einem beliebigen Texteditor verwenden können. Es ist nicht erforderlich, eine integrierte Entwicklungsumgebung (Integrated Development Environment, IDE) zu verwenden. Dennoch empfehlen wir der Einfachheit halber, eine der folgenden IDEs zu nutzen:
   • Visual Studio Code für macOS, Linux und Windows. Wenn Sie Visual Studio Code verwenden, müssen Sie auch .NET Core 2.x installieren.
   • Visual Studio 2017 für Windows. In dieser Version ist .NET Core 2.x bereits enthalten. Wenn Sie Visual Studio 2017 einsetzen, sollten Sie das Plug-in Google Cloud Tools for Visual Studio verwenden, das die App Engine-Bereitstellung in die IDE einbindet.
   • Visual Studio für Mac. In dieser Version ist .NET Core 2.x bereits enthalten.

8. Sie benötigen eine Anwendung, um Anfragen an die Beispiel-API zu senden. Diese Anleitung enthält ein Beispiel, bei dem Invoke-WebRequest verwendet wird. Der Befehl wird in PowerShell ab Version 3.0 unterstützt.

9. Laden Sie die Google Cloud CLI herunter.
10. Aktualisieren Sie die gcloud CLI und installieren Sie die Endpoints-Komponenten.

    gcloud components update

11. Die Google Cloud CLI (gcloud) muss berechtigt sein, auf Ihre Daten und Dienste in Google Cloud zuzugreifen:

    gcloud auth login

    Ein neuer Browsertab wird geöffnet. Wählen Sie dort ein Konto aus.
12. 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.

13. Wählen Sie die Region aus, in der Sie die App Engine-Anwendung erstellen möchten. Führen Sie den folgenden Befehl aus, um eine Liste der Regionen abzurufen:

    gcloud app regions list

14. Erstellen Sie 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 laden Sie die Beispiel-API herunter:

1. Laden Sie den Beispielcode als ZIP-Datei herunter.

2. Extrahieren Sie die ZIP-Datei und wechseln Sie zum Verzeichnis dotnet-docs-samples-master\endpoints\getting-started.

3. Öffnen Sie GettingStarted.sln mit Visual Studio oder verwenden Sie einen Editor Ihrer Wahl, um die Dateien im Verzeichnis endpoints\getting-started\src\IO.Swagger zu bearbeiten.

Endpoints konfigurieren

Der Beispielcode enthält die OpenAPI-Konfigurationsdatei openapi-appengine.yaml, die auf der OpenAPI-Spezifikation Version 2.0 beruht.

So konfigurieren Sie Endpoints:

1. Öffnen Sie im Beispielcodeverzeichnis die Konfigurationsdatei openapi-appengine.yaml.

   swagger: "2.0"
   info:
     description: "A simple Google Cloud Endpoints API example."
     title: "Endpoints Example"
     version: "1.0.0"
   host: "YOUR-PROJECT-ID.appspot.com"
   

   Wichtige Hinweise:

   • Im Konfigurationsbeispiel sind die Zeilen in der Nähe des Feldes host zu sehen, die Sie ändern müssen. Zum Bereitstellen der Datei openapi-appengine.yaml in Endpoints ist das vollständige OpenAPI-Dokument erforderlich.
   • Die Beispieldatei openapi-appengine.yaml enthält einen Abschnitt zum Konfigurieren der Authentifizierung, der für diese Anleitung nicht benötigt wird. Die Zeilen mit YOUR-SERVICE-ACCOUNT-EMAIL und YOUR-CLIENT-ID brauchen Sie nicht zu konfigurieren.
   • OpenAPI ist eine sprachunabhängige Spezifikation. Die Datei openapi-appengine.yaml für das Beispiel getting-started ist im GitHub-Repository aller Sprachen die gleiche.

2. Ersetzen Sie in der Zeile mit dem Feld host den Text YOUR-PROJECT-ID durch die ID Ihres Google Cloud-Projekts. Beispiel:

   host: "example-project-12345.appspot.com"
   

Endpoints verwendet den Text im Feld host als Dienstnamen. Wenn Sie die API im App Engine-Backend bereitstellen, wird automatisch ein DNS-Eintrag mit einem Namen im Format YOUR-PROJECT-ID.appspot.com erstellt.

Informationen zu den Feldern im OpenAPI-Dokument, die für Endpoints erforderlich sind, finden Sie unter Endpoints konfigurieren.

Endpoints-Konfiguration bereitstellen

Die Endpoints-Konfiguration wird mit dem Befehl gcloud endpoints services deploy bereitgestellt. Dieser Befehl erstellt mithilfe von Service Management einen verwalteten Dienst.

So stellen Sie die Endpoints-Konfiguration bereit:

1. Sie müssen sich im Verzeichnis endpoints/getting-started befinden.
2. Laden Sie die Konfiguration hoch und erstellen Sie einen verwalteten Dienst:

   gcloud endpoints services deploy openapi-appengine.yaml
   

Der Befehl gcloud ruft dann die Service Management API auf, um einen verwalteten Dienst mit dem Namen zu erstellen, den Sie im Feld host der Datei openapi-appengine.yaml angegeben haben. In der Service Management API wird der Dienst gemäß den Einstellungen in der Datei openapi-appengine.yaml konfiguriert. Wenn Sie Änderungen an openapi-appengine.yamlopenapi.yaml vornehmen, müssen Sie die Datei noch einmal bereitstellen, um den Endpoints-Dienst zu aktualisieren.

Beim Erstellen und Konfigurieren des Dienstes gibt Service Management Informationen an das Terminal aus. Warnungen mit dem Hinweis, dass für die Pfade in der Datei openapi-appengine.yaml kein API-Schlüssel erforderlich ist, können Sie ignorieren. Nach Abschluss der Dienstkonfiguration wird von Service Management eine Meldung mit der Dienstkonfigurations-ID und dem Dienstnamen angezeigt, die etwa so aussieht:

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

Im vorherigen Beispiel ist 2017-02-13r0 die Dienstkonfigurations-ID und example-project-12345.appspot.com der Name des Endpoints-Dienstes. Die Dienstkonfigurations-ID besteht aus einem Datumsstempel und einer Überarbeitungsnummer. Wenn Sie die Datei openapi-appengine.yaml am selben Tag noch einmal bereitstellen, erhöht sich die Überarbeitungsnummer in der Dienstkonfigurations-ID. Sie können die Konfiguration des Endpoints-Dienstes in der Google Cloud Console auf der Seite Endpunkte > Dienste ansehen.

Wenn Sie eine Fehlermeldung erhalten, lesen Sie Fehlerbehebung bei der Endpoints-Konfigurationsbereitstellung.

Erforderliche Dienste prüfen

Für Endpoints und den ESP müssen mindestens die folgenden Google-Dienste aktiviert sein:

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.

API-Backend bereitstellen

Bisher haben Sie zwar das OpenAPI-Dokument für Service Management bereitgestellt, den Code für das API-Back-End haben Sie jedoch noch nicht implementiert. In diesem Abschnitt wird die Bereitstellung der Beispiel-API und des ESPs in App Engine beschrieben.

So stellen Sie das API-Back-End bereit:

1. Öffnen Sie die Datei endpoints/getting-started/src/IO.Swagger/app.yaml und fügen Sie den Dienstnamen hinzu:

endpoints_api_service:
  # The following values are to be replaced by information from the output of
  # 'gcloud endpoints services deploy openapi-appengine.yaml' command. If you have
  # previously run the deploy command, you can list your existing configuration
  # ids using the 'configs list' command as follows:
  # 'gcloud endpoints configs list --service=[PROJECT-ID].appspot.com'
  # where [PROJECT-ID].appspot.com is your Endpoints service name.
  name: ENDPOINTS-SERVICE-NAME
  rollout_strategy: managed

Ersetzen Sie ENDPOINTS-SERVICE-NAME durch den Namen Ihres Endpoints-Diensts. Dies ist der Name, den Sie im Feld host Ihres OpenAPI-Dokuments konfiguriert haben. Beispiel:

endpoints_api_service:
  name: example-project-12345.appspot.com
  rollout_strategy: managed

Mit der Option rollout_strategy: managed legen Sie fest, dass der ESP die zuletzt bereitgestellte Dienstkonfiguration verwendet. Wenn Sie diese Option innerhalb von 5 Minuten nach der Bereitstellung einer neuen Dienstkonfiguration angeben, erkennt der ESP die Änderung und verwendet automatisch die neue Konfiguration. Wir empfehlen, diese Option anstelle einer konkreten Konfigurations-ID anzugeben, die vom ESP verwendet werden soll.

2. Speichern Sie die Datei app.yaml.

Da Sie den Abschnitt endpoints_api_service in die Datei app.yaml eingefügt haben, wird der ESP durch den Befehl gcloud app deploy in einem separaten Container in der flexiblen App Engine-Umgebung bereitgestellt und konfiguriert. Sämtliche Anfragen werden über den ESP weitergeleitet. Dieser sendet Anfragen und Antworten zum und vom Container, in dem Ihr Back-End-Servercode ausgeführt wird.

3. Sie müssen sich im Verzeichnis endpoints/getting-started befinden, in dem die Konfigurationsdatei openapi-appengine.yaml gespeichert ist.
4. Stellen Sie die Beispiel-API und den ESP in App Engine bereit:

    dotnet restore
    dotnet publish
    gcloud app deploy src\IO.Swagger\bin\Debug\netcoreapp2.0\publish\app.yaml

Mit dem Befehl gcloud app deploy wird ein DNS-Eintrag im Format YOUR_PROJECT_ID.appspot.com erstellt. Sie verwenden diesen Eintrag zum Senden von Anfragen an die API. Warten Sie damit jedoch einige Minuten, damit App Engine die Initialisierung abschließen kann.

Wenn Sie eine Fehlermeldung erhalten, lesen Sie die Informationen unter Fehlerbehebung bei der flexiblen App Engine-Bereitstellung.

Weitere Informationen finden Sie unter API-Back-End bereitstellen.

Anfragen an die API senden

Nachdem Sie die API bereitgestellt haben, können Sie Anfragen an sie senden.

API-Schlüssel erstellen und Umgebungsvariable festlegen

Für den Beispielcode ist ein API-Schlüssel erforderlich. Zur Vereinfachung der Anfrage legen Sie eine Umgebungsvariable für den API-Schlüssel fest.

1. Erstellen Sie in dem Google Cloud-Projekt, das Sie für Ihre API verwendet haben, auf der Seite mit den API-Anmeldedaten einen API-Schlüssel. Informationen zum Erstellen eines API-Schlüssels in einem anderen Google Cloud-Projekt finden Sie unter API im Google Cloud-Projekt aktivieren.

   Zur Seite "Domainbestätigung"

2. Klicken Sie auf Anmeldedaten erstellen und wählen Sie anschließend API-Schlüssel aus.
3. Kopieren Sie den Schlüssel in die Zwischenablage.
4. Klicken Sie auf Schließen.
5. Fügen Sie den API-Schlüssel auf Ihrem lokalen Computer ein, um ihn einer Umgebungsvariablen zuzuweisen: $Env:ENDPOINTS_KEY="AIza..."

Anfrage senden

1. Legen Sie in PowerShell eine Umgebungsvariable für die Projekt-URL von App Engine fest. Ersetzen Sie YOUR_PROJECT_ID durch Ihre Google Cloud-Projekt-ID.

   $Env:ENDPOINTS_HOST="https://YOUR_PROJECT_ID.appspot.com"

2. Testen Sie eine HTTP-Anfrage mit den Umgebungsvariablen ENDPOINTS_HOST und ENDPOINTS_KEY, die Sie vorhin festgelegt haben:

   Invoke-WebRequest "$ENDPOINTS_HOST/echo?key=$ENDPOINTS_KEY" `
     -Body '{"message": "hello world"}' -Method POST `
     -ContentType "application/json"
   

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"
}

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

Sie haben gerade eine API in Cloud Endpoints 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 auf der Endpoints-Seite die Aktivitätsgrafiken für Ihre API an.

   Endpoints-Dienste aufrufen

   Es kann einen Moment 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.

Informationen zum Beenden der in dieser Anleitung verwendeten Dienste finden Sie unter API und API-Instanzen löschen.

Nächste Schritte

• API mit einem anderen Entwickler teilen
• Mehr über die Authentifizierung erfahren
• Supportoptionen der Community kennenlernen