Erstellen einer anpassbaren externen Funktion auf AWS

In diesem Dokument wird eine Möglichkeit zum Erstellen einer externen Funktion auf der Amazon Web Services (AWS)-Cloudplattform gezeigt, einschließlich:

  • Erstellen eines Remotedienstes (Lambda-Funktion auf AWS)

  • Erstellen eines Proxydienstes (auf Amazon API Gateway)

  • Erstellen einer API-Integration in Snowflake

  • Erstellen einer externen Funktion in Snowflake

  • Aufrufen von externen Funktionen

Diese Anleitung setzt voraus, dass Sie bereits mit der AWS-Administration vertraut sind. Die Anweisungen geben allgemeine Schritte an, die Sie ausführen müssen, es werden allerdings keine detaillierten Anweisungen für die Verwendung der AWS-Administrationskonsole bereitgestellt, da sich die Details ändern können.

Unter diesem Thema:

Voraussetzungen

Sie benötigen:

  • Ein Konto mit AWS, einschließlich Berechtigungen für:

    • AWS-Rollen über IAM (Identitäts- und Zugriffsverwaltung) erstellen

    • AWS-Lambda-Funktionen erstellen

    • API Gateway-Endpunkte erstellen

  • Ein Snowflake-Konto, in dem Sie über ACCOUNTADMIN-Berechtigungen oder eine Rolle mit der Berechtigung CREATE INTEGRATION verfügen.

In diesem Dokument wird davon ausgegangen, dass Sie ein erfahrener AWS-Administrator sind.

Tipp

Während der Erstellung der externen Funktion müssen Sie authentifizierungsbezogene Informationen von Snowflake auf AWS und von AWS in Snowflake kopieren.

Snowflake empfiehlt, dass Sie beim Befolgen der Anweisungen die Informationen bei einigen Schritten auf dem folgenden Arbeitsblatt aufzeichnen, um sie in späteren Schritten zu verwenden:

AWS Account ID.............: _____________________________________________
Lambda Function Name.......: _____________________________________________
New IAM Role Name..........: _____________________________________________
New IAM Role ARN...........: _____________________________________________
Snowflake VPC ID (optional): _____________________________________________
New API Name...............: _____________________________________________
API Gateway Resource Name..: _____________________________________________
Resource Invocation URL....: _____________________________________________
Method Request ARN.........: _____________________________________________
API_AWS_IAM_USER_ARN.......: _____________________________________________
API_AWS_EXTERNAL_ID........: _____________________________________________

Schritt 1: Remotedienst erstellen (Lambda-Funktion auf AWS)

Es gibt mehrere Möglichkeiten, einen Remotedienst zu erstellen. Dieser Abschnitt zeigt, wie Sie einen Remotedienst erstellen, der als Python-Funktion implementiert ist, die in AWS Lambda ausgeführt wird.

Diese Beispielfunktion in Python-Sprache gibt lediglich die Eingaben zurück.

Diese Funktion akzeptiert Daten in demselben Format (JSON), das von Snowflake gesendet und gelesen wird.

Diese Python-Funktion empfängt zwei Parameter, event und context. Der Parameter event enthält viele Unterfelder, von denen eines body ist. „Body“ ist ein Wörterbuch, das einen Schlüssel mit dem Namen data enthält. Der entsprechende Wert für data ist eine Zeichenfolge, die die von Snowflake gesendeten Daten im JSON-Format enthält. Da AWS Lambda die von Snowflake gesendete HTTP-POST-Anforderung verarbeitet, den Body extrahiert und den Body innerhalb des Ereignisparameters übergibt, muss diese Beispielfunktion nicht die gesamte HTTP-POST-Anforderung parsen.

Nachdem diese Python-Funktion den Body als Zeichenfolge extrahiert hat, ruft die Funktion eine JSON-Bibliotheksfunktion auf, um die Zeichenfolge in eine Python-Datenstruktur zu konvertieren. Die Funktion extrahiert dann einzelne Zeilen aus dieser Datenstruktur, verarbeitet sie und gibt für jede einen Wert zurück.

Der JSON-Text für den typischen Rückgabewert einer AWS Lambda-Funktion sieht wie folgt aus:

{
"statusCode": <http_status_code>,
"body":
        {
            "data":
                  [
                      [ 0, <value> ],
                      [ 1, <value> ]
                      ...
                  ]
        }
}

Die Daten des Rückgabewerts stimmen mit dem zuvor für die Eingabedaten beschriebenen Format überein. Bei AWS besteht die Konvention für einen HTTP-kompatiblen Dienst darin, den Body in einem JSON-Objekt zurückzugeben, das auch den HTTP-Statuscode enthält.

