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.

PutBot

Crée un bot conversationnel Amazon Lex ou remplace un bot existant. Lorsque vous créez ou mettez à jour un bot, il vous suffit de spécifier un nom, un paramètre régional et de préciser si le bot est destiné aux enfants de moins de 13 ans. Vous pouvez l'utiliser pour ajouter des intentions ultérieurement ou pour supprimer des intentions d'un bot existant. Lorsque vous créez un bot avec le minimum d'informations, celui-ci est créé ou mis à jour, mais Amazon Lex renvoie la réponseFAILED. Vous pouvez créer le bot après avoir ajouté une ou plusieurs intentions. Pour plus d'informations sur les robots Amazon Lex, consultezAmazon Lex : comment ça marche.

Si vous spécifiez le nom d'un bot existant, les champs de la demande remplacent les valeurs existantes dans la $LATEST version du bot. Amazon Lex supprime tous les champs pour lesquels vous ne fournissez pas de valeurs dans la demande, à l'exception des privacySettings champs idleTTLInSeconds et, qui sont définis sur leurs valeurs par défaut. Si vous ne spécifiez aucune valeur pour les champs obligatoires, Amazon Lex émet une exception.

Cette opération exige des autorisations pour l'action lex:PutBot. Pour de plus amples informations, veuillez consulter Identity and Access Management pour Amazon Lex.

Syntaxe de la demande


PUT /bots/name/versions/$LATEST HTTP/1.1
Content-type: application/json

{
   "abortStatement": { 
      "messages": [ 
         { 
            "content": "string",
            "contentType": "string",
            "groupNumber": number
         }
      ],
      "responseCard": "string"
   },
   "checksum": "string",
   "childDirected": boolean,
   "clarificationPrompt": { 
      "maxAttempts": number,
      "messages": [ 
         { 
            "content": "string",
            "contentType": "string",
            "groupNumber": number
         }
      ],
      "responseCard": "string"
   },
   "createVersion": boolean,
   "description": "string",
   "detectSentiment": boolean,
   "enableModelImprovements": boolean,
   "idleSessionTTLInSeconds": number,
   "intents": [ 
      { 
         "intentName": "string",
         "intentVersion": "string"
      }
   ],
   "locale": "string",
   "nluIntentConfidenceThreshold": number,
   "processBehavior": "string",
   "tags": [ 
      { 
         "key": "string",
         "value": "string"
      }
   ],
   "voiceId": "string"
}

Paramètres de demande URI

La demande utilise les paramètres URI suivants.

name

Le nom du bot. Le nom ne distingue pas les majuscules et minuscules.

Contraintes de longueur : longueur minimale de 2. Longueur maximale de 50.

Modèle : ^([A-Za-z]_?)+$

Obligatoire : oui

Corps de la demande

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

abortStatement

Lorsqu'Amazon Lex ne parvient pas à comprendre la saisie de l'utilisateur dans son contexte, il essaie d'obtenir les informations à plusieurs reprises. Amazon Lex envoie ensuite le message défini abortStatement à l'utilisateur, puis annule la conversation. Pour définir le nombre de tentatives, utilisez le valueElicitationPrompt champ correspondant au type de slot.

Par exemple, dans un robot de commande de pizzas, Amazon Lex peut demander à un utilisateur « Quel type de croûte souhaitez-vous ? » Si la réponse de l'utilisateur n'est pas l'une des réponses attendues (par exemple, « croûte mince », « plat profond », etc.), Amazon Lex essaie d'obtenir une réponse correcte plusieurs fois de plus.

Par exemple, dans une application de commande de pizzas, OrderPizza cela peut être l'une des intentions. Cette intention peut nécessiter le CrustType slot. Vous spécifiez le valueElicitationPrompt champ lorsque vous créez le CrustType slot.

Si vous avez défini une intention de remplacement, la déclaration d'annulation ne sera pas envoyée à l'utilisateur, c'est l'intention de secours qui est utilisée à la place. Pour plus d'informations, consultez AMAZON. FallbackIntent.

Type : objet Statement

Obligatoire : non

checksum

Identifie une révision spécifique de la $LATEST version.

