Création d'une fonction scalaire Lambda définie par l'utilisateur

Amazon Redshift peut utiliser des fonctions personnalisées définies dans le AWS Lambda cadre de requêtes SQL. Vous pouvez écrire des UDF Lambda scalaires dans tous les langages de programmation pris en charge par Lambda, tels que Java, Go, Node.js, C# PowerShell, Python et Ruby. Vous pouvez également utiliser une exécution personnalisée.

Les fonctions UDF Lambda sont définies et gérées dans Lambda, et vous pouvez contrôler les privilèges d'accès pour invoquer ces fonctions UDF dans Amazon Redshift. Vous pouvez invoquer plusieurs fonctions Lambda dans la même requête ou invoquer la même fonction plusieurs fois.

Utilisez les Lambda UDF dans toutes les clauses des instructions SQL où les fonctions scalaires sont prises en charge. Vous pouvez également utiliser les fonctions UDF Lambda dans n'importe quelle instruction SQL telle que SELECT, UPDATE, INSERT ou DELETE.

Note

L'utilisation des UDF Lambda peut entraîner des frais supplémentaires de la part du service Lambda. Cela dépend de facteurs tels que le nombre de requêtes Lambda (invocations UDF) et la durée totale de l'exécution du programme Lambda. Cependant, il n'y a pas de frais supplémentaires pour l'utilisation des fonctions UDF Lambda dans Amazon Redshift. Pour plus d'informations sur la tarification AWS Lambda, consultez AWS Lambda la section Tarification.

Le nombre de requêtes Lambda varie en fonction de la clause d'instruction SQL spécifique dans laquelle la fonction UDF Lambda est utilisée. Par exemple, supposons que la fonction soit utilisée dans une clause WHERE telle que la suivante.

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

Dans ce cas, Amazon Redshift appelle la première instruction SELECT pour chaque ligne et n'appelle la seconde instruction SELECT qu'une seule fois.

Toutefois, l'utilisation d'une fonction UDF dans la partie projection de la requête peut n'invoquer la fonction Lambda qu'une seule fois pour chaque ligne qualifiée ou agrégée de l'ensemble de résultats.

Enregistrement d'une fonction UDF Lambda

La commande CREATE EXTERNAL FUNCTION crée les paramètres suivants :

• (Facultatif) Une liste d'arguments avec le type de données.

• Un type de données de retour.

• Un nom pour la fonction externe appelée par Amazon Redshift.

• Un rôle IAM que le cluster Amazon Redshift est autorisé à assumer pour effectuer un appel à Lambda.

• Un nom de fonction Lambda que la fonction UDF Lambda invoque.

Pour plus d'informations sur l'instruction CREATE EXTERNAL FUNCTION, consultez CREATE EXTERNAL FUNCTION.

Les types de données d'entrée et de retour pour cette fonction peuvent être de n'importe quel type de données Amazon Redshift standard.

Amazon Redshift garantit que la fonction externe peut envoyer et recevoir des arguments et des résultats par lots.

Gestion de la sécurité et des privilèges pour les fonctions UDF Lambda

Pour créer une fonction UDF Lambda, assurez-vous de disposer d'autorisations d'utilisation sur LANGUAGE EXFUNC. Vous devez accorder explicitement le privilège USAGE ON LANGUAGE EXFUNC, ou le révoquer, à des utilisateurs, des groupes ou des publics spécifiques.

L'exemple suivant accorde l'utilisation sur EXFUNC à PUBLIC.

grant usage on language exfunc to PUBLIC; 

L'exemple suivant révoque le privilège USAGE pour exfunc de PUBLIC, puis accorde USAGE au groupe d'utilisateurs lambda_udf_devs.

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

Pour exécuter une fonction UDF Lambda, assurez-vous que vous avez l'autorisation pour chaque fonction appelée. Par défaut, l'autorisation d'exécution pour les nouvelles fonctions UDF Lambda est accordée à PUBLIC. Pour limiter l'utilisation, révoquez cette autorisation de PUBLIC pour la fonction. Ensuite, accordez le privilège à des utilisateurs ou à des groupes spécifiques.

L'exemple suivant révoque le privilège d'exécution de la fonction exfunc_sum de PUBLIC. Ensuite, il accorde le privilège USAGE au groupe d'utilisateurs lambda_udf_devs.

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

Les super-utilisateurs ont tous les privilèges par défaut.

Pour plus d'informations sur l'octroi et la révocation des privilèges, consultez GRANT et REVOKE.

Configuration du paramètre d'autorisation pour les fonctions UDF Lambda

L'instruction CREATE EXTERNAL FUNCTION nécessite une autorisation pour invoquer les fonctions Lambda dans AWS Lambda. Pour démarrer l'autorisation, spécifiez un rôle AWS Identity and Access Management (IAM) lorsque vous exécutez la commande CREATE EXTERNAL FUNCTION. Pour plus d’informations sur les rôles IAM, consultez Rôles IAM dans le manuel IAM Guide de l’utilisateur.

S'il existe un rôle IAM disposant des autorisations nécessaires pour invoquer les fonctions Lambda attachées à votre cluster, vous pouvez utiliser votre rôle Amazon Resource Name (ARN) dans le paramètre IAM_ROLE de l'instruction. Les sections suivantes décrivent les étapes à suivre pour utiliser un rôle IAM dans l'instruction CREATE EXTERNAL FUNCTION.

Création d'un rôle IAM pour Lambda

