Strukturált válaszsablon

Cikk
10/24/2023

A KÖVETKEZŐKRE VONATKOZIK: SDK v4

A strukturált válaszsablonok lehetővé teszik a fejlesztők számára, hogy olyan összetett struktúrát határozzanak meg, amely támogatja a nyelvi generáció (LG) széles körű funkcióit, például a templatingot, a kompozíciót, miközben a strukturált válasz értelmezését az LG-kódtár hívójára bízza.

Robotalkalmazások esetén a következő támogatás érhető el:

A Bot Framework tevékenységsablonja számos testreszabható mezőt tartalmaz. A leggyakrabban használt tulajdonságok a következő tulajdonságok, amelyek egy tevékenységsablon definíciója alapján konfigurálhatók:

Property	Use case
SMS	A csatorna által vizuálisan megjelenített szöveg megjelenítése
Beszéd	Kimondott szöveg, amelyet a csatorna használ a hangjelzés megjelenítéséhez
Mellékletek	A mellékletek listája a típusukkal. A csatornák felhasználói felületi kártyaként vagy más általános fájlmelléklet-típusként való megjelenítésre használják.
SuggestedActions	A felhasználónak javaslatként megjelenített műveletek listája.
InputHint	A hangrögzítés streamállapotát szabályozza a beszélt bemenetet támogató eszközökön. A lehetséges értékek közé tartoznak a következők: `accepting`, `expecting`vagy `ignoring`.

A sablonfeloldó nem valósítja meg az alapértelmezett tartalék viselkedést. Ha egy tulajdonság nincs megadva, akkor nem határozható meg. A tulajdonság például Speak nem lesz automatikusan hozzárendelve a Text tulajdonsághoz, ha csak a Text tulajdonság van megadva.

Definition

A strukturált sablon definíciója:

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

Íme egy példa egy egyszerű szöveges sablonra:

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

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

Íme egy példa egy javasolt művelettel rendelkező szövegre. Lista jelölésére használható | .

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

Íme egy példa a Hero-kártya definíciójára:

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

Megjegyzés:

Az LG némi variabilitást biztosít a kártyadefinícióban, amelyet az SDK-kártyadefiníciónak megfelelően alakítunk át. Például mind image a images mezők támogatottak az LG összes kártyadefiníciójában, annak ellenére, hogy csak images az SDK-kártya definíciója támogatja őket.

A Rendszer a HeroCard vagy miniatűr kártya összes image mezőjében és images mezőjében definiált értékeket kombinálja és képlistává alakítja a létrehozott kártyán. A többi kártyatípus esetében a sablon utolsó definiált értéke lesz hozzárendelve a image mezőhöz. A mezőhöz image/images hozzárendelt értékek lehetnek sztringek, adaptív kifejezések vagy tömbök a következő |formátumban:

Az alábbiakban az előző sablonok kombinációja látható:

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

Alapértelmezés szerint a strukturált sablon kiértékelése során a rendszer egyszer kiértékeli a sablonhivatkozásokat.

Például # AskForAge.prompt ugyanazt a felbontásszöveget adja vissza mind a tulajdonságokhoz, mind a SpeakText tulajdonságokhoz.

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

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

Egy <TemplateName>!() strukturált sablonon belül minden hivatkozáshoz új értékelést kérhet.

Az alábbi példában eltérő felbontási szöveg jelenhet meg, SpeakText mert GetAge az egyes példányokon újraértékelik.

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

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

Az alábbiak szerint jeleníthet meg egy körhintát a kártyákból:

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

Használjon \ menekülési karakterként.

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

Strukturált sablonösszeállítás

A strukturált sablonok az alábbi összetételi viselkedést támogatják:

A szerkezet környezettudatos. Ha a hivatkozott célsablon szintén strukturált sablon, akkor a struktúratípusnak meg kell egyeznie. Egy ActivityTemplate például egy másik ActivityTemplate-ban is hivatkozható.
Az egyszerű vagy feltételes válaszsablonra mutató hivatkozások strukturált sablonon belül bárhol létezhetnek.

Tegyük fel, hogy a következő sablonnal rendelkezik:

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

# T2
- This is awesome

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

Egy hívás evaluateTemplate('T1') a következő belső struktúrát eredményezné:

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

Teljes hivatkozás egy másik strukturált sablonra

Hivatkozhat egy másik strukturált sablonra tulajdonságként egy másik strukturált sablonban, vagy hivatkozásként egy másik egyszerű vagy feltételes válaszsablonban

Íme egy példa egy másik strukturált sablonra való teljes hivatkozásra:

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

Ezzel a tartalommal egy hívás evaluateTemplate('ST1') a következő belső struktúrát eredményezi:

[MyStruct
    Text = foo
    Speak = bar
]

Ha ugyanaz a tulajdonság mind a hívósablonban, mind a hívott sablonban megtalálható, a hívó tartalma felülírja a hívott sablon tartalmát.

Here's an example:

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

Ebben a kontextusban egy hívás evaluateTemplate('ST1') a következő belső struktúrát eredményezi:

[MyStruct
    Text = foo
    Speak = bar
]

Vegye figyelembe, hogy ez a kompozíciós stílus csak a gyökérszinten létezhet. Ha egy tulajdonságon belül egy másik strukturált sablonra hivatkozik, akkor a megoldás környezetfüggő az adott tulajdonsághoz.

Külső fájlhivatkozás strukturált mellékletben

A fájlok külső hivatkozásához két előre összeállított függvény használható

fromFile(fileAbsoluteOrRelativePath) betölt egy megadott fájlt. A függvény által visszaadott tartalom támogatja a tartalom kiértékelését. A rendszer kiértékeli a sablonhivatkozásokat, tulajdonságokat és kifejezéseket.
ActivityAttachment(content, contentType) beállítja, contentType ha még nincs megadva a tartalomban.

Ezzel a két előre összeállított funkcióval bármilyen külsőleg definiált tartalmat lekérhet, beleértve az összes kártyatípust is. A következő strukturált LG-t használva írjon egy tevékenységet:

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

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

Az alábbiakban látható mellékleteket is használhatja:

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

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

További információ

C# API-referencia
JavaScript API-referencia
A sablonok elemzésének és hibakeresésének megismeréséhez olvassa el a hibakeresést az Adaptív eszközökkel .

Megosztás a következőn keresztül: