Se utilizzi Amazon Lex V2, consulta invece la guida Amazon Lex V2.
Se utilizzi Amazon Lex V1, ti consigliamo di aggiornare i bot ad Amazon Lex V2. Non stiamo più aggiungendo nuove funzionalità alla V1 e consigliamo vivamente di utilizzare la V2 per tutti i nuovi bot.
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à.
PutSession
Crea una nuova sessione o modifica una sessione esistente con un bot Amazon Lex. Utilizzate questa operazione per consentire all'applicazione di impostare lo stato del bot.
Per ulteriori informazioni, consulta Gestione delle sessioni.
Sintassi della richiesta
POST /bot/botName
/alias/botAlias
/user/userId
/session HTTP/1.1
Accept: accept
Content-type: application/json
{
"activeContexts": [
{
"name": "string
",
"parameters": {
"string
" : "string
"
},
"timeToLive": {
"timeToLiveInSeconds": number
,
"turnsToLive": number
}
}
],
"dialogAction": {
"fulfillmentState": "string
",
"intentName": "string
",
"message": "string
",
"messageFormat": "string
",
"slots": {
"string
" : "string
"
},
"slotToElicit": "string
",
"type": "string
"
},
"recentIntentSummaryView": [
{
"checkpointLabel": "string
",
"confirmationStatus": "string
",
"dialogActionType": "string
",
"fulfillmentState": "string
",
"intentName": "string
",
"slots": {
"string
" : "string
"
},
"slotToElicit": "string
"
}
],
"sessionAttributes": {
"string
" : "string
"
}
}
Parametri della richiesta URI
La richiesta utilizza i seguenti parametri URI.
- accept
-
Il messaggio che Amazon Lex restituisce nella risposta può essere testuale o vocale a seconda del valore di questo campo.
-
Se il valore è
text/plain; charset=utf-8
, Amazon Lex restituisce il testo nella risposta. -
Se il valore inizia con
audio/
, Amazon Lex restituisce la voce nella risposta. Amazon Lex utilizza Amazon Polly per generare il parlato nella configurazione specificata. Ad esempio, se si specificaaudio/mpeg
come valore, Amazon Lex restituisce la voce in formato MPEG. -
Se il valore è
audio/pcm
, la voce viene restituitaaudio/pcm
nel formato little endian a 16 bit. -
I valori accettati sono i seguenti:
-
audio/mpeg
-
audio/ogg
-
audio/pcm
-
audio/*
(il valore predefinito è mpeg) -
text/plain; charset=utf-8
-
-
- botAlias
-
L'alias in uso per il bot che contiene i dati della sessione.
Campo obbligatorio: sì
- botName
-
Il nome del bot che contiene i dati della sessione.
Campo obbligatorio: sì
- userId
-
L'ID dell'utente dell'applicazione client. Amazon Lex lo utilizza per identificare la conversazione di un utente con il tuo bot.
Vincoli di lunghezza: lunghezza minima di 2. Lunghezza massima di 100.
Modello:
[0-9a-zA-Z._:-]+
Campo obbligatorio: sì
Corpo della richiesta
La richiesta accetta i seguenti dati in formato JSON.
- activeContexts
-
Un elenco di contesti attivi per la richiesta. Un contesto può essere attivato quando viene soddisfatto un intento precedente o includendo il contesto nella richiesta,
Se non specifichi un elenco di contesti, Amazon Lex utilizzerà l'elenco corrente di contesti per la sessione. Se specifichi un elenco vuoto, tutti i contesti della sessione vengono cancellati.
Tipo: matrice di oggetti ActiveContext
Membri dell'array: numero minimo di 0 elementi. Numero massimo di 20 elementi.
Campo obbligatorio: no
- dialogAction
-
Imposta l'azione successiva che il bot deve intraprendere per completare la conversazione.
Tipo: oggetto DialogAction
Campo obbligatorio: no
- recentIntentSummaryView
-
Un riepilogo delle intenzioni recenti del bot. È possibile utilizzare la visualizzazione di riepilogo degli intenti per impostare un'etichetta di checkpoint su un intento e modificare gli attributi degli intenti. Puoi anche usarla per rimuovere o aggiungere oggetti di riepilogo degli intenti all'elenco.
Un intento che modifichi o aggiungi all'elenco deve avere senso per il bot. Ad esempio, il nome dell'intento deve essere valido per il bot. È necessario fornire valori validi per:
-
intentName
-
nomi di slot
-
slotToElict
Se si invia il
recentIntentSummaryView
parametro in unaPutSession
richiesta, il contenuto della nuova visualizzazione di riepilogo sostituisce la vecchia visualizzazione di riepilogo. Ad esempio, se unaGetSession
richiesta restituisce tre intenti nella visualizzazione di riepilogo e si chiamaPutSession
con un intento nella visualizzazione di riepilogo, la chiamata successivaGetSession
restituirà solo un intento.Tipo: matrice di oggetti IntentSummary
Membri dell'array: numero minimo di 0 elementi. Numero massimo di 3 elementi.
Campo obbligatorio: no
-
- sessionAttributes
-
Mappa delle coppie chiave/valore che rappresentano le informazioni di contesto specifiche della sessione. Contiene informazioni sull'applicazione trasferite tra Amazon Lex e un'applicazione client.
Tipo: mappatura stringa a stringa
Campo obbligatorio: no
Sintassi della risposta
HTTP/1.1 200
Content-Type: contentType
x-amz-lex-intent-name: intentName
x-amz-lex-slots: slots
x-amz-lex-session-attributes: sessionAttributes
x-amz-lex-message: message
x-amz-lex-encoded-message: encodedMessage
x-amz-lex-message-format: messageFormat
x-amz-lex-dialog-state: dialogState
x-amz-lex-slot-to-elicit: slotToElicit
x-amz-lex-session-id: sessionId
x-amz-lex-active-contexts: activeContexts
audioStream
Elementi di risposta
Se l'operazione riesce, il servizio restituisce una risposta HTTP 200.
La risposta restituisce le seguenti intestazioni HTTP.
- activeContexts
-
Un elenco di contesti attivi per la sessione.
- contentType
-
Tipo di contenuto specificato nell'intestazione
Accept
HTTP della richiesta. - dialogState
-
-
ConfirmIntent
- Amazon Lex si aspetta una risposta «sì» o «no» per confermare l'intento prima di realizzarlo. -
ElicitIntent
- Amazon Lex vuole suscitare l'intento dell'utente. -
ElicitSlot
- Amazon Lex prevede il valore di uno slot per l'intento attuale. -
Failed
- Indica che la conversazione con l'utente è fallita. Ciò può accadere per vari motivi, tra cui l'utente non fornisce una risposta appropriata alle richieste del servizio o se la funzione Lambda non riesce a soddisfare l'intento. -
Fulfilled
- Indica che la funzione Lambda ha raggiunto con successo l'intento. -
ReadyForFulfillment
- Indica che il cliente deve soddisfare l'intento.
Valori validi:
ElicitIntent | ConfirmIntent | ElicitSlot | Fulfilled | ReadyForFulfillment | Failed
-
- encodedMessage
-
Il messaggio successivo che deve essere presentato all'utente.
Il
encodedMessage
campo è codificato in base 64. È necessario decodificare il campo prima di poter utilizzare il valore.Limitazioni di lunghezza: lunghezza minima pari a 1. Lunghezza massima di 1366.
- intentName
-
Il nome dell'intento corrente.
- message
-
Questa intestazione è obsoleta.
Il messaggio successivo che dovrebbe essere presentato all'utente.
Puoi utilizzare questo campo solo nelle versioni locali de-DE, en-AU, en-GB, en-US, es-419, es-ES, es-US, fr-CA, fr-FR e it-IT.
message
In tutte le altre lingue, il campo è nullo. Dovresti invece usare ilencodedMessage
campo.Limitazioni di lunghezza: lunghezza minima pari a 1. La lunghezza massima è 1024 caratteri.
- messageFormat
-
Il formato del messaggio di risposta. Uno dei seguenti valori:
-
PlainText
- Il messaggio contiene testo UTF-8 semplice. -
CustomPayload
- Il messaggio è un formato personalizzato per il cliente. -
SSML
- Il messaggio contiene testo formattato per l'output vocale. -
Composite
- Il messaggio contiene un oggetto JSON in escape contenente uno o più messaggi provenienti dai gruppi a cui sono stati assegnati i messaggi al momento della creazione dell'intento.
Valori validi:
PlainText | CustomPayload | SSML | Composite
-
- sessionAttributes
-
Mappa di coppie chiave/valore che rappresentano informazioni di contesto specifiche della sessione.
- sessionId
-
Un identificatore univoco per la sessione.
- slots
-
Mappa degli slot con zero o più intenti rilevati da Amazon Lex in base all'input dell'utente durante la conversazione.
Amazon Lex crea un elenco di risoluzioni contenente i valori probabili per uno slot. Il valore restituito è determinato dal valore
valueSelectionStrategy
selezionato al momento della creazione o dell'aggiornamento del tipo di slot. SevalueSelectionStrategy
è impostato suORIGINAL_VALUE
, viene restituito il valore fornito dall'utente, se il valore utente è simile ai valori dello slot. SevalueSelectionStrategy
è impostatoTOP_RESOLUTION
su Amazon Lex restituisce il primo valore nell'elenco delle risoluzioni o, se non esiste un elenco di risoluzioni, null. Se non specifichi a,valueSelectionStrategy
l'impostazione predefinita èORIGINAL_VALUE
. - slotToElicit
-
Se
dialogState
èElicitSlot
, restituisce il nome dello slot per il quale Amazon Lex sta ottenendo un valore.
La risposta restituisce quanto segue come corpo HTTP.
- audioStream
-
La versione audio del messaggio da trasmettere all'utente.
Errori
- BadGatewayException
-
Il bot Amazon Lex è ancora in fase di creazione oppure uno dei servizi dipendenti (Amazon Polly, AWS Lambda) non è riuscito a causa di un errore interno del servizio.
Codice di stato HTTP: 502
- BadRequestException
-
La convalida della richiesta non è riuscita, non è presente alcun messaggio utilizzabile nel contesto oppure la compilazione del bot non è riuscita, è ancora in corso o contiene modifiche non integrate.
Codice di stato HTTP: 400
- ConflictException
-
Due client utilizzano lo stesso account AWS, lo stesso bot Amazon Lex e lo stesso ID utente.
Codice di stato HTTP: 409
- DependencyFailedException
-
Una delle dipendenze, come AWS Lambda o Amazon Polly, generava un'eccezione. Ad esempio,
-
Se Amazon Lex non dispone di autorizzazioni sufficienti per chiamare una funzione Lambda.
-
Se l'esecuzione di una funzione Lambda richiede più di 30 secondi.
-
Se una funzione Lambda di adempimento restituisce un'azione di
Delegate
dialogo senza rimuovere alcun valore dello slot.
Codice di stato HTTP: 424
-
- InternalFailureException
-
Errore interno del servizio. Riprova la chiamata.
Codice di stato HTTP: 500
- LimitExceededException
-
È stato superato un limite.
Codice di stato HTTP: 429
- NotAcceptableException
-
L'intestazione accept nella richiesta non ha un valore valido.
Codice di stato HTTP: 406
- NotFoundException
-
La risorsa (ad esempio il bot Amazon Lex o un alias) a cui si fa riferimento non è stata trovata.
Codice di stato HTTP: 404
Vedi anche
Per ulteriori informazioni sull'utilizzo di questa API in uno degli AWS SDK specifici della lingua, consulta quanto segue: