Erste Schritte mit API Gateway und Cloud Run

Auf dieser Seite wird beschrieben, wie Sie API Gateway zum Verwalten und Sichern eines Cloud Run-Backend-Dienstes 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 bereitzustellen.

  1. Erstellen Sie ein Google Cloud -Projekt oder wählen Sie ein vorhandenes Projekt aus.
  2. Wenn Sie Cloud Run nicht selbst bereitgestellt haben, stellen Sie einen Beispieldienst bereit. Siehe Schritt 7 in Vorbereitung.
  3. Aktivieren Sie die erforderlichen API-Gateway-Dienste.
  4. Erstellen Sie eine OpenAPI-Beschreibung, die Ihre API beschreibt, und konfigurieren Sie die Routen zu Ihrem Cloud Run-Backend-Dienst. Siehe API-Konfiguration erstellen.
  5. Stellen Sie ein API-Gateway mithilfe Ihrer API-Konfiguration bereit. Siehe API-Gateway bereitstellen.
  6. Überwachen Sie die Aktivitäten der Dienste. Siehe API-Aktivitäten verfolgen.
  7. So vermeiden Sie Gebühren für Ihr Google Cloud -Konto. Weitere Informationen finden Sie unter 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 sich die Projekt-ID, die Sie für diese Anleitung verwenden möchten. Nachstehend wird hier die Projekt-ID als PROJECT_ID bezeichnet.

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

    gcloud CLI herunterladen

  5. Aktualisieren Sie die gcloud-Komponenten:

    gcloud components update

  6. Legen Sie das Standardprojekt fest. Ersetzen Sie PROJECT_ID durch Ihre Google Cloud Projekt-ID.

    gcloud config set project PROJECT_ID

  7. Wenn Sie noch keinen eigenen Cloud Run-Dienst bereitgestellt haben, folgen Sie der Kurzanleitung: Vorgefertigten Beispielcontainer bereitstellen, um ein Google Cloud -Projekt auszuwählen oder zu erstellen und ein Beispiel-Back-End bereitzustellen. Notieren Sie sich die Anwendungs-URL sowie die Region und die Projekt-ID, in der Ihre Anwendungen bereitgestellt werden.

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

Verwenden Sie die folgenden Befehle, um diese Dienste zu 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 erstellen

Bevor Sie das API-Gateway zur Verwaltung des Traffics zu Ihrem bereitgestellten Cloud Run-Backend verwenden können, ist eine API-Konfiguration erforderlich.

Sie können eine API-Konfiguration mithilfe einer OpenAPI-Beschreibung erstellen, die spezielle Annotationen enthält, um das gewünschte API-Gateway-Verhalten zu definieren. Sie müssen ein Google-spezifisches Feld hinzufügen, das die URL für jede Cloud Run-Anwendung enthält, damit API Gateway die zum Aufrufen einer Anwendung erforderlichen Informationen zur Verfügung stehen.

Weitere Informationen zu unterstützten OpenAPI-Erweiterungen finden Sie unter:

So erstellen Sie Ihre API-Konfiguration:

  1. Erstellen Sie eine Textdatei namens openapi-run.yaml. Der Einfachheit halber wird die OpenAPI-Beschreibung auf dieser Seite mit diesem Dateinamen bezeichnet. Sie können sie aber auch anders benennen, wenn Sie möchten.
  2. Kopieren Sie den Inhalt der folgenden Datei in Ihre openapi-run.yaml-Datei:

    OpenAPI 2.0

    # openapi-run.yaml
swagger: '2.0'
info:
  title: API_ID optional-string
  description: Sample API on API Gateway with a Cloud Run backend
  version: 1.0.0
schemes:
- https
produces:
- application/json
x-google-backend:
  address: APP_URL
paths:
  /assets/{asset}:
    get:
      parameters:
        - in: path
          name: asset
          type: string
          required: true
          description: Name of the asset.
      summary: Assets
      operationId: getAsset
      responses:
        '200':
          description: A successful response
          schema:
            type: string
  /hello:
    get:
      summary: Cloud Run hello world
      operationId: hello
      responses:
        '200':
          description: A successful response
          schema:
            type: string
    • Ersetzen Sie im Feld title API_ID durch den Namen Ihrer API und ersetzen Sie optional-string durch eine kurze Beschreibung Ihrer Wahl. Wenn Ihre API noch nicht vorhanden ist, erstellt der Befehl zum Erstellen der API-Konfiguration auch die API mit dem von Ihnen angegebenen Namen. Der Wert des Felds title wird verwendet, wenn API-Schlüssel erstellt werden, die Zugriff auf diese API gewähren. Richtlinien zur API-ID
    • Ersetzen Sie APP_URL im Feld address des Abschnitts x-google-backend durch die tatsächliche URL Ihres Cloud Run-Dienstes (den vollständigen Pfad der aufgerufenen API). Beispiel: https://hello-abc1def2gh-uc.a.run.app.

    OpenAPI 3.x

    # openapi-run.yaml
