TurnContext class

套件:

botbuilder-core

提供 Bot 回合的內容。

備註

內容提供處理傳入活動所需的資訊。 內容物件是由 BotAdapter 所建立，並會保存回合的長度。

建構函式

TurnContext(BotAdapter, Partial<Activity>)	建立 TurnCoNtext 類別的新實例。
TurnContext(TurnContext)	建立 TurnCoNtext 類別的新實例。

屬性

activity	取得與此回合相關聯的活動。
adapter	取得建立此內容物件的 Bot 配接器。
bufferedReplyActivities	當 時 context.activity.deliveryMode == 'expectReplies' 要傳送的活動清單。
locale	取得儲存在 turnState 中的地區設定。 設定儲存在 turnState 中的地區設定。
responded	指出 Bot 是否已在此回合回復使用者。 在目前的回合內容上設定回應旗標。
turnState	取得在此內容物件上註冊的服務。

方法

applyConversationReference(Partial<Activity>, Partial<ConversationReference>, boolean)	更新具有現有交談參考傳遞資訊的活動。
deleteActivity(string | Partial<ConversationReference>)	以非同步方式刪除先前傳送的活動。
getConversationReference(Partial<Activity>)	從活動複製交談參考資訊。
getMentions(Partial<Activity>)	取得活動中包含的所有提及實體。
getReplyConversationReference(Partial<Activity>, ResourceResponse)	從已傳送活動的資源回應複製交談參考資訊。
onDeleteActivity(DeleteActivityHandler)	新增刪除活動作業的回應處理常式。
onSendActivities(SendActivitiesHandler)	新增傳送活動作業的回應處理常式。
onUpdateActivity(UpdateActivityHandler)	新增更新活動作業的回應處理常式。
removeMentionText(Partial<Activity>, string)	從活動的文字中移除指定識別碼的提及，並傳回更新的文字。 請小心使用;此函式會改變活動的 文字 屬性。
removeRecipientMention(Partial<Activity>)	從活動的文字中移除活動的 收件者 提及，並傳回更新的文字。 請小心使用;此函式會改變活動的 文字 屬性。
sendActivities(Partial<Activity>[])	以非同步方式將一組活動傳送給傳入活動的傳送者。
sendActivity(string | Partial<Activity>, string, string)	以非同步方式將活動傳送給傳入活動的傳送者。
sendTraceActivity(string, any, string, string)	以非同步方式將活動傳送給傳入活動的傳送者。
updateActivity(Partial<Activity>)	以非同步方式更新先前傳送的活動。

建構函式詳細資料

TurnContext(BotAdapter, Partial<Activity>)

建立 TurnCoNtext 類別的新實例。

new TurnContext(adapterOrContext: BotAdapter, request: Partial<Activity>)

參數

adapterOrContext

BotAdapter

建立內容的配接器。

request

Partial<Activity>

回合的傳入活動。

TurnContext(TurnContext)

建立 TurnCoNtext 類別的新實例。

new TurnContext(adapterOrContext: TurnContext)

參數

adapterOrContext

TurnContext

建立內容的配接器。

屬性詳細資料

activity

取得與此回合相關聯的活動。

Activity activity

屬性值

Activity

與此回合相關聯的活動。

備註

此範例示範如何從活動取得使用者修剪的語句：

const utterance = (context.activity.text || '').trim();

adapter

取得建立此內容物件的 Bot 配接器。

BotAdapter adapter

屬性值

BotAdapter

建立此內容物件的 Bot 配接器。

bufferedReplyActivities

當 時 context.activity.deliveryMode == 'expectReplies' 要傳送的活動清單。

bufferedReplyActivities: Partial<Activity>[]

屬性值

Partial<Activity>[]

locale

取得儲存在 turnState 中的地區設定。 設定儲存在 turnState 中的地區設定。

string | undefined locale

屬性值

string | undefined

儲存在 turnState 中的地區設定。

responded

指出 Bot 是否已在此回合回復使用者。 在目前的回合內容上設定回應旗標。

boolean responded

屬性值

boolean