Führen Sie die folgenden Schritte aus, um diese AWS Lambda-Funktion zu erstellen:

  1. Melden Sie sich bei der AWS Management Console an, falls Sie dies noch nicht getan haben.

  2. Notieren Sie sich Ihre AWS-Konto-ID auf dem obigen Arbeitsblatt.

    Wenn Sie Ihre AWS-Konto-ID suchen müssen, befolgen Sie die AWS-Anleitung.

  3. Wählen Sie „Lambda“ aus.

  4. Wählen Sie „Create function“ aus.

  5. Geben Sie einen Funktionsnamen ein.

    Notieren Sie sich den Namen auf dem obigen Arbeitsblatt in der Zeile „Lambda Function Name“.

  6. Wählen Sie die zu verwendende Sprache aus. Wählen Sie in diesem Beispiel „Python 3.7“ aus.

  7. Wählen Sie eine Ausführungsrolle für diese Funktion aus, oder erstellen Sie diese.

    Wählen Sie die entsprechenden Optionen aus, normalerweise „Create a new role with basic Lambda permissions“ zum Erstellen einer neuen Rolle mit grundlegenden Lambda-Berechtigungen.

    (Diese Rolle ist von der Rolle Ihres Cloudkontos und von Ihren Snowflake-Rollen getrennt.)

  8. Klicken Sie auf die Schaltfläche Create Function.

  9. Geben Sie auf der Registerkarte lambda_function den Code für die Funktion ein. Wenn Sie noch keine eigene Funktion geschrieben haben, können Sie den Standardfunktionscode durch den folgenden Code ersetzen, der die Eingabe wiedergibt. Sie können diesen Code später ersetzen oder aktualisieren, wenn Sie bereit sind, eine benutzerdefinierte Funktion zu erstellen.

    Dieser Beispielcode geht davon aus, dass Sie die Lambda-Proxyintegration verwenden, wie von Snowflake in der Anleitung zum Erstellen des API Gateway-Endpunkts empfohlen.

    Wenn Sie nichts in das Bearbeitungsfenster einfügen können, versuchen Sie einen Doppelklick auf dem Dateinamen der Funktion, um die Bearbeitung zu aktivieren.

    import json
    
    def lambda_handler(event, context):
    
        # 200 is the HTTP status code for "ok".
        status_code = 200
    
        # The return value will contain an array of arrays (one inner array per input row).
        array_of_rows_to_return = [ ]
    
        try:
            # From the input parameter named "event", get the body, which contains
            # the input rows.
            event_body = event["body"]
    
            # Convert the input from a JSON string into a JSON object.
            payload = json.loads(event_body)
            # This is basically an array of arrays. The inner array contains the
            # row number, and a value for each parameter passed to the function.
            rows = payload["data"]
    
            # For each input row in the JSON object...
            for row in rows:
                # Read the input row number (the output row number will be the same).
                row_number = row[0]
    
                # Read the first input parameter's value. For example, this can be a
                # numeric value or a string, or it can be a compound value such as
                # a JSON structure.
                input_value_1 = row[1]
    
                # Read the second input parameter's value.
                input_value_2 = row[2]
    
                # Compose the output based on the input. This simple example
                # merely echoes the input by collecting the values into an array that
                # will be treated as a single VARIANT value.
                output_value = ["Echoing inputs:", input_value_1, input_value_2]
    
                # Put the returned row number and the returned value into an array.
                row_to_return = [row_number, output_value]
    
                # ... and add that array to the main array.
                array_of_rows_to_return.append(row_to_return)
    
            json_compatible_string_to_return = json.dumps({"data" : array_of_rows_to_return})
    
        except Exception as err:
            # 400 implies some type of error.
            status_code = 400
            # Tell caller what this function could not handle.
            json_compatible_string_to_return = event_body
    
        # Return the return value and HTTP status code.
        return {
            'statusCode': status_code,
            'body': json_compatible_string_to_return
        }
    
  10. Klicken Sie auf die Schaltfläche Deploy, um die Funktion bereitzustellen.

  11. Optional, aber dringend empfohlen: Testen Sie Ihre Funktion.

    Verwenden Sie für die von Snowflake bereitgestellte Python-Beispielfunktion die folgenden Testdaten (ersetzen Sie alle Standarddaten durch die folgenden Daten):

    {
      "body":
        "{ \"data\": [ [ 0, 43, \"page\" ], [ 1, 42, \"life, the universe, and everything\" ] ] }"
    }
    

    Die Ausführungsergebnisse sollten ungefähr wie folgt aussehen:

    Response:
    {
      "statusCode": 200,
      "body": "{\"data\": [[0, [\"Echoing inputs:\", 43, \"page\"]], [1, [\"Echoing inputs:\", 42, \"life, the universe, and everything\"]]]}"
    }
    ...
    

Wenn die vorherigen Aktionen erfolgreich waren, haben Sie jetzt eine AWS Lambda-Funktion, die Sie als Remotedienst für Ihre externe Funktion verwenden können.

Schritt 2: Proxydienst konfigurieren (Amazon API Gateway) und API-Integration erstellen (in Snowflake).

