Erste Schritte mit Endpoints für die App Engine-Standardumgebung mit ESPv2

Auf dieser Seite erfahren Sie, wie Sie Cloud Endpoints für App Engine einrichten. Endpoints verwendet Extensible Service Proxy V2 Beta (ESPv2 Beta) als API-Gateway. Für die API-Verwaltung für App Engine stellen Sie den vordefinierten ESPv2 Beta-Container für Cloud Run bereit. Anschließend können Sie die Anwendung mit dem Identity-Aware Proxy (IAP) sichern, damit nur ESPv2 Beta diese aufrufen kann.

Mit dieser Konfiguration fängt ESPv2 Beta alle Anfragen an Ihre Anwendung ab und führt vor dem Aufrufen der Anwendung die erforderlichen Prüfungen (z. B. Authentifizierung) durch. Wenn die Anwendung antwortet, erfasst und meldet ESPv2 Beta Telemetriedaten. Sie können Messwerte für Ihre Anwendung auf der Seite Endpunkte > Dienste in der Google Cloud Console ansehen.

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

Zu ESPv2 Beta migrieren

In früheren Versionen von Cloud Endpoints wurde die Verwendung von Extensible Service Proxy (ESP) mit Cloud Run unterstützt. Wenn bereits APIs vorhanden sind, die Sie zu ESPv2 Beta migrieren möchten, finden Sie weitere Informationen unter Zu Extensible Service Proxy V2 Beta migrieren.

Aufgabenliste

Verwenden Sie beim Durcharbeiten der Anleitung die folgende Aufgabenliste. Alle Aufgaben müssen ausgeführt werden, damit Endpoints die Anwendung verwalten kann.

  1. Erstellen Sie ein Google Cloud-Projekt. Wenn Sie App Engine nicht selbst bereitgestellt haben, stellen Sie eine Beispielanwendung bereit. Siehe Vorbereitung.
  2. Konfigurieren Sie den IAP, um Ihre Anwendung zu sichern. Siehe IAP konfigurieren.
  3. Stellen Sie den ESPv2 Beta-Container für Cloud Run bereit. Siehe ESPv2 Beta bereitstellen.
  4. Erstellen Sie ein OpenAPI-Dokument, das Ihre API beschreibt, und konfigurieren Sie die Routen zu Ihrer App Engine. Siehe Endpoints konfigurieren.
  5. Stellen Sie das OpenAPI-Dokument bereit, um einen verwalteten Dienst zu erstellen. Siehe Endpoints-Konfiguration bereitstellen.
  6. Erstellen Sie ein neues ESPv2 Beta-Docker-Image mit Ihrer Endpoints-Dienstkonfiguration und stellen Sie es bereit. Erteilen Sie dann ESPv2 Beta die Berechtigung von Identity and Access Management (IAM) zum Aufrufen Ihres Dienstes. Siehe Neues ESPv2 Beta-Image erstellen.
  7. Rufen Sie die Anwendung auf. Siehe Anfrage an die API senden.
  8. Überwachen Sie die Aktivitäten der Anwendungen. Siehe API-Aktivitäten verfolgen.
  9. Vermeiden Sie Gebühren, die Ihrem Google Cloud-Konto in Rechnung gestellt werden. Siehe Bereinigen.

Vorbereitung

Einrichtung vorbereiten:

  1. Rufen Sie in der Cloud Console die Seite Ressourcen verwalten auf und erstellen Sie ein Projekt.

    Zur Seite "Ressourcen verwalten"

  2. Die Abrechnung für Ihr Projekt muss aktiviert sein.

    Weitere Informationen zum Aktivieren der Abrechnung

  3. Notieren Sie die Projekt-ID für die nächsten Schritte. Nachstehend wird hier die Projekt-ID als ESP_PROJECT_ID bezeichnet.

  4. Notieren Sie die Projektnummer für die nächsten Schritte. Nachstehend wird hier die Projektnummer als ESP_PROJECT_NUMBER bezeichnet.

  5. Laden Sie das Cloud SDK herunter und installieren Sie es.

    Cloud SDK herunterladen

  6. Wenn Sie noch keine eigene App Engine-Anwendung bereitgestellt haben, folgen Sie der Anleitung in der App Engine-Kurzanleitung. Notieren Sie die Region, in der Ihre Anwendungen bereitgestellt werden, und die Projekt-ID. Nachstehend wird die Projekt-ID als APP_PROJECT_ID bezeichnet.

