Syntaxe de la demande Paramètres de demande URI Corps de la demande Syntaxe de la réponse Eléments de réponse Erreurs consultez aussi

Si vous utilisez Amazon Lex V2, consultez plutôt le guide Amazon Lex V2.

Si vous utilisez Amazon Lex V1, nous vous recommandons de mettre à niveau vos robots vers Amazon Lex V2. Nous n'ajoutons plus de nouvelles fonctionnalités à la V1 et recommandons vivement d'utiliser la V2 pour tous les nouveaux robots.

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.

PostText

Envoie les données de l'utilisateur à Amazon Lex. Les applications clientes peuvent utiliser cette API pour envoyer des demandes à Amazon Lex lors de l'exécution. Amazon Lex interprète ensuite les entrées de l'utilisateur à l'aide du modèle d'apprentissage automatique qu'il a conçu pour le bot.

En réponse, Amazon Lex renvoie le suivant message pour indiquer à l'utilisateur un affichage facultatifresponseCard. Examinez les exemples de messages suivants :

Lorsqu'un utilisateur saisit « Je voudrais une pizza », Amazon Lex peut renvoyer une réponse contenant un message demandant des informations sur le créneau (par exemple, PizzaSize) : « Quelle taille de pizza souhaitez-vous ? »
Une fois que l'utilisateur a fourni toutes les informations relatives à la commande de pizza, Amazon Lex peut renvoyer une réponse contenant un message pour obtenir la confirmation de l'utilisateur « Poursuivre la commande de pizza ? ».
Une fois que l'utilisateur a répondu « oui » à une invite de confirmation, Amazon Lex peut renvoyer une déclaration de conclusion : « Merci, votre pizza au fromage a été commandée ».

Tous les messages Amazon Lex ne nécessitent pas de réponse de l'utilisateur. Par exemple, une déclaration de conclusion ne nécessite pas de réponse. Certains messages nécessitent uniquement une réponse « oui » ou « non » de l'utilisateur. En outremessage, Amazon Lex fournit un contexte supplémentaire sur le message contenu dans la réponse, que vous pouvez utiliser pour améliorer le comportement des clients, par exemple pour afficher l'interface utilisateur client appropriée. Il s'agit des slots champs slotToElicit dialogStateintentName,, et de la réponse. Considérez les exemples suivants :