Das Konfigurieren des Amazon API Gateway als Proxydienst erfordert mehrere Schritte wie:

  • Erstellen einer neuen IAM-Rolle in Ihrem AWS-Konto

  • Erstellen und Konfigurieren eines Amazon API Gateway-Endpunkts

  • Sichern des Amazon API Gateway-Endpunkts

  • Erstellen eines API-Integrationsobjekts in Snowflake

  • Einrichten einer Vertrauensstellung zwischen Snowflake und der neuen IAM-Rolle

Die Schritte überlappen sich, da für die API-Integration Informationen vom API Gateway (ARN (Amazon Resource Name) der Rolle) benötigt werden und für das API Gateway Informationen von der API-Integration (API_AWS_EXTERNAL_ID und API_AWS_IAM_USER_ARN) benötigt werden.

Neue IAM-Rolle in Ihrem AWS-Konto erstellen

Damit sich Snowflake bei Ihrem AWS-Konto authentifizieren kann, muss einem Snowflake-eigenen IAM-Benutzer (Identitäts- und Zugriffsverwaltung) die Berechtigung erteilt werden, eine IAM-Rolle in Ihrem AWS-Konto zu übernehmen. Dazu muss eine Vertrauensstellung eingerichtet werden. Um die Vertrauensstellung einzurichten, müssen Sie eine IAM-Rolle in Ihrem AWS-Konto erstellen und mit dem ARN des Snowflake-eigenen IAM-Benutzers konfigurieren. Außerdem müssen Sie in Snowflake ein API-Integrationsobjekt erstellen und das API-Integrationsobjekt mit den Informationen darüber konfigurieren, welche IAM-Rolle übernommen werden soll.

  1. Erstellen Sie eine neue IAM-Rolle.

  2. Wenn Sie aufgefordert werden, den Typ der vertrauenswürdigen Entität auszuwählen, wählen Sie „Another AWS account“ aus.

  3. Wenn Sie aufgefordert werden, Konten anzugeben, die diese Rolle verwenden können („Specify accounts that can use this role“), fügen Sie die zuvor auf dem Arbeitsblatt notierte AWS-Konto-ID ein.

  4. Klicken Sie auf „Next: Permissions“, um zu den Berechtigungseinstellungen zu gelangen.

  5. Legen Sie bei Bedarf Berechtigungen fest („Attach permissions policies“).

  6. Geben Sie einen Rollennamen ein.

    • Notieren Sie sich den Rollennamen unter „New IAM Role Name“.

  7. Klicken Sie auf die Schaltfläche Create role. Nachdem Sie die Rolle erstellt haben:

    • Notieren Sie sich die „Role ARN“ auf dem obigen Arbeitsblatt unter „New IAM Role ARN“.

API im Amazon-API-Gateway erstellen und konfigurieren

Wählen Sie Ihren Endpunkttyp: Regionaler Endpunkt vs. Privater Endpunkt

Sie greifen auf einen Proxydienst (wie das Amazon API Gateway) über eine URI zu, manchmal auch als „Endpunkt“ bezeichnet. Für Ihren Amazonas API Gateway können Sie beides erstellen:

  • Einen regionalen Endpunkt

  • Einen privaten Endpunkt

Auf einen regionalen Endpunkt kann über Regionen oder sogar über Clouds hinweg zugegriffen werden. Ihre Snowflake-Instanz, Ihr Proxydienst und Ihr Remotedienst können sich alle in verschiedenen Regionen oder sogar auf verschiedenen Cloudplattformen befinden. Beispielsweise könnte eine Snowflake-Instanz, die auf Azure ausgeführt wird, Anfragen an einen regionalen Amazon API Gateway-Endpunkt senden, der seinerseits Daten an einen Remotedienst weiterleiten könnte, der auf GCP ausgeführt wird.

Ein privater Endpunkt kann so konfiguriert werden, dass der Zugriff nur von einer Snowflake VPC (Virtual Private Cloud) in der gleichen AWS-Region über PrivateLink möglich ist.

Weitere Einzelheiten zu den verschiedenen Typen von Endpunkten auf AWS finden Sie unter:

Wenn Sie einen privaten Endpunkt verwenden möchten und sich nicht sicher sind, welche Region Sie verwenden, können Sie Ihre Region feststellen, indem Sie einen der folgenden Aktionen ausführen:

  • Rufen Sie die SQL-Funktion CURRENT_REGION() auf (z. B. SELECT CURRENT_REGION()).

  • Überprüfen Sie den Hostnamen Ihres Snowflake-Kontos, der normalerweise den Cloudanbieter und die Region angibt. Weitere Informationen zu Hostnamen von Konten, Regionen und Cloudanbieter finden Sie unter Unterstützte Regionen.

Um einen privaten Endpunkt verwenden zu können, muss Ihr Konto die folgenden Anforderungen erfüllen:

  • Business Critical Edition (oder höhere) von Snowflake.

Auf AWS unterstützt Snowflake die Verbindung von Snowflake-Konten mit AWS VPCs. Private Endpunkte ermöglichen die Kommunikation zwischen VPCs (Virtuelle Private Clouds) über PrivateLink. Weitere Informationen zu Snowflake und AWS PrivateLink finden Sie unter

