Sintaxis de la solicitud Parámetros de solicitud del URI Cuerpo de la solicitud Sintaxis de la respuesta Elementos de respuesta Errores Ejemplos Véase también

PostContent

Envía entradas de usuarios (texto o voz) a Amazon Lex. Los clientes utilizan esta API para enviar solicitudes de texto y audio a Amazon Lex en tiempo de ejecución. Amazon Lex interpreta la entrada del usuario con el modelo de machine learning que ha compilado para el bot.

La operación PostContent es compatible con la entrada de audio a 8 kHz y 16 kHz. Puede utilizar audio a 8 kHz para mejorar la precisión del reconocimiento de voz en aplicaciones de audio por teléfono.

Como respuesta, Amazon Lex devuelve el siguiente mensaje para transmitirlo al usuario. Considere los siguientes ejemplos de mensaje:

Para la entrada de usuario “Quiero una pizza”, Amazon Lex puede devolver una respuesta con un mensaje para obtener datos de ranura (por ejemplo, PizzaSize): “¿De qué tamaño quiere la pizza?”.
Una vez que el usuario haya proporcionado toda la información necesaria para pedir la pizza, Amazon Lex puede devolver una respuesta con un mensaje para obtener la confirmación del usuario: “¿Desea pedir la pizza?”.
Si el usuario responde “sí” a la pregunta de confirmación, es posible que Amazon Lex devuelva una afirmación de cierre: “Muchas gracias. Se ha realizado el pedido de su pizza de quesos”.

No todos los mensajes de Amazon Lex requieren una respuesta del usuario. Por ejemplo, las afirmaciones de cierre no requieren respuesta. Algunos mensajes solo requieren una respuesta afirmativa o negativa. Además de message, Amazon Lex proporciona contexto adicional sobre el mensaje de la respuesta para que pueda mejorar el comportamiento del cliente, como mostrar la interfaz de usuario adecuada al cliente. Considere los siguientes ejemplos:

Si el mensaje tiene como objetivo obtener datos de ranuras, Amazon Lex devuelve la siguiente información de contexto:
- El encabezado x-amz-lex-dialog-state establecido en ElicitSlot
- El encabezado x-amz-lex-intent-name establecido en el nombre de la intención en el contexto actual
- El encabezado x-amz-lex-slot-to-elicit establecido en el nombre de la ranura para el que message obtiene información
- El encabezado x-amz-lex-slots establecido en una asignación de ranuras configurada para la intención con sus valores actuales
Si el mensaje es una pregunta de confirmación, el encabezado x-amz-lex-dialog-state se establece en Confirmation y el encabezado x-amz-lex-slot-to-elicit se omite.
Si el mensaje es una pregunta aclaratoria configurada para la intención, lo que indica que no se ha comprendido la intención del usuario, el encabezado x-amz-dialog-state se establece en ElicitIntent y el encabezado x-amz-slot-to-elicit se omite.

Además, Amazon Lex también devuelve los valores sessionAttributes específicos de la aplicación. Para obtener más información, consulte Administración del contexto de la conversación.

Sintaxis de la solicitud


POST /bot/botName/alias/botAlias/user/userId/content HTTP/1.1
x-amz-lex-session-attributes: sessionAttributes
x-amz-lex-request-attributes: requestAttributes
Content-Type: contentType
Accept: accept
x-amz-lex-active-contexts: activeContexts

inputStream

Parámetros de solicitud del URI

La solicitud utiliza los siguientes parámetros URI.

accept

Este valor se transfiere como el encabezado HTTP Accept.

El mensaje que Amazon Lex devuelve en la respuesta puede ser texto o voz basado en el valor del encabezado HTTP Accept de la solicitud.

