Skalares Lambda UDFs

PDFRSS

Amazon Redshift kann benutzerdefinierte Funktionen verwenden, die AWS Lambda als Teil von SQL-Abfragen definiert sind. Sie können skalares Lambda UDFs in allen von Lambda unterstützten Programmiersprachen wie Java, Go, Node.js, C# PowerShell, Python und Ruby schreiben. Sie können auch eine benutzerdefinierte Laufzeit verwenden.

Der Befehl CREATE EXTERNAL FUNCTION erstellt die folgenden Parameter:

• (Optional) Eine Liste von Argumenten mit Datentyp.

• Ein Rückgabedatentyp

• Ein Funktionsname der externen Funktion, die von Amazon Redshift aufgerufen wird.

• Eine IAM-Rolle, die der Amazon-Redshift-Cluster übernehmen und Lambda aufrufen darf.

• Ein Lambda-Funktionsname, den die Lambda-UDF aufruft.

Weitere Hinweise zu CREATE EXTERNAL FUNCTION finden Sie unter CREATE EXTERNAL FUNCTION.

Ein- und Rückgabedaten für diese Funktion können jeden standardmäßigen Amazon-Redshift-Datentyp verwenden.

Amazon Redshift stellt sicher, dass die externe Funktion Batch-Argumente und -Ergebnisse senden und empfangen kann.

Lambda UDFs wird in Lambda definiert und verwaltet, und Sie können die Zugriffsrechte steuern, um diese UDFs in Amazon Redshift aufzurufen. Sie können mehrere Lambda-Funktionen in derselben Abfrage aufrufen oder die gleiche Funktion mehrmals aufrufen.

Verwenden Sie Lambda UDFs in allen Klauseln der SQL-Anweisungen, in denen Skalarfunktionen unterstützt werden. Sie können Lambda auch UDFs in jeder SQL-Anweisung wie SELECT, UPDATE, INSERT oder DELETE verwenden.

Anmerkung

Für die Nutzung von Lambda UDFs können zusätzliche Gebühren durch den Lambda-Service anfallen. Ob dies geschieht, hängt von Faktoren wie der Anzahl der Lambda-Anforderungen (UDF-Aufrufe) und der Gesamtdauer der Lambda-Programmausführung ab. Für die Verwendung von Lambda UDFs in Amazon Redshift fallen jedoch keine zusätzlichen Gebühren an. Informationen zu den AWS Lambda-Preisen finden Sie unter AWS Lambda Preise.

Die Anzahl der Lambda-Anforderungen hängt von der spezifischen SQL-Anweisungsklausel ab, in der die Lambda-UDF verwendet wird. Angenommen, die Funktion wird in einer WHERE-Klausel wie der folgenden verwendet.

SELECT a, b FROM t1 WHERE lambda_multiply(a, b) = 64; SELECT a, b FROM t1 WHERE a*b = lambda_multiply(2, 32)

In diesem Fall ruft Amazon Redshift die erste SELECT-Anweisung für jede und ruft die zweite SELECT-Anweisung nur einmal auf.

Wenn Sie jedoch ein UDF im Projektionsteil der Abfrage verwenden, wird die Lambda-Funktion möglicherweise nur einmal für jede qualifizierte oder aggregierte Zeile in der Ergebnismenge aufgerufen.

UDF-Sicherheit und Berechtigungen

Um eine Lambda-UDF zu erstellen, stellen Sie sicher, dass Sie über Berechtigungen für die Verwendung auf LANGUAGE EXFUNC verfügen. Sie müssen USAGE ON LANGUAGE EXFUNC explizit gewähren oder USAGE ON LANGUAGE EXFUNC für bestimmte Benutzer, Gruppen oder öffentliche Benutzer widerrufen.

Im folgenden Beispiel wird PUBLIC die Verwendung auf EXFUNC gewährt.

grant usage on language exfunc to PUBLIC; 

Im folgenden Beispiel wird die Verwendung auf exfunc von PUBLIC widerrufen. Anschließend wird die Nutzung der Benutzergruppe lambda_udf_devs erlaubt.

revoke usage on language exfunc from PUBLIC;
grant usage on language exfunc to group lambda_udf_devs;

Stellen Sie zum Ausführen einer Lambda-UDF sicher, dass Sie die Berechtigung für jede aufgerufene Funktion haben. Standardmäßig wird PUBLIC die Erlaubnis erteilt, neues Lambda UDFs auszuführen. Um die Nutzung einzuschränken, widerrufen Sie diese Berechtigung für die Funktion von PUBLIC. Gewähren Sie die Berechtigung anschließend den spezifischen Benutzern oder Gruppen.

Beim folgenden Beispiel wird die Ausführung der Funktion exfunc_sum durch Benutzer mit Berechtigungen der Gruppe PUBLIC untersagt. Daraufhin wird die Nutzung der Benutzergruppe lambda_udf_devs erlaubt.

revoke execute on function exfunc_sum(int, int) from PUBLIC;
grant execute on function exfunc_sum(int, int) to group lambda_udf_devs;

Superuser haben standardmäßig alle Berechtigungen.

Weitere Informationen zum Erteilen und Widerrufen von Berechtigungen finden Sie unter GRANT und REVOKE.

Konfiguration des Autorisierungsparameters für Lambda UDFs

Der Befehl CREATE EXTERNAL FUNCTION erfordert die Autorisierung, Lambda-Funktionen in AWS Lambda aufzurufen. Um die Autorisierung zu starten, geben Sie eine AWS Identity and Access Management (IAM-) Rolle an, wenn Sie den Befehl CREATE EXTERNAL FUNCTION ausführen. Weitere Informationen zu IAM-Rollen finden Sie unter IAM-Rollen im IAM-Benutzerhandbuch.

Wenn bereits eine IAM-Rolle mit Berechtigungen zum Aufrufen von Lambda-Funktionen vorhanden ist, können Sie den Befehl durch Ihre Rolle Amazon-Ressourcenname (ARN) im Parameter IAM_ROLE ersetzen. Die folgenden Abschnitte beschreiben die Schritte zur Verwendung einer IAM-Rolle im Befehl CREATE EXTERNAL FUNCTION.

Erstellen einer IAM-Rolle für Lambda

Die IAM-Rolle erfordert die Berechtigung zum Aufrufen von Lambda-Funktionen. Geben Sie beim Erstellen der IAM-Rolle die Berechtigung auf eine der folgenden Arten an:

• Fügen Sie die AWSLambdaRole-Richtlinie auf der Seite Berechtigungsrichtlinie anfügen an, während Sie eine IAM-Rolle erstellen. DieAWSLambdaRole-Richtlinie erteilt Berechtigungen zum Aufrufen von Lambda-Funktionen, was die minimale Anforderung ist. Weitere Informationen und andere Richtlinien finden Sie unter Identitätsbasierte IAM-Richtlinien für AWS Lambda im AWS Lambda -Entwicklerhandbuch.

• Erstellen Sie Ihre eigene benutzerdefinierte Richtlinie, die Sie Ihrer IAM-Rolle mit der lambda:InvokeFunction-Berechtigung entweder für alle Ressourcen oder eine bestimmten Lambda-Funktion mit dem ARN dieser Funktion anfügen. Weitere Informationen zum Erstellen von Richtlinien finden Sie unter Erstellen von IAM-Richtlinien im IAM-Benutzerhandbuch.

  Die folgende Beispielrichtlinie ermöglicht das Aufrufen von Lambda für eine bestimmte Lambda-Funktion.

  {
      "Version": "2012-10-17",
      "Statement": [
          {
              "Sid": "Invoke",
              "Effect": "Allow",
              "Action": [
                  "lambda:InvokeFunction"
              ],
              "Resource": "arn:aws:lambda:us-west-2:123456789012:function:my-function"
          }
      ]
  }

  Weitere Informationen zu Ressourcen für Lambda Funktionen finden Sie unter Ressourcen und Bedingungen für Lambda-Aktionen in der IAM-API-Referenz.

  Nachdem Sie Ihre benutzerdefinierte Richtlinie mit den erforderlichen Berechtigungen erstellt haben, können Sie Ihre Richtlinie der IAM-Rolle auf der Registerkarte Berechtigungsrichtlinie anfügen anfügen, während Sie eine IAM-Rolle erstellen.

Schritte zum Erstellen einer IAM-Rolle finden Sie unter Autorisieren von Amazon Redshift für den Zugriff auf andere AWS Services in Ihrem Namen im Amazon Redshift Management Guide.

Wenn Sie keine neue IAM-Rolle erstellen möchten, können Sie die zuvor genannten Berechtigungen zu Ihrer vorhandenen IAM-Rolle hinzufügen.

Zuweisen einer IAM-Rolle zum Cluster

Fügen Sie die IAM-Rolle an Ihren Cluster an. Sie können über die Amazon-Redshift-Managementkonsole, die CLI oder eine API einem Cluster eine Rolle hinzufügen oder die Rollen anzeigen, die mit einem Cluster verknüpft sind. Weitere Informationen finden Sie unter Verknüpfen einer IAM-Rolle mit einem Cluster im Amazon-Redshift-Verwaltungshandbuch.

Einschließen der IAM-Rolle in den Befehl