openapi: 3.0.4
info:
  title: API_ID optional-string
  description: Sample API on API Gateway with a Cloud Run backend
  version: 1.0.0
# Define reusable components in x-google-api-management
x-google-api-management:
  backends:
    cloudrun_backend:
      address: APP_URL
      deadline: 30.0
      pathTranslation: APPEND_PATH_TO_ADDRESS
      protocol: "http/1.1"
# Apply the backend configuration by referencing it by name. Set at the root so this applies to all operations unless overridden.
x-google-backend: cloudrun_backend
paths:
  /hello:
    get:
      summary: Greet a user
      operationId: hello
      responses:
        "200":
          description: A successful response
          content:
            application/json:
              schema:
                type: string
    • Ersetzen Sie im Feld title API_ID durch den Namen Ihrer API und ersetzen Sie optional-string durch eine kurze Beschreibung Ihrer Wahl. Wenn Ihre API noch nicht vorhanden ist, erstellt der Befehl zum Erstellen der API-Konfiguration auch die API mit dem von Ihnen angegebenen Namen. Der Wert des Felds title wird verwendet, wenn API-Schlüssel erstellt werden, die Zugriff auf diese API gewähren. Richtlinien zur API-ID
    • Ersetzen Sie im Feld address APP_URL durch die tatsächliche URL Ihres Cloud Run-Dienstes (den vollständigen Pfad der aufgerufenen API). Beispiel: https://hello-687541448612.us-central1.run.app.
  3. Geben Sie den folgenden Befehl ein. Dabei gilt:
    • CONFIG_ID gibt den Namen der API-Konfiguration an.
    • API_ID gibt den Namen der API an. Wenn die API nicht bereits vorhanden ist, wird sie von diesem Befehl erstellt.
    • PROJECT_ID gibt den Namen Ihres Google Cloud Projekts an.
    • SERVICE_ACCOUNT_EMAIL gibt das Dienstkonto an, das zum Signieren von Tokens für Back-Ends mit konfigurierter Authentifizierung verwendet wird. Weitere Informationen finden Sie unter Dienstkonto erstellen. 
    gcloud api-gateway api-configs create CONFIG_ID \
  --api=API_ID --openapi-spec=openapi2-run.yaml \
  --project=PROJECT_ID --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL

    Dieser Vorgang kann einige Minuten dauern, da die API-Konfiguration an nachgelagerte Systeme weitergegeben wird. Das Erstellen einer komplexen API-Konfiguration kann bis zu zehn Minuten dauern.

  4. Nachdem die API-Konfiguration erstellt wurde, können Sie die Details mit dem folgenden Befehl ansehen: 
    gcloud api-gateway api-configs describe CONFIG_ID \
  --api=API_ID

API-Gateway bereitstellen

Jetzt können Sie Ihre API auf API Gateway bereitstellen. Durch die Bereitstellung einer API in API Gateway wird auch eine externe URL definiert, mit der API-Clients auf Ihre API zugreifen können.

Führen Sie den folgenden Befehl aus, um die soeben erstellte API-Konfiguration in API 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 ist die Google Cloud -Region für das bereitgestellte Gateway.

  • PROJECT_ID gibt den Namen Ihres Google Cloud Projekts an.

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.

API-Bereitstellung testen

Jetzt können Sie Anfragen über die bei der Bereitstellung des Gateways generierte URL an Ihre API senden.

Geben Sie die folgende URL in den Webbrowser ein. Dabei gilt:

  • DEFAULT_HOSTNAME gibt den Hostnamen-Teil der bereitgestellten Gateway-URL an.
  • hello ist der in Ihrer API-Konfiguration angegebene Pfad.
https://DEFAULT_HOSTNAME/hello

Beispiel: 

https://my-gateway-687541448612.us-central1.run.app/hello

Der Cloud Run-Container, in dem die Anwendung ausgeführt wird, sollte im Browser angezeigt werden.

Fertig! Ihr Gateway verwaltet den Zugriff auf Ihren Cloud Run-Backend-Dienst.

API-Aktivitäten verfolgen

  1. Sehen Sie sich in derGoogle Cloud console auf der Seite API Gateway die Aktivitätsgrafiken Ihrer API an. Klicken Sie auf Ihre API, um die Aktivitätsdiagramme 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 derGoogle Cloud Console.

    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.

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.