Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà. # Eseguire query con funzioni definite dall’utente Funzioni definite dall'utente (FDU) in Amazon Athena consentono di creare funzioni personalizzate per elaborare registri o gruppi di registri. Una funzione definita dall'utente accetta parametri, esegue il lavoro e quindi restituisce un risultato. Per utilizzare una funzione definita dall'utente in Athena, scrivi una clausola `USING EXTERNAL FUNCTION` prima di un'istruzione `SELECT` in una query SQL. L'istruzione `SELECT` fa riferimento alla funzione definita dall'utente e definisce le variabili che vengono passate alla funzione definita dall'utente quando viene eseguita la query. La query SQL richiama una funzione Lambda utilizzando il runtime Java quando chiama l'UDF. UDFssono definiti all'interno della funzione Lambda come metodi in un pacchetto di distribuzione Java. UDFsÈ possibile definirne più di uno nello stesso pacchetto di distribuzione Java per una funzione Lambda. Puoi anche specificare il nome della funzione Lambda nella clausola `USING EXTERNAL FUNCTION`. Sono disponibili due opzioni per distribuire una funzione Lambda per Athena. UDFs Puoi distribuire la funzione direttamente utilizzando Lambda oppure puoi utilizzare AWS Serverless Application Repository. Per trovare le funzioni Lambda esistenti per UDFs, puoi cercare nell'archivio pubblico AWS Serverless Application Repository o privato e poi distribuirle su Lambda. Puoi inoltre creare o modificare il codice sorgente Java, creare un pacchetto in un file JAR e distribuirlo utilizzando Lambda o il AWS Serverless Application Repository. Per esempi di codice origine e pacchetti Java con cui iniziare, consulta [Creare e distribuiredi una UDF utilizzando Lambda](udf-creating-and-deploying.md). Per ulteriori informazioni su Lambda, consulta la [Guida per gli sviluppatori di AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/). [Per ulteriori informazioni in merito AWS Serverless Application Repository, consulta la Guida per gli sviluppatori.AWS Serverless Application Repository](https://docs.aws.amazon.com/serverlessrepo/latest/devguide/) Per un esempio che utilizza UDFs Athena per tradurre e analizzare il testo, consulta l'articolo del AWS Machine Learning Blog [Tradurre e analizzare il testo utilizzando le funzioni SQL con Amazon Athena, Amazon Translate e Amazon Comprehend oppure](https://aws.amazon.com/blogs/machine-learning/translate-and-analyze-text-using-sql-functions-with-amazon-athena-amazon-translate-and-amazon-comprehend/) guarda il. [video](udf-videos.md#udf-videos-xlate) *Per un esempio di utilizzo UDFs per estendere le query geospaziali in Amazon Athena, consulta Estendere le [query geospaziali in Amazon Athena con e nel Big Data Blog](https://aws.amazon.com/blogs/big-data/extend-geospatial-queries-in-amazon-athena-with-udfs-and-aws-lambda/). UDFs AWS LambdaAWS * **Topics** + [Video su UDFs In Athena](udf-videos.md) + [Considerazioni e limitazioni](udf-considerations-limitations.md) + [Eseguire query utilizzando la sintassi query UDF](udf-query-syntax.md) + [Creare e distribuiredi una UDF utilizzando Lambda](udf-creating-and-deploying.md) # Video su UDFs In Athena Guarda i video seguenti per saperne di più sull'utilizzo UDFs in Athena. **Video: Presentazione delle funzioni definite dall'utente (UDFs) in Amazon Athena** Il video seguente mostra come utilizzare UDFs Amazon Athena per oscurare informazioni sensibili. **Nota** La sintassi in questo video è precedente al rilascio, ma i concetti sono gli stessi. Utilizza Athena senza il gruppo di lavoro `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) **Video: Tradurre, analizzare e redigere campi di testo utilizzando query SQL in Amazon Athena** Il video seguente mostra come utilizzare UDFs Amazon Athena insieme ad altri Servizi AWS per tradurre e analizzare il testo. **Nota** La sintassi in questo video è precedente al rilascio, ma i concetti sono gli stessi. Per la sintassi corretta, vedere il post del blog correlato [Tradurre, redigere e analizzare il testo utilizzando le funzioni SQL con Amazon Athena, Amazon Translate e Amazon Comprehend](https://aws.amazon.com/blogs/machine-learning/translate-and-analyze-text-using-sql-functions-with-amazon-athena-amazon-translate-and-amazon-comprehend/) sul*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) # Considerazioni e limitazioni Considerate i seguenti punti quando utilizzate la funzione definita dall'utente (UDFs) in Athena. + **Funzioni Athena integrate**: le funzioni integrate in Athena sono progettate per essere altamente performanti. Ti consigliamo di utilizzare le funzioni integrate UDFs quando possibile. Per ulteriori informazioni sulle funzioni incorporate, consulta [Funzioni in Amazon Athena](functions.md). + ** UDFs Solo scalare**: Athena supporta solo lo UDFs scalare, che elabora una riga alla volta e restituisce un valore a colonna singola. Athena passa un batch di righe, potenzialmente in parallelo, all'UDF ogni volta che invoca Lambda. Durante la progettazione UDFs e le interrogazioni, presta attenzione al potenziale impatto di questa elaborazione sul traffico di rete. + **Le funzioni del gestore UDF utilizzano un formato abbreviato**: usa il formato abbreviato (non il formato completo) per le funzioni UDF (ad esempio, `package.Class` anziché `package.Class::method`). + **I metodi UDF devono essere scritti in lettere minuscole**: i metodi UDF devono essere scritti in lettere minuscole; la notazione a cammello non è consentita. + **I metodi UDF richiedono parametri**: i metodi UDF devono avere almeno un parametro di input. Il tentativo di richiamare una UDF definita senza parametri di input causa un'eccezione di runtime. UDFs sono pensati per eseguire funzioni sui record di dati, ma una UDF senza argomenti non accetta dati, quindi si verifica un'eccezione. + **Supporto Java runtime**: attualmente, Athena UDFs supporta i runtime Java 8, Java 11 e Java 17 per Lambda. Per ulteriori informazioni, consulta [Creazione di funzioni Lambda con Java](https://docs.aws.amazon.com/lambda/latest/dg/lambda-java.html) nella *Guida per gli sviluppatori di AWS Lambda *. **Nota** Per Java 17, bisogna impostare il valore della variabile di ambiente `JAVA_TOOL_OPTIONS` come `--add-opens=java.base/java.nio=ALL-UNNAMED` in Lambda. + **Autorizzazioni IAM** — Per eseguire e creare istruzioni di query UDF in Athena, l'entità principale IAM che esegue la query deve essere autorizzata a eseguire operazioni in aggiunta alle funzioni Athena. Per ulteriori informazioni, consulta [Consenti l'accesso ad Athena UDFs: politiche di esempio](udf-iam-access.md). + Quote **Lambda: le quote** Lambda si applicano a. UDFs Per ulteriori informazioni, consulta la sezione [Quote Lambda](https://docs.aws.amazon.com/lambda/latest/dg/limits.html) nella *Guida per gli sviluppatori di AWS Lambda *. + **Filtraggio a livello di riga: il filtro** a livello di riga di Lake Formation non è supportato per. UDFs + Visualizzazioni: non è **possibile utilizzare le viste** con. UDFs + **Problemi noti**: per la maggior parte up-to-date dei problemi noti, consulta [Limitazioni e problemi](https://github.com/awslabs/aws-athena-query-federation/wiki/Limitations_And_Issues) nella sezione awslabs/ aws-athena-query-federation di. GitHub # Eseguire query utilizzando la sintassi query UDF La `USING EXTERNAL FUNCTION` clausola specifica una o più UDF a UDFs cui è possibile fare riferimento da un'istruzione successiva nella query. `SELECT` È necessario il nome del metodo per la funzione definita dall'utente e il nome della funzione Lambda che ospita la funzione definita dall'utente. Al posto del nome della funzione Lambda, puoi utilizzare l'ARN Lambda. Negli scenari con più account, è necessario l'utilizzo dell'ARN Lambda. ## Riepilogo ``` 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 **UTILIZZO DELLA FUNZIONE ESTERNA *UDF\$1name* (*variable1**data\$1type*[, *variable2**data\$1type*] [,...])** *UDF\$1name*specifica il nome dell'UDF, che deve corrispondere a un metodo Java all'interno della funzione Lambda di riferimento. Ciascuno *variable data\$1type* specifica una variabile denominata e il tipo di dati corrispondente che l'UDF accetta come input. *data\$1type*Deve essere uno dei tipi di dati Athena supportati elencati nella tabella seguente e deve essere mappato al tipo di dati Java corrispondente. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/athena/latest/ug/udf-query-syntax.html) **RESTITUZIONI *data\$1type*** `data_type` specifica il tipo di dati SQL restituito dall'UDF come output. I tipi di dati Athena elencati nella tabella precedente sono supportati. Per il tipo di `DECIMAL` dati, usa la sintassi `RETURNS DECIMAL(precision, scale)` where *precision* e *scale* sono numeri interi. **LAMBDA '' *lambda\$1function*** *lambda\$1function*specifica il nome della funzione Lambda da richiamare durante l'esecuzione dell'UDF. **SELEZIONA [...] *UDF\$1name*(*expression*) [...]** L'`SELECT`interrogazione che passa i valori all'UDF e restituisce un risultato. *UDF\$1name*specifica l'UDF da utilizzare, seguita da una *expression* che viene valutata per passare valori. I valori passati e restituiti devono corrispondere ai tipi di dati corrispondenti specificati per la funzione definita dall'utente nella clausola `USING EXTERNAL FUNCTION`. ### Esempi Per esempio, le query basate sul codice [UDFHandlerAthena](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-udfs/src/main/java/com/amazonaws/athena/connectors/udfs/AthenaUDFHandler.java) .java GitHub on, consulta la pagina del connettore Amazon GitHub [Athena UDF](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-udfs). # Creare e distribuiredi una UDF utilizzando Lambda Per creare una funzione definita dall'utente personalizzata, crea una nuova classe Java estendendo la classe `UserDefinedFunctionHandler`. Il codice sorgente del [UserDefinedFunctionHandlerfile.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) nell'SDK è disponibile nell'[archivio awslabs/aws-athena-query-federation/athena -federation-sdk, insieme GitHub a esempi di implementazioni UDF che puoi esaminare e modificare](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-federation-sdk) [per creare una UDF personalizzata](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-udfs). La procedura in questa sezione illustra la scrittura e la creazione di un file Jar della funzione definita dall'utente personalizzata utilizzando [Apache Maven](https://maven.apache.org/index.html) dalla riga di comando e una distribuzione. Procedere con i seguenti passaggi per creare una funzione definita dall’utente personalizzata per Athena utilizzando Maven 1. [Duplicazione dell'SDK e preparazione dell'ambiente di sviluppo](#udf-create-install-sdk-prep-environment) 1. [Creazione del progetto Maven](#create-maven-project) 1. [Aggiunta di dipendenze e plugin al progetto Maven](#udf-add-maven-dependencies) 1. [Scrivere codice Java per UDFs](#udf-write-java) 1. [Compilazione del file JAR](#udf-create-package-jar) 1. [Distribuisci il JAR in AWS Lambda](#udf-create-deploy) ## Duplicazione dell'SDK e preparazione dell'ambiente di sviluppo Prima di iniziare, assicurati che git sia installato sul tuo sistema utilizzando `sudo yum install git -y`. **AWS Per installare il Query Federation SDK** + Immettere quanto segue nella riga di comando per clonare il repository SDK. Questo repository include l'SDK, esempi e una suite di connettori di origine dati. Per ulteriori informazioni sui connettori di origine dati, consulta [Utilizza Amazon Athena Federated Query](federated-queries.md). ``` git clone https://github.com/awslabs/aws-athena-query-federation.git ``` **Per installare i prerequisiti per questa procedura** Se state lavorando su una macchina di sviluppo su cui sono già installati Apache Maven AWS CLI, lo strumento di AWS Serverless Application Model compilazione e sviluppo, potete saltare questo passaggio. 1. Dalla radice della directory `aws-athena-query-federation` creata durante la clonazione, esegui lo script [prepare\$1dev\$1env.sh](https://github.com/awslabs/aws-athena-query-federation/blob/master/tools/prepare_dev_env.sh) che prepara l'ambiente di sviluppo. 1. Aggiorna la shell per generare nuove variabili create dal processo di installazione o riavvia la sessione del terminale. ``` source ~/.profile ``` **Importante** Se salti questo passaggio, in seguito riceverai degli errori relativi all'impossibilità dello strumento AWS CLI o AWS SAM build di pubblicare la tua funzione Lambda. ## Creazione del progetto Maven Esegui il comando seguente per creare il progetto Maven. Sostituiscila *groupId* con l'ID univoco della tua organizzazione e *my-athena-udf* sostituiscila con il nome dell'applicazione. Per ulteriori informazioni, vedi [Come faccio a creare il mio primo progetto Maven](https://maven.apache.org/guides/getting-started/index.html#How_do_I_make_my_first_Maven_project)? nella documentazione di Apache Maven. ``` mvn -B archetype:generate \ -DarchetypeGroupId=org.apache.maven.archetypes \ -DgroupId=groupId \ -DartifactId=my-athena-udfs ``` ## Aggiunta di dipendenze e plugin al progetto Maven Aggiungi le seguenti configurazioni al file `pom.xml` del progetto Maven. Per un esempio, consultate il [file pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-udfs/pom.xml) in. 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 ``` ## Scrivere codice Java per UDFs Crea una nuova classe estendendo [UserDefinedFunctionHandler.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) Scrivi i tuoi dati UDFs all'interno della classe. Nell'esempio seguente, all'interno della classe vengono creati due metodi Java per UDFs `compress()` e `decompress()``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); } } ``` ## Compilazione del file JAR Esegui `mvn clean install` per compilare il progetto. Una volta completato con successo, viene creato un file JAR nella `target` cartella denominata del progetto`artifactId-version.jar`, dove si *artifactId* trova il nome fornito nel progetto Maven, ad esempio. `my-athena-udfs` ## Distribuisci il JAR in AWS Lambda Hai a disposizione due opzioni per distribuire il codice in Lambda: + Distribuisci utilizzando AWS Serverless Application Repository (consigliato) + Creazione di una funzione Lambda dal file JAR ### Opzione 1: eseguire la distribuzione su AWS Serverless Application Repository Quando si distribuisce il file JAR su AWS Serverless Application Repository, si crea un file YAML AWS SAM modello che rappresenta l'architettura dell'applicazione. Quindi devi specificare questo file YAML e un bucket Amazon S3 in cui gli artefatti dell'applicazione vengono caricati e resi disponibili ad AWS Serverless Application Repository. Nella procedura riportata di seguito viene utilizzato lo script [publish.sh](https://github.com/awslabs/aws-athena-query-federation/blob/master/tools/publish.sh) che si trova nella directory `athena-query-federation/tools` dell'SDK di Athena Query Federation clonato in precedenza. Per ulteriori informazioni e requisiti, consulta [Pubblicazione di applicazioni](https://docs.aws.amazon.com/serverlessrepo/latest/devguide/serverlessrepo-publishing-applications.html) nella *AWS Serverless Application Repository Developer Guide*, [concetti di AWS SAM template](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-template-basics.html) nella *AWS Serverless Application Model Developer Guide* e [Pubblicazione di applicazioni serverless utilizzando la AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-template-publishing-applications.html). Nell'esempio seguente vengono illustrati i parametri in un file YAML. Aggiungi parametri simili al file YAML e salvalo nella directory del progetto. Vedi [athena-udf.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-udfs/athena-udfs.yaml) in per un esempio completo. 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 ``` Copia lo script `publish.sh` nella directory del progetto in cui è stato salvato il file YAML ed esegui il comando seguente: ``` ./publish.sh MyS3Location MyYamlFile ``` Ad esempio, se la posizione del bucket è `s3://amzn-s3-demo-bucket/mysarapps/athenaudf` e il file YAML è stato salvato come `my-athena-udfs.yaml`: ``` ./publish.sh amzn-s3-demo-bucket/mysarapps/athenaudf my-athena-udfs ``` **Come creare una funzione Lambda** 1. Apri la console Lambda all'indirizzo [https://console.aws.amazon.com/lambda/](https://console.aws.amazon.com/lambda/), scegli **Crea funzione**, quindi scegli **Browse serverless app repository** 1. Scegliere **Private applications (Applicazioni private)**, trovare l'applicazione nell'elenco o cercarla usando le parole chiave e selezionarla. 1. Rivedere e fornire i dettagli dell'applicazione, quindi scegliere **Deploy (Distribuisci)**. Ora puoi usare i nomi dei metodi definiti nel file JAR della funzione Lambda come in UDFs Athena. ### Opzione 2: Creare direttamente una funzione Lambda Puoi anche creare una funzione Lambda direttamente utilizzando la console o. AWS CLI L'esempio seguente illustra l'utilizzo del comando CLI della `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 ```