Erste Schritte mit dem API-Gateway und Cloud Run für gRPC

Auf dieser Seite wird beschrieben, wie Sie das API-Gateway zum Verwalten und Sichern eines Cloud Run-Backend-Dienstes mit gRPC einrichten.

Aufgabenliste

Verwenden Sie beim Durcharbeiten der Anleitung die folgende Aufgabenliste. Alle Aufgaben sind erforderlich, um ein API-Gateway für Ihren Cloud Run-Backend-Dienst mit gRPC bereitzustellen.

  1. Google Cloud-Projekt erstellen oder auswählen.
  2. Wenn Sie keinen eigenen Cloud Run-Dienst bereitgestellt haben, stellen Sie einen Beispieldienst bereit. Siehe Schritt 7 in Vorbereitung.
  3. Aktivieren Sie die erforderlichen API-Gateway-Dienste.
  4. Erstellen Sie ein gRPC-API-Konfigurationsdokument, das Ihre API beschreibt und die Routen zu Ihrem Cloud Run konfiguriert. Siehe API-Konfiguration mit gRPC konfigurieren.
  5. Stellen Sie ein API-Gateway mithilfe Ihrer API-Konfiguration bereit. Siehe API-Gateway bereitstellen.
  6. Testen Sie die API-Bereitstellung. Senden Sie dazu eine Anfrage. Siehe Anfrage an die API senden.
  7. Überwachen Sie die Aktivitäten der Dienste. Siehe API-Aktivitäten verfolgen.
  8. Vermeiden Sie Gebühren, die Ihrem Google Cloud-Konto in Rechnung gestellt werden. Siehe Bereinigen.

Hinweise

  1. Rufen Sie in der Google Cloud Console die Seite Dashboard auf und wählen Sie ein Google Cloud-Projekt aus oder erstellen Sie eines.

    Zu Google Dashboard

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

    Abrechnung aktivieren

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

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

  5. Laden Sie die Google Cloud CLI herunter und installieren Sie sie.

    gcloud CLI herunterladen

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

  7. Stellen Sie den Beispiel-Back-End-gRPC-Cloud Run-Dienst python-grpc-bookstore-server zur Verwendung mit dieser Anleitung bereit. Der gRPC-Dienst verwendet das folgende Container-Image:

    gcr.io/endpointsv2/python-grpc-bookstore-server:2

    Führen Sie die Schritte unter Schnellstart: Vordefinierten Beispielcontainer bereitstellen aus, um den Dienst bereitzustellen. Achten Sie darauf, das in dieser Kurzanleitung angegebene Container-Image durch gcr.io/endpointsv2/python-grpc-bookstore-server:2 zu ersetzen.

    Notieren Sie sich die Dienst-URL sowie die Region und die Projekt-ID, in der Ihr Dienst bereitgestellt wird.

Erforderliche Dienste aktivieren

Für API Gateway müssen Sie die folgenden Google-Dienste aktivieren:

Name Titel
apigateway.googleapis.com API Gateway API
servicemanagement.googleapis.com Service Management API
servicecontrol.googleapis.com Service Control API

Mit dem folgenden Befehl bestätigen Sie, dass die erforderlichen Dienste aktiviert sind:

gcloud services list

Wenn die erforderlichen Dienste nicht aufgeführt sind, müssen Sie sie aktivieren:

gcloud services enable apigateway.googleapis.com
gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com

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

API-Konfiguration mit gRPC erstellen

Das Beispiel bookstore-grpc enthält die Dateien, die Sie lokal kopieren und konfigurieren müssen.

  1. Erstellen Sie aus der Datei .proto Ihres Dienstes eine abgeschlossene protobuf-Deskriptordatei:
    1. Speichern Sie eine Kopie von bookstore.proto aus dem Beispiel-Repository in Ihrem aktuellen Arbeitsverzeichnis. Diese Datei definiert die API für den Bookstore-Dienst.
    2. Erstellen Sie das folgende Verzeichnis unter Ihrem Arbeitsverzeichnis: mkdir generated_pb2
    3. Erstellen Sie die Deskriptordatei api_descriptor.pb mit dem Protokollpuffercompiler protoc. Führen Sie den folgenden Befehl in dem Verzeichnis aus, in dem Sie bookstore.proto gespeichert haben: 
      python3 -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 gespeicherten bookstore.proto-Datei durchsucht.

  2. Erstellen Sie eine Textdatei mit dem Namen api_config.yaml in Ihrem aktuellen Arbeitsverzeichnis (dasselbe Verzeichnis, das bookstore.proto enthält). Der Einfachheit halber bezieht sich diese Seite auf das gRPC API-Konfigurationsdokument mit diesem Dateinamen, Sie können es aber auch anders benennen, wenn Sie möchten. Fügen Sie der Datei diesen Inhalt hinzu: 
    # The configuration schema is defined by the service.proto file.
# https://github.com/googleapis/googleapis/blob/master/google/api/service.proto

type: google.api.Service
config_version: 3
name: "*.apigateway.PROJECT_ID.cloud.goog"
title: API Gateway + Cloud Run gRPC
apis:
  - name: endpoints.examples.bookstore.Bookstore
