Yapılandırılmış yanıt şablonu

Makale
10/24/2023

ŞUNLAR IÇIN GEÇERLIDIR: SDK v4

Yapılandırılmış yanıt şablonları, geliştiricilerin yapılandırılmış yanıtın yorumunu LG kitaplığının çağırana kadar bırakırken şablon oluşturma, kompozisyon gibi Dil oluşturma (LG) kapsamlı işlevselliğini destekleyen karmaşık bir yapı tanımlamasına olanak sağlar.

Bot uygulamaları için aşağıdaki destek sağlanır:

etkinlik tanımı
kart tanımı

Bot Framework etkinlik şablonu birkaç özelleştirilebilir alan içerir. Aşağıdaki özellikler en yaygın kullanılan özelliklerdir ve bir etkinlik şablonu tanımı aracılığıyla yapılandırılabilir:

Özellik	Kullanım örneği
Metin	Kanal tarafından görsel olarak işlemek için kullanılan metni görüntüleme
Konuş	Kanal tarafından sesli olarak işlemek için kullanılan konuşulan metin
Ekler	Türlerine sahip eklerin listesi. Kanallar tarafından ui kartları veya diğer genel dosya eki türleri olarak işlemek için kullanılır.
SuggestedActions	Kullanıcıya öneri olarak işlenen eylemlerin listesi.
InputHint	Konuşulan girişi destekleyen cihazlarda ses yakalama akış durumunu denetler. Olası değerler , `expecting`veya `ignoring`değerlerini içerir`accepting`.

Şablon çözümleyicisi tarafından uygulanan varsayılan geri dönüş davranışı yoktur. Bir özellik belirtilmezse belirtilmemiş olarak kalır. Örneğin, Speak özellik, yalnızca Text özellik belirtilirse özellik olarak otomatik olarak atanamazText.

Açıklama

Yapılandırılmış şablonun tanımı aşağıdadır:

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

Aşağıda temel bir metin şablonu örneği verilmişti:

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

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

Aşağıda önerilen eylem içeren bir metin örneği verilmiştir. Listeyi belirtmek için kullanın | .

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

Hero kart tanımı örneği aşağıda verilmişti:

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

Dekont

LG, SDK kart tanımıyla uyumlu olacak şekilde dönüştürülen kart tanımında bazı değişkenlik sağlar. Örneğin, hem hem de image images alanlar, YALNıZCA SDK kart tanımında destekleniyor olsa images bile LG'deki tüm kart tanımlarında desteklenir.

HeroCard veya küçük resim kartındaki ve images alanlarının image tamamında tanımlanan değerler birleştirilir ve oluşturulan karttaki bir resim listesine dönüştürülür. Diğer kart türleri için şablondaki son tanımlı değer alana atanır image . Alanına atadığınız image/images değerler kullanılarak |biçiminde bir dize, uyarlamalı ifade veya dizi olabilir.

Önceki şablonların birleşimi aşağıdadır:

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

Varsayılan olarak, yapılandırılmış bir şablon değerlendirilirken tüm şablon başvuruları bir kez değerlendirilir.

Örneğin, # AskForAge.prompt hem hem Text de Speak özellikleri için aynı çözünürlük metnini döndürür.

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

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

Yapılandırılmış bir şablon içindeki her başvuruda yeni bir değerlendirme istemek için kullanabilirsiniz <TemplateName>!() .

Aşağıdaki Speak örnekte ve Text her örnekte yeniden değerlendirildiğinden farklı bir çözümleme metni GetAge olabilir.

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

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

Kartlardan oluşan bir döngü şu şekilde görüntülenir:

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

Kaçış karakteri olarak kullanın \ .

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

Yapılandırılmış şablon oluşturma

Aşağıdaki oluşturma davranışı yapılandırılmış şablonlarla desteklenir:

Oluşturma, yapı bağlam bilgisi olan bir yapıdır. Başvurulmakta olan hedef şablon da yapılandırılmış bir şablonsa, yapı türünün eşleşmesi gerekir. Örneğin, bir ActivityTemplate'a başka bir ActivityTemplate'da başvurulabilir.
Basit veya koşullu yanıt şablonuna başvurular, yapılandırılmış bir şablonun içinde herhangi bir yerde bulunabilir.

Aşağıdaki şablona sahip olduğunuzu varsayalım:

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

# T2
- This is awesome

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

çağrısı evaluateTemplate('T1') aşağıdaki iç yapıya neden olur:

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

Başka bir yapılandırılmış şablona tam başvuru

Başka bir yapılandırılmış şablona başvuru, başka bir yapılandırılmış şablonda özellik olarak veya başka bir basit veya koşullu yanıt şablonuna başvuru olarak ekleyebilirsiniz

Başka bir yapılandırılmış şablona tam başvuru örneği aşağıda verilmişti:

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

Bu içerikle, çağrısı evaluateTemplate('ST1') aşağıdaki iç yapıya neden olur:

[MyStruct
    Text = foo
    Speak = bar
]

Hem çağrılan şablonda hem de çağrılan şablonda aynı özellik mevcut olduğunda, çağıran içindeki içerik, çağrılan şablondaki tüm içeriğin üzerine yazılır.

Bir örnek aşağıda verilmiştir:

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

Bu bağlamla, çağrısı evaluateTemplate('ST1') aşağıdaki iç yapıya neden olur:

[MyStruct
    Text = foo
    Speak = bar
]

Bu kompozisyon stilinin yalnızca kök düzeyinde mevcut olabileceğini unutmayın. Bir özellik içinde başka bir yapılandırılmış şablona başvuru varsa, çözümleme bu özelliğe bağlamsaldır.

Yapılandırılmış ekte dış dosya başvurusu

Dosyalara dışarıdan başvurmak için kullanılan önceden oluşturulmuş iki işlev vardır

fromFile(fileAbsoluteOrRelativePath) belirtilen bir dosyayı yükler. Bu işlev tarafından döndürülen içerik, içeriğin değerlendirilmesini destekleyecektir. Şablon başvuruları, özellikleri ve ifadeleri değerlendirilir.
ActivityAttachment(content, contentType) , içerikte contentType önceden belirtilmemişse değerini ayarlar.

Bu iki önceden oluşturulmuş işlevle, tüm kart türleri dahil olmak üzere dış tanımlı tüm içeriği çekebilirsiniz. Etkinlik oluşturmak için aşağıdaki yapılandırılmış LG'yi kullanın:

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

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

Aşağıda görülen ekleri de kullanabilirsiniz:

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

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

Ek Bilgi

C# API Başvurusu
JavaScript API'si başvurusu
Şablonları analiz etmeyi ve hatalarını ayıklamayı öğrenmek için Uyarlamalı Araçlarla Hata Ayıklama'ya bakın.

Aracılığıyla paylaş