API Gateway-Endpunkt erstellen

Bevor Sie Ihr API Gateway erstellen und konfigurieren, wählen Sie, ob Sie einen regionalen Endpunkt oder einen privaten Endpunkt verwenden möchten. Weitere Informationen dazu finden Sie unter Wählen Sie Ihren Endpunkttyp: Regionaler Endpunkt vs. Privater Endpunkt.

Bemerkung

Sie können eine externe Funktion auch für Snowflake-Instanzen erstellen, die nicht auf AWS gehostet werden. Wenn sich Ihr virtuelles Warehouse auf Azure oder GCP (Google Cloud Platform) befindet, können Sie eine externe Funktion erstellen, die über ein Amazon API Gateway auf einen Remotedienst zugreift.

Die Schritte zum Erstellen eines API Gateway-Endpunkts sind unten aufgeführt:

  1. Wenn Sie planen, einen privaten Endpunkt zu verwenden, dann führen Sie folgenden Befehl über die Snowflake-Weboberfläche aus, um die VPC (Virtual Private Cloud)-ID zu erhalten:

    select system$get_snowflake_platform_info();
    

    Diese Ausgabe sollte ungefähr wir folgt aussehen:

    {"snowflake-vpc-id":["vpc-12345699"]}
    

    Notieren Sie sich die VPC-ID (z. B. „vpc-12345699“) auf dem obigen Arbeitsblatt im Feld „Snowflake VPC ID“.

    (Hinweis: Sie müssen eine VPC-ID verwenden, keine VPC-Endpunkt-ID. VPC-Endpunkt-IDs können sich im Verlauf der Zeit ändern).

  2. Wählen Sie auf der AWS Management Console die Option API Gateway aus.

  3. Wählen Sie Create API aus.

  4. Wählen Sie den Typ des Endpunkts (regional oder privat) aus.

    • Wenn Sie einen regionalen Endpunkt verwenden möchten:

      • Suchen Sie nach REST API, und klicken Sie auf die Schaltfläche Build.

    • Wenn Sie einen privaten Endpunkt verwenden möchten:

      • Suchen Sie nach REST API private, und klicken Sie auf die Schaltfläche Build.

    Wichtig

    Stellen Sie sicher, dass Sie REST API oder REST API private auswählen. Wählen Sie nicht HTTP API oder eine andere Option aus.

  5. Wählen Sie die Option New API aus.

  6. Geben Sie einen Namen für die neue API ein.

    Notieren Sie sich diesen Namen auf dem Arbeitsblatt unter „New API Name“.

  7. Wenn Sie aufgefordert werden, einen Endpoint Type auszuwählen, wählen Sie entweder Regional oder Private aus.

  8. Wenn Sie einen privaten Endpunkt erstellen, geben Sie die Snowflake-VPC-ID ein, die Sie sich auf dem Arbeitsblatt im Feld „Snowflake VPC-ID“ notiert haben.

    (Wenn Sie keinen privaten Endpunkt erstellen, brauchen Sie keine VPC-ID einzugeben).

  9. Klicken Sie auf die Schaltfläche Create API.

    Dies sollte Sie zu einem neuen Bildschirm führen, in dem Sie Ressourcen erstellen können.

  10. Erstellen Sie eine Ressource.

    (Möglicherweise müssen Sie auf die Schaltfläche Actions klicken, um die Option Create Resource anzuzeigen).

    Notieren Sie sich den Ressourcennamen zur späteren Verwendung auf dem Arbeitsblatt unter „API Gateway Resource Name“.

    Nachdem Sie auf die Schaltfläche Create Resource geklickt haben, sollte auf dem Bildschirm Folgendes angezeigt werden: No methods defined for the resource.

  11. Erstellen Sie eine neue Methode. Klicken Sie auf Actions, und wählen Sie Create Method für diese Ressource aus.

    Geben Sie die Option POST an. (Wenn die Option POST nicht angezeigt wird, klicken Sie auf das kleine Dropdown-Menüfeld unter dem Ressourcennamen).

    Dies sollte einen neuen Fensterbereich anzeigen, der Integration type und andere Optionen anzeigt.

  12. Der Integration type sollte Lambda Function sein. Wenn dieser nicht bereits ausgewählt ist, wählen Sie ihn aus.

  13. Aktivieren Sie das Kontrollkästchen Use Lambda Proxy integration.

    Es ist wichtig, Lambda-Proxyintegration auszuwählen, da sich JSON ohne Lambda-Proxyintegration von JSON mit Lambda-Proxyintegration unterscheidet. Weitere Informationen zur Lambda-Proxyintegration finden Sie in der AWS-Dokumentation unter:

  14. Fügen Sie in das Feld Lambda Function den Lambda-Funktionsnamen ein, den Sie sich auf dem Arbeitsblatt notiert haben.

  15. Speichern Sie die Eingaben.

  16. Klicken Sie auf die Schaltfläche Actions, und wählen Sie die Aktion Deploy API aus.

  17. Wählen Sie einen Stagingbereich für diese Funktion aus, oder erstellen Sie einen.

  18. Unter dem Ressourcennamen sollte POST angezeigt sein.

    Wenn dies nicht angezeigt wird, müssen Sie möglicherweise den Ressourcenstrukturbaum erweitern, indem Sie auf das Dreieck links neben dem Ressourcennamen klicken.

  19. Klicken Sie auf POST, und notieren Sie sich dann die Invoke URL für die POST-Anforderung im Feld „Resource Invocation URL“ auf dem Arbeitsblatt.

    Stellen Sie sicher, dass die Aufruf-URL den Namen der Ressource enthält. Ist dies nicht der Fall, haben Sie möglicherweise auf die Aufruf-URL für den Stagingbereich und nicht auf die Ressource geklickt.

  20. Klicken Sie auf Save Changes.