Schließen Sie die IAM-Rolle ARN in den Befehl CREATE EXTERNAL FUNCTION ein. Beim Erstellen einer IAM-Rolle gibt IAM einen Amazon-Ressourcennamen (ARN) für die Rolle zurück. Um eine IAM-Rolle anzugeben, geben Sie für den ARN der Rolle den Parameter IAM_ROLE an. Im Folgenden wird die Syntax für den Parameter IAM_ROLE gezeigt.

IAM_ROLE 'arn:aws:iam::aws-account-id:role/role-name'

Informationen zum Aufrufen von Lambda-Funktionen, die sich in anderen Konten innerhalb derselben Region befinden, finden Sie unter Verketten von IAM-Rollen in Amazon Redshift.

Verwenden der JSON-Schnittstelle zwischen Amazon Redshift und AWS Lambda

Amazon Redshift verwendet eine gemeinsame Schnittstelle für alle Lambda-Funktionen, mit denen Amazon Redshift kommuniziert.

Die folgende Tabelle zeigt die Liste der Eingabefelder, die die designierten Lambda-Funktionen für die JSON-Payload erwarten können.

Feldname	Beschreibung	Wertebereich
request_id	Eine UUID (Universally Unique Identifier), die jede Aufrufanforderung eindeutig identifiziert.	Eine gültige UUID.
Cluster	Der vollständige Amazon-Ressourcenname (ARN) des Clusters.	Ein gültiger Cluster-ARN.
user	Der Name des Benutzers, der den Aufruf ausführt.	Ein gültiger Benutzername.
Datenbank	Der Name der -Datenbank, auf der die Abfrage ausgeführt wird.	Ein gültiger Datenbankname.
external_function	Der vollqualifizierte Name der externen Funktion, die den Aufruf ausführt.	Ein gültiger vollqualifizierter Funktionsname.
query_id	Die Abfrage-ID der Abfrage, die den Aufruf ausführt.	Eine gültige Abfrage-ID.
num_records	Die Anzahl der Argumente in der Nutzlast.	Ein Wert von 1 - 2^64.
arguments	Die Datennutzlast im angegebenen Format.	Die Daten im Array-Format müssen ein JSON-Array sein. Jedes Element ist ein Datensatz, der ein Array ist, wenn die Anzahl der Argumente größer als 1 ist. Durch die Verwendung eines Arrays behält Amazon Redshift die Reihenfolge der Datensätze in der Nutzlast bei.

Die Reihenfolge des JSON-Arrays bestimmt die Reihenfolge der Batch-Verarbeitung. Die Lambda Funktion muss die Argumente iterativ wiederholen und die genaue Anzahl von Datensätzen erzeugen. Im Folgenden sehen Sie ein Beispiel für eine Nutzlast.

{
  "request_id" : "23FF1F97-F28A-44AA-AB67-266ED976BF40",
  "cluster" : "arn:aws:redshift:xxxx",
  "user" : "adminuser",
  "database" : "db1",
  "external_function": "public.foo",
  "query_id" : 5678234,
  "num_records" : 4,
  "arguments" : [
     [ 1, 2 ],
     [ 3, null],
     null,
     [ 4, 6]
   ]
 }

Die Ausgabe der Lambda-Funktion sollte folgende Felder umfassen.

Feldname	Beschreibung	Wertebereich
Erfolg	Der Hinweis auf Erfolg oder Fehlschlag der Funktion.	Ein Wert von "true" oder "false".
error_msg	Die Fehlermeldung, wenn der Erfolgswert "false" ist (wenn die Funktion fehlschlägt); andernfalls wird dieses Feld ignoriert.	Eine gültige Nachricht.
num_records	Die Anzahl der Datensätze in der Nutzlast.	Ein Wert von 1 - 2^64.
results	Die Ergebnisse des Aufrufs im angegebenen Format.	N/A

Im Folgenden sehen Sie ein Beispiel für die Ausgabe der Lambda-Funktion.

{
  "success": true,   // true indicates the call succeeded
  "error_msg" : "my function isn't working",  // shall only exist when success != true
  "num_records": 4,      // number of records in this payload
  "results" : [
     1,
     4,
     null,
     7
   ]
}

Wenn Sie Lambda-Funktionen aus SQL-Abfragen aufrufen, stellt Amazon Redshift die Sicherheit der Verbindung mit den folgenden Überlegungen sicher:

• GRANT- und REVOKE-Berechtigungen. Weitere Informationen zur UDF-Sicherheit und zu Berechtigungen finden Sie unter. UDF-Sicherheit und Berechtigungen

• Amazon Redshift sendet nur den Mindestdatensatz an die dafür vorgesehene Lambda-Funktion.

• Amazon Redshift ruft nur die designierte Lambda-Funktion mit der angegebenen IAM-Rolle auf.