Lorsque vous créez un nouveau bot, laissez le checksum champ vide. Si vous spécifiez une somme de contrôle, vous obtenez une BadRequestException exception.

Lorsque vous souhaitez mettre à jour un bot, définissez le checksum champ sur la somme de contrôle de la dernière révision de la $LATEST version. Si vous ne spécifiez pas le checksum champ, ou si la somme de contrôle ne correspond pas à la $LATEST version, vous obtenez une PreconditionFailedException exception.

Type : chaîne

Obligatoire : non

childDirected

Pour chaque bot Amazon Lex créé avec Amazon Lex Model Building Service, vous devez indiquer si votre utilisation d'Amazon Lex est liée à un site Web, à un programme ou à une autre application destiné ou ciblé, en tout ou en partie, aux enfants de moins de 13 ans et soumis à la loi COPPA (Children's Online Privacy Protection Act) en spécifiant true ou false dans le childDirected champ. trueEn spécifiant dans ce childDirected champ, vous confirmez que votre utilisation d'Amazon Lex est liée à un site Web, à un programme ou à une autre application destiné ou ciblé, en tout ou en partie, aux enfants de moins de 13 ans et soumis à la COPPA. falseEn spécifiant dans ce childDirected champ, vous confirmez que votre utilisation d'Amazon Lex n'est pas liée à un site Web, à un programme ou à une autre application destiné ou ciblé, en tout ou en partie, aux enfants de moins de 13 ans et soumis à la COPPA. Vous ne pouvez pas spécifier de valeur par défaut pour le childDirected champ qui ne reflète pas exactement si votre utilisation d'Amazon Lex est liée à un site Web, à un programme ou à une autre application destiné ou ciblé, en tout ou en partie, aux enfants de moins de 13 ans et soumis à la COPPA.

Si votre utilisation d'Amazon Lex concerne un site Web, un programme ou une autre application destinés, en tout ou en partie, à des enfants de moins de 13 ans, vous devez obtenir le consentement parental vérifiable requis en vertu de la COPPA. Pour plus d'informations concernant l'utilisation d'Amazon Lex en relation avec des sites Web, des programmes ou d'autres applications destinés ou ciblés, en tout ou en partie, aux enfants de moins de 13 ans, consultez la FAQ Amazon Lex.

Type : booléen

Obligatoire : oui

clarificationPrompt

Lorsqu'Amazon Lex ne comprend pas l'intention de l'utilisateur, il utilise ce message pour obtenir des éclaircissements. Pour spécifier combien de fois Amazon Lex doit répéter l'invite de clarification, utilisez le maxAttempts champ. Si Amazon Lex ne comprend toujours pas, il envoie le message abortStatement sur le terrain.

Lorsque vous créez une invite de clarification, assurez-vous qu'elle suggère la bonne réponse de la part de l'utilisateur. Par exemple, pour un bot qui commande des pizzas et des boissons, vous pouvez créer cette invite de clarification : « Que souhaitez-vous faire ? Vous pouvez dire « Commandez une pizza » ou « Commandez un verre ». »

Si vous avez défini une intention de remplacement, elle sera invoquée si l'invite de clarification est répétée le nombre de fois défini dans le maxAttempts champ. Pour plus d'informations, consultez AMAZON. FallbackIntent.

Si vous ne définissez pas d'invite de clarification, Amazon Lex renverra une exception 400 Bad Request au moment de l'exécution dans trois cas :

Demande de suivi : lorsque l'utilisateur répond à une demande de suivi sans fournir d'intention. Par exemple, en réponse à une demande de suivi indiquant « Voulez-vous autre chose aujourd'hui ? » l'utilisateur répond « Oui ». Amazon Lex renverra une exception 400 Bad Request car aucune demande de clarification n'est à envoyer à l'utilisateur pour obtenir une intention.
Fonction Lambda : lorsque vous utilisez une fonction Lambda, vous renvoyez un type de dialogue. ElicitIntent Amazon Lex n'étant pas invité à clarifier l'intention de l'utilisateur, il renvoie une exception 400 Bad Request.
PutSession opération - Lorsque vous utilisez l'PutSessionopération, vous envoyez un type ElicitIntent de dialogue. Amazon Lex n'étant pas invité à clarifier l'intention de l'utilisateur, il renvoie une exception 400 Bad Request.