Amazon API Gateway-Endpunkt sichern

Eine Übersicht zum Sichern von Proxydienst-Endpunkten wie Amazon API Gateway-Endpunkten finden Sie unter Proxydienst-Endpunkt sichern.

So sichern Sie einen Amazon API Gateway-Endpunkt:

  1. An diesem Punkt sollten Sie sich auf dem Bildschirm befinden, der Ihre API Gateway-Informationen anzeigt, und Sie sollten Ihre Ressource und die „POST“-Methode sehen.

    Wenn Sie sich noch nicht dort befinden, gehen Sie wie folgt vor:

    1. Wechseln Sie von der AWS-Weboberfläche auf die API Gateway-Seite.

    2. Wählen Sie Ihr API Gateway, wenn Sie dies nicht bereits getan haben.

    3. Klicken Sie im linken Fensterbereich auf Resources.

    4. Klicken Sie auf das Feld POST. (Wenn das Feld nicht angezeigt wird, erweitern Sie den Ressourcenstrukturbaum, indem Sie im Resources-Fensterbereich, der normalerweise der zweite Fensterbereich von links ist, auf das Dreieck links neben der Ressource klicken).

  2. Kopieren Sie die Methodenanforderungs-ARN aus dem Feld Method Request in das Feld „Method Request ARN“ auf dem Arbeitsblatt oben.

  3. Klicken Sie auf die Kachel Method Request.

  4. Geben Sie an, dass die Method Request eine AWS_IAM-Autorisierung erfordert.

    Beachten Sie, dass Sie nach der Auswahl der AWS_IAM-Autorisierung im Dropdownmenü auf das kleine Häkchen neben dem Menü klicken müssen, um Ihre Wahl zu bestätigen.

  5. Legen Sie die Ressourcenrichtlinie für das API Gateway fest, um anzugeben, wer zum Aufrufen des Gateway-Endpunkts berechtigt ist.

    Um das Bearbeitungsfenster zu erreichen, in dem Sie eine Ressourcenrichtlinie eingeben können, müssen Sie eventuell in der linken Spalte des Fensters auf Resource Policy für die API klicken.

    • Regionaler Endpunkt:

      Fügen Sie die unten stehende Ressourcenrichtlinienvorlage in den Ressourcenrichtlinien-Editor ein, und ersetzen Sie dann die Platzhalter durch die entsprechenden Werte vom Arbeitsblatt, wie unten beschrieben.

      {
          "Version": "2012-10-17",
          "Statement":
          [
              {
              "Effect": "Allow",
              "Principal":
                  {
                  "AWS": "arn:aws:sts::<12-digit-number>:assumed-role/<external_function_role>/snowflake"
                  },
              "Action": "execute-api:Invoke",
              "Resource": "<method_request_ARN>"
              }
          ]
      }
      

      Ersetzen Sie die folgenden Teile der Ressourcenrichtlinie:

      • Ersetzen Sie die <12-stellige Zahl> durch die AWS-Konto-ID, die Sie auf dem Arbeitsblatt notiert haben.

      • Ersetzen Sie <Rolle_für_externe_Funktion> durch den Rollennamen aus dem Feld „New IAM Role Name“.

        Wenn Ihr AWS-Rollenname wie folgt ist:

        arn:aws:iam::987654321098:role/MyNewIAMRole
        

        dann sollte das Ergebnis wie folgt sein:

        "AWS": "arn:aws:sts::987654321098:assumed-role/MyNewIAMRole/snowflake"
        
      • Die „Resource“ muss für die POST-Methode der Ressource auf den Wert des Methodenanforderungs-ARN gesetzt werden.

        Bemerkung

        Durch Festlegen der Ressource auf den Methodenanforderungs-ARN wird angegeben, dass das API Gateway nur Aufrufe der angegebenen Ressource zulassen soll. Es ist möglich, eine Teilmenge des Methodenanforderungs-ARN als Präfix anzugeben, sodass mehrere Ressourcen desselben API-Gateway aufgerufen werden können.

        Wenn beispielsweise der Methodenanforderungs-ARN wie folgt lautet:

        arn:aws:execute-api:us-west-1:123456789012:a1b2c3d4e5/*/POST/MyResource
        

        dann können Sie nur das folgende Präfix angeben:

        arn:aws:execute-api:us-west-1:123456789012:a1b2c3d4e5/*/
        
    • Privater Endpunkt:

      Fügen Sie die unten stehende Ressourcenrichtlinienvorlage in den Ressourcenrichtlinien-Editor ein, und ersetzen Sie dann die Platzhalter durch die entsprechenden Werte vom Arbeitsblatt, wie unten beschrieben.

      {
          "Version": "2012-10-17",
          "Statement": [
              {
                  "Effect": "Allow",
                  "Principal": {
                      "AWS": "arn:aws:sts::<12-digit-number>:assumed-role/<external_function_role>/snowflake"
                  },
                  "Action": "execute-api:Invoke",
                  "Resource": "<method_request_ARN>",
                  "Condition": {
                      "StringEquals": {
                          "aws:sourceVpc": "<VPC_ID>"
                      }
                  }
              }
          ]
      }
      

      Ersetzen Sie die folgenden Teile der Ressourcenrichtlinie:

      • Ersetzen Sie die <12-stellige Nummer>, <Rolle_für_externe_Funktion> und <Methodenanforderung_ARN> wie oben für einen regionalen Endpunkt beschrieben.

      • Ersetzen Sie den Wert im Feld „<VPD_ID>“ durch die Snowflake-VPC-ID Ihrer Region, die im Feld „Snowflake VPC ID“ des Arbeitsblatts eingetragen sein sollte.

  6. Wenn Sie nicht bereits auf Save geklickt haben, um die Ressourcenrichtlinie zu speichern, tun Sie dies jetzt.

  7. Stellen Sie die aktualisierten API bereit.