True 是表示 如果至少針對目前的回合傳送一個回應;否則為 false。

備註

如果目前回合至少傳送一個回應，則為true;否則為false。 使用此方法可判斷您的 Bot 是否需要在其他正常處理之後執行後援邏輯。

追蹤活動未設定此旗標。

例如：

await routeActivity(context);
if (!context.responded) {
   await context.sendActivity(`I'm sorry. I didn't understand.`);
}

turnState

取得在此內容物件上註冊的服務。

TurnContextStateCollection turnState

屬性值

TurnContextStateCollection

在此內容物件上註冊的服務。

備註

中介軟體、其他元件和服務通常會使用此專案來快取 Bot 在回合期間多次要求的資訊。 您可以使用此快取，在 Bot 的元件之間傳遞資訊。

例如：

const cartKey = Symbol();
const cart = await loadUsersShoppingCart(context);
context.turnState.set(cartKey, cart);

提示

建立中介軟體或協力廠商元件時，請使用快取金鑰的唯一符號，以避免與 Bot 或其他中介軟體或其他中介軟體或元件發生狀態命名衝突。

方法詳細資料

applyConversationReference(Partial<Activity>, Partial<ConversationReference>, boolean)

更新具有現有交談參考傳遞資訊的活動。

static function applyConversationReference(activity: Partial<Activity>, reference: Partial<ConversationReference>, isIncoming?: boolean): Partial<Activity>

參數

activity

Partial<Activity>

要更新的活動。

reference

Partial<ConversationReference>

複製傳遞資訊的來源交談參考。

isIncoming

boolean

選擇性。 true 將活動視為傳入活動，其中 Bot 是收件者;否則為 false 。 預設值為 false ，而活動會將 Bot 顯示為傳送者。

傳回

Partial<Activity>

此活動會使用傳遞資訊進行更新。

備註

在傳入的活動上呼叫 getConversationReference 方法，以取得交談參考，然後可用來以正確的傳遞資訊更新傳出活動。

deleteActivity(string | Partial<ConversationReference>)

以非同步方式刪除先前傳送的活動。

function deleteActivity(idOrReference: string | Partial<ConversationReference>): Promise<void>

參數

idOrReference

string | Partial<ConversationReference>

要刪除之活動的識別碼或交談參考。

傳回

Promise<void>

代表非同步作業的 Promise。

備註

如果指定識別碼，則會使用目前要求的交談參考來取得所需的其餘資訊。

例如：

const matched = /approve (.*)/i.exec(context.activity.text);
if (matched) {
   const savedId = await approveExpenseReport(matched[1]);
   await context.deleteActivity(savedId);
}

另請參閱

• sendActivity
• updateActivity
• getReplyConversationReference

getConversationReference(Partial<Activity>)

從活動複製交談參考資訊。

static function getConversationReference(activity: Partial<Activity>): Partial<ConversationReference>

參數

activity

Partial<Activity>

要從中取得資訊的活動。

傳回

Partial<ConversationReference>

包含此活動之交談的交談參考。

備註

您可以將交談參考儲存為 JSON 物件，並在稍後使用它來主動傳送訊息給使用者。

例如：

const reference = TurnContext.getConversationReference(context.request);

另請參閱

• BotAdapter.continueConversation

getMentions(Partial<Activity>)

取得活動中包含的所有提及實體。

static function getMentions(activity: Partial<Activity>): Mention[]

參數

activity

Partial<Activity>

活動。

傳回

Mention[]

活動中包含的所有提及實體。

備註

活動的 實體 屬性包含有關此活動的中繼資料物件的一般清單，而且可以包含 提及 實體。 這個方法會傳回指定活動的所有這類實體。

例如：

const mentions = TurnContext.getMentions(turnContext.request);

getReplyConversationReference(Partial<Activity>, ResourceResponse)

從已傳送活動的資源回應複製交談參考資訊。

static function getReplyConversationReference(activity: Partial<Activity>, reply: ResourceResponse): Partial<ConversationReference>

參數

activity

Partial<Activity>

傳送的活動。

reply

ResourceResponse

