Schritt 2: Proxydienst (Google Cloud API Gateway) über die Konsole erstellen

Snowflake sendet keine Daten (HTTP-POST-Anforderungen) direkt an einen Remotedienst. Stattdessen sendet Snowflake die Daten an einen Proxydienst, der die Daten von Snowflake an den Remotedienst und vom Remotedienst (d. h. der GCP Cloud Function) zurück an Snowflake leitet.

Unter diesem Thema finden Sie eine Anleitung zum Erstellen und Konfigurieren eines Google Cloud API Gateway zur Verwendung als Proxydienst für Ihre externe Funktion.

Unter diesem Thema:

API-Definition erstellen

Erstellen Sie in Ihrem lokalen Dateisystem eine YAML-formatierte Konfigurationsdatei, die die zu erstellenden API spezifiziert. Die Datei sollte die Erweiterung .yaml oder .yml haben.

Vorlage für die Konfigurationsdatei:

swagger: '2.0'
info:
  title: API Gateway config for Snowflake external function.
  description: This configuration file connects the API Gateway resource to the remote service (Cloud Function).
  version: 1.0.0
schemes:
  - https
produces:
  - application/json
paths:
  /<PATH>:
    post:
      summary: Echo the input.
      operationId: echo
      x-google-backend:
        address: <HTTP ENDPOINT TO ROUTE REQUEST TO>
        protocol: h2
      responses:
        '200':
          description: <DESCRIPTION>
          schema:
            type: string

Füllen Sie die folgenden Felder aus, oder aktualisieren Sie diese:

  1. Ersetzen Sie <PATH> durch einen eindeutigen Namen. Dieser Wert wird in URLs übernommen, verwenden Sie also nur Zeichen, die in URLs gültig sind. Geben Sie zum Beispiel demo-func-resource ein.

    Beachten Sie, dass Sie im Gegensatz zu den anderen Feldern in dieser Konfigurationsdatei den Wert für <PATH> vor dem Doppelpunkt und nicht nach dem Doppelpunkt eingeben müssen. Beispielsweise ist Folgendes korrekt:

    paths:
      /demo-func-resource:
    

    Der Pfadname darf keine Pfadparameter enthalten. Google unterstützt Pfadparameter beim Einstellen des Pfades auf eine URL. Snowflake unterstützt jedoch keine Pfadparameter in der entsprechenden URL, die in der CREATE EXTERNAL FUNCTION-Anweisung angegeben wird.

  2. Kopieren Sie den Pfad (z. B. demo-func-resource) aus dem unmittelbar vorangegangenen Schritt in das Feld „Path Suffix“ auf Ihrem Arbeitsblatt.

  3. Suchen Sie das Feld address unter dem Feld x-google-backend, und ersetzen Sie <HTTP ENDPOINT TO ROUTE REQUEST TO> durch den Wert aus dem Feld „Cloud Function Trigger URL“ auf Ihrem Arbeitsblatt. Das Ergebnis sollte in etwa wie folgt aussehen:

    x-google-backend:
      address: https:// ...
    

    Die URL darf nicht in Anführungszeichen gesetzt werden.

    Die URL muss kein von Google gehosteter Endpunkt sein, sondern kann der Pfad zu einem beliebigen HTTP-Endpunkt sein.

    Wenn Sie in Schritt 1: Remotedienst (Google Cloud Function) über die Konsole erstellen die Option Require HTTPS ausgewählt haben, müssen Sie sicherstellen, dass die URL, die Sie in das Feld address eingeben, mit https beginnt.

  4. Optional können Sie jeden der folgenden Werte aktualisieren:

    • title im Abschnitt info

    • description im Abschnitt info

    • operationId im Unterabschnitt post des Abschnitts paths

    • summary im Unterabschnitt post des Abschnitts paths

  5. Überprüfen Sie Ihre Beispielkonfigurationsdatei. Diese sollte ungefähr wir folgt aussehen:

    swagger: '2.0'
    info:
      title: "API Gateway config for Snowflake external function"
      description: "This configuration file connects the API Gateway resource to the remote service (Cloud Function)."
      version: 1.0.0
    schemes:
      - https
    produces:
      - application/json
    paths:
      /demo-func-resource:
        post:
          summary: "echo the input"
          operationId: echo
          x-google-backend:
            address: https://my_dev.cloudfunctions.net/demo-cloud-function-01
            protocol: h2
          responses:
            '200':
              description: echo result
              schema:
                type: string
    

    Bemerkung

    Mit dieser Konfiguration bleibt Ihr Gateway für die Öffentlichkeit zugänglich, bis Sie es in Schritt 5: GCP-Sicherheitsrichtlinie für Proxydienst über die Konsole erstellen diese Tutorials sichern.

  6. Um sicherzustellen, dass niemand Ihr Gateway in der Zwischenzeit verwenden kann, fügen Sie optional eine Sicherheitsdefinition in die Konfigurationsdatei ein, die einen temporären, ungültigen Dienstkontonamen (google_service_account) verwendet, wie in diesem optionalen Schritt beschrieben. Das Hinzufügen dieser Sicherheitsdefinition in diesem Schritt bedeutet, dass Sie Ihre externe Funktion erst testen können, wenn Sie die Konfiguration der Sicherheit in Schritt 5: GCP-Sicherheitsrichtlinie für Proxydienst über die Konsole erstellen abgeschlossen haben. Insbesondere wird die Anleitung zum Testen Ihrer externen Funktion in Schritt 4: Externe Funktion für GCP in Snowflake erstellen noch nicht funktionieren.

    1. Fügen Sie den folgenden securityDefinitions-Abschnitt direkt über dem Abschnitt schemes der Konfigurationsdatei und auf der gleichen Einrückungsebene hinzu.

      securityDefinitions:
        <security-def-name>:
          authorizationUrl: ""
          flow: "implicit"
          type: "oauth2"
          x-google-issuer: "google_service_account"
          x-google-jwks_uri: "https://www.googleapis.com/robot/v1/metadata/x509/google_service_account"
      
      • Ersetzen Sie <security-def-name> durch einen eindeutigen Namen für die Sicherheitsdefinition (z. B. snowflakeAccess01).

      • Notieren Sie sich den Namen auf dem Arbeitsblatt im Feld „Security Definition Name“.

    2. Aktualisieren Sie in der Konfigurationsdatei den Abschnitt post:, um auf die oben erstellte Sicherheitsdefinition zu verweisen. Fügen Sie unterhalb des Feldes operationId Folgendes hinzu:

      security:
        - <security-def-name>: []
      
      • Achten Sie darauf, dass es auf der gleichen Ebene wie das Feld operationId eingerückt ist.

      • Ersetzen Sie <security-def-name> durch den Wert aus dem Feld „Security Definition Name“ Ihres Arbeitsblatts.

      • Stellen Sie sicher, dass vor dem Namen der Sicherheitsdefinition ein Bindestrich und ein Leerzeichen stehen, wie oben gezeigt.

      • Achten Sie darauf, dass die leeren eckigen Klammern ([]) nach dem Doppelpunkt enthalten sind.

      Beispiel:

      paths:
        /demo-func-resource:
          post:
            summary: "echo the input"
            operationId: echo
            security:
              - snowflakeAccess01: []
            x-google-backend:
              address: https://my_dev.cloudfunctions.net/demo-cloud-function-01
              protocol: h2
      
  7. Speichern Sie die Konfigurationsdatei.

  8. Notieren Sie sich Dateipfad und Dateiname im Feld „Name der Konfigurationsdatei“ Ihres Arbeitsblatts.