IAP konfigurieren, um die Anwendung zu sichern

Mit dem Identity-Aware Proxy (IAP) sichern Sie die App Engine-Anwendung und sorgen dafür, dass die Anfragen authentifiziert werden.

Folgen Sie den Schritten zum Aktivieren des IAP und überprüfen Sie, ob Sie sich in der Anwendung anmelden können.

Notieren Sie beim Konfigurieren des OAuth-Clients außerdem den OAuth-client_id. Dieser wird in dieser Anleitung als IAP_CLIENT_ID bezeichnet.

ESPv2 Beta bereitstellen

So stellen Sie den ESPv2 Beta-Container für Cloud Run bereit:

  1. Achten Sie darauf, dass das Cloud SDK die Berechtigung für den Zugriff auf Ihre Daten und Dienste hat.
  2. Melden Sie sich an.
    gcloud auth login
  3. Es wird ein neuer Browsertab geöffnet. Dort wählen Sie ein Konto aus, das für das Google Cloud-Projekt, das Sie zum Bereitstellen von ESPv2 Beta für Cloud Run erstellt haben, die Rolle Bearbeiter oder Inhaber hat.
  • Legen Sie die Region fest.
    gcloud config set run/region us-central1
  • Stellen Sie ESPv2 Beta für Cloud Run bereit. Ersetzen Sie CLOUD_RUN_SERVICE_NAME durch den Namen, den Sie für den Dienst verwenden möchten.
    gcloud run deploy CLOUD_RUN_SERVICE_NAME \
        --image="gcr.io/endpoints-release/endpoints-runtime-serverless:2" \
        --allow-unauthenticated \
        --platform=managed \
        --project=ESP_PROJECT_ID
    

    Bei erfolgreicher Befehlsausführung wird eine Meldung angezeigt, die in etwa so aussieht:

    Service [CLOUD_RUN_SERVICE_NAME] revision [CLOUD_RUN_SERVICE_NAME-REVISION_NUM] has been deployed and is serving traffic at CLOUD_RUN_SERVICE_URL

    Hier ein Beispiel, in dem CLOUD_RUN_SERVICE_NAME auf gateway festgelegt ist:

    Service [gateway] revision [gateway-00001] has been deployed and is serving traffic at https://gateway-12345-uc.a.run.app

    In diesem Beispiel ist https://gateway-12345-uc.a.run.app die CLOUD_RUN_SERVICE_URL und gateway-12345-uc.a.run.app der CLOUD_RUN_HOSTNAME.

  • Notieren Sie sich CLOUD_RUN_HOSTNAME. Sie geben CLOUD_RUN_HOSTNAME im Feld host Ihres OpenAPI-Dokuments an.
  • Sie können kontrollieren, ob die anfängliche Version von ESPv2 Beta in Cloud Run bereitgestellt ist, wenn Sie die CLOUD_RUN_SERVICE_URL in Ihrem Webbrowser aufrufen. Sie sollten eine Warnmeldung zu einer fehlenden Umgebungsvariablen sehen. Diese Warnmeldung wird erwartet und wird so lange angezeigt, bis der Schritt Neues ESPv2-Beta-Image erstellen abgeschlossen ist.
  • Der Cloud Run-Dienst ist nun öffentlich im Internet verfügbar. Wenn Sie Authentifizierungsfunktionen hinzufügen möchten, empfehlen wir, eine der von Endpoints unterstützten Authentifizierungsmethoden zu verwenden.
  • Endpoints konfigurieren

    Sie benötigen ein OpenAPI-Dokument auf Grundlage der OpenAPI-Spezifikation Version 2.0, das die Oberfläche Ihrer Anwendungen sowie Authentifizierungsanforderungen beschreibt. Sie müssen außerdem ein Google-spezifisches Feld hinzufügen, das die URL für jede Anwendung enthält, damit ESPv2 Beta über die Informationen verfügt, die zum Aufrufen einer Anwendung erforderlich sind. Wenn Sie OpenAPI noch nicht kennen, finden Sie weitere Informationen in der OpenAPI-Übersicht

    1. Erstellen Sie eine Textdatei namens openapi-appengine.yaml. (Der Einfachheit halber wird das OpenAPI-Dokument hier so genannt, Sie können es jedoch auch beliebig anders benennen.)
    2. Ihre App Engine-Back-End-Anwendung wird oben in der Datei openapi-appengine.yaml in einer Definition vom Typ x-google-backend definiert. Beispiel:
        swagger: '2.0'
        info:
          title: Cloud Endpoints + App Engine
          description: Sample API on Cloud Endpoints with an App Engine backend
          version: 1.0.0
        host: HOST
        schemes:
          - https
        produces:
          - application/json
        x-google-backend:
          address: https://APP_PROJECT_ID.REGION.r.appspot.com
          jwt_audience: IAP_CLIENT_ID
          protocol: h2
        paths:
          /:
            get:
              summary: Greet a user
              operationId: hello
              responses:
                '200':
                  description: A successful response
                  schema:
                    type: string
      
      Die Einrückung ist für das YAML-Format wichtig. Das Feld host muss beispielsweise auf derselben Ebene wie info sein.
    3. Ersetzen Sie im Abschnitt x-google-backend im Feld address den Parameter APP_PROJECT_ID durch Ihre Google Cloud-Projekt-ID, REGION durch die GCP-Region, in der Sie App Engine bereitgestellt haben, und IAP_CLIENT_ID durch die OAuth-Client ID, die Sie beim Einrichten von IAP erstellt haben.
    4. Geben Sie im Feld host den Hostnamen-Teil CLOUD_RUN_HOSTNAME der URL an, die Cloud Run erstellt hat, als Sie ESPv2 Beta im obigen Abschnitt unter ESPv2 Beta bereitstellen bereitgestellt haben. Lassen Sie dabei die Protokollkennung https:// weg. Beispiel:

      swagger: '2.0'
        info:
          title: Cloud Endpoints + App Engine
          description: Sample API on Cloud Endpoints with an App Engine backend
          version: 1.0.0
        host: gateway-12345-uc.a.run.app
      
    5. Beachten Sie den Wert des Attributs title in der Datei openapi-appengine.yaml:

      title: Cloud Endpoints + App Engine

      Der Wert des Attributs title wird nach Bereitstellung der Konfiguration zum Namen des Endpoints-Dienstes.

    6. Speichern Sie das OpenAPI-Dokument.

    Weitere Informationen zu den Feldern im für Endpoints erforderlichen OpenAPI-Dokument finden Sie unter Cloud 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. Achten Sie darauf, dass Sie sich in dem Verzeichnis befinden, das Ihr OpenAPI-Dokument enthält.
    2. Laden Sie die Konfiguration hoch und erstellen Sie einen verwalteten Dienst.

      gcloud endpoints services deploy openapi-appengine.yaml \
        --project ESP_PROJECT_ID

      Dadurch wird ein neuer Endpoints-Dienst mit dem Namen erstellt, den Sie in der Datei openapi-appengine.yaml im Feld host angegeben haben. Der Dienst wird dem OpenAPI-Dokument entsprechend konfiguriert.

      Beim Erstellen und Konfigurieren des Dienstes gibt Service Management Informationen an das Terminal aus. Nach Abschluss der Bereitstellung erhalten Sie eine Meldung, die in etwa so aussieht:

      Service Configuration [CONFIG_ID] uploaded for service [CLOUD_RUN_HOSTNAME]

      CONFIG_ID ist die eindeutige Endpoints-Dienstkonfigurations-ID, die von der Bereitstellung erstellt wird. Beispiel:

      Service Configuration [2019-02-01r0] uploaded for service [gateway-12345-uc.a.run.app]

      Die Dienstkonfigurations-ID besteht aus einem Datumsstempel, gefolgt von einer Überarbeitungsnummer. Wenn Sie openapi-appengine.yaml am selben Tag noch einmal bereitstellen, wird die Überarbeitungsnummer in der Dienstkonfigurations-ID erhöht. In der Cloud Console auf der Seite Endpoints > Dienste können Sie die Dienstkonfiguration und den Bereitstellungsverlauf einsehen.

      Wenn Sie eine Fehlermeldung erhalten, lesen Sie Fehlerbehebung bei der Bereitstellung von Cloud Endpoints-Konfigurationen.

    Erforderliche Dienste prüfen

    Für Endpoints und 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 Endpoints 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.

    Neues ESPv2 Beta-Image erstellen

    Erstellen Sie aus der Endpoints-Dienstkonfiguration ein neues ESPv2 Beta-Docker-Image und stellen Sie den Cloud Run-Dienst von ESPv2 Beta mit dem Image noch einmal bereit. Erteilen Sie dann ESPv2 Beta die IAM-Berechtigung zum Aufrufen Ihrer Dienste.

    So binden Sie die Dienstkonfiguration in ein neues ESPv2 Beta-Docker-Image ein:

    1. Laden Sie dieses Skript auf Ihren lokalen Computer herunter, auf dem das gcloud SDK installiert ist, und führen Sie es so aus:

      chmod +x gcloud_build_image
      
      ./gcloud_build_image -s CLOUD_RUN_HOSTNAME \
          -c CONFIG_ID -p ESP_PROJECT_ID

      Geben Sie als CLOUD_RUN_HOSTNAME den Hostnamen der URL an, die Cloud Run erstellt hat, als Sie ESPv2 Beta weiter oben unter ESPv2 Beta bereitstellen bereitgestellt haben. Lassen Sie dabei die Protokollkennung https:// weg.

      Beispiel:

      chmod +x gcloud_build_image
      ./gcloud_build_image -s gateway-12345-uc.a.run.app \
          -c 2019-02-01r0 -p ESP_PROJECT_ID

      Das Skript verwendet den gcloud-Befehl, um die Dienstkonfiguration herunterzuladen, die Dienstkonfiguration in ein neues ESPv2 Beta-Image einzubinden und das neue Image in Ihre Projekt-Container Registry hochzuladen. Das Skript verwendet automatisch den neuesten Release von ESPv2 Beta, der durch ESP_VERSION im Ausgabe-Image-Namen angegeben ist. Das Ausgabebild wird hochgeladen in:

      gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID

      Beispiel:

      gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:2.14.0-gateway-12345-uc.a.run.app-2019-02-01r0"
    2. Stellen Sie den Cloud Run-Dienst von ESPv2 Beta mit dem neuen Image noch einmal bereit. Ersetzen Sie CLOUD_RUN_SERVICE_NAME durch denselben Cloud Run-Dienstnamen, den Sie bei der ursprünglichen Bereitstellung im obigen Abschnitt ESPv2 Beta bereitstellen verwendet haben:

      gcloud run deploy CLOUD_RUN_SERVICE_NAME \
        --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \
        --allow-unauthenticated \
        --platform managed \
        --project=ESP_PROJECT_ID
    3. Wenn Sie Endpoints so konfigurieren möchten, dass zusätzliche ESPv2 Beta-Startoptionen wie das Aktivieren von CORS verwendet werden, können Sie die Argumente in der Umgebungsvariablen ESPv2_ARGS übergeben:

      gcloud run deploy CLOUD_RUN_SERVICE_NAME \
        --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \
        --set-env-vars=ESPv2_ARGS=--cors_preset=basic \
        --allow-unauthenticated \
        --platform managed \
        --project ESP_PROJECT_ID

      Weitere Informationen und Beispiele zum Festlegen der Umgebungsvariablen ESPv2_ARGS, einschließlich der Liste der verfügbaren Optionen und Informationen zur Angabe mehrerer Optionen, finden Sie unter Startoptionen von Extensible Service Proxy V2 Beta.

    4. Gewähren Sie ESPv2 Beta die Berechtigung, Ihre mit IAP gesicherte App aufzurufen. Führen Sie für jeden Dienst den folgenden Befehl aus. Nehmen Sie dazu im nachstehenden Befehl folgende Änderungen vor:
      • Ersetzen Sie APP_PROJECT_ID durch den Namen Ihrer App Engine-Projekt-ID.
      • Ersetzen Sie ESP_PROJECT_NUMBER durch die Projektnummer des Projekts, das Sie für ESPv2 Beta erstellt haben. Sie finden sie zum Beispiel in der IAM-Console: Suchen Sie dort das Compute-Standarddienstkonto. Das ist das Dienstkonto, das im Flag "member" verwendet wird.
        gcloud projects add-iam-policy-binding APP_PROJECT_ID \
            --member "serviceAccount:ESP_PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
            --role "roles/iap.httpsResourceAccessor"
          

    Weitere Informationen finden Sie unter Zugriff mit IAM verwalten.

    Anfragen an die API senden

    In diesem Abschnitt wird beschrieben, wie Sie Anfragen an die API senden.

    1. Erstellen Sie eine Umgebungsvariable für den Endpoints-Dienstnamen. Das ist der Name, den Sie im Feld host Ihres OpenAPI-Dokuments angegeben haben. Beispiel:
      • Linux oder MacOS:

        export ENDPOINTS_HOST=gateway-12345-uc.a.run.app

      • Windows PowerShell:

        $Env: ENDPOINTS_HOST="gateway-12345-uc.a.run.app"

    Linux oder macOS

    Senden Sie mit curl eine HTTP-Anfrage mithilfe der im vorherigen Schritt festgelegten Umgebungsvariable ENDPOINTS_HOST.

    curl --request GET \
       --header "content-type:application/json" \
       "https://${ENDPOINTS_HOST}/"

    PowerShell

    Senden Sie mit Invoke-WebRequest eine HTTP-Anfrage mithilfe der im vorherigen Schritt festgelegten Umgebungsvariable ENDPOINTS_HOST.

    (Invoke-WebRequest -Method GET `
        -Headers @{"content-type"="application/json"} `
        -URI "https://$Env:ENDPOINTS_HOST/").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 auch eine Drittanbieteranwendung wie die Chrome-Browsererweiterung "Postman" verwenden.

    • Wählen Sie als HTTP-Verb GET aus.
    • Wählen Sie für den Header den Schlüssel content-type und den Wert application/json aus.
    • Verwenden Sie anstelle der Umgebungsvariablen die tatsächliche URL. Beispiel:

      https://gateway-12345-uc.a.run.app/
      

    Wenn als Antwort ein Fehler zurückgegeben wird, lesen Sie die Informationen unter Fehlerbehebung bei Antwortfehlern.

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

    API-Aktivitäten verfolgen

    1. Sehen Sie sich in der Cloud Console auf der Seite Endpoints > Dienste die Aktivitätsgrafiken Ihrer API an.

      Endpoints-Aktivitätsgrafiken ansehen

      Es kann einen Moment dauern, bis die Anfrage in den Grafiken angezeigt wird.

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

      Endpoints-Anfragelogs ansehen

    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

    Mit den folgenden Schritten vermeiden Sie, dass Ihrem Google Cloud-Konto die in dieser Kurzanleitung verwendeten Ressourcen in Rechnung gestellt werden:

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

    Weitere Informationen