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

Auf dieser Seite erfahren Sie, wie Sie Cloud Endpoints für App Engine einrichten. Endpoints verwendet den Extensible Service Proxy (ESP) als API-Gateway. Für die API-Verwaltung für App Engine stellen Sie den vordefinierten ESP-Container für Cloud Run bereit. Anschließend können Sie die Anwendung mit dem Identity-Aware Proxy (IAP) sichern, damit der ESP sie aufrufen kann. Mit dieser Einrichtung überwacht der ESP alle Anfragen an die Anwendung und führt vor dem Aufrufen der Anwendung die erforderlichen Prüfungen (z. B. Authentifizierung) durch. Wenn die Anwendung antwortet, sammelt und meldet der ESP Telemetriedaten. Sie können Messwerte für Ihre Anwendung auf der Seite Endpoints > Dienste in der Google Cloud Console ansehen.

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

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 ESP-Container für Cloud Run bereit. Siehe ESP 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. Konfigurieren Sie den ESP so, dass er die Konfiguration für Ihren Dienst finden kann. Siehe ESP konfigurieren.
  7. Rufen Sie eine 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

Da sich Endpoints für App Engine in der Alphaphase befindet, empfehlen wir Folgendes:

  • Erstellen Sie ein neues Google Cloud-Projekt, das beim Bereitstellen des ESP-Containers für Cloud Run verwendet werden soll.

  • Erstellen Sie entweder ein neues Projekt oder wählen Sie ein vorhandenes für die App Engine-Anwendung aus.

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 den Schritten unter App Engine-Kurzanleitung für Ihre Sprache, um das gcloud-Befehlszeilentool zum Auswählen oder Erstellen eines Google Cloud-Projekts sowie zum Bereitstellen einer Beispielanwendung zu verwenden. Notieren Sie die Region, in der Ihre Anwendungen bereitgestellt werden, und die Projekt-ID. Nachstehend wird hier 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 die OAuth-client_id. Diese wird in dieser Kurzanleitung als IAP_CLIENT_ID bezeichnet.

ESP bereitstellen

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

  1. Überprüfen Sie, ob 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 in dem Google Cloud-Projekt, das Sie für die Bereitstellung des ESP für Cloud Run erstellt haben, die Rolle Bearbeiter oder Inhaber hat.
  • Legen Sie die Region fest. Derzeit wird für Cloud Run nur die Region us-central1 unterstützt.
    gcloud config set run/region us-central1
  • Stellen Sie den ESP für Cloud Run bereit. Ersetzen Sie CLOUD_RUN_SERVICE_NAME durch den Namen, den Sie für den Dienst verwenden möchten.
    gcloud beta run deploy CLOUD_RUN_SERVICE_NAME \
        --image="gcr.io/endpoints-release/endpoints-runtime-serverless:1.30.0" \
        --allow-unauthenticated \
        --project=ESP_PROJECT_ID
    

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

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

    Im obigen Beispiel ist gateway der Name des Cloud Run-Dienstes.

  • Notieren Sie den Hostnamen aus der URL. Diesen Hostnamen müssen Sie im OpenAPI-Dokument in das Feld host eingeben.
  • 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. Außerdem müssen Sie ein Google-spezifisches Feld mit der URL für jede Anwendung hinzufügen, damit dem ESP die zum Aufrufen einer Anwendung erforderlichen Informationen zur Verfügung stehen. Wenn Sie mit OpenAPI noch nicht vertraut sind, sind unter Überblick über OpenAPI weitere Informationen erhältlich.

    1. Erstellen Sie eine Textdatei mit dem Namen openapi-appengine.yaml. (Der Einfachheit halber wird das OpenAPI-Dokument hier so genannt. Sie können es jedoch auch beliebig anders benennen.)
    2. Jede Anwendung muss in der Datei openapi-appengine.yaml im Abschnitt paths aufgeführt werden. 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
        paths:
          /hello:
            get:
              summary: Greet a user
              operationId: hello
              responses:
                '200':
                  description: A successful response
                  schema:
                    type: string
      
    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 in das Feld host den Hostnamen der Bereitstellungs-URL ein, die Cloud Run für den ESP erstellt hat. Lassen Sie dabei die Protokollkennung https:// weg. Zum 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
      

      Der Name, den Sie im Feld host konfigurieren, wird von Endpoints als Name für den Dienst verwendet.

    5. 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 [2019-02-01-r0] uploaded for service [gateway-12345-uc.a.run.app]
    

    Im vorherigen Beispiel ist 2019-02-01-r0 die Dienstkonfigurations-ID und gateway-12345-uc.a.run.app der Endpoints-Dienstname. 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 aufrufen.

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

    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 Bestimmen von 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 Werte für ENDPOINTS_SERVICE_NAME wird in der Spalte Dienstname angezeigt.

    • Für OpenAPI ist ENDPOINTS_SERVICE_NAME der Wert, den Sie im Feld host Ihrer OpenAPI-Spezifikation angegeben haben. Für gRPC ist ENDPOINTS_SERVICE_NAME der Wert, den Sie im Feld name Ihrer gRPC Endpoints-Konfiguration festgelegt haben.

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

    ESP konfigurieren

    Konfigurieren Sie den ESP so, dass er die Endpoints-Dienstkonfiguration finden kann. Erteilen Sie dann dem ESP die Cloud IAM-Berechtigung zum Aufrufen der durch den IAP geschützten Anwendung.

    So konfigurieren Sie den ESP:

    1. Legen Sie den Endpoint-Dienstnamen fest, damit der ESP Ihre Endpoints-Konfiguration finden und laden kann. Nehmen Sie dazu im nachstehenden Befehl folgende Änderungen vor:

      • Ersetzen Sie YOUR_SERVICE_NAME durch den Namen Ihres Endpoint-Dienstes. Das ist der Name, den Sie im Feld host Ihres OpenAPI-Dokuments angegeben haben.
      • Ersetzen Sie CLOUD_RUN_SERVICE_NAME durch den Namen Ihres Cloud Run-Dienstes.
      gcloud beta run services update CLOUD_RUN_SERVICE_NAME \
         --set-env-vars ENDPOINTS_SERVICE_NAME=YOUR_SERVICE_NAME \
         --project ESP_PROJECT_ID
      
    2. Wenn Sie Endpoints so konfigurieren möchten, dass zusätzliche ESP-Startoptionen wie das Aktivieren von CORS verwendet werden, können Sie die Argumente in der Umgebungsvariablen ESP_ARGS übergeben:

      gcloud beta run services update CLOUD_RUN_SERVICE_NAME \
         --set-env-vars="^|^ENDPOINTS_SERVICE_NAME=YOUR_SERVICE_NAME|ESP_ARGS=--rollout_strategy=managed,--cors_preset=basic" \
         --project ESP_PROJECT_ID
      

      Sie müssen sowohl einen ENDPOINTS_SERVICE_NAME als auch einen --rollout_strategy angeben.

    3. Erteilen Sie dem ESP die Berechtigung zum Aufrufen der durch IAP gesicherten Anwendung. Führen Sie den folgenden Befehl aus: Nehmen Sie folgende Änderungen am Befehl 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 den ESP erstellt haben. Sie finden sie z. B. in der IAM-Konsole: 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"
      

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

    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/hello").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/hello
      

    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