Modèle de réponse structurée

S’APPLIQUE À : SDK v4

Les modèles de réponse structurés permettent aux développeurs de définir une structure complexe qui prend en charge les fonctionnalités étendues de génération de langage (LG), telles que la création de modèles et la composition, tout en laissant à l’appelant de la bibliothèque de génération de langage le soin d’interpréter la réponse structurée.

Pour les applications bot, la prise en charge suivante est assurée :

• définition de l'activité
• définition de la carte

Le modèle d’activité Bot Framework inclut plusieurs champs personnalisables. Les propriétés suivantes sont les plus utilisées et sont configurables via une définition de modèle d’activité :

Il n’existe aucun comportement de secours par défaut implémenté par le programme de résolution du modèle. Si une propriété n’est pas spécifiée, elle reste non spécifiée. Par exemple, la propriété Speak n’est pas automatiquement affectée à la propriété Text si seule la propriété Text est spécifiée.

Définition

Voici la définition d’un modèle structuré :

# TemplateName
> this is a comment
[Structure-name
    Property1 = <plain text> .or. <plain text with template reference> .or. <expression>
    Property2 = list of values are denoted via '|'. e.g. a | b
> this is a comment about this specific property
    Property3 = Nested structures are achieved through composition
]

Voici un exemple de modèle de texte de base :

# AskForAge.prompt
[Activity
    Text = ${GetAge()}
    Speak = ${GetAge()}
]

# GetAge
- how old are you?
- what is your age?

Voici un exemple de texte avec une action suggérée. Utilisez | pour désigner une liste.

> With '|' you are making attachments a list.
# AskForAge.prompt
[Activity
    Text = ${GetAge()}
    SuggestedActions = 10 | 20 | 30
]

Voici un exemple de définition de carte de bannière :

# HeroCard
[Herocard
    title = Hero Card Example
    subtitle = Microsoft Bot Framework
    text = Build and connect intelligent bots to interact with your users naturally wherever they are, from text/sms to Skype, Slack, Office 365 mail and other popular services.
    images = https://sec.ch9.ms/ch9/7ff5/e07cfef0-aa3b-40bb-9baa-7c9ef8ff7ff5/buildreactionbotframework_960.jpg
    buttons = Option 1| Option 2| Option 3
]

Vous trouverez ci-dessous la combinaison des modèles précédents :

# AskForAge.prompt
[Activity
    Text = ${GetAge()}
    Speak = ${GetAge()}
    Attachments = ${HeroCard()}
    SuggestedActions = 10 | 20 | 30
    InputHint = expecting
]

# GetAge
- how old are you?
- what is your age?

# HeroCard
[Herocard
    title = Hero Card Example
    subtitle = Microsoft Bot Framework
    text = Build and connect intelligent bots to interact with your users naturally wherever they are, from text/sms to Skype, Slack, Office 365 mail and other popular services.
    images = https://sec.ch9.ms/ch9/7ff5/e07cfef0-aa3b-40bb-9baa-7c9ef8ff7ff5/buildreactionbotframework_960.jpg
    buttons = Option 1| Option 2| Option 3
]

Par défaut, toute référence de modèle est évaluée une fois, dans le cadre de l’évaluation d’un modèle structuré.

Par exemple, # AskForAge.prompt retourne le même texte de résolution pour les deux propriétés Speak et Text.

# AskForAge.prompt
[Activity
    Text = ${GetAge()}
    Speak = ${GetAge()}
]

# GetAge
- how old are you?
- what is your age?

Vous pouvez utiliser <TemplateName>!() pour demander une nouvelle évaluation sur chaque référence au sein d’un modèle structuré.

Dans l’exemple ci-dessous, Speak et Text peuvent avoir un texte de résolution différent, car GetAge est réévalué sur chaque instance.

[Activity
    Text = ${GetAge()}
    Speak = ${GetAge!()}
]

# GetAge
- how old are you?
- what is your age?

Voici comment afficher un carrousel de cartes :

