Kurzanleitung: Traffic zu einem Dienst mit der gcloud CLI sichern

Auf dieser Seite erfahren Sie, wie Sie eine API in API Gateway bereitstellen, um den Traffic zu einem Backend-Dienst zu sichern.

Führen Sie die folgenden Schritte aus, um eine neue API für den Zugriff auf einen Backend-Dienst in Cloud Run Functions über die Google Cloud CLI bereitzustellen. In dieser Kurzanleitung wird auch beschrieben, wie Sie Ihr Backend mithilfe eines API-Schlüssels vor unbefugtem Zugriff schützen.

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. Hier kannst du überprüfen, ob das der Fall ist.

    Abrechnung aktivieren

  3. Prüfen Sie, ob die Google Cloud CLI heruntergeladen und auf Ihrem Computer installiert wurde.

    gcloud CLI herunterladen

  4. Aktualisieren Sie die gcloud-Komponenten:

    gcloud components update

  5. Legen Sie das Standardprojekt fest. Ersetzen Sie dabei PROJECT_ID durch die ID Ihres Projekts in Google Cloud .

    gcloud config set project PROJECT_ID

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-Back-End bereitstellen

API Gateway steht vor einem bereitgestellten Backend-Dienst und verarbeitet alle eingehenden Anfragen. In dieser Kurzanleitung leitet API Gateway eingehende Aufrufe an ein Cloud Run Functions-Backend namens helloGET weiter, das die folgende Funktion enthält:

/**
 * HTTP Cloud Function.
 * This function is exported by index.js, and is executed when
 * you make an HTTP request to the deployed function's endpoint.
 *
 * @param {Object} req Cloud Function request context.
 *                     More info: https://expressjs.com/en/api.html#req
 * @param {Object} res Cloud Function response context.
 *                     More info: https://expressjs.com/en/api.html#res
 */

exports.helloGET = (req, res) => {
  res.send('Hello World!');
};

Folgen Sie der Kurzanleitung: Google Cloud CLI verwenden, um den Beispielcode für Cloud Run-Funktionen herunterzuladen und den Backend-Dienst der Cloud Run-Funktion bereitzustellen.

API erstellen

Jetzt können Sie Ihre API in API Gateway erstellen.

  1. Geben Sie den folgenden Befehl ein. Dabei gilt:

    Beispiel:

    gcloud api-gateway apis create my-api

  2. Nach erfolgreichem Abschluss können Sie den folgenden Befehl verwenden, um Details zur neuen API aufzurufen:

    gcloud api-gateway apis describe API_ID

    Beispiel:

    gcloud api-gateway apis describe my-api

    Dieser Befehl gibt Folgendes zurück:

      createTime: '2020-02-29T21:52:20.297426875Z'
  displayName: my-api
  managedService: my-api-123abc456def1.apigateway.my-project.cloud.goog
  name: projects/my-project/locations/global/apis/my-api
  state: ACTIVE
  updateTime: '2020-02-29T21:52:20.647923711Z'

Beachten Sie den Wert des Attributs managedService. Dieser Wert wird in einem nachfolgenden Schritt verwendet, um Ihre API zu aktivieren.

API-Konfiguration erstellen

Bevor Sie das API-Gateway zur Verwaltung des Traffics zu Ihrem bereitgestellten API-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. Weitere Informationen zu unterstützten OpenAPI-Erweiterungen finden Sie unter:

Die für diese Kurzanleitung verwendete OpenAPI-Beschreibung enthält Routinganweisungen für das Cloud Run-Funktions-Backend:

OpenAPI 2.0

# openapi-functions.yaml
swagger: '2.0'
info:
  title: API_ID optional-string
  description: Sample API on API Gateway with a Google Cloud Functions backend
  version: 1.0.0
schemes:
  - https
produces:
  - application/json
paths:
  /hello:
    get:
      summary: Greet a user
      operationId: hello
      x-google-backend:
        address: https://GATEWAY_LOCATION-PROJECT_ID.cloudfunctions.net/helloGET
      responses:
        '200':
          description: A successful response
          schema:
            type: string

OpenAPI 3.x

# openapi-functions.yaml
openapi: 3.0.4
info:
  title: API_ID optional-string
  description: Sample API on API Gateway with a Google Cloud Functions backend
  version: 1.0.0
# Define reusable components in x-google-api-management
x-google-api-management:
  backend:
    functions_backend:
      address: https://GATEWAY_LOCATION-PROJECT_ID.cloudfunctions.net/helloGET
      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: functions_backend
paths:
  /hello:
    get:
      summary: Greet a user
      operationId: hello
      responses:
        '200':
          description: A successful response
          content:
            application/json:
              schema:
                type: string