usage:
  rules:
  # ListShelves methods can be called without an API Key.
  - selector: endpoints.examples.bookstore.Bookstore.ListShelves
    allow_unregistered_calls: true
backend:
  rules:
    - selector: "*"
      address: grpcs://python-grpc-bookstore-server-HASH-uc.a.run.app
     Die Einrückung ist für das YAML-Format wichtig. Das Feld name muss beispielsweise auf derselben Ebene wie type sein.
  3. Geben Sie in das Feld name einen Dienst mit dem Namen *.apigateway.PROJECT_ID.cloud.goog ein, wobei PROJECT_ID der Name Ihrer Google Cloud-Projekt-ID ist.

  4. Ersetzen Sie grpcs://python-grpc-bookstore-server-HASH-uc.a.run.app im Feld address des Abschnitts backend.rules durch die tatsächliche URL des gRPC-Back-Ends von python-grpc-bookstore-server. Dabei ist HASH der eindeutige Hash-Code, der beim Erstellen des Dienstes generiert wurde.

    In diesem Beispiel wird davon ausgegangen, dass Sie den unter Vorbereitung erstellten Backend-Dienst für gRPC Bookstore verwenden. Ersetzen Sie diesen Wert gegebenenfalls durch die URL Ihres Cloud Run-Dienstes.

  5. Speichern Sie Ihr gRPC API-Konfigurationsdokument.
  6. Erstellen Sie die API-Konfiguration: 
    gcloud api-gateway api-configs create CONFIG_ID \
--api=API_ID --project=PROJECT_ID \
--grpc-files=api_descriptor.pb,api_config.yaml
     wobei:
    • CONFIG_ID gibt den Namen der API-Konfiguration an.
    • API_ID den Namen der API angibt.
    • PROJECT_ID den Namen Ihres Google Cloud-Projekts angibt.
    Beispiel: 
    gcloud api-gateway api-configs create grpc-config \
--api=grpc-test --project=my-test-project \
--grpc-files=api_descriptor.pb,api_config.yaml

API Gateway bereitstellen

Führen Sie den folgenden Befehl aus, um die gRPC API-Konfiguration für ein Gateway bereitzustellen:

gcloud api-gateway gateways create GATEWAY_ID \
  --api=API_ID --api-config=CONFIG_ID \
  --location=GCP_REGION --project=PROJECT_ID

wobei

  • GATEWAY_ID den Namen des Gateways angibt.
  • API_ID den Namen der API Gateway API angibt, die mit diesem Gateway verknüpft ist.
  • CONFIG_ID den Namen der im Gateway bereitgestellten API-Konfiguration angibt.

  • GCP_REGION die Google Cloud-Region für das bereitgestellte Gateway ist.

  • PROJECT_ID gibt den Namen Ihres Google Cloud-Projekts an.

Beispiel:

gcloud api-gateway gateways create bookstore-grpc \
  --api=grpc-test --api-config=grpc-config \
  --location=us-central1 --project=my-project

Nach erfolgreichem Abschluss können Sie den folgenden Befehl verwenden, um Details zum Gateway anzuzeigen:

gcloud api-gateway gateways describe GATEWAY_ID \
  --location=GCP_REGION --project=PROJECT_ID

Beachten Sie den Wert des Attributs defaultHostname in der Ausgabe dieses Befehls. Dies ist der Hostname in der Gateway-URL, mit dem Sie Ihre Bereitstellung im nächsten Schritt testen.

Beispiel: 

https://my-gateway-a12bcd345e67f89g0h.uc.gateway.dev

Anfrage an die API senden

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, in 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:

    pip3 install virtualenv
virtualenv env
source env/bin/activate
pip3 install -r requirements.txt

  4. Senden Sie eine Anfrage an die Beispiel-API:

    python3 bookstore_client.py --host=DEFAULT_HOSTNAME --port 443 --use_tls true

    Geben Sie das Attribut defaultHostname Ihres Gateways in DEFAULT_HOSTNAME ohne die Protokollkennung an. Beispiel:

    python3 bookstore_client.py --host=my-gateway-a12bcd345e67f89g0h.uc.gateway.dev --port 443 --use_tls true

API-Aktivität verfolgen

  1. Sehen Sie sich in der Google Cloud Console auf der Seite API Gateway die Aktivitätsgrafiken Ihrer API an. Klicken Sie auf die API, um die Aktivitätsgrafiken auf der Seite Übersicht aufzurufen. Es kann einen Moment dauern, bis die Anfragen in den Grafiken angezeigt werden.

  2. Sehen Sie sich auf der Seite Log-Explorer die Anfragelogs an. Einen Link zur Seite Log-Explorer finden Sie auf der Seite API Gateway in der Google Cloud Console.

    API Gateway aufrufen

    Auf der API Gateway-Seite:

    1. Wählen Sie die API aus, die Sie ansehen möchten.
    2. Klicken Sie auf den Tab Details.
    3. Klicken Sie auf den Link unter Logs.

Sie haben gerade eine API in API Gateway mit gRPC bereitgestellt und getestet!

Bereinigen

So vermeiden Sie, dass Ihrem Google Cloud-Konto die in dieser Kurzanleitung verwendeten Ressourcen in Rechnung gestellt werden:

Alternativ können Sie auch das für diese Anleitung verwendete Google Cloud-Projekt löschen.