Auf dieser Seite wird erläutert, wie Sie einen einfachen gRPC mit dem Extensible Service Proxy (ESP) in einem Docker-Container in Compute Engine bereitstellen.
Auf dieser Seite wird die Python-Version des Beispiels bookstore-grpc
verwendet. gRPC-Beispiele in anderen Sprachen finden Sie unter Weitere Informationen.
Eine Übersicht über Cloud Endpoints finden Sie in den Abschnitten Über Cloud Endpoints und Architekturübersicht zu Cloud Endpoints.
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.
- Richten Sie ein Google Cloud-Projekt ein und laden Sie die erforderliche Software herunter. Siehe Vorbereitung.
- Compute Engine-VM-Instanz erstellen Siehe Compute Engine-Instanz erstellen.
- Kopieren und konfigurieren Sie die Dateien aus dem Beispiel
bookstore-grpc
. Siehe Endpoints konfigurieren. - Die Endpoints-Konfiguration bereitstellen, um einen Endpoints-Dienst zu erstellen. Siehe Endpoints-Konfiguration bereitstellen.
- Stellen Sie die API und den ESP auf der Compute Engine-VM bereit. Siehe API-Backend bereitstellen.
- Senden Sie eine Anfrage an die API. Siehe Anfrage an die API senden.
- 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
- 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.
-
Wählen Sie in der Google Cloud Console auf der Seite der Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.
-
Die Abrechnung für das Google Cloud-Projekt muss aktiviert sein.
-
Wählen Sie in der Google Cloud Console auf der Seite der Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.
-
Die Abrechnung für das Google Cloud-Projekt muss aktiviert sein.
- Notieren Sie sich die Projekt-ID, da sie später benötigt wird.
- Installieren und initialisieren Sie das Google Cloud CLI.
- Aktualisieren Sie die gcloud CLI und installieren Sie die Endpoints-Komponenten:
gcloud components update
-
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. -
Legen Sie für das Standardprojekt Ihre Projekt-ID fest:
gcloud config set project YOUR_PROJECT_ID
Ersetzen Sie YOUR_PROJECT_ID durch Ihre Projekt-ID. Wenn Sie weitere Google Cloud-Projekte mit
gcloud
verwalten möchten, lesen Sie Konfigurationen für die gcloud CLI verwalten. - Installieren Sie gRPC und die gRPC-Tools. Informationen dazu finden Sie in der Kurzanleitung für gRPC in Python.
Compute Engine-Instanz erstellen
- Rufen Sie in der Google Cloud Console die Seite Instanz erstellen auf.
- Wählen Sie im Bereich Firewall die Option HTTP-Traffic zulassen und HTTPS-Traffic zulassen.
- Klicken Sie auf Erstellen, um die VM zu erstellen.
- Bestätigen Sie, dass Sie eine Verbindung zu Ihrer VM-Instanz herstellen können.
- Klicken Sie in der Liste der VM-Instanzen in der Zeile der Instanz, zu der Sie eine Verbindung herstellen möchten, auf SSH.
- Sie können jetzt über das Terminal Linux-Befehle auf Ihrer Debian-Instanz ausführen.
- Geben Sie
exit
ein, um die Verbindung zur Instanz zu trennen.
- Notieren Sie den Instanznamen, die Zone und die externe IP-Adresse, da sie später benötigt werden.
So erstellen Sie eine Compute Engine-Instanz:
Warten Sie, bis die Instanz gestartet ist. Anschließend wird sie auf der Seite der VM-Instanzen mit einem grünen Statussymbol angezeigt.
Endpoints konfigurieren
Klonen Sie das Repository zum Beispiel bookstore-grpc
aus GitHub.
Endpoints konfigurieren:
- Erstellen Sie aus der Datei
.proto
des Dienstes eine eigenständige Protokollpuffer-Datei:- Speichern Sie eine Kopie von
bookstore.proto
aus dem Beispiel-Repository. Diese Datei definiert die API für den Bookstore-Dienst. - Erstellen Sie das folgende Verzeichnis:
mkdir generated_pb2
- Erstellen Sie die Deskriptordatei
api_descriptor.pb
mit dem Protokollpuffercompilerprotoc
. Führen Sie den folgenden Befehl in dem Verzeichnis aus, in dem Siebookstore.proto
gespeichert haben:python -m grpc_tools.protoc \ --include_imports \ --include_source_info \ --proto_path=. \ --descriptor_set_out=api_descriptor.pb \ --python_out=generated_pb2 \ --grpc_python_out=generated_pb2 \ bookstore.proto
Im vorherigen Befehl ist
--proto_path
auf das aktuelle Arbeitsverzeichnis festgelegt. Wenn Sie in Ihrer gRPC-Build-Umgebung ein anderes Verzeichnis für.proto
-Eingabedateien verwenden, ändern Sie--proto_path
entsprechend, sodass der Compiler das Verzeichnis mit der gespeichertenbookstore.proto
-Datei durchsucht.
- Speichern Sie eine Kopie von
- Erstellen Sie eine gRPC-API-Konfigurationsdatei in YAML:
- Speichern Sie eine Kopie der Datei
api_config.yaml
. Diese Datei definiert die gRPC API-Konfiguration für den Bookstore-Dienst. - Ersetzen Sie MY_PROJECT_ID in Ihrer Datei
api_config.yaml
durch Ihre Google Cloud-Projekt-ID. Beispiel:# # Name of the service configuration. # name: bookstore.endpoints.example-project-12345.cloud.goog
Beachten Sie, dass der Wert des Feldes
apis.name
in dieser Datei exakt mit dem vollständig qualifizierten API-Namen aus der Datei.proto
übereinstimmt. Andernfalls würde die Bereitstellung nicht funktionieren. Der Bookstore-Dienst ist inbookstore.proto
im Paketendpoints.examples.bookstore
definiert. Der vollständig qualifizierte API-Name lautetendpoints.examples.bookstore.Bookstore
, genau wie er in der Dateiapi_config.yaml
angezeigt wird.apis: - name: endpoints.examples.bookstore.Bookstore
- Speichern Sie eine Kopie der Datei
Weitere Informationen 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.
- Sie müssen sich in dem Verzeichnis befinden, in dem sich die Dateien
api_descriptor.pb
undapi_config.yaml
befinden. - Vergewissern Sie sich, dass das aktuell vom
gcloud
-Befehlszeilentool verwendete Standardprojekt das Google Cloud-Projekt ist, für das Sie die Endpoints-Konfiguration bereitstellen möchten. Überprüfen Sie anhand der vom folgenden Befehl zurückgegebenen Projekt-ID, ob der Dienst im richtigen Projekt erstellt wird.gcloud config list project
Wenn Sie das Standardprojekt ändern müssen, führen Sie den folgenden Befehl aus:
gcloud config set project YOUR_PROJECT_ID
- Stellen Sie die Datei
proto descriptor
und die Konfigurationsdatei mithilfe der Google Cloud CLI bereit:gcloud endpoints services deploy api_descriptor.pb api_config.yaml
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 [bookstore.endpoints.example-project.cloud.goog]
CONFIG_ID ist die eindeutige Endpoints-Dienstkonfigurations-ID, die von der Bereitstellung erstellt wird. Beispiel:
Service Configuration [2017-02-13r0] uploaded for service [bookstore.endpoints.example-project.cloud.goog]
Im obigen Beispiel ist
2017-02-13r0
die Dienstkonfigurations-ID undbookstore.endpoints.example-project.cloud.goog
der Dienstname. Die Dienstkonfigurations-ID besteht aus einem Datumsstempel und einer Überarbeitungsnummer. Wenn Sie die Endpoints-Konfiguration am selben Tag noch einmal bereitstellen, erhöht sich die Überarbeitungsnummer in der Dienstkonfigurations-ID.
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.comgcloud 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 Feldname
Ihrer gRPC-Endpoints-Konfiguration angegeben haben.
Weitere Informationen zu den gcloud
-Befehlen finden Sie unter gcloud
-Dienste.
Wenn Sie eine Fehlermeldung erhalten, lesen Sie Fehlerbehebung bei der Cloud Endpoints-Konfigurationsbereitstellung.
Weitere Informationen finden Sie unter Endpoints-Konfiguration bereitstellen.
API-Back-End bereitstellen
Bisher haben Sie die API-Konfiguration für Service Management, aber noch nicht den Code für das API-Back-End bereitgestellt. In diesem Abschnitt erfahren Sie, wie Sie Docker für Ihre VM-Instanz einrichten und den API-Backend-Code sowie den ESP in einem Docker-Container ausführen.
Docker auf der VM-Instanz installieren
So installieren Sie Docker auf der VM-Instanz:
- Legen Sie mit dem folgenden Befehl die Zone für Ihr Projekt fest:
gcloud config set compute/zone YOUR_INSTANCE_ZONE
Ersetzen Sie YOUR_INSTANCE_ZONE durch die Zone, in der die Instanz ausgeführt wird.
- Stellen Sie mit dem folgenden Befehl eine Verbindung zu Ihrer Instanz her:
gcloud compute ssh INSTANCE_NAME
Ersetzen Sie INSTANCE_NAME durch den Namen Ihrer VM-Instanz.
- Richten Sie anhand der Docker-Dokumentation das Docker-Repository ein. Folgen Sie dabei den Anleitungen für die Version und Architektur Ihrer VM-Instanz:
- Jessie oder neuer
- x86_64/amd64
Beispiel-API und ESP in einem Docker-Container ausführen
So führen Sie den gRPC-Beispieldienst mit dem ESP in einem Docker-Container aus, damit Clients ihn verwenden können:
- Erstellen Sie auf der VM-Instanz Ihr eigenes Containernetzwerk mit dem Namen
esp_net
.sudo docker network create --driver bridge esp_net
- Führen Sie den Server für das Bookstore-Beispiel aus, der die Beispiel-API bereitstellt:
sudo docker run \ --detach \ --name=bookstore \ --net=esp_net \ gcr.io/endpointsv2/python-grpc-bookstore-server:1
- Führen Sie den vorkonfigurierten ESP-Docker-Container aus. Ersetzen Sie in den ESP-Startoptionen SERVICE_NAME durch den Namen Ihrer Dienstes. Dies ist der Name, den Sie in der Datei
api_config.yaml
im Feldname
konfiguriert haben. Beispiel:bookstore.endpoints.example-project-12345.cloud.goog
.sudo docker run \ --detach \ --name=esp \ --publish=80:9000 \ --net=esp_net \ gcr.io/endpoints-release/endpoints-runtime:1 \ --service=SERVICE_NAME \ --rollout_strategy=managed \ --http2_port=9000 \ --backend=grpc://bookstore:8000
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. Weitere Informationen zu den ESP-Argumenten finden Sie unter ESP-Startoptionen.
Wenn Sie Transcodierung aktiviert haben, müssen Sie einen Port für HTTP1.1- oder SSL-Traffic konfigurieren.
Wenn Sie eine Fehlermeldung erhalten, lesen Sie die Informationen unter Fehlerbehebung bei Endpoints auf Compute Engine.
Anfrage an die API senden
Wenn Sie die Anfrage von derselben Instanz aus senden, in der die Docker-Container ausgeführt werden, können Sie $SERVER_IP
durch localhost
ersetzen. Andernfalls ersetzen Sie $SERVER_IP
durch die externe IP-Adresse der Instanz.
Sie finden die externe IP-Adresse, wenn Sie folgenden Befehl ausführen:
gcloud compute instances list
Zum Senden von Requests an die Beispiel-API können Sie einen gRPC-Beispielclient verwenden, der in Python geschrieben wurde.
Klonen Sie das Git-Repository an dem Ort, an dem der gRPC-Clientcode gehostet wird:
git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git
Ändern Sie Ihr Arbeitsverzeichnis:
cd python-docs-samples/endpoints/bookstore-grpc/
Installieren Sie die Abhängigkeiten:
pip install virtualenv
virtualenv env
source env/bin/activate
python -m pip install -r requirements.txt
Senden Sie eine Anfrage an die Beispiel-API:
python bookstore_client.py --host SERVER_IP --port 80
Sehen Sie sich auf der Seite Endpoints > Dienste die Aktivitätsgrafiken für Ihre API an.
Es kann einen Moment dauern, bis die Anfrage in den Grafiken angezeigt wird.
Sehen Sie sich auf der Seite "Log Explorer" die Anfragelogs an.
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!
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.
- Löschen Sie die API:
gcloud endpoints services delete SERVICE_NAME
Ersetzen Sie
SERVICE_NAME
durch den Namen Ihres Diensts. - Rufen Sie in der Google Cloud Console die Seite VM-Instanzen auf.
- Klicken Sie auf das Kästchen für die Die Instanz, die Sie löschen möchten.
- Klicken Sie zum Löschen der Instanz auf Weitere Aktionen, dann auf Löschen, und folgen Sie dann der Anleitung.