So laden Sie diese OpenAPI-Beschreibung hoch und erstellen mit der gcloud CLI eine API-Konfiguration:

  1. Erstellen Sie über die Befehlszeile eine neue Datei mit dem Namen openapi-functions.yaml.

  2. Kopieren Sie den Inhalt der OpenAPI-Beschreibung und fügen Sie ihn in die neu erstellte Datei ein.

  3. Bearbeiten Sie die Datei so:

    1. Ersetzen Sie im Feld title API_ID durch den Namen Ihrer API und ersetzen Sie optional-string durch eine kurze Beschreibung Ihrer Wahl. Der Wert dieses Felds wird verwendet, wenn API-Schlüssel erstellt werden, die Zugriff auf diese API gewähren.
    2. Ersetzen Sie im Feld address GATEWAY_LOCATION durch die Google Cloud Region der bereitgestellten Funktion und PROJECT_ID durch den Namen Ihres Google Cloud Projekts.

  4. 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.
    • API_DEFINITION gibt den Dateinamen der OpenAPI-Spezifikation 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 konfigurieren. 
    gcloud api-gateway api-configs create CONFIG_ID \
  --api=API_ID --openapi-spec=API_DEFINITION \
   --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL

    Beispiel:

    gcloud api-gateway api-configs create my-config \
  --api=my-api --openapi-spec=openapi2-functions.yaml \
  --backend-auth-service-account=0000000000000-compute@developer.gserviceaccount.com

    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.

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

    Beispiel:

    gcloud api-gateway api-configs describe my-config \
  --api=my-api

    Die Ausgabe enthält die API-Konfigurationsdetails, einschließlich Name und Status, wie im folgenden Beispiel gezeigt:

    createTime: '2020-02-07T18:17:01.839180746Z'
displayName: my-config
gatewayConfig:
backendConfig:
  googleServiceAccount: 0000000000000-compute@developer.gserviceaccount.com
name: projects/my-project/locations/global/apis/my-api/configs/my-config
serviceRollout:
rolloutId: 2020-02-07r0
state: ACTIVE
updateTime: '2020-02-07T18:17:02.173778118Z'

Gateway erstellen

Stellen Sie nun die API-Konfiguration auf einem Gateway bereit. Durch das Bereitstellen einer API-Konfiguration auf einem Gateway wird eine externe URL definiert, über die 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

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.

Beispiel:

gcloud api-gateway gateways create my-gateway \
  --api=my-api --api-config=my-config \
  --location=us-central1

Verwenden Sie nach erfolgreichem Abschluss den folgenden Befehl, um Details zum Gateway aufzurufen:

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

Beispiel:

gcloud api-gateway gateways describe my-gateway \
  --location=us-central1

Dieser Befehl gibt Folgendes zurück:

apiConfig: projects/my-project/locations/global/apis/my-api/configs/my-config
createTime: '2020-02-05T13:44:12.997862831Z'
defaultHostname: my-gateway-a12bcd345e67f89g0h.uc.gateway.dev
displayName: my-gateway
name: projects/my-project/locations/us-central1/gateways/my-gateway
serviceAccount:
      email: 0000000000000-compute@developer.gserviceaccount.com
state: ACTIVE
updateTime: '2020-02-05T13:45:00.844705087Z'

Beachten Sie den Wert des Attributs defaultHostname. 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 den folgenden curl-Befehl ein. Dabei gilt:

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

Beispiel: 

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

Die Ausgabe sieht so aus:

Hello World!

Sie haben erfolgreich ein API Gateway erstellt und bereitgestellt.

Zugriff mit einem API-Schlüssel sichern

Um den Zugriff auf Ihr API-Backend zu sichern, können Sie einen mit Ihrem Projekt verknüpften API-Schlüssel generieren und diesem Schlüssel Zugriff zum Aufrufen der API gewähren. Weitere Informationen finden Sie unter API-Zugriff mit API-Schlüsseln einschränken.

Wenn dem Google Cloud -Projekt, das Sie in dieser Kurzanleitung verwenden, noch kein API-Schlüssel zugeordnet ist, können Sie einen hinzufügen. Führen Sie dazu die Schritte unter API-Schlüssel erstellen aus.