活動的資源回應，由 sendActivity 或 sendActivities 方法傳回。

傳回

Partial<ConversationReference>

可儲存及稍後用來刪除或更新活動的 ConversationReference。

備註

您可以將交談參考儲存為 JSON 物件，並在稍後使用它來更新或刪除訊息。

例如：

var reply = await context.sendActivity('Hi');
var reference = TurnContext.getReplyConversationReference(context.activity, reply);

另請參閱

• deleteActivity
• updateActivity

onDeleteActivity(DeleteActivityHandler)

新增刪除活動作業的回應處理常式。

function onDeleteActivity(handler: DeleteActivityHandler): this

參數

handler

DeleteActivityHandler

要加入至內容物件的處理常式。

傳回

this

更新的內容物件。

備註

這個方法會傳回回合內容物件的參考。

呼叫 deleteActivity 方法時，會依新增至內容物件的順序呼叫已註冊的處理常式，再刪除活動。

此範例示範如何接聽和記錄活動刪除。

context.onDeleteActivity(async (ctx, reference, next) => {
   // Delete activity
   await next();

   // Log delete
   logDelete(activity);
});

onSendActivities(SendActivitiesHandler)

新增傳送活動作業的回應處理常式。

function onSendActivities(handler: SendActivitiesHandler): this

參數

handler

SendActivitiesHandler

要加入至內容物件的處理常式。

傳回

this

更新的內容物件。

備註

這個方法會傳回回合內容物件的參考。

呼叫 sendActivity 或 sendActivities 方法時，會依新增至內容物件的順序呼叫已註冊的處理常式，再傳送活動。

此範例示範如何接聽和記錄傳出 message 活動。

context.onSendActivities(async (ctx, activities, next) => {
   // Log activities before sending them.
   activities.filter(a => a.type === 'message').forEach(a => logSend(a));

   // Allow the send process to continue.
   next();
});

onUpdateActivity(UpdateActivityHandler)

新增更新活動作業的回應處理常式。

function onUpdateActivity(handler: UpdateActivityHandler): this

參數

handler

UpdateActivityHandler

要加入至內容物件的處理常式。

傳回

this

更新的內容物件。

備註

這個方法會傳回回合內容物件的參考。

呼叫 updateActivity 方法時，註冊的處理常式會依更新活動之前新增至內容物件的順序呼叫。

此範例示範如何接聽和記錄活動更新。

context.onUpdateActivity(async (ctx, activity, next) => {
   // Replace activity
   await next();

   // Log update
   logUpdate(activity);
});

removeMentionText(Partial<Activity>, string)

從活動的文字中移除指定識別碼的提及，並傳回更新的文字。 請小心使用;此函式會改變活動的 文字 屬性。

static function removeMentionText(activity: Partial<Activity>, id: string): string

參數

activity

Partial<Activity>

要從中移除的活動。

id

string

在提及時移除的使用者或 Bot 識別碼。

傳回

string

更新活動的文字。

備註

某些頻道，例如 Microsoft Teams，將提及新增至訊息活動的文字。

使用此協助程式方法來修改活動的 文字 屬性。 它會移除指定 Bot 或使用者識別碼的所有提及，然後傳回更新的屬性值。

例如，當您從包含 「@echoBot Hi Bot」 文字的活動中移除 echoBot 的提及時，活動文字會更新，而 方法會傳回 「Hi Bot」。

提及 實體 的格式與通道相依。 不過，提及的 文字 屬性應該包含使用者在活動文字中顯示的確切文字。

例如，不論通道使用 「username 」 或 「@username」，此字串都位於活動的文字中，而且這個方法將會從文字中移除該字串的所有出現專案。

例如：

const updatedText = TurnContext.removeMentionText(activity, activity.recipient.id);

另請參閱

• removeRecipientMention

removeRecipientMention(Partial<Activity>)

從活動的文字中移除活動的 收件者 提及，並傳回更新的文字。 請小心使用;此函式會改變活動的 文字 屬性。

static function removeRecipientMention(activity: Partial<Activity>): string

參數

activity

