Erste Schritte mit Endpoints für Compute Engine mit ESP

---

OpenAPI   |  gRPC

Auf dieser Seite wird erläutert, wie Sie einen einfachen gRPC-Beispieldienst mit dem Extensible Service Proxy (ESP) in einem Docker-Container in der 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.

Ziele

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 und laden Sie die erforderliche Software herunter. Siehe Vorbereitung.
2. Compute Engine-VM-Instanz erstellen Siehe Compute Engine-Instanz erstellen.
3. Dateien aus dem Beispiel bookstore-grpc kopieren und konfigurieren. Siehe Endpoints konfigurieren.
4. Die Endpoints-Konfiguration bereitstellen, um einen Endpoints-Dienst zu erstellen. Siehe Endpoints-Konfiguration bereitstellen.
5. Die API und den ESP auf der Compute Engine-VM bereitstellen: Siehe API-Backend bereitstellen.
6. Senden Sie eine Anfrage an die API. Siehe Anfrage an die API senden.
7. Vermeiden Sie Gebühren für Ihr Google Cloud -Konto. Siehe Bereinigen.

Kosten

In diesem Dokument verwenden Sie die folgenden kostenpflichtigen Komponenten von Google Cloud:

• Compute 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.

Hinweis

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

5. Make sure that billing is enabled for your Google Cloud project.

6. Notieren Sie sich die Projekt-ID, da sie später benötigt wird.
7. Installieren und initialisieren Sie das Google Cloud CLI.
8. Aktualisieren Sie die gcloud CLI und installieren Sie die Endpoints-Komponenten:

   gcloud components update

9. Die Google Cloud CLI (gcloud) muss für den Zugriff auf Ihre Daten und Dienste auf Google Cloudberechtigt sein:

   gcloud auth login

   Ein neuer Browsertab wird geöffnet. Wählen Sie dort ein Konto aus.
10. 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 den Hilfeartikel gcloud CLI-Konfigurationen verwalten.

11. Installieren Sie gRPC und die gRPC-Tools. Informationen dazu finden Sie in der Kurzanleitung für gRPC in Python.

Compute Engine-Instanz erstellen

So erstellen Sie eine Compute Engine-Instanz:

1. In the Google Cloud console, go to the Create an instance page.

   Go to Create an instance

2. In the Firewall section, select Allow HTTP traffic and Allow HTTPS traffic.
3. To create the VM, click Create.



Warten Sie, bis die Instanz gestartet ist. Anschließend wird sie auf der Seite der VM-Instanzen mit einem grünen Statussymbol angezeigt.

4. Bestätigen Sie, dass Sie eine Verbindung zu Ihrer VM-Instanz herstellen können.
   1. In the list of virtual machine instances, click SSH in the row of the instance that you want to connect to.
   2. Sie können jetzt über das Terminal Linux-Befehle auf Ihrer Debian-Instanz ausführen.
   3. Geben Sie exit ein, um die Verbindung zur Instanz zu trennen.
5. Notieren Sie den Instanznamen, die Zone und die externe IP-Adresse, da sie später benötigt werden.

Endpoints konfigurieren

Klonen Sie das Repository zum Beispiel bookstore-grpc aus GitHub.

So konfigurieren Sie Endpoints:

1. Create a self-contained protobuf descriptor file from your service .proto file:
   1. Save a copy of bookstore.proto from the example repository. This file defines the Bookstore service's API.
   2. Create the following directory: mkdir generated_pb2
   3. Create the descriptor file, api_descriptor.pb, by using the protoc protocol buffers compiler. Run the following command in the directory where you saved bookstore.proto:

      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

      In the preceding command, --proto_path is set to the current working directory. In your gRPC build environment, if you use a different directory for .proto input files, change --proto_path so the compiler searches the directory where you saved bookstore.proto.

2. Create a gRPC API configuration YAML file:
   1. Save a copy of the api_config.yamlfile. This file defines the gRPC API configuration for the Bookstore service.
   2. Replace MY_PROJECT_ID in your api_config.yaml file with your Google Cloud project ID. For example:

      #
      # Name of the service configuration.
      #
      name: bookstore.endpoints.example-project-12345.cloud.goog
      

      Note that the apis.name field value in this file exactly matches the fully-qualified API name from the .proto file; otherwise deployment won't work. The Bookstore service is defined in bookstore.proto inside package endpoints.examples.bookstore. Its fully-qualified API name is endpoints.examples.bookstore.Bookstore, just as it appears in the api_config.yaml file.

      apis:
        - name: endpoints.examples.bookstore.Bookstore

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.

1. Make sure you are in the directory where the api_descriptor.pb and api_config.yaml files are located.
2. Confirm that the default project that the gcloud command-line tool is currently using is the Google Cloud project that you want to deploy the Endpoints configuration to. Validate the project ID returned from the following command to make sure that the service doesn't get created in the wrong project.

   gcloud config list project
   

   If you need to change the default project, run the following command:

   gcloud config set project YOUR_PROJECT_ID
   

3. Deploy the proto descriptor file and the configuration file by using the Google Cloud CLI:

   gcloud endpoints services deploy api_descriptor.pb api_config.yaml
   

   As it is creating and configuring the service, Service Management outputs information to the terminal. When the deployment completes, a message similar to the following is displayed:

   Service Configuration [CONFIG_ID] uploaded for service [bookstore.endpoints.example-project.cloud.goog]

   CONFIG_ID is the unique Endpoints service configuration ID created by the deployment. For example:

   Service Configuration [2017-02-13r0] uploaded for service [bookstore.endpoints.example-project.cloud.goog]
   

   In the previous example, 2017-02-13r0 is the service configuration ID and bookstore.endpoints.example-project.cloud.goog is the service name. The service configuration ID consists of a date stamp followed by a revision number. If you deploy the Endpoints configuration again on the same day, the revision number is incremented in the service configuration ID.

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 vorhandenesGoogle 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 Feld name 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:

1. 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.

2. 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.

3. 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:

1. Erstellen Sie auf der VM-Instanz Ihr eigenes Containernetzwerk mit dem Namen esp_net.

   sudo docker network create --driver bridge esp_net
   

2. 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
   

3. 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 Feld name 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.

1. 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
      

2. Ändern Sie Ihr Arbeitsverzeichnis:

   cd python-docs-samples/endpoints/bookstore-grpc/
     

3. Installieren Sie die Abhängigkeiten:

   pip install virtualenv
   virtualenv env
   source env/bin/activate
   python -m pip install -r requirements.txt

4. 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.
     

     Endpoints-Dienste aufrufen

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

   • Sehen Sie sich auf der Seite "Log Explorer" die Anfragelogs an.
     

     Zur Seite „Log-Explorer“

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.

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.

1. Löschen Sie die API:

   gcloud endpoints services delete SERVICE_NAME

   Ersetzen Sie SERVICE_NAME durch den Namen Ihres Diensts.

2. In the Google Cloud console, go to the VM instances page.

   Go to VM instances

3. Select the checkbox for the instance that you want to delete.
4. To delete the instance, click More actions, click Delete, and then follow the instructions.

Nächste Schritte

• Konfiguration einer eigenen gRPC API für Cloud Endpoints
• Bookstore-Beispiel auf GitHub genauer ansehen. Sowohl der Client als auch der Server sind in Python und Java verfügbar.
• Das Beispiel getting-started-grpc ist auf GitHub in den folgenden Sprachen verfügbar:
  • Java
  • Python
  • Ruby
  • Go
  • Node.js