Cloud Endpoints OpenAPI für Standardumgebung mit ESPv2 einrichten
Auf dieser Seite erfahren Sie, wie Sie Cloud Endpoints für App Engine einrichten. Endpoints verwendet Extensible Service Proxy V2 (ESPv2) als API-Gateway. Für die API-Verwaltung für App Engine stellen Sie den vordefinierten ESPv2-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 Einrichtung überwacht ESPv2 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 ESPv2 Telemetriedaten und erfasst diese, wie in der folgenden Abbildung dargestellt. 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 Architekturübersicht zu Cloud Endpoints.
Zu ESPv2 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 migrieren möchten, finden Sie weitere Informationen unter Zu Extensible Service Proxy V2 migrieren.
Aufgabenliste
Verwenden Sie beim Durcharbeiten der Anleitung die folgende Aufgabenliste. Alle Aufgaben müssen ausgeführt werden, damit Endpoints die Anwendung verwalten kann.
- Erstellen Sie ein Google Cloud-Projekt. Wenn Sie keine eigene App Engine-Anwendung bereitgestellt haben, stellen Sie eine Beispiel-Back-End-Anwendung bereit. Weitere Informationen finden Sie unter Vorbereitung.
- Konfigurieren Sie den IAP, um Ihre Anwendung zu sichern. Siehe IAP konfigurieren.
- Reservieren Sie einen Cloud Run-Hostnamen für den ESPv2-Dienst. Weitere Informationen erhalten Sie unter Cloud Run-Hostname reservieren.
- Erstellen Sie ein OpenAPI-Dokument, das Ihre API beschreibt, und konfigurieren Sie die Routen zu Ihrer App Engine. Siehe Endpoints konfigurieren.
- Stellen Sie das OpenAPI-Dokument bereit, um einen verwalteten Dienst zu erstellen. Siehe Endpoints-Konfiguration bereitstellen.
- Erstellen Sie ein neues ESPv2-Docker-Image mit Ihrer Endpoints-Dienstkonfiguration. Siehe Neues ESPv2-Image erstellen.
- Stellen Sie den ESPv2-Container für Cloud Run bereit. Erteilen Sie dann ESPv2 die Berechtigung von Identity and Access Management (IAM) zum Aufrufen Ihres Dienstes. Siehe ESPv2-Container bereitstellen.
- Rufen Sie die Anwendung auf. Siehe Anfrage an die API senden.
- Überwachen Sie die Aktivitäten der Anwendungen. Siehe API-Aktivitäten verfolgen.
- 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:
Mit dem Preisrechner können Sie eine Kostenschätzung für Ihre voraussichtliche Nutzung vornehmen.
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
Einrichtung vorbereiten:
Rufen Sie in der Google Cloud Console die Seite Ressourcen verwalten auf und erstellen Sie ein Projekt.
Die Abrechnung für Ihr Projekt muss aktiviert sein.
Notieren Sie die Projekt-ID für die nächsten Schritte. Nachstehend wird hier die Projekt-ID als ESP_PROJECT_ID bezeichnet.
Notieren Sie die Projektnummer für die nächsten Schritte. Nachstehend wird hier die Projektnummer als ESP_PROJECT_NUMBER bezeichnet.
Laden Sie die Google Cloud CLI herunter und installieren Sie sie.
Wenn Sie noch kein eigenes Back-End in App Engine 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 Ihre 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.
Cloud Run-Hostname reservieren
Sie müssen einen Cloud Run-Hostnamen für den ESPv2-Dienst reservieren, um das OpenAPI-Dokument oder die gRPC-Dienstkonfiguration zu konfigurieren. Zur Reservierung eines Hostnamens stellen Sie einen Beispielcontainer für Cloud Run bereit. Später führen Sie eine Bereitstellung des ESPv2-Containers für den gleichen Cloud Run-Dienst aus.
-
Achten Sie darauf, dass die gcloud CLI zum Zugriff auf Ihre Daten und Dienste berechtigt ist.
- Melden Sie sich an.
gcloud auth login
- 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 für Cloud Run erstellt haben, die Rolle Bearbeiter oder Inhaber hat.
- Melden Sie sich an.
- Legen Sie die Region fest.
gcloud config set run/region us-central1
-
Stellen Sie das Beispiel-Image
gcr.io/cloudrun/hello
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/cloudrun/hello" \ --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 undgateway-12345-uc.a.run.app
der CLOUD_RUN_HOSTNAME. - Notieren Sie sich CLOUD_RUN_SERVICE_NAME und CLOUD_RUN_HOSTNAME.
Später stellen Sie ESPv2 für den Cloud Run-Dienst CLOUD_RUN_SERVICE_NAME bereit.
Sie geben CLOUD_RUN_HOSTNAME im Feld
host
Ihres OpenAPI-Dokuments an.
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 hinzufügen, das die URL für jede Anwendung enthält, damit ESPv2 die zum Aufrufen einer Anwendung erforderlichen Informationen zur Verfügung stehen. Falls Sie mit OpenAPI noch nicht vertraut sind, stehen unter OpenAPI – Übersicht weitere Informationen bereit.
-
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.) -
Ihre App Engine-Back-End-Anwendung wird oben in der Datei
openapi-appengine.yaml
in einer Definition vom Typx-google-backend
definiert. Beispiel: Die Einrückung ist für das YAML-Format wichtig. Das Feldswagger: '2.0' info: title: Cloud Endpoints + App Engine description: Sample API on Cloud Endpoints with an App Engine backend version: 1.0.0 host: CLOUD_RUN_HOSTNAME 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
host
muss beispielsweise auf derselben Ebene wieinfo
sein. - Ersetzen Sie im Abschnitt
x-google-backend
im Feldaddress
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. Legen Sie im Feld
host
den Wert CLOUD_RUN_HOSTNAME fest. Dies ist der Hostname in der URL, der oben unter Cloud Run-Hostname reservieren reserviert wurde. Lassen Sie dabei die Protokollkennunghttps://
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
Beachten Sie den Wert des Attributs
title
in der Dateiopenapi-appengine.yaml
:title: Cloud Endpoints + App Engine
Der Wert des Attributs
title
wird nach Bereitstellung der Konfiguration zum Namen des Endpoints-Dienstes.- Speichern Sie das OpenAPI-Dokument.
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:
- Achten Sie darauf, dass Sie sich in dem Verzeichnis befinden, das Ihr OpenAPI-Dokument enthält.
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 Feldhost
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 Google 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 |
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
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 Feldname
Ihrer gRPC-Endpoints-Konfiguration angegeben haben.
Weitere Informationen zu den gcloud
-Befehlen finden Sie unter gcloud
-Dienste.
Neues ESPv2-Image erstellen
Erstellen Sie die Endpoints-Dienstkonfiguration in einem neuen Docker-Image für ESPv2. Später werden Sie dieses Image für den reservierten Cloud Run-Dienst bereitstellen.
So integrieren Sie die Dienstkonfiguration in ein neues ESPv2-Docker-Image:
Laden Sie dieses Skript auf Ihren lokalen Computer herunter, auf dem die gcloud CLI installiert ist.
Führen Sie das Skript mit dem folgenden Befehl aus:
chmod +x gcloud_build_image
./gcloud_build_image -s CLOUD_RUN_HOSTNAME \ -c CONFIG_ID -p ESP_PROJECT_ID
Geben Sie unter CLOUD_RUN_HOSTNAME den Hostnamen der URL ein, den Sie oben unter Cloud Run-Hostname reservieren reserviert 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 your-project-id
-
Das Skript verwendet den
gcloud
-Befehl, um die Dienstkonfiguration herunterzuladen, die Dienstkonfiguration in ein neues ESPv2-Image einzubinden und das neue Image in Ihre Projekt-Container Registry hochzuladen. Das Skript verwendet automatisch den neuesten Release von ESPv2, 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/your-project-id/endpoints-runtime-serverless:2.14.0-gateway-12345-uc.a.run.app-2019-02-01r0"
ESPv2-Container bereitstellen
Stellen Sie den Cloud Run-Dienst von ESPv2 mit dem neuen Image bereit, das Sie oben erstellt haben. Ersetzen Sie dabei CLOUD_RUN_SERVICE_NAME durch den Cloud Run-Dienstnamen, den Sie bei der ursprünglichen Reservierung des Hostnamens im Abschnitt Cloud Run-Hostname reservieren 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
Wenn Sie Endpoints so konfigurieren möchten, dass zusätzliche ESPv2-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 Flags in Extensible Service Proxy V2.- Gewähren Sie ESPv2 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 erstellt haben. Sie finden sie zum Beispiel in der IAM-Konsole: Suchen Sie dort das Compute Engine-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.
- 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
GET
als HTTP-Verb. - Wählen Sie für den Header den Schlüssel
content-type
und den Wertapplication/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ät verfolgen
Sehen Sie sich in der Google 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.
Sehen Sie sich auf der Seite "Log Explorer" die Anfragelogs an.
Entwicklerportal für die API erstellen
Sie können das Cloud Endpoints-Portal verwenden, um ein Entwicklerportal zu erstellen. Dabei handelt es sich um 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 Anleitung verwendeten Ressourcen in Rechnung gestellt werden:
Informationen zum Beenden der in dieser Anleitung verwendeten Dienste finden Sie unter API und API-Instanzen löschen.