Delen via

Sjabloon voor gestructureerd antwoord

  • Artikel

VAN TOEPASSING OP: SDK v4

Met gestructureerde antwoordsjablonen kunnen ontwikkelaars een complexe structuur definiëren die ondersteuning biedt voor de uitgebreide functionaliteit van taalgeneratie (LG), zoals sjablonen, samenstelling, terwijl de interpretatie van de gestructureerde reactie tot de aanroeper van de LG-bibliotheek wordt overgelaten.

Voor bottoepassingen wordt de volgende ondersteuning geboden:

De Bot Framework-activiteitssjabloon bevat verschillende aanpasbare velden. De volgende eigenschappen zijn de meest gebruikte en configureerbaar via een definitie van een activiteitssjabloon:

Eigenschappen Gebruiksscenario
Sms verzenden Tekst weergeven die door het kanaal wordt gebruikt om visueel weer te geven
Spreken Gesproken tekst die door het kanaal wordt gebruikt om hoorbaar weer te geven
Bijlagen Lijst met bijlagen met hun type. Wordt gebruikt door kanalen om weer te geven als UI-kaarten of andere algemene bestandstypen.
SuggestedActions Lijst met acties die worden weergegeven als suggesties voor de gebruiker.
InputHint Hiermee bepaalt u de status van de audioopnamestream op apparaten die gesproken invoer ondersteunen. Mogelijke waarden zijn, expectingignoringof accepting.

Er is geen standaardterugvalgedrag geïmplementeerd door de sjabloon-resolver. Als er geen eigenschap is opgegeven, blijft deze niet opgegeven. De eigenschap wordt bijvoorbeeld Speak niet automatisch toegewezen aan de Text eigenschap als alleen de Text eigenschap is opgegeven.

Definitie

Hier volgt de definitie van een gestructureerde sjabloon:

# 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
]

Hier volgt een voorbeeld van een basistekstsjabloon:

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

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

Hier volgt een voorbeeld van tekst met een voorgestelde actie. Gebruik | dit om een lijst aan te geven.

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

Hier volgt een voorbeeld van een Hero-kaartdefinitie :

# 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
]

Notitie

LG biedt enige variabiliteit in de kaartdefinitie, die wordt geconverteerd naar overeenstemming met de SDK-kaartdefinitie. Beide velden worden images bijvoorbeeld image ondersteund in alle kaartdefinities in LG, ook al worden ze alleen images ondersteund in de SDK-kaartdefinitie.

De waarden die zijn gedefinieerd in alle image velden images in een HeroCard- of miniatuurkaart, worden gecombineerd en geconverteerd naar een lijst met afbeeldingen in de gegenereerde kaart. Voor de andere typen kaarten wordt de laatst gedefinieerde waarde in de sjabloon toegewezen aan het image veld. De waarden die u aan het image/images veld toewijst, kunnen een tekenreeks, adaptieve expressie of matrix zijn in de indeling met behulp van |.

Hieronder ziet u de combinatie van de vorige sjablonen:

# 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
]

Standaard wordt elke sjabloonreferentie eenmaal geëvalueerd tijdens de evaluatie van een gestructureerde sjabloon.

Retourneert bijvoorbeeld # AskForAge.prompt dezelfde resolutietekst voor zowel de als Text de Speak eigenschappen.

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

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

U kunt een <TemplateName>!() nieuwe evaluatie aanvragen voor elke verwijzing in een gestructureerde sjabloon.

In het onderstaande voorbeeld kunnen Text er verschillende resolutieteksten zijn, Speak omdat GetAge deze voor elk exemplaar opnieuw wordt geëvalueerd.

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

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

U kunt als volgt een carrousel met kaarten weergeven:

# 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
]

Als \ escape-teken gebruiken.

> 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
]

Samenstelling van gestructureerde sjablonen

Het volgende samenstellingsgedrag wordt ondersteund met gestructureerde sjablonen:

  • Samenstelling is structuurcontextbewust. Als de doelsjabloon waarnaar wordt verwezen ook een gestructureerde sjabloon is, moet het structuurtype overeenkomen. Een ActivityTemplate kan bijvoorbeeld worden genoemd in een andere ActivityTemplate.
  • Verwijzingen naar een eenvoudige of voorwaardelijke responssjabloon kunnen overal in een gestructureerde sjabloon bestaan.

Stel dat u de volgende sjabloon hebt:

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

# T2
- This is awesome

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

Een aanroep om te evaluateTemplate('T1') leiden tot de volgende interne structuur:

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

Volledige verwijzing naar een andere gestructureerde sjabloon

U kunt een verwijzing naar een andere gestructureerde sjabloon opnemen als een eigenschap in een andere gestructureerde sjabloon of als verwijzing in een andere eenvoudige of voorwaardelijke antwoordsjabloon

Hier volgt een voorbeeld van een volledige verwijzing naar een andere gestructureerde sjabloon:

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

Met deze inhoud leidt een aanroep naar evaluateTemplate('ST1') de volgende interne structuur:

[MyStruct
    Text = foo
    Speak = bar
]

Wanneer dezelfde eigenschap bestaat in zowel de aanroepende sjabloon als de aangeroepen sjabloon, overschrijft de inhoud in de aanroeper alle inhoud in de aangeroepen sjabloon.

Hier volgt een voorbeeld:

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

Met deze context resulteert een aanroep naar evaluateTemplate('ST1') de volgende interne structuur:

[MyStruct
    Text = foo
    Speak = bar
]

Houd er rekening mee dat deze samenstellingsstijl alleen op het hoofdniveau kan bestaan. Als er een verwijzing naar een andere gestructureerde sjabloon binnen een eigenschap is, is de resolutie contextueel voor die eigenschap.

Verwijzing naar extern bestand in bijlage gestructureerd

Er zijn twee vooraf gedefinieerde functies die worden gebruikt om extern te verwijzen naar bestanden

  1. fromFile(fileAbsoluteOrRelativePath) laadt een opgegeven bestand. Inhoud die door deze functie wordt geretourneerd, ondersteunt de evaluatie van inhoud. Sjabloonverwijzingen, eigenschappen en expressies worden geëvalueerd.
  2. ActivityAttachment(content, contentType) stelt de contentType waarde in als deze nog niet is opgegeven in de inhoud.

Met deze twee vooraf gedefinieerde functies kunt u alle extern gedefinieerde inhoud ophalen, inclusief alle kaarttypen. Gebruik de volgende gestructureerde LG om een activiteit op te stellen:

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

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

U kunt ook bijlagen gebruiken, zie hieronder:

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

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

Aanvullende informatie