Type : objet Prompt

Obligatoire : non

createVersion

Lorsqu'il est réglé sur true une nouvelle version numérotée du bot est créée. Cela revient à appeler l'CreateBotVersionopération. Si vous ne le spécifiez pascreateVersion, la valeur par défaut estfalse.

Type : booléen

Obligatoire : non

description

Description du bot.

Type : chaîne

Contraintes de longueur : longueur minimum de 0. Longueur maximum de 200.

Obligatoire : non

detectSentiment

Lorsque ce paramètre est défini sur « true utilisateur », les énoncés sont envoyés à Amazon Comprehend pour analyse des sentiments. Si vous ne le spécifiez pasdetectSentiment, la valeur par défaut estfalse.

Type : booléen

Obligatoire : non

enableModelImprovements

Réglez sur true pour permettre l'accès aux améliorations de compréhension du langage naturel.

Lorsque vous définissez le enableModelImprovements paramètre sur, true vous pouvez l'nluIntentConfidenceThresholdutiliser pour configurer les scores de confiance. Pour plus d'informations, consultez la section Scores de confiance.

Vous ne pouvez définir le enableModelImprovements paramètre que dans certaines régions. Si vous définissez le paramètre surtrue, votre bot a accès à des améliorations de précision.

Les régions dans lesquelles vous pouvez définir le enableModelImprovements paramètre false pour les paramètres régionaux en-US sont les suivantes :

USA Est (Virginie du Nord) (us-east-1)
USA Ouest (Oregon) (us-west-2)
Asie-Pacifique (Sydney) (ap-southeast-2)
EU (Irlande) (eu-west-1)

Dans les autres régions et régions, le enableModelImprovements paramètre est défini true par défaut. Dans ces régions et régions, le fait de définir le paramètre false sur génère une ValidationException exception.

Type : booléen

Obligatoire : non

idleSessionTTLInSeconds

Durée maximale en secondes pendant laquelle Amazon Lex conserve les données collectées au cours d'une conversation.

Une session d'interaction utilisateur reste active pendant la durée spécifiée. Si aucune conversation n'a lieu pendant cette période, la session expire et Amazon Lex supprime toutes les données fournies avant l'expiration du délai.

Supposons, par exemple, qu'un utilisateur choisisse son OrderPizza intention, mais qu'il se laisse distraire à mi-chemin de la commande. Si l'utilisateur ne termine pas la commande dans le délai imparti, Amazon Lex supprime les informations sur les créneaux qu'il a collectées et l'utilisateur doit recommencer à zéro.

Si vous n'incluez pas l'idleSessionTTLInSecondsélément dans une demande d'PutBotopération, Amazon Lex utilise la valeur par défaut. Cela est également vrai si la demande remplace un bot existant.

La valeur par défaut est de 300 secondes (5 minutes).

Type : entier

Plage valide : Valeur minimum de 60. Valeur maximum de 86 400.

Obligatoire : non

intents

Tableau d’objets Intent. Chaque intention représente une commande qu'un utilisateur peut exprimer. Par exemple, un robot de commande de pizzas peut soutenir une OrderPizza intention. Pour de plus amples informations, veuillez consulter Amazon Lex : comment ça marche.

Type : tableau d’objets Intent

Obligatoire : non

locale

Spécifie les paramètres régionaux cibles pour le bot. Toute intention utilisée dans le bot doit être compatible avec les paramètres régionaux du bot.

L’argument par défaut est en-US.

Type : chaîne

Obligatoire : oui

nluIntentConfidenceThreshold

Détermine le seuil auquel Amazon Lex insérera AMAZON.FallbackIntent le AMAZON.KendraSearchIntent ou les deux lorsqu'il renvoie des intentions alternatives dans une PostTextréponse PostContentou. AMAZON.FallbackIntentet ne AMAZON.KendraSearchIntent sont insérés que s'ils sont configurés pour le bot.

Vous devez définir le enableModelImprovements paramètre sur true pour utiliser les scores de confiance dans les régions suivantes.

