Mall för strukturerade svar

Artikel
10/24/2023

GÄLLER FÖR: SDK v4

Med strukturerade svarsmallar kan utvecklare definiera en komplex struktur som stöder den omfattande funktionen för språkgenerering (LG), till exempel templating, sammansättning, samtidigt som tolkningen av det strukturerade svaret lämnas till anroparen av LG-biblioteket.

För robotprogram tillhandahålls följande stöd:

Bot Framework-aktivitetsmallen innehåller flera anpassningsbara fält. Följande egenskaper är de vanligaste och kan konfigureras via en definition av aktivitetsmallen:

Property	Användningsfall
Text	Visa text som används av kanalen för att återge visuellt
Tala	Talad text som används av kanalen för att återge hörbart
Bifogade filer	Lista över bifogade filer med deras typ. Används av kanaler för att återges som användargränssnittskort eller andra typer av generiska filbilagor.
Föreslagna åtgärder	Lista över åtgärder som återges som förslag till användare.
InputHint	Styr strömtillståndet för ljudupptagning på enheter som stöder talade indata. Möjliga värden är `accepting`, `expecting`eller `ignoring`.

Det finns inget standardåterställningsbeteende som implementeras av malllösaren. Om en egenskap inte har angetts förblir den ospecificerad. Egenskapen tilldelas till exempel Speak inte automatiskt till Text egenskapen om endast egenskapen Text har angetts.

Definition

Här är definitionen av en strukturerad mall:

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

Här är ett exempel på en grundläggande textmall:

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

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

Här är ett exempel på text med en föreslagen åtgärd. Använd | för att ange en lista.

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

Här är ett exempel på en Hero-kortdefinition :

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

Kommentar

LG ger viss variabilitet i kortdefinitionen, som konverteras för att överensstämma med SDK-kortdefinitionen. Till exempel stöds både image och images fält i alla kortdefinitioner i LG även om endast images stöds i SDK-kortdefinitionen.

Värdena som definieras i alla fälten image och images i ett HeroCard- eller miniatyrkort kombineras och konverteras till en bildlista i det genererade kortet. För de andra korttyperna tilldelas det senast definierade värdet i mallen till fältet image . De värden som du tilldelar fältet image/images kan vara en sträng, ett anpassningsbart uttryck eller en matris i formatet med hjälp av |.

Nedan visas en kombination av tidigare mallar:

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

Som standard utvärderas alla mallreferenser en gång under utvärderingen av en strukturerad mall.

Returnerar till exempel # AskForAge.prompt samma upplösningstext för både Speak egenskaperna och Text .

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

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

Du kan använda <TemplateName>!() för att begära en ny utvärdering av varje referens i en strukturerad mall.

I exemplet nedan Speak och Text kan ha olika upplösningstext eftersom GetAge utvärderas på nytt för varje instans.

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

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

Så här visar du en karusell med kort:

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

Använd \ som escape-tecken.

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

Strukturerad mallsammansättning

Följande sammansättningsbeteende stöds med strukturerade mallar:

Sammansättning är strukturkontextmedveten. Om målmallen som refereras också är en strukturerad mall måste strukturtypen matcha. Till exempel kan en ActivityTemplate refereras till i en annan ActivityTemplate.
Referenser till en mall för enkla eller villkorsstyrda svar kan finnas var som helst i en strukturerad mall.

Anta att du har följande mall:

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

# T2
- This is awesome

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

Ett anrop till evaluateTemplate('T1') skulle resultera i följande interna struktur:

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

Fullständig referens till en annan strukturerad mall

Du kan inkludera en referens till en annan strukturerad mall som en egenskap i en annan strukturerad mall, eller som referens i en annan enkel eller villkorsstyrd svarsmall

Här är ett exempel på en fullständig referens till en annan strukturerad mall:

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

Med det här innehållet resulterar ett anrop till evaluateTemplate('ST1') i följande interna struktur:

[MyStruct
    Text = foo
    Speak = bar
]

När samma egenskap finns i både den anropande mallen och den anropade mallen skriver innehållet i anroparen över allt innehåll i den anropade mallen.

Här är ett exempel:

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

Med den här kontexten resulterar ett anrop till evaluateTemplate('ST1') i följande interna struktur:

[MyStruct
    Text = foo
    Speak = bar
]

Observera att den här kompositionsstilen bara kan finnas på rotnivå. Om det finns en referens till en annan strukturerad mall i en egenskap är lösningen kontextuell för den egenskapen.

Referens för extern fil i en strukturerad bifogad fil

Det finns två fördefinierade funktioner som används för att referera till filer externt

fromFile(fileAbsoluteOrRelativePath) läser in en angiven fil. Innehåll som returneras av den här funktionen stöder utvärdering av innehåll. Mallreferenser, egenskaper och uttryck utvärderas.
ActivityAttachment(content, contentType)contentType anger om den inte redan har angetts i innehållet.

Med dessa två fördefinierade funktioner kan du hämta allt externt definierat innehåll, inklusive alla korttyper. Använd följande strukturerade LG för att skapa en aktivitet:

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

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

Du kan också använda bifogade filer som visas nedan:

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

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

Ytterligare Information

C#API-referens
JavaScript API-referens
Läs Felsöka med anpassningsbara verktyg för att lära dig hur du analyserar och felsöker mallar.

Dela via