Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra. # Interrogation avec des fonctions définies par l’utilisateur Les fonctions définies par l'utilisateur (UDF) dans Amazon Athena vous permettent de créer des fonctions personnalisées pour traiter des registres ou des groupes de registres. Une UDF accepte les paramètres, effectue le travail, puis renvoie un résultat. Pour utiliser une UDF dans Athena, vous écrivez une clause `USING EXTERNAL FUNCTION` avant une instruction `SELECT` dans une requête SQL. L'instruction `SELECT` fait référence à l'UDF et définit les variables qui sont transmises à l'UDF lors de l'exécution de la requête. La requête SQL invoque une fonction Lambda à l'aide de l'environnement d'exécution Java lorsqu'elle appelle l'UDF. UDFssont définies dans la fonction Lambda en tant que méthodes dans un package de déploiement Java. Plusieurs UDFs peuvent être définis dans le même package de déploiement Java pour une fonction Lambda. Vous spécifiez également le nom de la fonction Lambda dans la clause `USING EXTERNAL FUNCTION`. Deux options s'offrent à vous pour déployer une fonction Lambda pour Athena. UDFs Vous pouvez déployer la fonction directement en utilisant Lambda, ou vous pouvez utiliser le AWS Serverless Application Repository. Pour trouver les fonctions Lambda existantes pour UDFs, vous pouvez effectuer une recherche dans le référentiel public AWS Serverless Application Repository ou privé, puis les déployer sur Lambda. Vous pouvez également créer ou modifier le code source Java, le packager dans un fichier JAR et le déployer à l'aide de Lambda ou du AWS Serverless Application Repository. Pour des exemples de code source Java et de packages pour vous aider à démarrer, voir [Création et déploiement d’une UDF à l’aide de Lambda](udf-creating-and-deploying.md). Pour plus d'informations sur Lambda, consultez le [Guide du développeur AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/). Pour plus d'informations à ce sujet AWS Serverless Application Repository, consultez le [guide du AWS Serverless Application Repository développeur](https://docs.aws.amazon.com/serverlessrepo/latest/devguide/). Pour un exemple d'utilisation de UDFs with Athena pour traduire et analyser du texte, consultez l'article du blog AWS Machine Learning [Translate and analysis text using SQL functions with Amazon Athena, Amazon Translate et Amazon Comprehend](https://aws.amazon.com/blogs/machine-learning/translate-and-analyze-text-using-sql-functions-with-amazon-athena-amazon-translate-and-amazon-comprehend/), ou regardez le. [video](udf-videos.md#udf-videos-xlate) *Pour un exemple d'utilisation UDFs pour étendre les requêtes géospatiales dans Amazon Athena, [consultez la section Étendre les requêtes géospatiales dans Amazon Athena UDFs avec AWS Lambda](https://aws.amazon.com/blogs/big-data/extend-geospatial-queries-in-amazon-athena-with-udfs-and-aws-lambda/) et dans le blog Big Data.AWS * **Topics** + [Vidéos sur UDFs In Athena](udf-videos.md) + [Considérations et restrictions](udf-considerations-limitations.md) + [Interrogation à l’aide de la syntaxe de requête UDF](udf-query-syntax.md) + [Création et déploiement d’une UDF à l’aide de Lambda](udf-creating-and-deploying.md) # Vidéos sur UDFs In Athena Regardez les vidéos suivantes pour en savoir plus sur l'utilisation UDFs dans Athena. **Vidéo : Présentation des fonctions définies par l'utilisateur (UDFs) dans Amazon Athena** La vidéo suivante montre comment utiliser UDFs Amazon Athena pour supprimer des informations sensibles. **Note** La syntaxe de cette vidéo est une version préliminaire, mais les concepts sont les mêmes. Utilisez Athena sans le groupe de travail `AmazonAthenaPreviewFunctionality`. [![AWS Videos](http://img.youtube.com/vi/https://www.youtube.com/embed/AxJ6jP4Pfmo/0.jpg)](http://www.youtube.com/watch?v=https://www.youtube.com/embed/AxJ6jP4Pfmo) **Vidéo : Traduction, analyse et rédaction de champs de texte à l'aide de requêtes SQL dans Amazon Athena** La vidéo suivante montre comment vous pouvez utiliser UDFs Amazon Athena avec d'autres outils Services AWS pour traduire et analyser du texte. **Note** La syntaxe de cette vidéo est une version préliminaire, mais les concepts sont les mêmes. Pour connaître la syntaxe correcte, consultez l'article de blog intitulé [Traduction, rédaction et analyse de texte à l'aide de fonctions SQL avec Amazon Athena, Amazon Translate et Amazon Comprehend](https://aws.amazon.com/blogs/machine-learning/translate-and-analyze-text-using-sql-functions-with-amazon-athena-amazon-translate-and-amazon-comprehend/) sur le blog *AWS Machine Learning*. [![AWS Videos](http://img.youtube.com/vi/https://www.youtube.com/embed/Od7rXG-WMO4/0.jpg)](http://www.youtube.com/watch?v=https://www.youtube.com/embed/Od7rXG-WMO4) # Considérations et restrictions Tenez compte des points suivants lorsque vous utilisez la fonction définie par l'utilisateur (UDFs) dans Athena. + **Fonctions Athena intégrées** – Les fonctions intégrées dans Athena sont conçues pour être très performantes. Nous vous recommandons d'utiliser les fonctions intégrées UDFs lorsque cela est possible. Pour de plus amples informations sur les fonctions intégrées, veuillez consulter [Fonctions dans Amazon Athena](functions.md). + **Scalaire UDFs uniquement** : Athena ne prend en charge que le UDFs scalaire, qui traite une ligne à la fois et renvoie une seule valeur de colonne. Athena transmet un lot de lignes, potentiellement en parallèle, à l'UDF chaque fois qu'il invoque Lambda. Lors de la conception UDFs et des requêtes, tenez compte de l'impact potentiel de ce traitement sur le trafic réseau. + **Les fonctions du gestionnaire de UDF utilisent un format abrégé** — Utilisez un format abrégé (pas le format complet), pour vos fonctions UDF (par exemple, `package.Class` et non de `package.Class::method`). + **Les méthodes UDF doivent être en minuscules** — Les méthodes UDF doivent être en minuscules ; la casse chameau n'est pas autorisée. + **Les méthodes UDF nécessitent des paramètres** – Les méthodes UDF doivent avoir au moins un paramètre d'entrée. Toute tentative d'appel d'un UDF défini sans paramètres d'entrée entraîne une exception d'exécution. UDFs sont destinés à exécuter des fonctions sur des enregistrements de données, mais un UDF sans arguments n'accepte aucune donnée, donc une exception se produit. + **Support d'exécution Java** — Athena prend actuellement en UDFs charge les environnements d'exécution Java 8, Java 11 et Java 17 pour Lambda. Pour plus d'informations, consultez la rubrique [Création de fonctions Lambda avec Java](https://docs.aws.amazon.com/lambda/latest/dg/lambda-java.html) du *Guide du développeur AWS Lambda *. **Note** Pour Java 17, vous devez définir la valeur de la variable d’environnement `JAVA_TOOL_OPTIONS` sur `--add-opens=java.base/java.nio=ALL-UNNAMED` dans votre Lambda. + **Autorisations IAM** – Pour exécuter et créer des instructions de requête UDF dans Athena, le principal IAM qui exécute la requête doit être autorisé à effectuer des actions en plus des fonctions Athena. Pour de plus amples informations, veuillez consulter [Autoriser l'accès à Athéna UDFs : exemples de politiques](udf-iam-access.md). + Quotas **Lambda : les quotas** Lambda s'appliquent à. UDFs Pour plus d’informations, consultez [Quotas Lambda](https://docs.aws.amazon.com/lambda/latest/dg/limits.html) dans le *Guide du développeur AWS Lambda *. + **Filtrage au niveau des lignes : le filtrage au niveau** des lignes de Lake Formation n'est pas pris en charge pour. UDFs + **Vues** : vous ne pouvez pas utiliser de vues avec UDFs. + **Problèmes connus** — Pour obtenir la up-to-date liste la plus complète des problèmes connus, voir [Limitations et problèmes](https://github.com/awslabs/aws-athena-query-federation/wiki/Limitations_And_Issues) dans la section awslabs/ aws-athena-query-federation de. GitHub # Interrogation à l’aide de la syntaxe de requête UDF La `USING EXTERNAL FUNCTION` clause spécifie un UDF ou un multiple UDFs qui peut être référencé par une `SELECT` instruction ultérieure dans la requête. Vous avez besoin du nom de la méthode de l'UDF et du nom de la fonction Lambda qui héberge l'UDF. À la place du nom de la fonction Lambda, vous pouvez utiliser l'ARN Lambda. Dans les scénarios entre comptes, l'ARN Lambda est requis. ## Résumé ``` USING EXTERNAL FUNCTION UDF_name(variable1 data_type[, variable2 data_type][,...]) RETURNS data_type LAMBDA 'lambda_function_name_or_ARN' [, EXTERNAL FUNCTION UDF_name2(variable1 data_type[, variable2 data_type][,...]) RETURNS data_type LAMBDA 'lambda_function_name_or_ARN'[,...]] SELECT [...] UDF_name(expression) [, UDF_name2(expression)] [...] ``` ## Parameters **UTILISATION D'UNE FONCTION EXTERNE *UDF\$1name* (*variable1**data\$1type*[, *variable2**data\$1type*] [,...])** *UDF\$1name*spécifie le nom de l'UDF, qui doit correspondre à une méthode Java au sein de la fonction Lambda référencée. Chacune *variable data\$1type* spécifie une variable nommée et le type de données correspondant que l'UDF accepte en entrée. *data\$1type*Il doit s'agir de l'un des types de données Athena pris en charge répertoriés dans le tableau suivant et correspondre au type de données Java correspondant. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/athena/latest/ug/udf-query-syntax.html) **RETOURS *data\$1type*** `data_type` spécifie le type de données SQL que l'UDF renvoie en sortie. Les types de données Athena répertoriés dans le tableau ci-dessus sont pris en charge. Pour le type de `DECIMAL` données, utilisez la syntaxe `RETURNS DECIMAL(precision, scale)` où *precision* et *scale* sont des entiers. **LAMBDA « » *lambda\$1function*** *lambda\$1function*spécifie le nom de la fonction Lambda à invoquer lors de l'exécution de l'UDF. **SÉLECTIONNEZ [...] *UDF\$1name*(*expression*) [...]** `SELECT`Requête qui transmet des valeurs à l'UDF et renvoie un résultat. *UDF\$1name*indique l'UDF à utiliser, suivi d'un *expression* UDF évalué pour transmettre des valeurs. Les valeurs transmises et renvoyées doivent correspondre aux types de données correspondants spécifiés pour l'UDF dans la clause `USING EXTERNAL FUNCTION`. ### Exemples Pour des exemples de requêtes basées sur le code [Athena UDFHandler .java activé](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-udfs/src/main/java/com/amazonaws/athena/connectors/udfs/AthenaUDFHandler.java) GitHub, consultez la page du connecteur GitHub [Amazon Athena UDF](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-udfs). # Création et déploiement d’une UDF à l’aide de Lambda Pour créer une UDF personnalisée, vous créez une nouvelle classe Java en étendant la classe `UserDefinedFunctionHandler`. Le code source du [UserDefinedFunctionHandlerfichier .java contenu](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-federation-sdk/src/main/java/com/amazonaws/athena/connector/lambda/handlers/UserDefinedFunctionHandler.java) dans le SDK est disponible GitHub dans le [référentiel awslabs/aws-athena-query-federation/athena](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-federation-sdk) -federation-sdk, ainsi que des [exemples d'implémentations UDF](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-udfs) que vous pouvez examiner et modifier pour créer un UDF personnalisé. Les étapes de cette section illustrent l'écriture et la création d'un fichier Jar UDF personnalisé à l'aide d' [Apache Maven](https://maven.apache.org/index.html) à partir de la ligne de commande, ainsi qu'un déploiement. Exécutez les étapes suivantes pour créer une UDF personnalisée pour Athena à l’aide de Maven : 1. [Cloner le kit SDK et préparer votre environnement de développement](#udf-create-install-sdk-prep-environment) 1. [Créez votre projet Maven](#create-maven-project) 1. [Ajouter des dépendances et des plugins à votre projet Maven](#udf-add-maven-dependencies) 1. [Écrivez du code Java pour UDFs](#udf-write-java) 1. [Construire le fichier JAR](#udf-create-package-jar) 1. [Déployez le fichier JAR sur AWS Lambda](#udf-create-deploy) ## Cloner le kit SDK et préparer votre environnement de développement Avant de commencer, assurez-vous que git est installé sur votre système en utilisant `sudo yum install git -y`. **Pour installer le SDK de fédération de AWS requêtes** + Saisissez ce qui suit sur la ligne de commande pour cloner le référentiel SDK. Ce référentiel inclut le kit SDK, des exemples et une suite de connecteurs de source de données. Pour de plus amples informations sur les connecteurs de source de données, veuillez consulter [Utilisation de la requête fédérée Amazon Athena](federated-queries.md). ``` git clone https://github.com/awslabs/aws-athena-query-federation.git ``` **Pour installer les éléments requis pour cette procédure** Si vous travaillez sur une machine de développement sur laquelle Apache Maven, le AWS CLI, et l'outil de AWS Serverless Application Model compilation sont déjà installés, vous pouvez ignorer cette étape. 1. À partir de la racine du répertoire `aws-athena-query-federation` que vous avez créé lors du clonage, exécutez le script [prepare\$1dev\$1env.sh](https://github.com/awslabs/aws-athena-query-federation/blob/master/tools/prepare_dev_env.sh) qui prépare votre environnement de développement. 1. Mettez à jour votre shell pour obtenir les nouvelles variables créées par le processus d'installation ou redémarrez votre session de terminal. ``` source ~/.profile ``` **Important** Si vous ignorez cette étape, vous recevrez ultérieurement des erreurs indiquant que l'outil AWS CLI ou l'outil de AWS SAM génération ne sera pas en mesure de publier votre fonction Lambda. ## Créez votre projet Maven Exécutez la commande suivante pour créer votre projet Maven. Remplacez *groupId* par l'identifiant unique de votre organisation et remplacez *my-athena-udf* par le nom de votre application. Pour plus d'informations, voir [Comment créer mon premier projet Maven](https://maven.apache.org/guides/getting-started/index.html#How_do_I_make_my_first_Maven_project) ? dans la documentation d'Apache Maven. ``` mvn -B archetype:generate \ -DarchetypeGroupId=org.apache.maven.archetypes \ -DgroupId=groupId \ -DartifactId=my-athena-udfs ``` ## Ajouter des dépendances et des plugins à votre projet Maven Ajoutez les configurations suivantes au fichier `pom.xml` du projet Maven. Pour un exemple, consultez le fichier [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-udfs/pom.xml) dans GitHub. ``` 2022.47.1 com.amazonaws aws-athena-federation-sdk ${aws-athena-federation-sdk.version} org.apache.maven.plugins maven-shade-plugin 3.2.1 false *:* META-INF/*.SF META-INF/*.DSA META-INF/*.RSA package shade ``` ## Écrivez du code Java pour UDFs Créez une nouvelle classe en étendant le [UserDefinedFunctionHandlerfichier .java.](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-federation-sdk/src/main/java/com/amazonaws/athena/connector/lambda/handlers/UserDefinedFunctionHandler.java) Écrivez votre UDFs intérieur dans la classe. Dans l'exemple suivant, deux méthodes Java pour UDFs, `compress()` et`decompress()`, sont créées dans la classe`MyUserDefinedFunctions`. ``` *package *com.mycompany.athena.udfs; public class MyUserDefinedFunctions extends UserDefinedFunctionHandler { private static final String SOURCE_TYPE = "MyCompany"; public MyUserDefinedFunctions() { super(SOURCE_TYPE); } /** * Compresses a valid UTF-8 String using the zlib compression library. * Encodes bytes with Base64 encoding scheme. * * @param input the String to be compressed * @return the compressed String */ public String compress(String input) { byte[] inputBytes = input.getBytes(StandardCharsets.UTF_8); // create compressor Deflater compressor = new Deflater(); compressor.setInput(inputBytes); compressor.finish(); // compress bytes to output stream byte[] buffer = new byte[4096]; ByteArrayOutputStream byteArrayOutputStream = new ByteArrayOutputStream(inputBytes.length); while (!compressor.finished()) { int bytes = compressor.deflate(buffer); byteArrayOutputStream.write(buffer, 0, bytes); } try { byteArrayOutputStream.close(); } catch (IOException e) { throw new RuntimeException("Failed to close ByteArrayOutputStream", e); } // return encoded string byte[] compressedBytes = byteArrayOutputStream.toByteArray(); return Base64.getEncoder().encodeToString(compressedBytes); } /** * Decompresses a valid String that has been compressed using the zlib compression library. * Decodes bytes with Base64 decoding scheme. * * @param input the String to be decompressed * @return the decompressed String */ public String decompress(String input) { byte[] inputBytes = Base64.getDecoder().decode((input)); // create decompressor Inflater decompressor = new Inflater(); decompressor.setInput(inputBytes, 0, inputBytes.length); // decompress bytes to output stream byte[] buffer = new byte[4096]; ByteArrayOutputStream byteArrayOutputStream = new ByteArrayOutputStream(inputBytes.length); try { while (!decompressor.finished()) { int bytes = decompressor.inflate(buffer); if (bytes == 0 && decompressor.needsInput()) { throw new DataFormatException("Input is truncated"); } byteArrayOutputStream.write(buffer, 0, bytes); } } catch (DataFormatException e) { throw new RuntimeException("Failed to decompress string", e); } try { byteArrayOutputStream.close(); } catch (IOException e) { throw new RuntimeException("Failed to close ByteArrayOutputStream", e); } // return decoded string byte[] decompressedBytes = byteArrayOutputStream.toByteArray(); return new String(decompressedBytes, StandardCharsets.UTF_8); } } ``` ## Construire le fichier JAR Exécutez `mvn clean install` pour construire votre projet. Une fois la compilation réussie, un fichier JAR est créé dans le `target` dossier de votre projet nommé`artifactId-version.jar`, où *artifactId* est le nom que vous avez fourni dans le projet Maven, par exemple,`my-athena-udfs`. ## Déployez le fichier JAR sur AWS Lambda Vous avez deux options pour déployer votre code sur Lambda : + Déployer à l'aide de AWS Serverless Application Repository (recommandé) + Création d'une fonction Lambda à partir du fichier JAR ### Option 1 : Déployer sur AWS Serverless Application Repository Lorsque vous déployez votre fichier JAR sur le AWS Serverless Application Repository, vous créez un AWS SAM modèle de fichier YAML qui représente l'architecture de votre application. Vous spécifiez ensuite ce fichier YAML et un compartiment Simple Storage Service (Amazon S3) où les artefacts de votre application sont téléchargés et mis à disposition du AWS Serverless Application Repository. La procédure ci-dessous utilise le script [publish.sh](https://github.com/awslabs/aws-athena-query-federation/blob/master/tools/publish.sh) situé dans le répertoire `athena-query-federation/tools` du kit Athena Query Federation SDK que vous avez cloné précédemment. Pour plus d'informations et pour connaître les exigences, consultez [les sections Publication d'applications](https://docs.aws.amazon.com/serverlessrepo/latest/devguide/serverlessrepo-publishing-applications.html) dans le *Guide du AWS Serverless Application Repository développeur*, [concepts de AWS SAM modèles](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-template-basics.html) dans le *Guide du AWS Serverless Application Model développeur* et [Publication d'applications sans serveur à l'aide de la AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-template-publishing-applications.html). L'exemple suivant illustre les paramètres d'un fichier YAML. Ajoutez des paramètres similaires à votre fichier YAML et enregistrez-le dans votre répertoire de projet. Voir [athena-udf.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-udfs/athena-udfs.yaml) pour un exemple complet. GitHub ``` Transform: 'AWS::Serverless-2016-10-31' Metadata: 'AWS::ServerlessRepo::Application': Name: MyApplicationName Description: 'The description I write for my application' Author: 'Author Name' Labels: - athena-federation SemanticVersion: 1.0.0 Parameters: LambdaFunctionName: Description: 'The name of the Lambda function that will contain your UDFs.' Type: String LambdaTimeout: Description: 'Maximum Lambda invocation runtime in seconds. (min 1 - 900 max)' Default: 900 Type: Number LambdaMemory: Description: 'Lambda memory in MB (min 128 - 3008 max).' Default: 3008 Type: Number Resources: ConnectorConfig: Type: 'AWS::Serverless::Function' Properties: FunctionName: !Ref LambdaFunctionName Handler: "full.path.to.your.handler. For example, com.amazonaws.athena.connectors.udfs.MyUDFHandler" CodeUri: "Relative path to your JAR file. For example, ./target/athena-udfs-1.0.jar" Description: "My description of the UDFs that this Lambda function enables." Runtime: java8 Timeout: !Ref LambdaTimeout MemorySize: !Ref LambdaMemory ``` Copiez le script `publish.sh` dans le répertoire du projet dans lequel vous avez enregistré votre fichier YAML et exécutez la commande suivante : ``` ./publish.sh MyS3Location MyYamlFile ``` Par exemple, si l'emplacement de votre compartiment est `s3://amzn-s3-demo-bucket/mysarapps/athenaudf` et que votre fichier YAML a été enregistré sous la forme `my-athena-udfs.yaml` : ``` ./publish.sh amzn-s3-demo-bucket/mysarapps/athenaudf my-athena-udfs ``` **Pour créer une fonction Lambda** 1. Ouvrez la console Lambda à l'adresse [https://console.aws.amazon.com/lambda/](https://console.aws.amazon.com/lambda/), choisissez **Create function**, puis choisissez **Parcourir le référentiel d'applications sans serveur** 1. Choisissez **Private applications** (Applications privées), recherchez votre application dans la liste ou recherchez-la en utilisant des mots clés, puis sélectionnez-la. 1. Vérifiez et fournissez les détails de l'application, puis choisissez **Déployer**. Vous pouvez désormais utiliser les noms de méthodes définis dans le fichier JAR de votre fonction Lambda comme dans UDFs Athena. ### Option 2 : Création directe d’une fonction Lambda Vous pouvez également créer une fonction Lambda directement à l'aide de la console ou. AWS CLI L'exemple suivant illustre l'utilisation de la commande CLI `create-function` Lambda. ``` aws lambda create-function \ --function-name MyLambdaFunctionName \ --runtime java8 \ --role arn:aws:iam::1234567890123:role/my_lambda_role \ --handler com.mycompany.athena.udfs.MyUserDefinedFunctions \ --timeout 900 \ --zip-file fileb://./target/my-athena-udfs-1.0-SNAPSHOT.jar ```