In den nächsten Schritten erstellen Sie ein Snowflake-API-Integrationsobjekt. Schließen Sie jetzt nicht das AWS-Administrationsfenster. Sie müssen später zu diesem Fenster zurückkehren.

API-Integrationsobjekt in Snowflake erstellen

  1. Öffnen Sie (falls noch nicht geschehen) eine Snowflake-Sitzung, normalerweise eine Snowflake-Weboberflächensitzung.

  2. Verwenden Sie eine Snowflake-Rolle mit ACCOUNTADMIN-Berechtigungen oder mit der CREATE INTEGRATION-Berechtigung, zum Beispiel:

    use role has_accountadmin_privileges;
    
  3. Geben Sie den Befehl CREATE API INTEGRATION ein, um eine API-Integration zu erstellen. Der Befehl sollte ungefähr wie folgt aussehen:

    CREATE OR REPLACE API INTEGRATION my_api_integration_01
      api_provider = aws_api_gateway
      api_aws_role_arn = '<new_IAM_role_ARN>'
      api_allowed_prefixes = ('https://')
      enabled = true
    ;
    

    Passen Sie den Befehl an:

    • Wenn Sie einen privaten Endpunkt verwenden, sollte der „api_provider“ den Wert „aws_private_api_gateway“ sein. Andernfalls sollte „api_provider“ den Wert „aws_api_gateway“ haben.

    • Der <neue_IAM_Rollen_ARN> muss der Name sein, den Sie zuvor unter „New IAM Role ARN“ notiert haben.

    • Das Feld „api_allowed_prefixes“ sollte die Ressourcenaufruf-URL enthalten, die Sie zuvor notiert haben.

    • Möglicherweise möchten Sie auch den Namen der API-Integration anpassen, anstatt den Wert aus dem Beispiel zu verwenden.

    Im Folgenden finden Sie ein Beispiel für eine vollständige CREATE API INTEGRATION-Anweisung:

    create or replace api integration demonstration_external_api_integration_01
        api_provider=aws_api_gateway
        api_aws_role_arn='arn:aws:iam::123456789012:role/my_cloud_account_role'
        api_allowed_prefixes=('https://xyz.execute-api.us-west-2.amazonaws.com/production/')
        enabled=true;
    
  4. Führen Sie den oben eingegebenen CREATE API INTEGRATION-Befehl aus.

  5. Führen Sie den Befehl DESCRIBE INTEGRATION aus:

    DESCRIBE INTEGRATION <my_integration_name>;
    

    Beispiel:

    DESCRIBE INTEGRATION my_api_integration_01;
    
  6. Suchen Sie nach der Eigenschaft API_AWS_IAM_USER_ARN, und notieren Sie sich den „property_value“ der Eigenschaft auf dem Arbeitsblatt.

  7. Suchen Sie nach der Eigenschaft API_AWS_EXTERNAL_ID, und notieren Sie sich den Wert von „property_value“ dieser Eigenschaft auf dem Arbeitsblatt.

    Beachten Sie, dass der Eigenschaftswert von API_AWS_EXTERNAL_ID häufig mit einem Gleichheitszeichen („=“) endet. Das Gleichheitszeichen ist Teil des Wertes. Stellen Sie also sicher, dass Sie es zusammen mit dem Rest des „property_value“ ausschneiden und einfügen.