USA Est (Virginie du Nord) (us-east-1)
USA Ouest (Oregon) (us-west-2)
Asie-Pacifique (Sydney) (ap-southeast-2)
EU (Irlande) (eu-west-1)

Dans les autres régions, le enableModelImprovements paramètre est défini true par défaut.

Supposons, par exemple, qu'un bot soit configuré avec le seuil de confiance de 0,80 et leAMAZON.FallbackIntent. Amazon Lex renvoie trois intentions alternatives avec les scores de confiance suivants : IntentA (0,70), IntentB (0,60), IntentC (0,50). La réponse de l'PostTextopération serait la suivante :

AMAZON. FallbackIntent
à Tenta
Intente B
Intente C

Type : double

Plage valide : Valeur minimum de 0. Valeur maximale de 1.

Obligatoire : non

processBehavior

Si vous définissez l'processBehaviorélément surBUILD, Amazon Lex crée le bot afin qu'il puisse être exécuté. Si vous définissez l'élément SAVE sur Amazon Lex, il enregistre le bot, mais ne le crée pas.

Si vous ne spécifiez pas cette valeur, la valeur par défaut estBUILD.

Type : chaîne

Valeurs valides : SAVE | BUILD

Obligatoire : non

tags

Une liste de balises à ajouter au bot. Vous ne pouvez ajouter des balises que lorsque vous créez un bot, vous ne pouvez pas utiliser l'PutBotopération pour mettre à jour les balises d'un bot. Pour mettre à jour les balises, utilisez l'opération TagResource.

Type : tableau d’objets Tag

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

Obligatoire : non

voiceId

L'identifiant vocal Amazon Polly que vous souhaitez qu'Amazon Lex utilise pour les interactions vocales avec l'utilisateur. Les paramètres régionaux configurés pour la voix doivent correspondre aux paramètres régionaux du bot. Pour plus d'informations, consultez Voices in Amazon Polly dans le manuel Amazon Polly Developer Guide.

Type : chaîne

Obligatoire : non

Syntaxe de la réponse


HTTP/1.1 200
Content-type: application/json

{
   "abortStatement": { 
      "messages": [ 
         { 
            "content": "string",
            "contentType": "string",
            "groupNumber": number
         }
      ],
      "responseCard": "string"
   },
   "checksum": "string",
   "childDirected": boolean,
   "clarificationPrompt": { 
      "maxAttempts": number,
      "messages": [ 
         { 
            "content": "string",
            "contentType": "string",
            "groupNumber": number
         }
      ],
      "responseCard": "string"
   },
   "createdDate": number,
   "createVersion": boolean,
   "description": "string",
   "detectSentiment": boolean,
   "enableModelImprovements": boolean,
   "failureReason": "string",
   "idleSessionTTLInSeconds": number,
   "intents": [ 
      { 
         "intentName": "string",
         "intentVersion": "string"
      }
   ],
   "lastUpdatedDate": number,
   "locale": "string",
   "name": "string",
   "nluIntentConfidenceThreshold": number,
   "status": "string",
   "tags": [ 
      { 
         "key": "string",
         "value": "string"
      }
   ],
   "version": "string",
   "voiceId": "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.

abortStatement

Le message utilisé par Amazon Lex pour annuler une conversation. Pour de plus amples informations, veuillez consulter PutBot.

Type : objet Statement

checksum

Somme de contrôle du bot que vous avez créé.

Type : chaîne

childDirected

Type : booléen

clarificationPrompt

Les invites qu'Amazon Lex utilise lorsqu'il ne comprend pas l'intention de l'utilisateur. Pour de plus amples informations, veuillez consulter PutBot.

Type : objet Prompt

createdDate

Date à laquelle le bot a été créé.

Type : Timestamp

createVersion

Truesi une nouvelle version du bot a été créée. Si le createVersion champ n'a pas été spécifié dans la demande, le createVersion champ est défini sur false dans la réponse.

Type : booléen

description

Description du bot.

Type : chaîne

Contraintes de longueur : longueur minimum de 0. Longueur maximum de 200.

detectSentiment

truesi le bot est configuré pour envoyer les déclarations des utilisateurs à Amazon Comprehend à des fins d'analyse des sentiments. Si le detectSentiment champ n'a pas été spécifié dans la demande, il figure false dans la réponse. detectSentiment

Type : booléen

enableModelImprovements

Indique si le bot utilise des améliorations de précision. trueindique que le bot utilise les améliorations, sinon,false.

Type : booléen

failureReason

Dans status l'affirmativeFAILED, Amazon Lex fournit la raison pour laquelle il n'a pas réussi à créer le bot.

Type : chaîne

idleSessionTTLInSeconds

Durée maximale pendant laquelle Amazon Lex conserve les données collectées au cours d'une conversation. Pour de plus amples informations, veuillez consulter PutBot.

Type : entier

Plage valide : Valeur minimum de 60. Valeur maximum de 86 400.

intents

Tableau d’objets Intent. Pour de plus amples informations, veuillez consulter PutBot.

Type : tableau d’objets Intent

lastUpdatedDate

Date à laquelle le bot a été mis à jour. Lorsque vous créez une ressource, la date de création et la date de dernière mise à jour sont identiques.

Type : Timestamp

locale

La localisation cible pour le bot.

Type : chaîne

name

Le nom du bot.

Type : chaîne

Contraintes de longueur : longueur minimale de 2. Longueur maximale de 50.

Modèle : ^([A-Za-z]_?)+$

nluIntentConfidenceThreshold

Le score qui détermine l'endroit où Amazon Lex insère le AMAZON.FallbackIntent ou les deux lorsqu'il renvoie des intentions alternatives dans une PostTextréponse PostContentou. AMAZON.KendraSearchIntent AMAZON.FallbackIntentest inséré si le score de confiance à toutes fins utiles est inférieur à cette valeur. AMAZON.KendraSearchIntentn'est inséré que s'il est configuré pour le bot.

Type : double

Plage valide : Valeur minimum de 0. Valeur maximale de 1.

status

Lorsque vous envoyez une demande pour créer un bot processBehavior défini surBUILD, Amazon Lex définit l'élément de status réponse surBUILDING.

Dans READY_BASIC_TESTING cet état, vous pouvez tester le bot avec des entrées utilisateur qui correspondent exactement aux énoncés configurés en fonction des intentions et des valeurs du bot dans les types d'emplacements.

Si Amazon Lex ne parvient pas à créer le bot, Amazon Lex status le configureFAILED. Amazon Lex renvoie la raison de l'échec dans l'élément de failureReason réponse.

Lorsque vous définissez processBehavior surSAVE, Amazon Lex définit le code de statut surNOT BUILT.

Lorsque le bot est dans READY cet état, vous pouvez le tester et le publier.

Type : chaîne

Valeurs valides : BUILDING | READY | READY_BASIC_TESTING | FAILED | NOT_BUILT

tags

Liste des balises associées au bot.

Type : tableau d’objets Tag

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

version

La version du bot. Pour un nouveau bot, la version est toujours$LATEST.

Type : chaîne

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

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

voiceId

L'identifiant vocal Amazon Polly utilisé par Amazon Lex pour l'interaction vocale avec l'utilisateur. Pour de plus amples informations, veuillez consulter PutBot.

Type : chaîne

Erreurs

BadRequestException

La demande n'est pas bien formulée. Par exemple, une valeur n'est pas valide ou un champ obligatoire est manquant. Vérifiez les valeurs des champs, puis réessayez.

Code d’état HTTP : 400

ConflictException

Un conflit s'est produit lors du traitement de la demande. Réessayez votre demande.

Code d’état HTTP : 409

InternalFailureException

Une erreur interne Amazon Lex s'est produite. Réessayez votre demande.

Code d’état HTTP : 500

LimitExceededException

La demande a dépassé une limite. Réessayez votre demande.

Code d’état HTTP : 429

PreconditionFailedException

La somme de contrôle de la ressource que vous essayez de modifier ne correspond pas à la somme de contrôle de la demande. Vérifiez le checksum de la ressource et réessayez.

Code d’état HTTP : 412

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

ListTagsForResource

PutBotAlias