Modello di risposta strutturata

SI APPLICA A: SDK v4

I modelli di risposta strutturata consentono agli sviluppatori di definire una struttura complessa che supporta le funzionalità complete di generazione del linguaggio, come la creazione di modelli e la composizione, lasciando l'interpretazione della risposta strutturata al chiamante della libreria di generazione del linguaggio.

Per le applicazioni bot, viene fornito il supporto seguente:

• definizione dell'attività
• definizione della scheda

Il modello di attività di Bot Framework include diversi campi personalizzabili. Le proprietà seguenti sono le più usate e sono configurabili tramite una definizione di modello di attività:

Non esiste un comportamento di fallback predefinito implementato dal resolver del modello. Se non viene specificata una proprietà, rimane non specificata. Ad esempio, la proprietà Speak non viene assegnata automaticamente come proprietà Text se è specificata solo la proprietà Text.

Definizione

Ecco la definizione di un modello strutturato.

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

Ecco un esempio di modello di testo di base:

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

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

Ecco un esempio di testo con un'azione suggerita. Usare | per indicare un elenco.

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

Ecco un esempio di definizione di una scheda banner:

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

Ecco la combinazione dei modelli precedenti:

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

Per impostazione predefinita, qualsiasi riferimento a un modello viene valutato una sola volta durante la valutazione di un modello strutturato.

Ad esempio, # AskForAge.prompt restituisce lo stesso testo di risoluzione per le proprietà Speak e Text.

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

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

È possibile usare <TemplateName>!() per richiedere una nuova valutazione per ogni riferimento all'interno di un modello strutturato.

Nell'esempio seguente il testo di risoluzione di Speak e Text può essere diverso perché GetAge viene rivalutato per ogni istanza.

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

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

Ecco come visualizzare un carosello di schede:

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

Usare \ come carattere di escape.

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

Composizione del modello strutturato

Con i modelli strutturati è supportato il comportamento di composizione seguente:

• La composizione deve riconoscere il contesto della struttura. Se il modello di destinazione a cui si fa riferimento è anche un modello strutturato, il tipo di struttura deve corrispondere. È ad esempio possibile fare riferimento a un modello ActivityTemplate in un altro modello ActivityTemplate.
• È possibile usare riferimenti al modello di risposta semplice o condizionale in qualsiasi punto di un modello strutturato.

Si supponga di avere il modello seguente:

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

# T2
- This is awesome

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

Una chiamata a evaluateTemplate('T1') comporterebbe la struttura interna seguente:

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

Riferimento completo a un altro modello strutturato

È possibile includere un riferimento a un altro modello strutturato come proprietà in un altro modello strutturato o come riferimento in un altro modello di risposta semplice o condizionale

Ecco un esempio di riferimento completo a un altro modello strutturato:

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

Con questo contenuto, una chiamata a evaluateTemplate('ST1') comporterà la struttura interna seguente:

[MyStruct
    Text = foo
    Speak = bar
]

Quando la stessa proprietà esiste sia nel modello chiamante che nel modello chiamato, il contenuto del chiamante sovrascriverà l'eventuale contenuto del modello chiamato.

Ecco un esempio:

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

Con questo contesto, una chiamata a evaluateTemplate('ST1') comporterà la struttura interna seguente:

[MyStruct
    Text = foo
    Speak = bar
]

Si noti che questo stile di composizione può esistere solo a livello radice. Se è presente un riferimento a un altro modello strutturato all'interno di una proprietà, la risoluzione è contestuale a tale proprietà.

Riferimento esterno a file nell'allegato strutturato

Esistono due funzioni predefinite usate per aggiungere un riferimento esterno ai file.

1. fromFile(fileAbsoluteOrRelativePath) carica un file specificato. Il contenuto restituito da questa funzione supporterà la valutazione del contenuto. Vengono valutati riferimenti, proprietà ed espressioni del modello.
2. ActivityAttachment(content, contentType) imposta se contentType non è già specificato nel contenuto.

Con queste due funzioni predefinite è possibile eseguire il pull di qualsiasi contenuto definito esternamente, inclusi tutti i tipi di schede. Usare la generazione del linguaggio strutturata seguente per comporre un'attività:

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

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

È anche possibile usare gli allegati, come illustrato di seguito:

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

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

Informazioni aggiuntive

• Informazioni di riferimento sulle API C#
• Informazioni di riferimento sull'API JavaScript
• Leggere Debug con strumenti adattivi per informazioni su come analizzare ed eseguire il debug dei modelli.