結構化回應範本

發行項
10/24/2023

適用于： SDK v4

結構化回應範本可讓開發人員定義複雜的結構，以支援語言產生（LG）的廣泛功能，例如範本化、組合，同時將結構化回應的解譯留給 LG 程式庫的呼叫者。

針對 Bot 應用程式，提供下列支援：

活動定義
卡片定義

Bot Framework 活動範本包含數個可自訂的欄位。下列屬性是最常用的屬性，可透過活動範本定義進行設定：

屬性	使用案例
Text	顯示通道用來以視覺化方式呈現的文字
說話	頻道用來轉譯奧迪的口語文字
附件	具有其類型的附件清單。通道用來轉譯為 UI 卡片或其他一般檔案附件類型。
SuggestedActions	轉譯為使用者建議的動作清單。
InputHint	控制支援語音輸入之裝置上的音訊擷取串流狀態。可能的值包括 `accepting` 、 `expecting` 或 `ignoring` 。

範本解析程式未實作預設後援行為。如果未指定屬性，則會保持未指定。例如， Speak 只有在 Text 指定屬性時，屬性不會自動指派為 Text 屬性。

定義

以下是結構化範本的定義：

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

以下是基本文字模板的範例：

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

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

以下是具有建議動作的文字範例。使用 | 表示清單。

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

以下是主圖卡片定義的範例：

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

注意

LG 提供卡片定義中的一些變化，其會轉換成與 SDK 卡片定義一致。例如， image 即使 SDK 卡片定義中只支援 SDK 卡定義中， images LG 中的所有卡片定義都支援和 images 欄位。

HeroCard 或縮圖卡片中所有 image 和 images 欄位中定義的值會合並並轉換成所產生卡片中的影像清單。針對其他類型的卡片，範本中最後一個定義的值將會指派給 image 欄位。您指派給 image/images 欄位的值可以是字串、調適型運算式，或是使用 | 格式的陣列。

以下是先前範本的組合：

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

根據預設，在評估結構化範本期間，會評估任何範本參考一次。

例如，針對和屬性， # AskForAge.prompt 傳回相同的解析度文字 Speak 。 Text

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

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

您可以使用 <TemplateName>!() 來要求結構化範本內每個參考的新評估。

在下列範例中，和 Text 可能會有不同的解析度文字， Speak 因為 GetAge 會在每個實例上重新評估。

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

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

以下說明如何顯示卡片的浮動切換：

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

使用 \ 作為逸出字元。

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

結構化範本組合

結構化範本支援下列組合行為：

組合是結構內容感知。如果所參考的目標範本也是結構化範本，則結構類型必須相符。例如，可以在另一個 ActivityTemplate 中參考 ActivityTemplate。
簡單或條件式回應範本的參考可以存在於結構化範本內的任何位置。

假設您有下列範本：

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

# T2
- This is awesome

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

對 evaluateTemplate('T1') 的呼叫會導致下列內部結構：

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

另一個結構化範本的完整參考

您可以將另一個結構化範本的參考納入為另一個結構化範本中的屬性，或作為另一個簡單或條件式回應範本中的參考

以下是另一個結構化範本的完整參考範例：

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

使用此內容時，對 evaluateTemplate('ST1') 的呼叫將會產生下列內部結構：

[MyStruct
    Text = foo
    Speak = bar
]

當呼叫範本和呼叫的範本中都有相同的屬性時，呼叫端中的內容將會覆寫所呼叫範本中的任何內容。

以下為範例：

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

在此內容中，對的呼叫 evaluateTemplate('ST1') 會導致下列內部結構：

[MyStruct
    Text = foo
    Speak = bar
]

請注意，這種組合樣式只能存在於根層級。如果屬性內有另一個結構化範本的參考，則解析與該屬性的內容相關。

附件結構化中的外部檔案參考

有兩個預先建置的函式可用來外部參考檔案

fromFile(fileAbsoluteOrRelativePath) 載入指定的檔案。此函式傳回的內容將支援內容評估。會評估範本參考、屬性和運算式。
ActivityAttachment(content, contentType)contentType如果內容中尚未指定，則會設定。

透過這兩個預先建置的函式，您可以提取任何外部定義的內容，包括所有卡片類型。使用下列結構化 LG 來撰寫活動：

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

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

您也可以使用附件，如下所示：

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

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

其他資訊

C# API 參考
JavaScript API 參考
若要瞭解如何分析和偵錯範本，請參閱使用 Adaptive Tools 進行偵錯。

共用方式為

結構化回應範本

定義

結構化範本組合

另一個結構化範本的完整參考

附件結構化中的外部檔案參考

其他資訊

其他資源