In den nächsten Schritten kehren Sie zum AWS-Verwaltungsfenster zurück. Schließen Sie jetzt nicht das Snowflake-Verwaltungsfenster. Sie müssen später zu diesem Fenster zurückkehren.

Vertrauensstellungen zwischen Snowflake und der neuen IAM-Rolle einrichten

In der AWS Management Console:

  1. Wählen Sie IAM aus.

  2. Wählen Sie Rollen aus.

  3. Suchen Sie nach dem neuen IAM-Rollennamen, den Sie zuvor erstellt und sich notiert haben, und wählen Sie diesen aus.

  4. Klicken Sie auf die Registerkarte „Trust relationships“ und dann auf die Schaltfläche Edit trust relationship.

    Dadurch wird das „Policy Document“ geöffnet, dem Sie Authentifizierungsinformationen hinzufügen können.

  5. Suchen Sie im Richtliniendokument das Feld „Statement.Principal.AWS“, und ersetzen Sie den Wert (nicht den Schlüssel) durch den zuvor gespeicherten Wert für API_AWS_IAM_USER_ARN.

  6. Suchen Sie das Feld „Statement.Condition“. Anfangs sollte dies nur geschweifte Klammern („{}“) enthalten.

  7. Fügen Sie Folgendes zwischen die geschweiften Klammern ein: "StringEquals": { "sts:ExternalId": "xxx" }.

  8. Ersetzen Sie „xxx“ durch den Wert von API_AWS_EXTERNAL_ID, den Sie zuvor aufgezeichnet haben.

  9. Nachdem Sie das „Policy Document“ für die Vertrauensstellung bearbeitet haben, sollte es wie folgt aussehen:

    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Principal": {
            "AWS": "arn:aws:iam::1234567898012:user/development/development_user"
          },
          "Action": "sts:AssumeRole",
          "Condition": {"StringEquals": { "sts:ExternalId": "EXTERNAL_FUNCTIONS_SFCRole=3_8Hcmbi9halFOkt+MdilPi7rdgOv=" }}
        }
      ]
    }
    
  10. Klicken Sie auf Update Trust Policy.

Schritt 3: Externe Funktion erstellen

Kehren Sie nun zu Ihrem Snowflake-Verwaltungsfenster zurück (in das Sie zuvor den Befehl CREATE API INTEGRATION eingegeben haben).

  1. Geben Sie den Befehl CREATE EXTERNAL FUNCTION ein: Dies sollte ungefähr wir folgt aussehen:

    CREATE EXTERNAL FUNCTION my_external_function(n INTEGER, v VARCHAR)
        RETURNS VARIANT
        API_INTEGRATION = <api_integration_name>
        AS '<resource_invocation_url>'
        ;
    

    Passen Sie den Befehl an:

    • Der Wert <api_integration_name> sollte den Namen der API-Integration enthalten, die Sie zuvor erstellt haben.

    • Der Wert für <resource_invocation_url> sollte die Ressourcenaufruf-URL sein, die Sie sich zuvor notiert haben. Stellen Sie sicher, dass diese URL nicht nur den Stagingbereichsnamen, sondern auch den API Gateway-Ressourcennamen enthält.

    • Möglicherweise möchten Sie auch den Funktionsnamen anpassen.

    In diesem Beispiel werden zwei Argumente übergeben (ein INTEGER und ein VARCHAR), da dies die Argumente sind, die die Lambda-Funktion erwartet. Wenn Sie Ihre eigene Lambda-Funktion erstellen, müssen Sie die entsprechenden Argumente für Ihre Lambda-Funktion übergeben.

  2. Wenn Sie den oben eingegebenen CREATE EXTERNAL FUNCTION-Befehl noch nicht ausgeführt haben, führen Sie ihn jetzt aus.

Schritt 4: Externe Funktion aufrufen

  1. Erteilen Sie gegebenenfalls einer oder mehreren Snowflake-Rollen die Berechtigung USAGE für die externe Funktion, damit diese Rollen die externe Funktion aufrufen können. (Eine Rolle muss über USAGE- oder OWNERSHIP-Berechtigung für diese externe Funktion verfügen.)

  2. Führen Sie Ihre Funktion aus, indem Sie Folgendes aufrufen:

    SELECT my_external_function(99, 'Luftballoons');
    

    Wenn Sie den Funktionsnamen im Befehl CREATE EXTERNAL FUNCTION angepasst haben, dann ersetzen Sie „my_external_function“ durch den angepassten Namen.

Zusätzliche Ressourcen für die Erstellung externer Funktionen auf AWS

Weitere Beispiele für Remotedienste, die auf Lambda-Funktionen basieren, finden Sie unter:

Problembehandlung

Siehe auch die allgemeinen Ausführungen unter Problembehandlung bei externen Funktionen.

Unable to read the requests body inside the Amazon AWS Lambda Function

Symptom:

