Session class

套件:

botbuilder

管理與使用者的 Bot 交談。

建構函式

Session(ISessionOptions)

建立工作階段的實例。

屬性

connector	用於此工作階段的連接器。
conversationData	交談的所有成員都可以看到的共用交談數據。
dialogData	只有目前對話框可以看到的數據。
library	對話的 Bot 根連結庫。
localizer	目前工作階段的當地語系化工具。
message	從使用者接收的訊息。 對於 Bot 產生的訊息，這只能包含 「to」 & 「from」 欄位。
privateConversationData	使用者只能看見的私人交談數據。
sessionState	工作階段目前的狀態資訊。
userData	與 Bot 所有交談中保存的用戶數據。

方法

activeDialogStackEntry(IDialogState[])	傳回堆疊使用中的對話框或 Null。
beginDialog<T>(string, T)	將交談的控制權傳遞至新的對話。 目前的對話框將會暫停，直到子對話完成為止。 子系結束之後，目前對話方塊將會收到呼叫 dialogResumed（），您可以在其中檢查從子系傳回的任何結果。
cancelDialog(string | number, string, any)	取消現有的對話框，並選擇性地啟動它的位置。 不同於 endDialog（） 和 replaceDialog（） 影響目前對話框，此方法可讓您在堆棧上的任何位置結束父對話。 已取消對話框的父代將會繼續，就像對話已呼叫 endDialog（） 一樣。 將會傳回特殊 ResumeReason.canceled，表示對話框已取消。
clearDialogStack()	清除目前的對話框堆疊。
delay(number)	在傳出訊息之間插入延遲。
dialogStack(IDialogState[])	取得/設定目前的對話框堆疊。 傳回目前對話框的複本，因此，如果對傳回的堆疊進行任何變更，則必須透過第二次呼叫將 session.dialogStack()複製到會話。
dispatch(ISessionState, IMessage, Function)	完成工作階段物件的初始化，然後透過所有已安裝的中間件路由傳送工作階段。 傳入的 next() 函式將會呼叫為中間件鏈結的最後一個步驟。
endConversation(TextOrMessageType, any[])	結束目前的交談，並選擇性地傳送訊息給使用者。
endDialog(TextOrMessageType, any[])	結束目前的對話框，並選擇性地傳送訊息給使用者。 父系將會以 IDialogResult.resumed 繼續 完成的原因。
endDialogWithResult(IDialogResult<any>)	結束目前的對話框，並選擇性地將結果傳回給對話框父代。
error(Error)	表示發生錯誤。 Bot 會透過 on（'error'， err） 事件發出錯誤訊號。
findDialogStackEntry(IDialogState[], string, boolean)	在正向或反向方向中搜尋特定對話框的對話框堆棧，並傳回其索引。
forEachDialogStackEntry(IDialogState[], boolean, (entry: IDialogState, index: number) => void)	列舉正向或反向方向中的所有堆疊對話框專案。
gettext(string, any[])	載入訊息語言的當地語系化字串。 如果傳遞自變數，當地語系化字串將會被視為範本，並使用 sprintf-js 格式化 （如需詳細資訊，請參閱其檔。
isReset()	如果會話已重設，則傳回 true。
messageSent()	如果已為此會話傳送訊息，則傳回 true。
ngettext(string, string, number)	載入訊息語言當地語系化字串的複數形式。 輸出字串會格式化為包含計數，方法是將字串中的 %d 取代為 count。
on(string, (data: any) => void)	註冊事件接聽程式。
popDialogStackEntry(IDialogState[])	從堆棧擷取使用中對話方塊，如果堆疊不是空的，則會傳回新的對話方塊。
preferredLocale(string, (err: Error) => void)	如果未提供任何參數，則傳回慣用的地區設定，否則會設定慣用的地區設定。
pruneDialogStack(IDialogState[], number)	從指定的索引開始刪除所有對話框堆疊專案，並傳回新的使用中對話方塊。
pushDialogStackEntry(IDialogState[], IDialogState)	將新的對話框推送至堆疊，並將它當做使用中的對話框傳回。
replaceDialog<T>(string, T)	結束目前的對話框，並啟動新的對話框。 在新的對話框完成之前，將不會繼續父對話。
reset(string, any)	清除會話呼叫堆疊，並使用已設定的 dialogId 重新啟動交談。
routeToActiveDialog(IRecognizeResult)	將會話分派至使用中的對話框或預設對話框進行處理。
save()	觸發 dialogData、userData、conversationdata或 [privateConversationData'（#privateconversationdata） 所做的變更儲存。
say(TextType, IMessageOptions)
say(TextType, TextType, IMessageOptions)	將文字和選擇性 SSML 訊息傳送給使用者。
sayLocalized(string, TextType, TextType, IMessageOptions)	使用特定當地語系化命名空間，將文字和選擇性 SSML 訊息傳送給使用者。
send(TextOrMessageType, any[])	傳送訊息給使用者。
sendBatch((err: Error, addresses?: IAddress[]) => void)	立即結束目前的批次，並傳遞任何已排入佇列的訊息。
sendLocalized(string, TextOrMessageType, any[])	使用特定當地語系化命名空間將訊息傳送給使用者。
sendTyping()	傳送使用者指出 Bot 正在輸入。 對於長時間執行的作業，應該每隔幾秒鐘呼叫一次。
toRecognizeContext()	以唯讀內容物件的形式傳回會話物件。
validateDialogStack(IDialogState[], Library)	確保對話堆疊上的所有專案都會參考連結庫階層內的有效對話。
watch(string, boolean)	啟用/停用目前會話的監看式。
watchable(string, IWatchableHandler)	加入或擷取可監看的變數。
watchableList()	傳回可監看變數的清單。
watchList()	傳回會話的目前監看變數清單。

建構函式詳細資料

Session(ISessionOptions)

建立工作階段的實例。

new Session(options: ISessionOptions)

參數

options

ISessionOptions

會話組態選項。

屬性詳細資料

connector

用於此工作階段的連接器。

connector: IConnector

屬性值

IConnector

conversationData

交談的所有成員都可以看到的共用交談數據。

conversationData: any

屬性值

any

dialogData

只有目前對話框可以看到的數據。

dialogData: any

屬性值

any

library

對話的 Bot 根連結庫。

library: Library

屬性值

Library

localizer

目前工作階段的當地語系化工具。

localizer: ILocalizer

屬性值

ILocalizer

message

從使用者接收的訊息。 對於 Bot 產生的訊息，這只能包含 「to」 & 「from」 欄位。

message: IMessage

屬性值

IMessage

privateConversationData

使用者只能看見的私人交談數據。

privateConversationData: any

屬性值

any

sessionState

工作階段目前的狀態資訊。

sessionState: ISessionState

屬性值

ISessionState

userData

與 Bot 所有交談中保存的用戶數據。

userData: any

屬性值

any

方法詳細資料

activeDialogStackEntry(IDialogState[])

傳回堆疊使用中的對話框或 Null。

static function activeDialogStackEntry(stack: IDialogState[])

參數

stack

IDialogState[]

要傳回專案的對話框堆疊。

傳回

IDialogState

beginDialog<T>(string, T)

將交談的控制權傳遞至新的對話。 目前的對話框將會暫停，直到子對話完成為止。 子系結束之後，目前對話方塊將會收到呼叫 dialogResumed（），您可以在其中檢查從子系傳回的任何結果。

function beginDialog<T>(id: string, args?: T)

參數

id

string

要啟動之對話框的唯一標識符。

args

T

（選擇性） 自變數，以傳遞至 dialogs begin（） 方法。

傳回

Session

cancelDialog(string | number, string, any)

取消現有的對話框，並選擇性地啟動它的位置。 不同於 endDialog（） 和 replaceDialog（） 影響目前對話框，此方法可讓您在堆棧上的任何位置結束父對話。 已取消對話框的父代將會繼續，就像對話已呼叫 endDialog（） 一樣。 將會傳回特殊 ResumeReason.canceled，表示對話框已取消。

function cancelDialog(dialogId: string | number, replaceWithId?: string, replaceWithArgs?: any)

參數

dialogId

string | number

• dialogId：{string} - 結束對話的標識符。 如果對話堆疊上有多個對話發生，則會取消最後一次發生。
• dialogId：{number} - 要取消之堆棧上對話框的索引。 這是從動作處理程式取消對話框的慣用方式，因為它可確保已取消正確的實例。

replaceWithId

string

（選擇性） 指定要在取消的對話框位置啟動的識別碼。 這可防止對話父代繼續。

replaceWithArgs

any

（選擇性） 要傳遞至新對話框的自變數。

傳回

Session

clearDialogStack()

清除目前的對話框堆疊。

function clearDialogStack()

傳回

Session

delay(number)

在傳出訊息之間插入延遲。

function delay(delay: number)

參數

delay

number

要暫停的毫秒數。

傳回

Session

dialogStack(IDialogState[])

取得/設定目前的對話框堆疊。 傳回目前對話框的複本，因此，如果對傳回的堆疊進行任何變更，則必須透過第二次呼叫將 session.dialogStack()複製到會話。

function dialogStack(newStack?: IDialogState[])

參數

newStack

IDialogState[]

（選擇性） 對話框堆疊，以指派給會話。 會話 dialogData 將會更新，以反映新使用中對話框的狀態。

傳回

IDialogState[]

dispatch(ISessionState, IMessage, Function)

完成工作階段物件的初始化，然後透過所有已安裝的中間件路由傳送工作階段。 傳入的 next() 函式將會呼叫為中間件鏈結的最後一個步驟。

function dispatch(sessionState: ISessionState, message: IMessage, next: Function)

參數

sessionState

ISessionState

目前的工作階段狀態。 如果 null 新的交談會從設定的 dialogId 開始，。

message

IMessage

要透過中間件路由傳送的訊息。

next

Function

要叫用作為中間件鏈結最後一個步驟的函式。

傳回

Session

endConversation(TextOrMessageType, any[])

結束目前的交談，並選擇性地傳送訊息給使用者。

function endConversation(message?: TextOrMessageType, args: any[])

參數

message

TextOrMessageType

（選擇性）文字/訊息，以在結束交談之前傳送使用者。

args

any[]

（選擇性） 自變數，當 訊息 為 {string|string[]}時，用來格式化最終輸出文字的自變數。

傳回

Session

endDialog(TextOrMessageType, any[])

結束目前的對話框，並選擇性地傳送訊息給使用者。 父系將會以 IDialogResult.resumed 繼續 完成的原因。

function endDialog(message?: TextOrMessageType, args: any[])

參數

message

TextOrMessageType

（選擇性）結束對話方塊之前傳送使用者的文字/訊息。

args

any[]

（選擇性） 自變數，當 訊息 為 {string|string[]}時，用來格式化最終輸出文字的自變數。

傳回

Session

endDialogWithResult(IDialogResult<any>)

結束目前的對話框，並選擇性地將結果傳回給對話框父代。

function endDialogWithResult(result?: IDialogResult<any>)

參數

result

IDialogResult<any>

（選擇性）傳送用戶的結果。 您想要傳回的值應該位於 [回應] 字段中。

傳回

Session

error(Error)

表示發生錯誤。 Bot 會透過 on（'error'， err） 事件發出錯誤訊號。

function error(err: Error)

參數

err

Error

發生錯誤。

傳回

Session

findDialogStackEntry(IDialogState[], string, boolean)

在正向或反向方向中搜尋特定對話框的對話框堆棧，並傳回其索引。

static function findDialogStackEntry(stack: IDialogState[], dialogId: string, reverse?: boolean)

參數

stack

IDialogState[]

要搜尋的對話框堆疊。

dialogId

string

要搜尋之對話框的唯一標識符，格式為 <namespace>:<dialog>。

reverse

boolean

（選擇性）如果為 true，則會從使用中的對話框開始搜尋堆疊，並依根目錄的方式運作。

傳回

number

forEachDialogStackEntry(IDialogState[], boolean, (entry: IDialogState, index: number) => void)

列舉正向或反向方向中的所有堆疊對話框專案。

static function forEachDialogStackEntry(stack: IDialogState[], reverse: boolean, fn: (entry: IDialogState, index: number) => void)

參數

stack

IDialogState[]

要列舉的對話框堆疊。

reverse

boolean

如果為 true，則會從使用中的對話框開始列舉專案，並處理到根對話。

fn

(entry: IDialogState, index: number) => void

函式，用來叫用堆疊上的每個專案。

gettext(string, any[])

載入訊息語言的當地語系化字串。 如果傳遞自變數，當地語系化字串將會被視為範本，並使用 sprintf-js 格式化 （如需詳細資訊，請參閱其檔。

function gettext(msgid: string, args: any[])

參數

msgid

string

要當做當地語系化字串資料表中索引鍵使用的字串。 一般而言，這隻會是字串的英文版本。

args

any[]

（選擇性） 用來格式化最終輸出字串的自變數。

傳回

string

isReset()

如果會話已重設，則傳回 true。

function isReset()

傳回

boolean

messageSent()

如果已為此會話傳送訊息，則傳回 true。

function messageSent()

傳回

boolean

ngettext(string, string, number)

載入訊息語言當地語系化字串的複數形式。 輸出字串會格式化為包含計數，方法是將字串中的 %d 取代為 count。

function ngettext(msgid: string, msgid_plural: string, count: number)

參數

msgid

string

字串的單一形式，用來做為當地語系化字串資料表中的索引鍵。 使用 %d 來指定計數應前往的位置。

msgid_plural

string

字串的複數形式，做為當地語系化字串資料表中的索引鍵。 使用 %d 來指定計數應前往的位置。

count

number

判斷是否應該使用字串的單數或複數形式時要使用的計數。

傳回

string

on(string, (data: any) => void)

註冊事件接聽程式。

function on(event: string, listener: (data: any) => void)

參數

event

string

事件的名稱。 事件類型：

• 錯誤： 發生錯誤。 傳遞 JavaScript Error 物件。

listener

(data: any) => void

要叫用的函式。

popDialogStackEntry(IDialogState[])

從堆棧擷取使用中對話方塊，如果堆疊不是空的，則會傳回新的對話方塊。

static function popDialogStackEntry(stack: IDialogState[])

參數

stack

IDialogState[]

要更新的對話框堆疊。

傳回

IDialogState

preferredLocale(string, (err: Error) => void)

如果未提供任何參數，則傳回慣用的地區設定，否則會設定慣用的地區設定。

function preferredLocale(locale?: string, callback?: (err: Error) => void)

參數

locale

string

（選擇性） 用於當地語系化訊息的地區設定。

callback

(err: Error) => void

（選擇性） 函式會在已針對提供的地區設定載入本地化數據表時呼叫。

傳回

string

pruneDialogStack(IDialogState[], number)

從指定的索引開始刪除所有對話框堆疊專案，並傳回新的使用中對話方塊。

static function pruneDialogStack(stack: IDialogState[], start: number)

參數

stack

IDialogState[]

要更新的對話框堆疊。

start

number

要移除之第一個專案的索引。

傳回

IDialogState

pushDialogStackEntry(IDialogState[], IDialogState)

將新的對話框推送至堆疊，並將它當做使用中的對話框傳回。

static function pushDialogStackEntry(stack: IDialogState[], entry: IDialogState)

參數

stack

IDialogState[]

要更新的對話框堆疊。

entry

IDialogState

要推送至堆疊的對話框專案。

傳回

IDialogState

replaceDialog<T>(string, T)

結束目前的對話框，並啟動新的對話框。 在新的對話框完成之前，將不會繼續父對話。

function replaceDialog<T>(id: string, args?: T)

參數

id

string

要啟動之對話框的唯一標識符。

args

T

（選擇性） 自變數，以傳遞至 dialogs begin（） 方法。

傳回

Session

reset(string, any)

清除會話呼叫堆疊，並使用已設定的 dialogId 重新啟動交談。

function reset(dialogId?: string, dialogArgs?: any)

參數

dialogId

string

（選擇性）要啟動之對話框的識別碼。

dialogArgs

any

（選擇性） 自變數，以傳遞至 dialogs begin（） 方法。

傳回

Session

routeToActiveDialog(IRecognizeResult)

將會話分派至使用中的對話框或預設對話框進行處理。

function routeToActiveDialog(recognizeResult?: IRecognizeResult)

參數

recognizeResult

IRecognizeResult

（選擇性） 從呼叫 Library.findRoutes（）傳回的結果，Library.findActiveDialogRoutes（）、 * 或 Dialog.recognize（）。

save()

觸發 dialogData、userData、conversationdata或 [privateConversationData'（#privateconversationdata） 所做的變更儲存。

function save()

傳回

Session

say(TextType, IMessageOptions)

function say(text: TextType, options?: IMessageOptions)

參數

text

TextType

options

IMessageOptions

傳回

Session

say(TextType, TextType, IMessageOptions)

將文字和選擇性 SSML 訊息傳送給使用者。

function say(text: TextType, speak?: TextType, options?: IMessageOptions)

參數

text

TextType

要傳送給使用者的文字。 這可以是 Null，只能傳送 SSML 或附件。

speak

TextType

（選擇性）應向使用者表達的訊息。 訊息的格式應為 語音合成標記語言 （SSML）。 如果傳遞陣列，則會隨機選擇回應。

options

IMessageOptions

（選擇性） 應包含在傳出訊息上的屬性。

傳回

Session

sayLocalized(string, TextType, TextType, IMessageOptions)

使用特定當地語系化命名空間，將文字和選擇性 SSML 訊息傳送給使用者。

function sayLocalized(libraryNamespace: string, text: TextType, speak?: TextType, options?: IMessageOptions)

參數

libraryNamespace

string

Namespace用於當地語系化訊息。

text

TextType

要傳送給使用者的文字。 這可以是 Null，只能傳送 SSML 或附件。

speak

TextType

（選擇性）應向使用者表達的訊息。 訊息的格式應為 語音合成標記語言 （SSML）。 如果傳遞陣列，則會隨機選擇回應。

options

IMessageOptions

（選擇性） 應包含在傳出訊息上的屬性。

傳回

Session

send(TextOrMessageType, any[])

傳送訊息給使用者。

function send(message: TextOrMessageType, args: any[])

參數

message

TextOrMessageType

要傳送給使用者的文字/訊息。 如果傳遞陣列，則會隨機選擇回應。

args

any[]

（選擇性） 自變數，當 訊息 為 {string|string[]}時，用來格式化最終輸出文字的自變數。

傳回

Session

sendBatch((err: Error, addresses?: IAddress[]) => void)

立即結束目前的批次，並傳遞任何已排入佇列的訊息。

function sendBatch(done?: (err: Error, addresses?: IAddress[]) => void)

參數

done

(err: Error, addresses?: IAddress[]) => void

（選擇性） 函式會在批次成功剖析或因某些原因而失敗時呼叫。

sendLocalized(string, TextOrMessageType, any[])

使用特定當地語系化命名空間將訊息傳送給使用者。

function sendLocalized(libraryNamespace: string, message: TextOrMessageType, args: any[])

參數

libraryNamespace

string

Namespace用於當地語系化訊息。

message

TextOrMessageType

要傳送給使用者的文字/訊息。

args

any[]

（選擇性） 自變數，當 訊息 為 {string|string[]}時，用來格式化最終輸出文字的自變數。

傳回

Session

sendTyping()

傳送使用者指出 Bot 正在輸入。 對於長時間執行的作業，應該每隔幾秒鐘呼叫一次。

function sendTyping()

傳回

Session

toRecognizeContext()

以唯讀內容物件的形式傳回會話物件。

function toRecognizeContext()

傳回

IRecognizeContext

validateDialogStack(IDialogState[], Library)

確保對話堆疊上的所有專案都會參考連結庫階層內的有效對話。

static function validateDialogStack(stack: IDialogState[], root: Library)

參數

stack

IDialogState[]

要驗證的對話框堆疊。

root

Library

連結庫階層的根目錄，通常是 Bot。

傳回

boolean

watch(string, boolean)

啟用/停用目前會話的監看式。

function watch(variable: string, enable?: boolean)

參數

variable

string

要監看/取消監看的變數名稱。

enable

boolean

（選擇性）如果為 true，則會監看變數，否則不會監看變數。 默認值為 true。

傳回

Session

watchable(string, IWatchableHandler)

加入或擷取可監看的變數。

static function watchable(variable: string, handler?: IWatchableHandler)

參數

variable

string

可監看的變數名稱。 案例僅用於顯示。

handler

IWatchableHandler

（選擇性）用來擷取變數目前值的函式。 如果指定新的處理程式將會註冊，則將會擷取現有的處理程式。

傳回

IWatchableHandler

watchableList()

傳回可監看變數的清單。

static function watchableList()

傳回

string[]

watchList()

傳回會話的目前監看變數清單。

function watchList()

傳回

string[]