Le rôle IAM nécessite une autorisation pour invoquer des fonctions Lambda. Lorsque vous créez le rôle IAM, fournissez l'autorisation de l'une des manières suivantes :

• Attacher la politique AWSLambdaRole sur la page Attach permission policy (Attacher une politique d'autorisations) lorsque vous créez un rôle IAM. La politique AWSLambdaRole accorde des autorisations pour invoquer des fonctions Lambda, ce qui est la condition minimale. Pour plus d'informations et pour connaître les autres politiques, consultez la rubrique Stratégies IAM basées sur l'identité pour AWS Lambda dans le Manuel du développeur AWS Lambda .

• Créez votre propre politique personnalisée à joindre à votre rôle IAM avec l'autorisation lambda:InvokeFunction de toutes les ressources ou d'une fonction Lambda particulière avec l'ARN de cette fonction. Pour plus d'informations sur la création de politiques IAM, consultez la section Création de stratégies dans le Guide de l'utilisateur IAM.

  L'exemple de politique suivant permet d'invoquer Lambda sur une fonction Lambda particulière.

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

  Pour plus d'informations sur les ressources pour les fonctions Lambda, consultez la rubrique Ressources et conditions pour les actions Lambda dans la Référence API IAM.

  Après avoir créé votre politique personnalisée avec les autorisations requises, vous pouvez l'attacher au rôle IAM sur la page Attacher une politique d'autorisations lorsque vous créez un rôle IAM.

Pour savoir comment créer un rôle IAM, consultez la section Autoriser Amazon Redshift à accéder à AWS d'autres services en votre nom dans le guide de gestion Amazon Redshift.

Si vous ne souhaitez pas créer un nouveau rôle IAM, vous pouvez ajouter les autorisations mentionnées précédemment à votre rôle IAM existant.

Association d'un rôle IAM au cluster

Attachez le rôle IAM à votre cluster. Vous pouvez ajouter un rôle à un cluster ou afficher les rôles associés à un cluster à l’aide de la console de gestion, de la CLI ou de l’API Amazon Redshift. Pour plus d'informations, consultez la rubrique Associer un rôle IAM à un cluster dans le Guide de gestion Amazon Redshift.

Inclusion du rôle IAM dans l'instruction

Incluez le rôle IAM ARN dans l'instruction CREATE EXTERNAL FUNCTION. Lorsque vous créez un rôle IAM, IAM renvoie un Amazon Resource Name (ARN) pour le rôle. Pour spécifier un rôle IAM, indiquez l'ARN de rôle avec le paramètre IAM_ROLE. L'exemple suivant montre la syntaxe du paramètre IAM_ROLE.

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

Pour invoquer des fonctions Lambda qui résident dans d'autres comptes au sein de la même région, consultez Chaîner les rôles IAM dans Amazon Redshift.

Utilisation de l'interface JSON entre Amazon Redshift et AWS Lambda

Amazon Redshift utilise une interface commune pour toutes les fonctions Lambda avec lesquelles Amazon Redshift communique.

Le tableau suivant présente la liste des champs d'entrée des fonctions Lambda désignées auxquels vous pouvez vous attendre pour la charge utile JSON.

Nom de champ	Description	Plage de valeurs
request_id	Identifiant universel unique (UUID) qui identifie de manière unique chaque requête d'invocation.	Un UUID valide.
cluster	Amazon Resource Name (ARN) complet du cluster.	Un ARN de cluster valide.
utilisateur	Nom de l'utilisateur qui effectue l'appel.	Un nom d'utilisateur valide.
database	Nom de la base de données sur laquelle la requête est exécutée.	Un nom de base de données valide.
external_function	Nom entièrement qualifié de la fonction externe qui effectue l'appel.	Un nom de fonction complet valide.
query_id	ID de la requête qui effectue l'appel.	Un ID de requête valide.
num_records	Nombre d'arguments dans la charge utile.	Une valeur de 1 à 2^64.
arguments	Charge utile de données dans le format spécifié.	Les données au format tableau doivent être un tableau JSON. Chaque élément est un enregistrement qui est un tableau si le nombre d'arguments est supérieur à 1. En utilisant un tableau, Amazon Redshift préserve l'ordre des enregistrements dans la charge utile.

L'ordre du tableau JSON détermine l'ordre du traitement par lots. La fonction Lambda doit traiter les arguments de manière itérative et produire le nombre exact d'enregistrements. Voici un exemple de charge utile.

{
  "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]
   ]
 }

La sortie de retour de la fonction Lambda contient les champs suivants.

Nom de champ	Description	Plage de valeurs
success	Indication du succès ou de l'échec de la fonction.	Une valeur de "true" ou "false".
error_msg	Message d'erreur si la valeur de succès est "false" (si la fonction échoue) ; sinon, ce champ est ignoré.	Un message valide.
num_records	Nombre d'enregistrements dans la charge utile.	Une valeur de 1 à 2^64.
results	Résultats de l'appel dans le format spécifié.	N/A

Voici un exemple de sortie de fonction Lambda.

{
  "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
   ]
}

Lorsque vous appelez des fonctions Lambda à partir de requêtes SQL, Amazon Redshift assure la sécurité de la connexion avec les considérations suivantes :

• Privilèges GRANT et REVOKE. Pour plus d'informations sur la sécurité et les privilèges des fonctions UDF, consultez Privilèges et sécurité des fonctions UDF.

• Amazon Redshift soumet uniquement le jeu minimal de données à la fonction Lambda désignée.

• Amazon Redshift appelle uniquement la fonction Lambda désignée avec le rôle IAM désigné.