Die Funktion ist nicht in der Lage, den in der HTTP-POST-Methode angegebenen Anforderungstext zu lesen.

Mögliche Ursachen:

Möglicherweise haben Sie die Lambda-Proxyintegration nicht aktiviert.

Mögliche Lösungen:

Aktivieren Sie die Lambda-Proxyintegration.

Weitere Informationen dazu finden Sie unter API im Amazon-API-Gateway erstellen und konfigurieren.

SQL execution error: Error assuming AWS_ROLE. Please verify the role and externalId are configured correctly in your AWS policy.

Symptom:

Beim Versuch, die externe Funktion aufzurufen, wird die folgende Fehlermeldung angezeigt:

SQL execution error: Error assuming AWS_ROLE. Please verify the role and externalId are configured correctly in your AWS policy.

Mögliche Ursachen:

  • In der AWS Trust Relationship Policy für Ihre Rolle ist ein falscher AWS-ARN angegeben. Mögliche Ursachen hierfür sind:

    • Sie haben keinen Wert angegeben.

    • Sie haben einen Wert angegeben, aber Sie haben anstelle des Benutzer-ARN den ARN der AWS-Rolle (falsch) verwendet, was Sie mit dem DESCRIBE INTEGRATION-Befehl in Snowflake prüfen können. Stellen Sie sicher, dass Sie API_AWS_IAM_USER_ARN anstelle von API_AWS_ROLE_ARN verwenden.

  • In Ihrer AWS Trust Relationship Policy ist ein falscher Wert für „std:ExternalId“ angegeben. Mögliche Ursachen hierfür sind:

    • Sie haben keinen Wert angegeben.

    • Sie haben das API-Integrationsobjekt neu erstellt. Durch das erneute Erstellen des API-Objekts wird die externe ID geändert.

Error: 403 '{"Message":"User: <ARN> is not authorized to perform: execute-api:Invoke on resource: <MethodRequestARN>"}'

Symptom:

Beim Versuch, die externe Funktion aufzurufen, wird die folgende Fehlermeldung angezeigt:

Request failed for external function <Funktionsname>. Error: 403 '{"Message":"User: <ARN> is not authorized to perform: execute-api:Invoke on resource: <MethodRequestARN>"}'

Mögliche Ursachen:

  • Die API Gateway-Ressourcenrichtlinie hat:

    • Den falschen IAM-Rollen-ARN.

    • Die falsch angenommene Rolle.

    • Den falschen Methodenanforderungs-ARN.

  • Der IAM-Rolle ist nicht die richtige Richtlinie zugeordnet.

Mögliche Lösungen:

  • Stellen Sie sicher, dass Sie die Ressourcenrichtlinienvorlage in Amazon API Gateway-Endpunkt sichern befolgt haben. Stellen Sie insbesondere sicher, dass für Ihre Ressourcenrichtlinie folgendes gilt:

    • Sie haben die <12-stellige Nummer> durch den Wert von „AWS Account ID“ auf dem Arbeitsplatz ersetzt.

    • Sie haben die <Rolle_für_externe_Funktion> durch „New IAM Role Name“ des Arbeitsblatts ersetzt.

    • Sie haben den method_request_ARN im Feld Resource durch den Methodenanforderungs-ARN ersetzt.

  • Wenn Sie sicherstellen müssen, dass der IAM-Rolle die korrekte Berechtigungsrichtlinie zugeordnet ist, können Sie die Liste der Berechtigungsrichtlinien der Rolle erhalten, indem Sie die folgenden Schritte ausführen:

    1. Wählen Sie in AWS die Rolle aus.

    2. Zeigen Sie die Summary für die Rolle an.

    3. Klicken Sie auf die Registerkarte Permissions.

    4. Überprüfen Sie, ob die gewünschte Richtlinie in der Liste Permissions policies enthalten ist.

Error: 403 '{"Message":"User: anonymous is not authorized to perform: execute-api:Invoke on resource: <MethodRequestARN>"}'

Symptom:

Beim Versuch, die externe Funktion aufzurufen, wird die folgende Fehlermeldung angezeigt:

Request failed for external function <Funktionsname>. Error: 403 '{"Message":"User: anonymous is not authorized to perform: execute-api:Invoke on resource: <MethodRequestARN>"}'

Mögliche Ursachen:

Eine mögliche Ursache ist, dass Sie bei der Konfiguration der Autorisierung für das API Gateway nicht angegeben haben, dass der Method Request eine AWS_IAM-Autorisierung für die Ressource benötigt.

Mögliche Lösungen:

Wenn Sie die Anweisungen zum Sichern des Amazon API Gateway nicht befolgt haben, dann befolgen Sie diese jetzt, um die AWS_IAM-Autorisierung anzugeben.

"Error parsing JSON response for external function ... Error: top-level JSON object must contain "data" JSON array element"

Mögliche Ursachen:

  • Möglicherweise haben Sie die Lambda-Proxyintegration für die API Gateway-Ressource nicht angegeben.

Mögliche Lösungen: