Templat respons terstruktur

Artikel
10/24/2023

BERLAKU UNTUK: SDK v4

Templat respons terstruktur memungkinkan pengembang menentukan struktur kompleks yang mendukung fungsionalitas ekstensif Pembuatan bahasa (LG), seperti templat, komposisi, sambil meninggalkan interpretasi respons terstruktur hingga pemanggil pustaka LG.

Untuk aplikasi bot, dukungan berikut disediakan:

Templat aktivitas Bot Framework menyertakan beberapa bidang yang dapat disesuaikan. Properti berikut adalah yang paling umum digunakan dan dapat dikonfigurasi melalui definisi templat aktivitas:

Properti	Gunakan huruf besar
Teks	Tampilkan teks yang digunakan oleh saluran untuk dirender secara visual
Bicara	Teks lisan yang digunakan oleh saluran untuk dirender dengan lantang
Lampiran	Daftar lampiran dengan jenisnya. Digunakan oleh saluran untuk dirender sebagai kartu UI atau jenis lampiran file generik lainnya.
SuggestedActions	Daftar tindakan yang dirender sebagai saran kepada pengguna.
InputHint	Mengontrol status aliran pengambilan audio pada perangkat yang mendukung input lisan. Nilai yang mungkin termasuk `accepting`, `expecting`, atau `ignoring`.

Tidak ada perilaku fallback default yang diterapkan oleh pemecah masalah templat. Jika properti tidak ditentukan, properti tetap tidak ditentukan. Misalnya, Speak properti tidak secara otomatis ditetapkan menjadi Text properti jika hanya properti yang Text ditentukan.

Devinisi

Berikut definisi templat terstruktur:

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

Berikut adalah contoh templat teks dasar:

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

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

Berikut adalah contoh teks dengan tindakan yang disarankan. Gunakan | untuk menunjukkan daftar.

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

Berikut adalah contoh definisi kartu Hero:

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

Catatan

LG menyediakan beberapa varianabilitas dalam definisi kartu, yang dikonversi agar selaras dengan definisi kartu SDK. Misalnya, bidang image dan images didukung dalam semua definisi kartu di LG meskipun hanya images didukung dalam definisi kartu SDK.

Nilai yang ditentukan dalam semua image bidang dan images dalam Kartu Hero atau kartu gambar mini digabungkan dan dikonversi ke daftar gambar dalam kartu yang dihasilkan. Untuk jenis kartu lainnya, nilai terakhir yang ditentukan dalam templat akan ditetapkan ke image bidang . Nilai yang Anda tetapkan ke image/images bidang bisa berupa string, ekspresi adaptif, atau array dalam format menggunakan |.

Di bawah ini adalah kombinasi templat sebelumnya:

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

Secara default, referensi templat apa pun dievaluasi sekali selama evaluasi templat terstruktur.

Misalnya, # AskForAge.prompt mengembalikan teks resolusi yang sama untuk Speak properti dan Text .

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

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

Anda dapat menggunakan <TemplateName>!() untuk meminta evaluasi baru pada setiap referensi dalam templat terstruktur.

Dalam contoh di bawah ini, Speak dan Text mungkin memiliki teks resolusi yang berbeda karena GetAge dievaluasi ulang pada setiap instans.

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

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

Berikut cara menampilkan carousel kartu:

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

Gunakan \ sebagai karakter 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
]

Komposisi templat terstruktur

Perilaku komposisi berikut didukung dengan templat terstruktur:

Komposisi sadar konteks struktur. Jika templat target yang dirujuk juga merupakan templat terstruktur, maka jenis struktur harus cocok. Misalnya, ActivityTemplate dapat dirujuk di ActivityTemplate lain.
Referensi ke templat respons sederhana atau bersyarkat dapat ada di mana saja di dalam templat terstruktur.

Misalkan Anda memiliki templat berikut:

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

# T2
- This is awesome

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

Panggilan ke evaluateTemplate('T1') akan menghasilkan struktur internal berikut:

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

Referensi lengkap ke templat terstruktur lain

Anda dapat menyertakan referensi ke templat terstruktur lain sebagai properti di templat terstruktur lain, atau sebagai referensi dalam templat respons sederhana atau bersyarkat lainnya

Berikut adalah contoh referensi lengkap ke templat terstruktur lainnya:

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

Dengan konten ini, panggilan ke evaluateTemplate('ST1') akan menghasilkan struktur internal berikut:

[MyStruct
    Text = foo
    Speak = bar
]

Ketika properti yang sama ada di templat panggilan serta templat yang dipanggil, konten dalam pemanggil akan menimpa konten apa pun dalam templat yang disebut.

Berikut contohnya:

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

Dengan konteks ini, panggilan ke evaluateTemplate('ST1') akan menghasilkan struktur internal berikut:

[MyStruct
    Text = foo
    Speak = bar
]

Perhatikan bahwa gaya komposisi ini hanya dapat ada di tingkat akar. Jika ada referensi ke templat terstruktur lain dalam properti, maka resolusinya kontekstual dengan properti tersebut.

Referensi file eksternal dalam lampiran terstruktur

Ada dua fungsi bawaan yang digunakan untuk mereferensikan file secara eksternal

fromFile(fileAbsoluteOrRelativePath) memuat file tertentu. Konten yang dikembalikan oleh fungsi ini akan mendukung evaluasi konten. Referensi templat, properti, dan ekspresi dievaluasi.
ActivityAttachment(content, contentType)contentType mengatur jika belum ditentukan dalam konten.

Dengan dua fungsi bawaan ini, Anda dapat menarik konten apa pun yang ditentukan secara eksternal, termasuk semua jenis kartu. Gunakan LG terstruktur berikut untuk menyusun aktivitas:

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

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

Anda juga dapat menggunakan lampiran, yang terlihat di bawah ini:

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

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

Informasi Tambahan

Referensi API C#
Referensi API JavaScript
Baca Debug dengan Alat Adaptif untuk mempelajari cara menganalisis dan men-debug templat.

Bagikan melalui