# AskForAge.prompt
[Activity
> Defaults to carousel layout in case of list of cards
    Attachments = ${foreach($cardValues, item, HeroCard(item)}
]

# AskForAge.prompt_2
[Activity
> Explicitly specify an attachment layout
    Attachments = ${foreach($cardValues, item, HeroCard(item)}
    AttachmentLayout = list
]

# HeroCard (title, subtitle, text)
[Herocard
    title = ${title}
    subtitle = ${subtitle}
    text = ${text}
    images = https://sec.ch9.ms/ch9/7ff5/e07cfef0-aa3b-40bb-9baa-7c9ef8ff7ff5/buildreactionbotframework_960.jpg
    buttons = Option 1| Option 2| Option 3
]

Utilisez \ comme caractère d'échappement.

> You can use '\' as an escape character
> \${GetAge()} would not be evaluated as expression, would be parsed as '${getAge()}' string
# AskForAge.prompt
[Activity
        Text = \${GetAge()}
        SuggestedActions = 10 \| cards | 20 \| cards
]

Composition de modèle structuré

Le comportement de composition suivant est pris en charge avec les modèles structurés :

• La composition est basée sur le contexte de la structure. Si le modèle cible référencé est également un modèle structuré, le type de structure doit correspondre. Par exemple, il est possible de faire référence à un ActivityTemplate dans un autre ActivityTemplate.
• Les références à un modèle de réponse simple ou conditionnel peuvent se trouver n’importe où dans un modèle structuré.

Supposez que vous disposiez du modèle suivant :

# T1
[Activity
    Text = ${T2()}
    Speak = foo bar ${T3().speak}
]

# T2
- This is awesome

# T3
[Activity
    Speak = I can also speak!
]

Un appel à evaluateTemplate('T1') aboutirait à la structure interne suivante :

[Activity
    Text = This is awesome
    Speak = I can also speak!
]

Référence complète à un autre modèle structuré

Vous pouvez inclure une référence à un autre modèle structuré en tant que propriété dans un autre modèle structuré, ou en tant que référence dans un autre modèle de réponse simple ou conditionnel

Voici un exemple de référence complète à un autre modèle structuré :

# ST1
[MyStruct
    Text = foo
    ${ST2()}
]
# ST2
[MyStruct
    Speak = bar
]

Avec ce contenu, un appel à evaluateTemplate('ST1') aboutit à la structure interne suivante :

[MyStruct
    Text = foo
    Speak = bar
]

Quand la même propriété existe à la fois dans le modèle appelant et dans le modèle appelé, le contenu de l’appelant remplace tout contenu du modèle appelé.

Voici un exemple :

# ST1
[MyStruct
    Text = foo
    ${ST2()}
]
# ST2
[MyStruct
    Speak = bar
    Text = zoo
]

Avec ce contexte, un appel à evaluateTemplate('ST1') aboutit à la structure interne suivante :

[MyStruct
    Text = foo
    Speak = bar
]

Notez que ce style de composition ne peut exister qu’au niveau de la racine. S’il existe une référence à un autre modèle structuré dans une propriété, la résolution dépend du contexte de cette propriété.

Référence de fichier externe dans une pièce jointe structurée

Deux fonctions prédéfinies sont utilisées pour référencer des fichiers en externe

1. fromFile(fileAbsoluteOrRelativePath) charge un fichier spécifié. Le contenu retourné par cette fonction prend en charge l’évaluation du contenu. Les références de modèle, les propriétés et les expressions sont évaluées.
2. ActivityAttachment(content, contentType) définit le contentType s’il n’est pas déjà spécifié dans le contenu.

Ces deux fonctions prédéfinies vous permettent d’extraire tout contenu défini en externe, notamment tous les types de cartes. Utilisez la génération de langage structurée suivante pour composer une activité :

# AdaptiveCard
[Activity
                Attachments = ${ActivityAttachment(json(fromFile('../../card.json')), 'adaptiveCard')}
]

# HeroCard
[Activity
                Attachments = ${ActivityAttachment(json(fromFile('../../card.json')), 'heroCard')}
]

Vous pouvez également utiliser des pièces jointes, comme indiqué ci-dessous :

# AdaptiveCard
[Attachment
    contenttype = adaptivecard
    content = ${json(fromFile('../../card.json'))}
]

# HeroCard
[Attachment
    contenttype = herocard
    content = ${json(fromFile('../../card.json'))}
]

Informations supplémentaires

• Référence API C#
• Informations de référence sur l’API JavaScript
• Lisez Débogage avec des outils adaptatifs pour apprendre à analyser et déboguer des modèles.