Udostępnij za pośrednictwem

Szablon odpowiedzi ustrukturyzowanej

  • Artykuł

DOTYCZY: ZESTAW SDK w wersji 4

Szablony odpowiedzi ustrukturyzowanych umożliwiają deweloperom definiowanie złożonej struktury obsługującej rozbudowane funkcje generowania języka (LG), takie jak tworzenie szablonów, kompozycja, pozostawiając interpretację ustrukturyzowanej odpowiedzi do obiektu wywołującego bibliotekę LG.

W przypadku aplikacji botów zapewniana jest następująca obsługa:

Szablon działania platformy Bot Framework zawiera kilka pól możliwych do dostosowania. Następujące właściwości są najczęściej używane i można je konfigurować za pomocą definicji szablonu działania:

Właściwości Przypadek użycia
Tekst Wyświetlanie tekstu używanego przez kanał do renderowania wizualnego
Mów Tekst mówiony używany przez kanał do renderowania dźwiękowego
Załączniki Lista załączników o ich typie. Używane przez kanały do renderowania jako karty interfejsu użytkownika lub inne ogólne typy załączników plików.
Sugerowane wyrażenia Lista akcji renderowanych jako sugestie dla użytkownika.
InputHint Steruje stanem strumienia przechwytywania dźwięku na urządzeniach, które obsługują wprowadzanie mówione. Możliwe wartości to accepting, expectinglub ignoring.

Nie ma domyślnego zachowania rezerwowego zaimplementowanego przez program rozpoznawania szablonów. Jeśli właściwość nie jest określona, pozostaje ona nieokreślona. Na przykład Speak właściwość nie jest automatycznie przypisywana do Text właściwości, jeśli określono tylko Text właściwość.

Definicja

Oto definicja szablonu strukturalnego:

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

Oto przykład podstawowego szablonu tekstowego:

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

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

Oto przykład tekstu z sugerowaną akcją. Służy | do oznaczania listy.

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

Oto przykład definicji karty 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
]

Uwaga

LG zapewnia pewną zmienność definicji karty, która jest konwertowana w celu dopasowania do definicji karty zestawu SDK. Na przykład oba image pola i images są obsługiwane we wszystkich definicjach kart w lg, mimo że są obsługiwane tylko images w definicji karty zestawu SDK.

Wartości zdefiniowane we wszystkich polach image i images w karcie HeroCard lub miniatury są łączone i konwertowane na listę obrazów na wygenerowanej karcie. W przypadku innych typów kart ostatnia zdefiniowana wartość w szablonie zostanie przypisana image do pola. Wartości przypisywane do image/images pola mogą być ciągiem, wyrażeniem adaptacyjnym lub tablicą w formacie przy użyciu polecenia |.

Poniżej znajduje się kombinacja poprzednich szablonów:

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

Domyślnie każde odwołanie do szablonu jest oceniane raz podczas oceny szablonu ustrukturyzowanego.

Na przykład # AskForAge.prompt zwraca ten sam tekst rozdzielczości dla właściwości Speak i Text .

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

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

Możesz użyć <TemplateName>!() polecenia , aby zażądać nowej oceny dla każdego odwołania w szablonie ustrukturyzowanym.

W poniższym przykładzie i Text może mieć inny tekst rozpoznawania, Speak ponieważ GetAge jest ponownie obliczany dla każdego wystąpienia.

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

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

Oto jak wyświetlić karuzeli kart:

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

Użyj \ jako znaku ucieczki.

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

Kompozycja szablonu strukturalnego

Następujące zachowanie kompozycji jest obsługiwane w przypadku szablonów strukturalnych:

  • Kompozycja jest świadoma kontekstu struktury. Jeśli określony szablon docelowy jest również szablonem ustrukturyzowanym, typ struktury musi być zgodny. Na przykład element ActivityTemplate można odwoływać się do innego elementu ActivityTemplate.
  • Odwołania do prostego lub warunkowego szablonu odpowiedzi mogą istnieć w dowolnym miejscu wewnątrz szablonu strukturalnego.

Załóżmy, że masz następujący szablon:

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

# T2
- This is awesome

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

Wywołanie metody w celu wywołania evaluateTemplate('T1') spowodowałoby następującą strukturę wewnętrzną:

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

Pełne odwołanie do innego szablonu ustrukturyzowanego

Odwołanie do innego szablonu strukturalnego można dołączyć jako właściwość w innym szablonie ustrukturyzowanym lub jako odwołanie do innego prostego lub warunkowego szablonu odpowiedzi

Oto przykład pełnego odwołania do innego szablonu strukturalnego:

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

W przypadku tej zawartości wywołanie metody wywołania evaluateTemplate('ST1') spowoduje następującą strukturę wewnętrzną:

[MyStruct
    Text = foo
    Speak = bar
]

Jeśli ta sama właściwość istnieje zarówno w szablonie wywołującym, jak i w wywoływanym szablonie, zawartość obiektu wywołującego zastąpi dowolną zawartość w wywołaniu szablonu.

Oto przykład:

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

W tym kontekście wywołanie evaluateTemplate('ST1') metody spowoduje utworzenie następującej struktury wewnętrznej:

[MyStruct
    Text = foo
    Speak = bar
]

Należy pamiętać, że ten styl kompozycji może istnieć tylko na poziomie głównym. Jeśli istnieje odwołanie do innego szablonu ustrukturyzowanego we właściwości, rozwiązanie jest kontekstowe dla tej właściwości.

Odwołanie do pliku zewnętrznego w załączniku ustrukturyzowane

Istnieją dwie wstępnie utworzone funkcje używane do plików referencyjnych zewnętrznych

  1. fromFile(fileAbsoluteOrRelativePath) ładuje określony plik. Zawartość zwrócona przez tę funkcję będzie obsługiwać ocenę zawartości. Obliczane są odwołania, właściwości i wyrażenia szablonu.
  2. ActivityAttachment(content, contentType) ustawia wartość , contentType jeśli nie została jeszcze określona w zawartości.

Dzięki tym dwóm wstępnie utworzonym funkcjom można ściągnąć dowolną zawartość zdefiniowaną zewnętrznie, w tym wszystkie typy kart. Użyj następującej struktury LG, aby utworzyć działanie:

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

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

Możesz również użyć załączników, jak pokazano poniżej:

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

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

Dodatkowe informacje