Avviso di fine del supporto: il 15 settembre 2025 AWS interromperà il supporto per Amazon Lex V1. Dopo il 15 settembre 2025, non potrai più accedere alla console di Amazon Lex V1 o alle risorse di Amazon Lex V1. Se utilizzi Amazon Lex V2, consulta invece la [guida Amazon Lex V2](https://docs.aws.amazon.com/lexv2/latest/dg/what-is.html). 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à. # Utilizzo delle funzioni Lambda Puoi creare AWS Lambda funzioni da utilizzare come code hook per il tuo bot Amazon Lex. Puoi identificare le funzioni Lambda per eseguire l'inizializzazione e la convalida, l'adempimento o entrambe nella configurazione dell'intento. Ti consigliamo di utilizzare una funzione Lambda come code hook per il tuo bot. Senza una funzione Lambda, il bot restituisce le informazioni sull'intento all'applicazione client per l'esecuzione. **Topics** + [Evento di input e formato di risposta della funzione Lambda](lambda-input-response-format.md) + [Amazon Lex e AWS Lambda Blueprints](lex-lambda-blueprints.md) # Evento di input e formato di risposta della funzione Lambda Questa sezione descrive la struttura dei dati degli eventi che Amazon Lex fornisce a una funzione Lambda. Usa queste informazioni per analizzare l'input nel tuo codice Lambda. Spiega inoltre il formato della risposta che Amazon Lex si aspetta che la funzione Lambda restituisca. **Topics** + [Formato dell'evento di input](#using-lambda-input-event-format) + [Formato della risposta](#using-lambda-response-format) ## Formato dell'evento di input Di seguito viene illustrato il formato generale di un evento Amazon Lex passato a una funzione Lambda. Usa queste informazioni quando scrivi la tua funzione Lambda. **Nota** Il formato di input potrebbe cambiare senza che corrisponda una modifica in `messageVersion`. Il codice non dovrebbe generare errori se sono presenti nuovi campi. ``` { "currentIntent": { "name": "intent-name", "nluIntentConfidenceScore": score, "slots": { "slot name": "value", "slot name": "value" }, "slotDetails": { "slot name": { "resolutions" : [ { "value": "resolved value" }, { "value": "resolved value" } ], "originalValue": "original text" }, "slot name": { "resolutions" : [ { "value": "resolved value" }, { "value": "resolved value" } ], "originalValue": "original text" } }, "confirmationStatus": "None, Confirmed, or Denied (intent confirmation, if configured)" }, "alternativeIntents": [ { "name": "intent-name", "nluIntentConfidenceScore": score, "slots": { "slot name": "value", "slot name": "value" }, "slotDetails": { "slot name": { "resolutions" : [ { "value": "resolved value" }, { "value": "resolved value" } ], "originalValue": "original text" }, "slot name": { "resolutions" : [ { "value": "resolved value" }, { "value": "resolved value" } ], "originalValue": "original text" } }, "confirmationStatus": "None, Confirmed, or Denied (intent confirmation, if configured)" } ], "bot": { "name": "bot name", "alias": "bot alias", "version": "bot version" }, "userId": "User ID specified in the POST request to Amazon Lex.", "inputTranscript": "Text used to process the request", "invocationSource": "FulfillmentCodeHook or DialogCodeHook", "outputDialogMode": "Text or Voice, based on ContentType request header in runtime API request", "messageVersion": "1.0", "sessionAttributes": { "key": "value", "key": "value" }, "requestAttributes": { "key": "value", "key": "value" }, "recentIntentSummaryView": [ { "intentName": "Name", "checkpointLabel": Label, "slots": { "slot name": "value", "slot name": "value" }, "confirmationStatus": "None, Confirmed, or Denied (intent confirmation, if configured)", "dialogActionType": "ElicitIntent, ElicitSlot, ConfirmIntent, Delegate, or Close", "fulfillmentState": "Fulfilled or Failed", "slotToElicit": "Next slot to elicit" } ], "sentimentResponse": { "sentimentLabel": "sentiment", "sentimentScore": "score" }, "kendraResponse": { Complete query response from Amazon Kendra }, "activeContexts": [ { "timeToLive": { "timeToLiveInSeconds": seconds, "turnsToLive": turns }, "name": "name", "parameters": { "key name": "value" } } ] } ``` Tieni conto delle ulteriori informazioni seguenti sui campi di evento: + **currentIntent**: fornisce i campi `name`, `slots`, `slotDetails` e `confirmationStatus` dell'intento.   `nluIntentConfidenceScore`è la fiducia di Amazon Lex che l'intento attuale è quello che meglio corrisponde all'intento attuale dell'utente.   `slots`è una mappa di nomi di slot, configurati per l'intento, ai valori degli slot che Amazon Lex ha riconosciuto nella conversazione con l'utente. Un valore di slot rimane null fino a quando l'utente non fornisca un valore.   Il valore dello slot nell'evento di input potrebbe non corrispondere a uno dei valori configurati per lo slot. Ad esempio, se l'utente risponde alla richiesta «Di che colore è l'auto che preferisci?» con «pizza», Amazon Lex restituirà «pizza» come valore dello slot. La funzione dovrebbe convalidare i valori per assicurare che questi abbiano senso nel contesto.   `slotDetails` fornisce ulteriori informazioni su un valore dello slot. La matrice `resolutions` contiene un elenco di valori aggiuntivi riconosciuti per lo slot. Ciascuno slot può avere un massimo di cinque valori.   Il campo `originalValue` contiene il valore che l'utente ha inserito per lo slot. Quando il tipo di slot è configurato per restituire il valore di risoluzione superiore come valore dello slot, `originalValue` potrebbe essere diverso dal valore del campo `slots`.   `confirmationStatus` fornisce la risposta dell'utente a un messaggio di richiesta di conferma, se disponibile. Ad esempio, se Amazon Lex chiede «Vuoi ordinare una pizza grande al formaggio? ,» a seconda della risposta dell'utente, il valore di questo campo può essere `Confirmed` o`Denied`. In caso contrario, il valore di questo campo è `None`.   Se l'utente conferma l'intento, Amazon Lex imposta questo campo su. `Confirmed` Se l'utente nega l'intenzione, Amazon Lex imposta questo valore su. `Denied`   Nella risposta di conferma, un'enunciazione utente potrebbe fornire aggiornamenti dello slot. Ad esempio, l'utente potrebbe dire "Sì, modifica dimensione a media". In questo caso, l'evento Lambda successivo ha il valore dello slot aggiornato, `PizzaSize` impostato su. `medium` Amazon Lex imposta il `confirmationStatus` to`None`, poiché l'utente ha modificato alcuni dati dello slot, richiedendo la funzione Lambda per eseguire la convalida dei dati utente.   + **AlternativeIntents**: se abiliti i punteggi di confidenza, Amazon Lex restituisce fino a quattro intenti alternativi. Ogni intento include un punteggio che indica il livello di fiducia di Amazon Lex rispetto all'intento corretto in base all'enunciato dell'utente.   Il contenuto degli intenti alternativi è lo stesso del contenuto del campo. `currentIntent` Per ulteriori informazioni, consulta [Utilizzo dei punteggi di confidenza](confidence-scores.md).   + **bot**: informazioni sul bot che ha elaborato la richiesta. + `name`: nome del bot che ha elaborato la richiesta. + `alias`: alias della versione del bot che ha elaborato la richiesta. + `version`: versione del bot che ha elaborato la richiesta.   + **userID**: questo valore viene fornito dall'applicazione client. Amazon Lex lo passa alla funzione Lambda.   + **inputTranscript**: testo utilizzato per elaborare la richiesta. Se si tratta di un input di testo, il campo `inputTranscript` contiene il testo inserito dall'utente.   In caso di input di flusso audio, il campo `inputTranscript` contiene il testo estratto dal flusso audio. Questo è il testo che viene effettivamente elaborato per riconoscere gli intenti e i valori dello slot.   + **InvocationSource**: per indicare il motivo per cui Amazon Lex richiama la funzione Lambda, la imposta su uno dei seguenti valori: + `DialogCodeHook`— Amazon Lex imposta questo valore per indirizzare la funzione Lambda a inizializzare la funzione e a convalidare l'input dei dati dell'utente.   Quando l'intento è configurato per richiamare una funzione Lambda come codice hook di inizializzazione e convalida, Amazon Lex richiama la funzione Lambda specificata su ogni input (enunciato) utente dopo che Amazon Lex ha compreso l'intento. **Nota** Se l'intento non è chiaro, Amazon Lex non può richiamare la funzione Lambda.   + `FulfillmentCodeHook`— Amazon Lex imposta questo valore per indirizzare la funzione Lambda a soddisfare un intento.   Se l'intento è configurato per richiamare una funzione Lambda come hook del codice di adempimento, Amazon Lex lo imposta su questo valore solo dopo aver ottenuto tutti i dati dello slot `invocationSource` per soddisfare l'intento.   Nella configurazione dell'intento, puoi avere due funzioni Lambda separate per inizializzare e convalidare i dati utente e soddisfare l'intento. Puoi anche usare una funzione Lambda per fare entrambe le cose. In tal caso, la funzione Lambda può utilizzare il `invocationSource` valore per seguire il percorso del codice corretto.   + **outputDialogMode**— Per ogni input dell'utente, il client invia la richiesta ad Amazon Lex utilizzando una delle operazioni API di runtime, [PostContent](API_runtime_PostContent.md) oppure[PostText](API_runtime_PostText.md). Amazon Lex utilizza i parametri di richiesta per determinare se la risposta al client è di testo o vocale e imposta questo campo di conseguenza.   La funzione Lambda può utilizzare queste informazioni per generare un messaggio appropriato. Ad esempio, se il client si aspetta una risposta vocale, la funzione Lambda potrebbe restituire Speech Synthesis Markup Language (SSML) anziché testo.   + **messageVersion** — La versione del messaggio che identifica il formato dei dati degli eventi che entrano nella funzione Lambda e il formato previsto della risposta da una funzione Lambda. **Nota** Puoi configurare questo valore quando definisci un intento. Nell'implementazione corrente, è supportata solo la versione 1.0 dei messaggi. Pertanto, la console presuppone il valore predefinito di 1.0 e non mostra la versione del messaggio. + **SessionAttributes**: attributi di sessione specifici dell'applicazione che il client invia nella richiesta. Se desideri che Amazon Lex li includa nella risposta al client, la tua funzione Lambda dovrebbe rispedirli ad Amazon Lex nella risposta. Per ulteriori informazioni, consulta [Impostazione degli attributi di sessione](context-mgmt-session-attribs.md)   + **RequestAttributes: attributi** specifici della richiesta che il client invia nella richiesta. Utilizza gli attributi di richiesta per inviare informazioni che non devono essere conservate per l'intera sessione. Se non ci sono attributi della richiesta, il valore sarà null. Per ulteriori informazioni, consulta [Impostazione degli attributi di richiesta](context-mgmt-request-attribs.md)   + **recentIntentSummaryVisualizza**: informazioni sullo stato di un intento. È possibile visualizzare informazioni sugli ultimi tre intenti utilizzati. Queste informazioni possono essere usate per impostare i valori nell'intento o per tornare a un intento precedente. Per ulteriori informazioni, consulta [Gestione delle sessioni con l'API Amazon Lex](how-session-api.md).   + **SentimentResponse**: il risultato di un'analisi del sentiment di Amazon Comprehend dell'ultima espressione. È possibile utilizzare queste informazioni per gestire il flusso di conversazione del bot in base all'emozione espressa dall'utente. Per ulteriori informazioni, consulta [Analisi delle emozioni](sentiment-analysis.md).   + **KendraResponse**: il risultato di una query su un indice Amazon Kendra. Presente solo nell'input a un hook di codice di adempimento e solo quando l'intento estende l'intento integrato `AMAZON.KendraSearchIntent`. Il campo contiene l'intera risposta della ricerca di Amazon Kendra. Per ulteriori informazioni, consulta [AMAZON.KendraSearchIntent](built-in-intent-kendra-search.md).   + **ActiveContexts**: uno o più contesti attivi durante questo turno di conversazione con l'utente. + **timeToLive**— La durata o il numero di turni della conversazione con l'utente durante i quali il contesto rimane attivo. + **nome**: il nome del contesto. + **parameters**: un elenco di key/value coppie che contiene il nome e il valore degli slot relativi all'intento che ha attivato il contesto. Per ulteriori informazioni, consulta [Impostazione del contesto degli intenti](context-mgmt-active-context.md). ## Formato della risposta Amazon Lex prevede una risposta da una funzione Lambda nel seguente formato: ``` { "sessionAttributes": { "key1": "value1", "key2": "value2" ... }, "recentIntentSummaryView": [ { "intentName": "Name", "checkpointLabel": "Label", "slots": { "slot name": "value", "slot name": "value" }, "confirmationStatus": "None, Confirmed, or Denied (intent confirmation, if configured)", "dialogActionType": "ElicitIntent, ElicitSlot, ConfirmIntent, Delegate, or Close", "fulfillmentState": "Fulfilled or Failed", "slotToElicit": "Next slot to elicit" } ], "activeContexts": [ { "timeToLive": { "timeToLiveInSeconds": seconds, "turnsToLive": turns }, "name": "name", "parameters": { "key name": "value" } } ], "dialogAction": { "type": "ElicitIntent, ElicitSlot, ConfirmIntent, Delegate, or Close", Full structure based on the type field. See below for details. } } ``` La risposta è composta da quattro campi. I `activeContexts` campi `sessionAttributes``recentIntentSummaryView`, e sono facoltativi, il `dialogAction` campo è obbligatorio. Il contenuto del campo `dialogAction` dipende dal valore del campo `type`. Per informazioni dettagliate, vedi [dialogAction](#lambda-response-dialogAction). ### sessionAttributes Opzionale. Se includi il campo `sessionAttributes`, questo può essere vuoto. Se la funzione Lambda non restituisce gli attributi di sessione, rimane l'ultimo `sessionAttributes` passato noto tramite l'API o la funzione Lambda. Per maggiori informazioni, consulta le operazioni [PostContent](API_runtime_PostContent.md) e [PostText](API_runtime_PostText.md). ``` "sessionAttributes": { "key1": "value1", "key2": "value2" } ``` ### recentIntentSummaryVisualizza Opzionale. Se incluso, imposta i valori per uno o più intenti recenti. È possibile includere informazioni per un massimo di tre intenti. Ad esempio, puoi impostare i valori per gli intenti precedenti in base alle informazioni raccolte dall'intento corrente. Le informazioni contenute nel riepilogo devono essere valide per l'intento. Ad esempio, il nome dell'intento deve essere un intento nel bot. Se includi un valore di slot nella visualizzazione riepilogo, lo slot deve essere presente nell'intento. Se non includi la `recentIntentSummaryView` nella risposta, tutti i valori degli intenti recenti rimangono invariati. Per ulteriori informazioni, vedere l'operazione [PutSession](API_runtime_PutSession.md) o il tipo di dati [IntentSummary](API_runtime_IntentSummary.md). ``` "recentIntentSummaryView": [ { "intentName": "Name", "checkpointLabel": "Label", "slots": { "slot name": "value", "slot name": "value" }, "confirmationStatus": "None, Confirmed, or Denied (intent confirmation, if configured)", "dialogActionType": "ElicitIntent, ElicitSlot, ConfirmIntent, Delegate, or Close", "fulfillmentState": "Fulfilled or Failed", "slotToElicit": "Next slot to elicit" } ] ``` ### Contesti attivi Opzionale. Se incluso, imposta il valore per uno o più contesti. Ad esempio, puoi includere un contesto per creare uno o più intenti che abbiano quel contesto come input idoneo al riconoscimento nel turno successivo della conversazione. I time-to-live valori di tutti i contesti attivi che non sono inclusi nella risposta vengono diminuiti e potrebbero essere ancora attivi alla richiesta successiva. Se si specifica un valore time-to-live pari a 0 per un contesto incluso nell'evento di input, questo sarà inattivo alla richiesta successiva. Per ulteriori informazioni, consulta [Impostazione del contesto degli intenti](context-mgmt-active-context.md). ### dialogAction Obbligatorio. Il `dialogAction` campo indirizza Amazon Lex alla linea d'azione successiva e descrive cosa aspettarsi dall'utente dopo che Amazon Lex ha restituito una risposta al client. Il campo `type` indica l'operazione successiva. Determina inoltre gli altri campi che la funzione Lambda deve fornire come parte del `dialogAction` valore. + `Close`— Informa Amazon Lex di non aspettarsi una risposta dall'utente. Ad esempio, "L'ordine della tua pizza è stato registrato" non richiede una risposta.   Il campo `fulfillmentState` è obbligatorio. Amazon Lex utilizza questo valore per impostare il `dialogState` campo nella [PostText](API_runtime_PostText.md) risposta [PostContent](API_runtime_PostContent.md) o all'applicazione client. I campi `message` e `responseCard` sono facoltativi. Se non specifichi un messaggio, Amazon Lex utilizza il messaggio di addio o il messaggio di follow-up configurato per l'intento. ``` "dialogAction": { "type": "Close", "fulfillmentState": "Fulfilled or Failed", "message": { "contentType": "PlainText or SSML or CustomPayload", "content": "Message to convey to the user. For example, Thanks, your pizza has been ordered." }, "responseCard": { "version": integer-value, "contentType": "application/vnd.amazonaws.card.generic", "genericAttachments": [ { "title":"card-title", "subTitle":"card-sub-title", "imageUrl":"URL of the image to be shown", "attachmentLinkUrl":"URL of the attachment to be associated with the card", "buttons":[ { "text":"button-text", "value":"Value sent to server on button click" } ] } ] } } ``` + `ConfirmIntent`— Informa Amazon Lex che l'utente deve rispondere sì o no per confermare o negare l'intenzione attuale.   È necessario includere i campi `intentName` e `slots`. Il campo `slots` deve contenere una voce per ciascuno slot riempito per l'intento specificato. Non è necessario includere una voce nel campo `slots` per gli slot che non vengono riempiti. È necessario includere il campo `message` se il campo intento `confirmationPrompt` è nullo. Il contenuto del `message` campo restituito dalla funzione Lambda ha la precedenza su quello `confirmationPrompt` specificato nell'intento. Il campo `responseCard` è facoltativo. ``` "dialogAction": { "type": "ConfirmIntent", "message": { "contentType": "PlainText or SSML or CustomPayload", "content": "Message to convey to the user. For example, Are you sure you want a large pizza?" }, "intentName": "intent-name", "slots": { "slot-name": "value", "slot-name": "value", "slot-name": "value" }, "responseCard": { "version": integer-value, "contentType": "application/vnd.amazonaws.card.generic", "genericAttachments": [ { "title":"card-title", "subTitle":"card-sub-title", "imageUrl":"URL of the image to be shown", "attachmentLinkUrl":"URL of the attachment to be associated with the card", "buttons":[ { "text":"button-text", "value":"Value sent to server on button click" } ] } ] } } ``` + `Delegate`— Indica ad Amazon Lex di scegliere la linea d'azione successiva in base alla configurazione del bot. Se la risposta non include alcun attributo di sessione, Amazon Lex conserva gli attributi esistenti. Per ottenere un valore null di uno slot, non occorre includere il campo slot nella richiesta. Si riceverà un'eccezione `DependencyFailedException` se la funzione di adempimento restituisce l'operazione di dialogo `Delegate` senza rimuovere alcuno slot. I campi `kendraQueryRequestPayload` e `kendraQueryFilterString` sono facoltativi e utilizzati solo quando l'intento è derivato dall'intento integrato `AMAZON.KendraSearchIntent`. Per ulteriori informazioni, consulta [AMAZON.KendraSearchIntent](built-in-intent-kendra-search.md). ``` "dialogAction": { "type": "Delegate", "slots": { "slot-name": "value", "slot-name": "value", "slot-name": "value" }, "kendraQueryRequestPayload": "Amazon Kendra query", "kendraQueryFilterString": "Amazon Kendra attribute filters" } ``` + `ElicitIntent`— Informa Amazon Lex che l'utente dovrebbe rispondere con un enunciato che include un intento. Ad esempio, "Voglio una pizza grande", che indica l'intento `OrderPizzaIntent`. L'espressione «grande», d'altra parte, non è sufficiente per Amazon Lex per dedurre l'intento dell'utente.   I campi `message` e `responseCard` sono facoltativi. Se non fornisci un messaggio, Amazon Lex utilizza uno dei prompt di chiarimento del bot. Se non è stata definita alcuna richiesta di chiarimento, Amazon Lex restituisce un'eccezione 400 Bad Request. ``` { "dialogAction": { "type": "ElicitIntent", "message": { "contentType": "PlainText or SSML or CustomPayload", "content": "Message to convey to the user. For example, What can I help you with?" }, "responseCard": { "version": integer-value, "contentType": "application/vnd.amazonaws.card.generic", "genericAttachments": [ { "title":"card-title", "subTitle":"card-sub-title", "imageUrl":"URL of the image to be shown", "attachmentLinkUrl":"URL of the attachment to be associated with the card", "buttons":[ { "text":"button-text", "value":"Value sent to server on button click" } ] } ] } } ``` + `ElicitSlot`— Informa Amazon Lex che l'utente deve fornire un valore di slot nella risposta.   I campi `intentName`, `slotToElicit` e `slots` sono obbligatori. I campi `message` e `responseCard` sono facoltativi. Se non specifichi un messaggio, Amazon Lex utilizza uno dei prompt di elicitazione dello slot configurati per lo slot. ``` "dialogAction": { "type": "ElicitSlot", "message": { "contentType": "PlainText or SSML or CustomPayload", "content": "Message to convey to the user. For example, What size pizza would you like?" }, "intentName": "intent-name", "slots": { "slot-name": "value", "slot-name": "value", "slot-name": "value" }, "slotToElicit" : "slot-name", "responseCard": { "version": integer-value, "contentType": "application/vnd.amazonaws.card.generic", "genericAttachments": [ { "title":"card-title", "subTitle":"card-sub-title", "imageUrl":"URL of the image to be shown", "attachmentLinkUrl":"URL of the attachment to be associated with the card", "buttons":[ { "text":"button-text", "value":"Value sent to server on button click" } ] } ] } } ``` # Amazon Lex e AWS Lambda Blueprints La console Amazon Lex fornisce bot di esempio (chiamati bot blueprint) preconfigurati in modo da poter creare e testare rapidamente un bot nella console. Per ognuno di questi progetti di bot, vengono forniti anche i blueprint delle funzioni Lambda. Questi piani forniscono il codice di esempio funzionante con i bot corrispondenti. Puoi usare questi blueprint per creare rapidamente un bot configurato con una funzione Lambda come code hook e testare end-to-end la configurazione senza dover scrivere codice. Puoi utilizzare i seguenti blueprint di bot di Amazon Lex e i corrispondenti blueprint di AWS Lambda funzioni come code hook per bot: + Progetto Amazon Lex — `OrderFlowers` + AWS Lambda progetto — `lex-order-flowers-python` + Progetto Amazon Lex — `ScheduleAppointment` + AWS Lambda progetto — `lex-make-appointment-python` + Progetto Amazon Lex — `BookTrip` + AWS Lambda progetto — `lex-book-trip-python` Per creare un bot utilizzando un blueprint e configurarlo per utilizzare una funzione Lambda come code hook, vedere. [Esercizio 1: Creare un bot Amazon Lex utilizzando un blueprint (console)](gs-bp.md) Per esempi di utilizzo di altri piani, consulta [Esempi aggiuntivi: creazione di bot Amazon Lex](additional-exercises.md). ## Aggiornamento di un blueprint per una locale specifica Se si utilizza un blueprint in una lingua diversa dall'inglese (USA) (en-US), è necessario aggiornare il nome di eventuali intenti per includere la lingua. Ad esempio, se si utilizza il `OrderFlowers` blueprint, è necessario effettuare le seguenti operazioni. + Trova la `dispatch` funzione vicino alla fine del codice della funzione Lambda. + Nella `dispatch` funzione, aggiorna il nome dell'intento per includere il locale che stai utilizzando. Ad esempio, se utilizzi la versione locale inglese (australiana) (en-AU), modifica la riga: `if intent_name == 'OrderFlowers':` in `if intent_name == 'OrderFlowers_enAU':` Altri blueprint utilizzano nomi di intenti diversi, pertanto devono essere aggiornati come indicato sopra prima di utilizzarli.