Si el valor es text/plain; charset=utf-8, Amazon Lex devuelve texto en la respuesta.
Si el valor comienza por audio/, Amazon Lex devuelve voz en la respuesta. Amazon Lex utiliza Amazon Polly para generar la voz (con la configuración que ha especificado en el encabezado Accept). Por ejemplo, si especifica audio/mpeg como valor, Amazon Lex devuelve voz en formato MPEG.
Si el valor es audio/pcm, la voz que se devuelve es audio/pcm en formato little endian de 16 bits.
A continuación se muestran los valores aceptados:
- audio/mpeg
- audio/ogg
- audio/pcm
- text/plain; charset=utf-8
- audio/* (el valor predeterminado es mpeg)

activeContexts

Una lista de los contextos activos para la solicitud. Un contexto se puede activar cuando se cumple una intención anterior o al incluir el contexto en la solicitud,

Si no especifica una lista de contextos, Amazon Lex utilizará la lista de contextos actual en la sesión. Si especifica una lista vacía, se borran todos los contextos de la sesión.

botAlias

El alias del bot de Amazon Lex.

Obligatorio: sí

botName

El nombre del bot de Amazon Lex.

Obligatorio: sí

contentType

Este valor se transfiere como el encabezado HTTP Content-Type.

Indica el formato de audio o de texto. El valor del encabezado debe comenzar por uno de los siguientes prefijos:

En el formato PCM, los datos de audio deben estar en el orden de bytes little endian.
- audio/l16; rate=16000; channels=1
- audio/x-l16; sample-rate=16000; channel-count=1
- audio/lpcm; frecuencia de muestreo = 8000; = 16; recuento de canales = 1; = falso sample-size-bits is-big-endian
Formato Opus
- audio/ -preámbulox-cbr-opus-with; tamaño del preámbulo = 0; tasa de bits=256000; =4 frame-size-milliseconds
Formato de texto
- text/plain; charset=utf-8

Obligatorio: sí

requestAttributes

Este valor se transfiere como el encabezado HTTP x-amz-lex-request-attributes.

La información específica de la solicitud que se pasa entre Amazon Lex y una aplicación cliente. El valor debe ser una asignación codificada en base64 y serializada en formato JSON con claves de cadena y valores. El tamaño total de los encabezados requestAttributes y sessionAttributes no puede superar 12 kB.

El espacio de nombres x-amz-lex: está reservado para atributos especiales. No cree atributos de solicitud con el prefijo x-amz-lex:.

Para obtener más información, consulte Configuración de atributos de solicitud.

sessionAttributes

Este valor se transfiere como el encabezado HTTP x-amz-lex-session-attributes.

La información específica de la aplicación que se pasa entre Amazon Lex y una aplicación cliente. El valor debe ser una asignación codificada en base64 y serializada en formato JSON con claves de cadena y valores. El tamaño total de los encabezados sessionAttributes y requestAttributes no puede superar 12 kB.

Para obtener más información, consulte Configuración de atributos de sesión.

userId

El ID del usuario de la aplicación cliente. Amazon Lex lo utiliza para identificar una conversación del usuario con el bot. En tiempo de ejecución, cada solicitud debe contener el campo userID.

Para decidir qué ID de usuario utilizará en la aplicación, tenga en cuenta lo siguiente.

El campo userID no debe contener información de identificación personal del usuario como, por ejemplo, nombre, número de identificación personal u otro tipo de datos personales del usuario final.
Si desea que un usuario inicie una conversación en un dispositivo y esta continúe en otro dispositivo, utilice un identificador específico del usuario.
Si desea que el mismo usuario pueda mantener dos conversaciones independientes en dos dispositivos distintos, elija un identificador específico del dispositivo.
Un usuario no puede mantener dos conversaciones independientes con dos versiones distintas del mismo bot. Por ejemplo, un usuario no puede mantener una conversación con las versiones PROD y BETA del mismo bot. Si piensa que un usuario podría necesitar dos versiones distintas para mantener conversaciones (por ejemplo, para realizar pruebas), incluya el alias del bot en el ID del usuario para separar las dos conversaciones.

Limitaciones de longitud: longitud mínima de 2. La longitud máxima es de 100 caracteres.

Patrón: [0-9a-zA-Z._:-]+

Obligatorio: sí

Cuerpo de la solicitud

La solicitud acepta los siguientes datos binarios.

inputStream

La entrada del usuario en formato de audio PCM u Opus o en formato de texto, tal como se describe en el encabezado HTTP Content-Type.

Puede transmitir datos de audio a Amazon Lex o crear un búfer local que recopile todos los datos de audio antes de enviarlos. En general, transmitir datos de audio ofrece un mejor rendimiento que almacenar los datos en un búfer local.

Obligatorio: sí

Sintaxis de la respuesta


HTTP/1.1 200
Content-Type: contentType
x-amz-lex-intent-name: intentName
x-amz-lex-nlu-intent-confidence: nluIntentConfidence
x-amz-lex-alternative-intents: alternativeIntents
x-amz-lex-slots: slots
x-amz-lex-session-attributes: sessionAttributes
x-amz-lex-sentiment: sentimentResponse
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-input-transcript: inputTranscript
x-amz-lex-encoded-input-transcript: encodedInputTranscript
x-amz-lex-bot-version: botVersion
x-amz-lex-session-id: sessionId
x-amz-lex-active-contexts: activeContexts

audioStream

Elementos de respuesta

Si la acción se realiza correctamente, el servicio devuelve una respuesta HTTP 200.

La respuesta devuelve los siguientes encabezados HTTP.

activeContexts

Una lista de los contextos activos para la sesión. Se puede establecer un contexto cuando se cumple una intención o mediante una llamada a la operación PostContent, PostText o PutSession.

Puede utilizar un contexto para controlar las intenciones que pueden acompañar una intención o para modificar la operación de la aplicación.

alternativeIntents

Entre una y cuatro intenciones alternativas que pueden ser aplicables a la intención del usuario.

Cada alternativa incluye una puntuación que indica la confianza de Amazon Lex en que la intención coincide con la intención del usuario. Las intenciones se ordenan por puntuación de confianza.

botVersion

La versión del bot que ha respondido a la conversación. Puede utilizar esta información para determinar si una versión de un bot rinde mejor que otra versión.

Limitaciones de longitud: longitud mínima de 1. La longitud máxima es de 64.

Patrón: [0-9]+|\$LATEST

contentType

El tipo de contenido, tal como se especifica en el encabezado HTTP Accept de la solicitud.

dialogState

Identifica el estado actual de la interacción del usuario. Amazon Lex devuelve uno de los siguientes valores como dialogState. Si lo desea, el cliente puede utilizar esta información para personalizar la interfaz de usuario.

ElicitIntent: Amazon Lex quiere obtener la intención del usuario. Considere los siguientes ejemplos:

Por ejemplo, un usuario puede expresar una intención (“Quiero pedir una pizza”). Si Amazon Lex no puede deducir la intención del usuario a partir de esta expresión, devolverá este estado de diálogo.
ConfirmIntent: Amazon Lex espera “sí” o “no” como respuesta.

Por ejemplo, Amazon Lex solicita la confirmación del usuario antes de cumplir con una intención. El usuario, en lugar de responder “sí” o “no”, puede responder con información adicional. Por ejemplo, “sí, pero quiero una pizza con masa gruesa” o “no, quiero pedir bebida”. Amazon Lex puede procesar dicha información adicional (en estos ejemplos, actualizar la ranura tipo corteza o cambiar la intención de OrderPizza a OrderDrink).
ElicitSlot: Amazon Lex espera el valor de una ranura para la intención actual.

Por ejemplo, supongamos que, en la respuesta, Amazon Lex envía el mensaje “¿De qué tamaño quiere la pizza?”. Un usuario puede responder con el valor de ranura (p. ej., “mediana”). El usuario también puede proporcionar información adicional en la respuesta (p. ej., “una pizza mediana con masa gruesa”). Amazon Lex puede procesar esta información adicional de forma adecuada.
Fulfilled: indica que la función de Lambda ha cumplido con la intención correctamente.
ReadyForFulfillment: indica que el cliente tiene que cumplir la solicitud.
Failed: indica que la conversación con el usuario ha fallado.

Esto puede ocurrir porque el usuario no ha proporcionado una respuesta adecuada a las preguntas del servicio (puede configurar el número de veces que Amazon Lex puede solicitar cierta información al usuario), porque la función de Lambda no ha podido cumplir con la intención o por otros motivos.

encodedInputTranscript

El texto que se utiliza para procesar la solicitud.

Si la entrada era una transmisión de audio, el campo encodedInputTranscript contiene el texto que se ha extraído de la transmisión de audio. Este es el texto que se procesa realmente para reconocer los valores de las intenciones y slot. Puede utilizar esta información para determinar si Amazon Lex está procesando correctamente el audio que ha enviado.

El campo encodedInputTranscript está codificado en base-64. Debe descodificar el campo antes de que pueda utilizar el valor.

encodedMessage

El mensaje que se va a transmitir al usuario. El mensaje puede provenir de la configuración del bot o de una función de Lambda.

Si la intención no está configurada con una función de Lambda o si la función de Lambda ha devuelto Delegate como dialogAction.type en su respuesta, Amazon Lex decide el siguiente procedimiento y selecciona un mensaje adecuado de la configuración del bot en función del contexto de la interacción actual. Por ejemplo, si Amazon Lex no puede entender las entradas del usuario, utiliza una pregunta aclaratoria.

Al crear una intención, puede asignar mensajes a grupos. Si los mensajes están asignados a grupos, Amazon Lex devuelve un mensaje de cada grupo en la respuesta. El campo del mensaje es una cadena JSON con secuencias de escape que contiene los mensajes. Para obtener más información acerca de la estructura de la cadena JSON devuelta, consulte Formatos de mensajes admitidos.

Si la función de Lambda devuelve un mensaje, Amazon Lex lo envía al cliente en su respuesta.

El campo encodedMessage está codificado en base-64. Debe descodificar el campo antes de que pueda utilizar el valor.

Limitaciones de longitud: longitud mínima de 1. Longitud máxima de 1366.

inputTranscript

Este encabezado ha quedado obsoleto.

El texto que se utiliza para procesar la solicitud.

Solo puede utilizar este campo en las configuraciones regionales de-DE, en-AU, en-GB, en-US, es-419, es-ES, es-US, fr-CA, fr-FR e it-IT. En el resto de configuraciones regionales, el campo inputTranscript es nulo. En su lugar, debe utilizar el campo encodedInputTranscript.

Si la entrada era una transmisión de audio, el campo inputTranscript contiene el texto que se ha extraído de la transmisión de audio. Este es el texto que se procesa realmente para reconocer los valores de las intenciones y slot. Puede utilizar esta información para determinar si Amazon Lex está procesando correctamente el audio que ha enviado.

intentName

La intención del usuario actual de la que Amazon Lex está pendiente.

message

Este encabezado ha quedado obsoleto.

Solo puede utilizar este campo en las configuraciones regionales de-DE, en-AU, en-GB, en-US, es-419, es-ES, es-US, fr-CA, fr-FR e it-IT. En el resto de configuraciones regionales, el campo message es nulo. En su lugar, debe utilizar el campo encodedMessage.

El mensaje que se va a transmitir al usuario. El mensaje puede provenir de la configuración del bot o de una función de Lambda.

Si la función de Lambda devuelve un mensaje, Amazon Lex lo envía al cliente en su respuesta.

Limitaciones de longitud: longitud mínima de 1. La longitud máxima es de 1024 caracteres.

messageFormat

El formato del mensaje de respuesta. Uno de los valores siguientes:

PlainText: el mensaje contiene texto UTF-8 sin formato.
CustomPayload: el mensaje está en un formato personalizado del cliente.
SSML: el mensaje contiene texto con formato para salida de voz.
Composite: el mensaje contiene un objeto JSON con secuencias de escape que contiene uno o más mensajes de los grupos a los que se asignaron cuando se creó la intención.

Valores válidos: PlainText | CustomPayload | SSML | Composite

nluIntentConfidence

Proporciona una puntuación que indica el grado de confianza de Amazon Lex en lo que respecta a la capacidad de una intención devuelta para satisfacer las expectativas del usuario. La puntuación es un valor entre 0,0 y 1,0.

La puntuación es relativa, no absoluta. La puntuación puede cambiar en función de las mejoras de Amazon Lex.

sentimentResponse

La opinión expresada en un enunciado.

Cuando el bot está configurado para enviar enunciados a Amazon Comprehend con el fin de analizar opiniones, este campo contiene el resultado del análisis.

sessionAttributes

Un mapa de pares clave/valor que representa la información de contexto específica de la sesión.

sessionId

El identificador único de la sesión.

slots

Una asignación de cero o más ranuras de intención (pares nombre/valor) que Amazon Lex ha detectado a partir de la entrada del usuario durante la conversación. El campo está codificado en base-64.

Amazon Lex crea una lista de resoluciones que contiene posibles valores para una ranura. El valor que devuelve viene determinado por el valor valueSelectionStrategy seleccionado cuando se creó o actualizó el tipo de ranura. Si valueSelectionStrategy se establece en ORIGINAL_VALUE, se devuelve el valor que proporciona el usuario, en caso de que el valor del usuario sea similar a los valores de la ranura. Si valueSelectionStrategy se establece en TOP_RESOLUTION, Amazon Lex devuelve el primer valor de la lista de resoluciones o, si no hay ninguna lista de resoluciones, un valor nulo. Si no especifica un valor valueSelectionStrategy, el valor predeterminado es ORIGINAL_VALUE.

slotToElicit

Si el valor dialogState es ElicitSlot, devuelve el nombre de la ranura para la que Amazon Lex quiere obtener un valor.

La respuesta devuelve lo siguiente como el cuerpo HTTP.

audioStream: La solicitud (o afirmación) que se transmite al usuario. Depende de la configuración del bot y el contexto. Por ejemplo, si Amazon Lex no ha comprendido la intención del usuario, envía el valor clarificationPrompt configurado para el bot. Si la intención requiere confirmación antes de llevar a cabo la acción de cumplimiento, envía confirmationPrompt. Otro ejemplo: supongamos que la función de Lambda ha cumplido la intención satisfactoriamente y ha enviado un mensaje para transmitirlo al usuario. A continuación, Amazon Lex envía el mensaje en la respuesta.

Errores

BadGatewayException

El bot de Amazon Lex aún se está compilando o uno de los servicios dependientes (Amazon Polly o AWS Lambda) ha fallado debido a un error de servicio interno.

Código de estado HTTP: 502

BadRequestException

Se ha producido un error al validar la solicitud, no hay mensajes útiles en el contexto o la compilación del bot ha fallado, está en curso o contiene cambios sin compilar.

Código de estado HTTP: 400

ConflictException

Dos clientes utilizan la misma cuenta de AWS, el mismo bot de Amazon Lex y el mismo ID de usuario.

Código de estado HTTP: 409

DependencyFailedException

Una de las dependencias, como AWS Lambda o Amazon Polly, ha generado una excepción. Por ejemplo:

Si Amazon Lex no tiene permisos suficientes para llamar a una función de Lambda
Si una función de Lambda tarda más de 30 segundos en ejecutarse
Si una función de Lambda de cumplimiento devuelve una acción de diálogo Delegate sin eliminar ningún valor de ranura.

Código de estado HTTP: 424

InternalFailureException

Error de servicio interno. Vuelva a intentar la llamada.

Código de estado HTTP: 500

LimitExceededException

Se ha superado un límite.

Código de estado HTTP: 429

LoopDetectedException

Esta excepción no se utiliza.

Código de estado HTTP: 508

NotAcceptableException

El encabezado de aceptación de la solicitud no cuenta con un valor válido.

Código de estado HTTP: 406

NotFoundException

No se ha encontrado el recurso (como el bot o un alias de Amazon Lex) al que se hace referencia.

Código de estado HTTP: 404

RequestTimeoutException

El mensaje de voz de la entrada es demasiado largo.

Código de estado HTTP: 408

UnsupportedMediaTypeException

El encabezado Content-Type (API PostContent) tiene un valor no válido.

Código de estado HTTP: 415

Ejemplos

Ejemplo 1

En esta solicitud, la URI identifica un bot (Traffic), una versión del bot ($LATEST) y el nombre del usuario final (someuser). El encabezado Content-Type identifica el formato del audio en el cuerpo. Amazon Lex también admite otros formatos. Para convertir audio de un formato a otro, si es necesario, puede utilizar el software de código abierto SoX. Para especificar el formato en el que desea obtener la respuesta, agregue el encabezado HTTP Accept.

En la respuesta, el encabezado x-amz-lex-message muestra la respuesta que ha devuelto Amazon Lex. A continuación, el cliente puede enviar esta respuesta al usuario. El mismo mensaje se envía en formato audio/MPEG mediante codificación fragmentada (según se solicite).

Solicitud de muestra


"POST /bot/Traffic/alias/$LATEST/user/someuser/content HTTP/1.1[\r][\n]"
"x-amz-lex-session-attributes: eyJ1c2VyTmFtZSI6IkJvYiJ9[\r][\n]"
"Content-Type: audio/x-l16; channel-count=1; sample-rate=16000f[\r][\n]"
"Accept: audio/mpeg[\r][\n]"
"Host: runtime.lex.us-east-1.amazonaws.com[\r][\n]"
"Authorization: AWS4-HMAC-SHA256 Credential=BLANKED_OUT/20161230/us-east-1/lex/aws4_request, 
SignedHeaders=accept;content-type;host;x-amz-content-sha256;x-amz-date;x-amz-lex-session-attributes, Signature=78ca5b54ea3f64a17ff7522de02cd90a9acd2365b45a9ce9b96ea105bb1c7ec2[\r][\n]"
"X-Amz-Date: 20161230T181426Z[\r][\n]"
"X-Amz-Content-Sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855[\r][\n]"
"Transfer-Encoding: chunked[\r][\n]"
"Connection: Keep-Alive[\r][\n]"
"User-Agent: Apache-HttpClient/4.5.x (Java/1.8.0_112)[\r][\n]"
"Accept-Encoding: gzip,deflate[\r][\n]"
"[\r][\n]"
"1000[\r][\n]"
"[0x7][0x0][0x7][0x0][\n]"
"[0x0][0x7][0x0][0xfc][0xff][\n]"
"[0x0][\n]"
…

Respuesta de ejemplo


"HTTP/1.1 200 OK[\r][\n]"
"x-amzn-RequestId: cc8b34af-cebb-11e6-a35c-55f3a992f28d[\r][\n]"
"x-amz-lex-message: Sorry, can you repeat that?[\r][\n]"
"x-amz-lex-dialog-state: ElicitIntent[\r][\n]"
"x-amz-lex-session-attributes: eyJ1c2VyTmFtZSI6IkJvYiJ9[\r][\n]"
"Content-Type: audio/mpeg[\r][\n]"
"Transfer-Encoding: chunked[\r][\n]"
"Date: Fri, 30 Dec 2016 18:14:28 GMT[\r][\n]"
"[\r][\n]"               
"2000[\r][\n]"
"ID3[0x4][0x0][0x0][0x0][0x0][0x0]#TSSE[0x0][0x0][0x0][0xf][0x0][0x0][0x3]Lavf57.41.100[0x0][0x0][0x0][0x0][0x0][0x0][0x0][0x0][0x0][0x0][0x0][0xff][0xf3]`[0xc4][0x0][0x1b]{[0x8d][0xe8][0x1]C[0x18][0x1][0x0]J[0xe0]`b[0xdd][0xd1][0xb][0xfd][0x11][0xdf][0xfe]";[0xbb][0xbb][0x9f][0xee][0xee][0xee][0xee]|DDD/[0xff][0xff][0xff][0xff]www?D[0xf7]w^?[0xff][0xfa]h[0x88][0x85][0xfe][0x88][0x88][0x88][[0xa2]'[0xff][0xfa]"{[0x9f][0xe8][0x88]]D[0xeb][0xbb][0xbb][0xa2]!u[0xfd][0xdd][0xdf][0x88][0x94][0x0]F[0xef][0xa1]8[0x0][0x82]w[0x88]N[0x0][0x0][0x9b][0xbb][0xe8][0xe
…

Véase también

Para obtener más información sobre el uso de esta API en uno de los idiomas específicos AWS SDKs, consulte lo siguiente:

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

GetSession

PostText