Wenn Sie mehr über die API-Konfigurationsdatei erfahren möchten, lesen Sie die folgende GCP-Dokumentation:

API-Gateway erstellen

So erstellen Sie ein API-Gateway:

  1. Erstellen Sie eine GCP API.

  2. Erstellen Sie eine API-Konfigurationsdatei.

  3. Erstellen Sie mit der API-Konfigurationsdatei ein Gateway.

GCP API erstellen

In diesem Schritt wird eine GCP-API erstellt, die ein Container ist, der mehrere API-Gateways und mehrere Konfigurationsdateien enthalten kann:

  1. Wechseln Sie auf den Google Cloud API Gateway-Bildschirm, indem Sie auf das GCP-Menü klicken und API Gateway auswählen.

  2. Klicken Sie auf CREATE GATEWAY.

  3. Geben Sie den Display Name und die API ID ein (z. B. demo-api-display-name-for-external-function1 und demo-api-id-for-external-function1).

    Diese Werte müssen Sie sich nicht auf dem Arbeitsblatt notieren, da Sie diese später zur Erstellung Ihrer externen Funktion nicht mehr benötigen. Sie sollten sich jedoch die API-ID notieren, damit Sie diese löschen können, wenn Sie fertig sind.

API-Konfigurationsdatei erstellen

Laden Sie Ihre Konfigurationsdatei auf die Konsole hoch, wodurch eine API Config erstellt wird.

  1. Scrollen Sie auf dem Bildschirm zum Abschnitt API Config.

  2. Suchen Sie nach dem Feld, das Upload an API Spec enthält.

    Klicken Sie auf BROWSE, und wählen Sie Ihre Konfigurationsdatei aus. Den Namen Ihrer Konfigurationsdatei haben Sie im Feld „Configuration File Name“ des Arbeitsblatts notiert.

  3. Geben Sie in das Feld Display Name einen Anzeigenamen ein.

  4. Wählen Sie ein Dienstkonto aus.

    Wenn Sie die Beispielfunktion erstellt haben, dann wählen Sie in dem Feld Select a Service Account die Option App Engine default service account aus.

    Wenn Sie eine Funktion erstellen, die in der Produktion verwendet werden soll (und nicht als Beispiel), können Sie ein anderes Dienstkonto auswählen.

    Das ausgewählte Dienstkonto muss über entsprechende Berechtigungen verfügen, einschließlich der Berechtigung zum Aufrufen der Cloud Function.

Gateway mit der API Config erstellen

  1. Scrollen Sie auf dem Bildschirm zum Abschnitt Gateway details.

  2. Geben Sie den Wert von Display Name des neuen API-Gateways ein.

  3. Klicken Sie in das Feld Location, und wählen Sie die entsprechende Region (z. B. us-central1) aus.

  4. Klicken Sie auf CREATE GATEWAY.

    Dadurch gelangen Sie zum Bildschirm APIs, auf der eine Liste Ihrer APIs angezeigt wird.

    Wenn Ihre neue API nicht sofort sichtbar ist, warten Sie einige Minuten, und klicken Sie dann auf die Schaltfläche Refresh.

  5. Kopieren Sie den Managed Service-Wert der API in das Feld „Managed Service Identifier“ des Arbeitsblatts.

  6. An diesem Punkt sollte noch eine Liste Ihrer APIs angezeigt werden. Klicken Sie auf den Namen der API.

    Es müssen vier Registerkarten angezeigt werden: OVERVIEW, DETAILS, CONFIGS und GATEWAYS.

  7. Klicken Sie auf die Registerkarte GATEWAYS.

  8. Notieren Sie sich die Gateway URL auf dem Arbeitsblatt im Feld „Gateway Base URL“.