Partial<Activity>

要從中移除的活動。

傳回

string

更新活動的文字。

備註

某些頻道，例如 Microsoft Teams，將提及詳細資料新增至訊息活動的文字。

使用此協助程式方法來修改活動的 文字 屬性。 它會移除活動 收件者 的所有提及，然後傳回更新的屬性值。

例如：

const updatedText = TurnContext.removeRecipientMention(turnContext.request);

另請參閱

• removeMentionText

sendActivities(Partial<Activity>[])

以非同步方式將一組活動傳送給傳入活動的傳送者。

function sendActivities(activities: Partial<Activity>[]): Promise<ResourceResponse[]>

參數

activities

Partial<Activity>[]

要傳送的活動。

傳回

Promise<ResourceResponse[]>

具有 ResourceResponse 的承諾。

備註

如果成功傳送活動，會產生 ResourceResponse 物件的陣列，其中包含指派給活動的接收通道識別碼。

傳送之前，會根據輸入輸入活動的傳遞資訊來更新每個輸出活動的傳遞資訊。

例如：

await context.sendActivities([
   { type: 'typing' },
   { type: 'delay', value: 2000 },
   { type: 'message', text: 'Hello... How are you?' }
]);

另請參閱

• sendActivity
• updateActivity
• deleteActivity

sendActivity(string | Partial<Activity>, string, string)

以非同步方式將活動傳送給傳入活動的傳送者。

function sendActivity(activityOrText: string | Partial<Activity>, speak?: string, inputHint?: string): Promise<ResourceResponse | undefined>

參數

activityOrText

string | Partial<Activity>

要傳送的活動或文字。

speak

string

選擇性。 Bot 在已啟用語音功能的通道上所要說出的文字。

inputHint

string

選擇性。 指出在訊息傳遞至用戶端之後，Bot 是否接受、預期或忽略使用者輸入。 其中一個：'acceptingInput'、'ignoringInput'或 'expectingInput'。 預設值為 'acceptingInput'。

傳回

Promise<ResourceResponse | undefined>

具有 ResourceResponse 的承諾。

備註

如果成功傳送活動，會產生 ResourceResponse 物件，其中包含指派給活動的接收通道識別碼。

如需 activityOrText 參數內容所加加的限制，請參閱通道的檔。

若要控制 Bot 語音的各種特性，例如語音、速率、音量、發音和音調，請以語音合成標記語言 (SSML) 格式指定 說話 。

例如：

await context.sendActivity(`Hello World`);

另請參閱

• sendActivities
• updateActivity
• deleteActivity

sendTraceActivity(string, any, string, string)

以非同步方式將活動傳送給傳入活動的傳送者。

function sendTraceActivity(name: string, value?: any, valueType?: string, label?: string): Promise<ResourceResponse | undefined>

參數

name

string

要傳送的活動或文字。

value

any

選擇性。 Bot 在已啟用語音功能的通道上所要說出的文字。

valueType

string

選擇性。 指出 Bot 是否接受、預期或忽略使用者

label

string

選擇性。 指出 Bot 是否接受、預期或忽略使用者

傳回

Promise<ResourceResponse | undefined>

具有 ResourceResponse 的承諾。

備註

建立並傳送追蹤活動。 只有在通道是模擬器時，才會傳送追蹤活動。

例如：

await context.sendTraceActivity(`The following exception was thrown ${msg}`);

另請參閱

• sendActivities

updateActivity(Partial<Activity>)

以非同步方式更新先前傳送的活動。

function updateActivity(activity: Partial<Activity>): Promise<ResourceResponse | void>

參數

activity

Partial<Activity>

取代原始活動。

傳回

Promise<ResourceResponse | void>

具有 ResourceResponse 的承諾。

備註

取代活動的 識別碼 表示要取代之交談中的活動。

例如：

const matched = /approve (.*)/i.exec(context.activity.text);
if (matched) {
   const update = await approveExpenseReport(matched[1]);
   await context.updateActivity(update);
}

另請參閱

• sendActivity
• deleteActivity
• getReplyConversationReference