Si le message vise à obtenir des données d'emplacement, Amazon Lex renvoie les informations contextuelles suivantes :
- dialogStateréglé sur ElicitSlot
- intentNamedéfini sur le nom de l'intention dans le contexte actuel
- slotToElicitdéfini sur le nom du slot pour lequel message il demande des informations
- slotsdéfini sur une carte de slots, configurée en fonction de l'intention, avec des valeurs actuellement connues
Si le message est une invite de confirmation, le dialogState est défini sur ConfirmIntent et SlotToElicit est défini sur null.
Si le message est une demande de clarification (configurée en fonction de l'intention) qui indique que l'intention de l'utilisateur n'est pas comprise, le dialogState est défini sur ElicitIntent et slotToElicit est défini sur null.

En outre, Amazon Lex renvoie également des informations spécifiques à votre applicationsessionAttributes. Pour plus d'informations, consultez la section Gestion du contexte de conversation.

Syntaxe de la demande


POST /bot/botName/alias/botAlias/user/userId/text HTTP/1.1
Content-type: application/json

{
   "activeContexts": [ 
      { 
         "name": "string",
         "parameters": { 
            "string" : "string" 
         },
         "timeToLive": { 
            "timeToLiveInSeconds": number,
            "turnsToLive": number
         }
      }
   ],
   "inputText": "string",
   "requestAttributes": { 
      "string" : "string" 
   },
   "sessionAttributes": { 
      "string" : "string" 
   }
}

Paramètres de demande URI

La demande utilise les paramètres URI suivants.

botAlias

Alias du bot Amazon Lex.

Obligatoire : oui

botName

Nom du bot Amazon Lex.

Obligatoire : oui

userId

ID de l'utilisateur de l'application cliente. Amazon Lex l'utilise pour identifier la conversation d'un utilisateur avec votre bot. Au moment de l'exécution, chaque demande doit contenir le userID champ.

Pour décider de l'ID utilisateur à utiliser pour votre application, tenez compte des facteurs suivants.

Le userID champ ne doit contenir aucune information personnellement identifiable de l'utilisateur, par exemple son nom, son numéro d'identification personnel ou toute autre information personnelle de l'utilisateur final.
Si vous souhaitez qu'un utilisateur entame une conversation sur un appareil et la poursuive sur un autre, utilisez un identifiant spécifique à l'utilisateur.
Si vous souhaitez que le même utilisateur puisse avoir deux conversations indépendantes sur deux appareils différents, choisissez un identifiant spécifique à l'appareil.
Un utilisateur ne peut pas avoir deux conversations indépendantes avec deux versions différentes du même bot. Par exemple, un utilisateur ne peut pas avoir de conversation avec les versions PROD et BETA du même bot. Si vous pensez qu'un utilisateur devra avoir une conversation avec deux versions différentes, par exemple pendant le test, incluez l'alias du bot dans l'ID utilisateur pour séparer les deux conversations.

Contraintes de longueur : longueur minimale de 2. Longueur maximum de 100.

Modèle : [0-9a-zA-Z._:-]+

Obligatoire : oui

Corps de la demande

Cette demande accepte les données suivantes au format JSON.

activeContexts

Liste des contextes actifs pour la demande. Un contexte peut être activé lorsqu'une intention précédente est satisfaite, ou en incluant le contexte dans la demande,

Si vous ne spécifiez pas de liste de contextes, Amazon Lex utilisera la liste actuelle des contextes pour la session. Si vous spécifiez une liste vide, tous les contextes de la session sont effacés.

Type : tableau d’objets ActiveContext

Membres du tableau : nombre minimum de 0 élément. Nombre maximum de 20 éléments.

Obligatoire : non

inputText

Le texte saisi par l'utilisateur (Amazon Lex interprète ce texte).

Lorsque vous utilisez l'AWS CLI, vous ne pouvez pas transmettre d'URL dans le --input-text paramètre. Passez plutôt l'URL en utilisant le --cli-input-json paramètre.

Type : chaîne

Contraintes de longueur : Longueur minimum de 1. Longueur maximum de 1024.

Obligatoire : oui

requestAttributes

Informations spécifiques à la demande transmises entre Amazon Lex et une application cliente.

L'espace de noms x-amz-lex: est réservé aux attributs spéciaux. Ne créez aucun attribut de demande avec le préfixex-amz-lex:.

Pour plus d'informations, consultez la section Définition des attributs de demande.

Type : mappage chaîne/chaîne

Obligatoire : non

sessionAttributes

Informations spécifiques à l'application transmises entre Amazon Lex et une application cliente.

Pour plus d'informations, consultez la section Définition des attributs de session.

Type : mappage chaîne/chaîne

Obligatoire : non

Syntaxe de la réponse


HTTP/1.1 200
Content-type: application/json

{
   "activeContexts": [ 
      { 
         "name": "string",
         "parameters": { 
            "string" : "string" 
         },
         "timeToLive": { 
            "timeToLiveInSeconds": number,
            "turnsToLive": number
         }
      }
   ],
   "alternativeIntents": [ 
      { 
         "intentName": "string",
         "nluIntentConfidence": { 
            "score": number
         },
         "slots": { 
            "string" : "string" 
         }
      }
   ],
   "botVersion": "string",
   "dialogState": "string",
   "intentName": "string",
   "message": "string",
   "messageFormat": "string",
   "nluIntentConfidence": { 
      "score": number
   },
   "responseCard": { 
      "contentType": "string",
      "genericAttachments": [ 
         { 
            "attachmentLinkUrl": "string",
            "buttons": [ 
               { 
                  "text": "string",
                  "value": "string"
               }
            ],
            "imageUrl": "string",
            "subTitle": "string",
            "title": "string"
         }
      ],
      "version": "string"
   },
   "sentimentResponse": { 
      "sentimentLabel": "string",
      "sentimentScore": "string"
   },
   "sessionAttributes": { 
      "string" : "string" 
   },
   "sessionId": "string",
   "slots": { 
      "string" : "string" 
   },
   "slotToElicit": "string"
}

Eléments de réponse

Si l’action aboutit, le service renvoie une réponse HTTP 200.

Les données suivantes sont renvoyées au format JSON par le service.

activeContexts

Liste des contextes actifs pour la session. Un contexte peut être défini lorsqu'une intention est remplie ou en appelant l'PutSessionopération PostContentPostText, ou.

Vous pouvez utiliser un contexte pour contrôler les intentions qui peuvent donner suite à une intention ou pour modifier le fonctionnement de votre application.

Type : tableau d’objets ActiveContext

Membres du tableau : nombre minimum de 0 élément. Nombre maximum de 20 éléments.

alternativeIntents

Une à quatre intentions alternatives qui peuvent être applicables à l'intention de l'utilisateur.

Chaque alternative inclut un score qui indique dans quelle mesure Amazon Lex est sûr que l'intention correspond à celle de l'utilisateur. Les intentions sont triées en fonction du score de confiance.

Type : tableau d’objets PredictedIntent

Membres du tableau : nombre maximum de 4 éléments.

botVersion

Version du bot qui a répondu à la conversation. Vous pouvez utiliser ces informations pour déterminer si une version d'un bot est plus performante qu'une autre.

Type : chaîne

Contraintes de longueur : longueur minimum de 1. Longueur maximale de 64.

Modèle : [0-9]+|\$LATEST

dialogState

Identifie l'état actuel de l'interaction de l'utilisateur. Amazon Lex renvoie l'une des valeurs suivantes sous la formedialogState. Le client peut éventuellement utiliser ces informations pour personnaliser l'interface utilisateur.

ElicitIntent- Amazon Lex souhaite obtenir l'intention des utilisateurs.

Par exemple, un utilisateur peut exprimer une intention (« Je veux commander une pizza »). Si Amazon Lex ne parvient pas à déduire l'intention de l'utilisateur à partir de cet énoncé, il renverra ce DialogState.
ConfirmIntent- Amazon Lex attend une réponse « oui » ou « non ».

Par exemple, Amazon Lex souhaite obtenir la confirmation de l'utilisateur avant de réaliser une intention.

Au lieu d'un simple « oui » ou « non », un utilisateur peut répondre en fournissant des informations supplémentaires. Par exemple, « oui, mais fais-en une pizza à croûte épaisse » ou « Non, je veux commander un verre ». Amazon Lex peut traiter ces informations supplémentaires (dans ces exemples, mettre à jour la valeur de l'emplacement du type de croûte ou modifier l'intention de OrderPizza à OrderDrink).
ElicitSlot- Amazon Lex attend une valeur de créneau correspondant à l'intention actuelle.

Supposons par exemple qu'Amazon Lex envoie le message suivant dans sa réponse : « Quelle taille de pizza aimeriez-vous ? ». Un utilisateur peut répondre en indiquant la valeur de l'emplacement (par exemple, « moyen »). L'utilisateur peut également fournir des informations supplémentaires dans la réponse (par exemple, « pizza à croûte moyenne épaisse »). Amazon Lex peut traiter ces informations supplémentaires de manière appropriée.
Fulfilled- Indique que la fonction Lambda configurée pour l'intention a répondu avec succès à l'intention.
ReadyForFulfillment- Indique que le client doit réaliser son intention.
Failed- Indique que la conversation avec l'utilisateur a échoué.

Cela peut se produire pour diverses raisons, notamment parce que l'utilisateur n'a pas répondu de manière appropriée aux demandes du service (vous pouvez configurer le nombre de fois qu'Amazon Lex peut demander à un utilisateur des informations spécifiques) ou que la fonction Lambda n'a pas répondu à son intention.

Type : chaîne

intentName

L'intention actuelle de l'utilisateur dont Amazon Lex a connaissance.

Type : chaîne

message

Le message à transmettre à l'utilisateur. Le message peut provenir de la configuration du bot ou d'une fonction Lambda.

Si l'intention n'est pas configurée avec une fonction Lambda, ou si la fonction Lambda est renvoyée Delegate comme réponse, Amazon Lex décide de la marche à suivre et sélectionne un message approprié dans la configuration du bot en fonction du contexte d'interaction actuel. dialogAction.type Par exemple, si Amazon Lex n'est pas en mesure de comprendre les informations saisies par les utilisateurs, il envoie un message de demande de clarification.

Lorsque vous créez une intention, vous pouvez attribuer des messages à des groupes. Lorsque des messages sont affectés à des groupes, Amazon Lex renvoie un message de chaque groupe dans la réponse. Le champ de message est une chaîne JSON échappée contenant les messages. Pour plus d'informations sur la structure de la chaîne JSON renvoyée, consultezFormats de message pris en charge.

Si la fonction Lambda renvoie un message, Amazon Lex le transmet au client dans sa réponse.

Type : chaîne

Contraintes de longueur : Longueur minimum de 1. Longueur maximum de 1024.

messageFormat

Format du message de réponse. L'une des valeurs suivantes :

PlainText- Le message contient du texte UTF-8 brut.
CustomPayload- Le message est un format personnalisé défini par la fonction Lambda.
SSML- Le message contient du texte formaté pour la sortie vocale.
Composite- Le message contient un objet JSON échappé contenant un ou plusieurs messages provenant des groupes auxquels les messages ont été affectés lors de la création de l'intention.

Type : chaîne

Valeurs valides : PlainText | CustomPayload | SSML | Composite

nluIntentConfidence

Fournit un score qui indique dans quelle mesure Amazon Lex est sûr que l'intention renvoyée correspond à l'intention de l'utilisateur. Le score est compris entre 0,0 et 1,0. Pour plus d'informations, consultez la section Scores de confiance.

Le score est un score relatif et non un score absolu. Le score peut changer en fonction des améliorations apportées à Amazon Lex.

Type : objet IntentConfidence

responseCard

Représente les options dont dispose l'utilisateur pour répondre à l'invite en cours. La carte de réponse peut provenir de la configuration du bot (dans la console Amazon Lex, cliquez sur le bouton de configuration à côté d'un emplacement) ou d'un crochet de code (fonction Lambda).

Type : objet ResponseCard

sentimentResponse

Le sentiment exprimé dans et dans l'énoncé.

Lorsque le bot est configuré pour envoyer des énoncés à Amazon Comprehend à des fins d'analyse des sentiments, ce champ contient le résultat de l'analyse.

Type : objet SentimentResponse

sessionAttributes

Une carte de paires clé-valeur représentant les informations contextuelles spécifiques à la session.

Type : mappage chaîne/chaîne

sessionId

Identifiant unique de la session.

Type : chaîne

slots

Les créneaux d'intention détectés par Amazon Lex à partir des données saisies par l'utilisateur dans la conversation.

Amazon Lex crée une liste de résolutions contenant les valeurs probables pour un emplacement. La valeur renvoyée est déterminée par la valeur valueSelectionStrategy sélectionnée lors de la création ou de la mise à jour du type d'emplacement. S'il valueSelectionStrategy est défini surORIGINAL_VALUE, la valeur fournie par l'utilisateur est renvoyée, si la valeur utilisateur est similaire aux valeurs des emplacements. Si la valeur valueSelectionStrategy est définie TOP_RESOLUTION sur Amazon Lex, elle renvoie la première valeur de la liste de résolutions ou, en l'absence de liste de résolutions, la valeur nulle. Si vous ne spécifiez pas devalueSelectionStrategy, la valeur par défaut estORIGINAL_VALUE.

Type : mappage chaîne/chaîne

slotToElicit

Si la dialogState valeur estElicitSlot, renvoie le nom de l'emplacement pour lequel Amazon Lex demande une valeur.

Type : chaîne

Erreurs

BadGatewayException

Soit le bot Amazon Lex est toujours en cours de création, soit l'un des services dépendants (Amazon Polly, AWS Lambda) a échoué en raison d'une erreur de service interne.

Code d’état HTTP : 502

BadRequestException

La validation de la demande a échoué, il n'y a aucun message utilisable dans le contexte, ou la création du bot a échoué, est toujours en cours ou contient des modifications non intégrées.

Code d’état HTTP : 400

ConflictException

Deux clients utilisent le même compte AWS, le même bot Amazon Lex et le même ID utilisateur.

Code d’état HTTP : 409

DependencyFailedException

L'une des dépendances, telle qu'AWS Lambda ou Amazon Polly, a généré une exception. Par exemple,

Si Amazon Lex ne dispose pas des autorisations suffisantes pour appeler une fonction Lambda.
Si l'exécution d'une fonction Lambda prend plus de 30 secondes.
Si une fonction Lambda d'exécution renvoie une action de Delegate dialogue sans supprimer aucune valeur d'intervalle.

Code d'état HTTP : 424

InternalFailureException

Erreur de service interne. Réessayez l'appel.

Code d’état HTTP : 500

LimitExceededException

Dépassement d'une limite.

Code d’état HTTP : 429

LoopDetectedException

Cette exception n'est pas utilisée.

Code d'état HTTP : 508

NotFoundException

La ressource (telle que le bot Amazon Lex ou un alias) à laquelle il est fait référence est introuvable.

Code d’état HTTP : 404

consultez aussi

Pour plus d’informations sur l’utilisation de cette API dans l’un des kits SDK AWS spécifiques au langage, consultez les ressources suivantes :

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

PostContent

PutSession