So sichern Sie den Zugriff auf Ihr Gateway mit einem API-Schlüssel:

  1. Aktivieren Sie die API-Schlüsselunterstützung für Ihren Dienst. Geben Sie den folgenden Befehl ein. Dabei gilt:
    • MANAGED_SERVICE_NAME ist der Name des verwalteten Dienstes, der beim Bereitstellen der API erstellt wurde. Dies kann im Attribut "Verwalteter Dienst" angezeigt werden, das mit dem Befehl gcloud apigee-gateway apis describe aufgelistet wird.
    • PROJECT_ID gibt den Namen Ihres Google Cloud Projekts an.
    gcloud services enable MANAGED_SERVICE_NAME.apigateway.PROJECT_ID.cloud.goog
     Beispiel: 
    gcloud services enable my-api-123abc456def1.apigateway.my-project.cloud.goog
  2. Ändern Sie die OpenAPI-Beschreibung, mit der Sie Ihre API-Konfiguration erstellt haben, um Anweisungen zur Durchsetzung einer Sicherheitsrichtlinie für die API-Schlüsselvalidierung für den gesamten Traffic aufzunehmen. Fügen Sie den Typ security und securityDefinitions wie unten gezeigt hinzu:

    OpenAPI 2.0

      # openapi2-functions.yaml
  swagger: '2.0'
  info:
    title: API_ID optional-string
    description: Sample API on API Gateway with a Google Cloud Functions backend
    version: 1.0.0
  schemes:
    - https
  produces:
    - application/json
  paths:
    /hello:
      get:
        summary: Greet a user
        operationId: hello
        x-google-backend:
          address: https://GATEWAY_LOCATION-PROJECT_ID.cloudfunctions.net/helloGET
        security:
        - api_key: []
        responses:
          '200':
            description: A successful response
            schema:
              type: string
  securityDefinitions:
    # This section configures basic authentication with an API key.
    api_key:
      type: "apiKey"
      name: "key"
      in: "query"
     Die securityDefinition konfiguriert die API so, dass ein API-Schlüssel als Abfrageparameter mit dem Namen key übergeben werden muss, wenn Zugriff auf alle in der Spezifikation definierten Pfade angefordert wird.

    OpenAPI 3.x

    # openapi-functions.yaml
openapi: 3.0.4
info:
  title: API_ID optional-string
  description: Sample API on API Gateway with a Google Cloud Functions backend
  version: 1.0.0
# Define reusable components in x-google-api-management
x-google-api-management:
  backend:
    functions_backend:
      address: https://GATEWAY_LOCATION-PROJECT_ID.cloudfunctions.net/helloGET
      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: functions_backend
components:
# This section configures basic authentication with an API key.
  securitySchemes:
    google_api_key:
      type: apiKey
      name: x-api-key
      in: header
security:
  - google_api_key: []
paths:
  /hello:
    get:
      summary: Greet a user
      operationId: hello
      responses:
        '200':
          description: A successful response
          content:
            application/json:
              schema:
                type: string
     Die securitySchemes konfiguriert die API so, dass ein API-Schlüssel als Abfrageparameter mit dem Namen key übergeben werden muss, wenn Zugriff auf alle in der Spezifikation definierten Pfade angefordert wird.
  3. Erstellen Sie mit dem folgenden Befehl eine neue API-Konfiguration mit der geänderten OpenAPI-Spezifikation: 
    gcloud api-gateway api-configs create NEW_CONFIG_ID \
--api=API_ID --openapi-spec=NEW_API_DEFINITION \
--backend-auth-service-account=SERVICE_ACCOUNT_EMAIL
     Beispiel: 
    gcloud api-gateway api-configs create my-config-key \
  --api=my-api --openapi-spec=openapi2-functions.yaml \
  --project=my-project --backend-auth-service-account=0000000000000compute@developer.gserviceaccount.com
  4. Führen Sie den folgenden Befehl aus, um Ihr bestehendes Gateway mit der neuen API-Konfiguration zu aktualisieren: 
    gcloud api-gateway gateways update GATEWAY_ID \
  --api=API_ID --api-config=NEW_CONFIG_ID \
  --location=GCP_REGION
    Beispiel: 
    gcloud api-gateway gateways update my-gateway \
  --api=my-api --api-config=my-config-key \
  --location=us-central1

API-Schlüssel testen

Nachdem Sie die geänderte API erstellt und bereitgestellt haben, versuchen Sie, eine Anfrage an sie zu senden.

Geben Sie den folgenden curl-Befehl ein. Dabei gilt:

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

Beispiel: 

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

Dies sollte zu folgendem Fehler führen:

UNAUTHENTICATED:Method doesn't allow unregistered callers (callers without established identity). Please use API Key or other form of API consumer identity to call this API.

Geben Sie jetzt den folgenden curl-Befehl ein, wobei:

  • DEFAULT_HOSTNAME gibt den Hostnamen-Teil der bereitgestellten Gateway-URL an.
  • hello ist der in Ihrer API-Konfiguration angegebene Pfad.
  • API_KEY den API-Schlüssel angibt, den Sie im vorherigen Schritt erstellt haben.
curl https://DEFAULT_HOSTNAME/hello?key=API_KEY

Nun sollte Hello World! in der Antwort Ihrer API angezeigt werden.

Das war's auch schon! Sie haben Ihr API-Backend mit einem API Gateway erfolgreich geschützt. Sie können jetzt mit der Einrichtung neuer API-Clients beginnen. Generieren Sie dazu zusätzliche API-Schlüssel.

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.

Nächste Schritte