TurnContext class

パッケージ:

botbuilder-core

ボットのターンのコンテキストを提供します。

注釈

コンテキストは、受信アクティビティを処理するために必要な情報を提供します。 コンテキスト オブジェクトは BotAdapter によって作成され、ターンの長さに対して保持されます。

コンストラクター

TurnContext(BotAdapter, Partial<Activity>)	TurnContext クラスの新しいインスタンスを作成します。
TurnContext(TurnContext)	TurnContext クラスの新しいインスタンスを作成します。

プロパティ

activity	このターンに関連付けられているアクティビティを取得します。
adapter	このコンテキスト オブジェクトを作成したボット アダプターを取得します。
bufferedReplyActivities	ときに context.activity.deliveryMode == 'expectReplies'送信するアクティビティの一覧。
locale	turnState に格納されているロケールを取得します。 turnState に格納されているロケールを設定します。
responded	ボットがこのターンでユーザーに返信したかどうかを示します。 現在のターン コンテキストで応答フラグを設定します。
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)	アクティビティのテキストから特定の ID のメンションを削除し、更新されたテキストを返します。 注意して使用してください。この関数は、アクティビティの text プロパティを変更します。
removeRecipientMention(Partial<Activity>)	アクティビティの 受信者 のメンションをアクティビティのテキストから削除し、更新されたテキストを返します。 注意して使用してください。この関数は、アクティビティの text プロパティを変更します。
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

このコンテキスト オブジェクトを作成したボット アダプターを取得します。

BotAdapter adapter

プロパティ値

BotAdapter

このコンテキスト オブジェクトを作成したボット アダプター。

bufferedReplyActivities

ときに context.activity.deliveryMode == 'expectReplies'送信するアクティビティの一覧。

bufferedReplyActivities: Partial<Activity>[]

プロパティ値

Partial<Activity>[]

locale

turnState に格納されているロケールを取得します。 turnState に格納されているロケールを設定します。

string | undefined locale

プロパティ値

string | undefined

turnState に格納されているロケール。

responded

ボットがこのターンでユーザーに返信したかどうかを示します。 現在のターン コンテキストで応答フラグを設定します。

boolean responded

プロパティ値

boolean

True を指定すると、現在のターンに対して少なくとも 1 つの応答が送信されます。それ以外の場合は false。

注釈

現在 のターンに対して少なくとも 1 つの応答が送信された場合は true。それ以外の場合は false。 これを使用して、ボットが他の通常の処理の後にフォールバック ロジックを実行する必要があるかどうかを判断します。

トレース アクティビティでは、このフラグは設定されません。

次に例を示します。

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

turnState

このコンテキスト オブジェクトに登録されているサービスを取得します。

TurnContextStateCollection turnState

プロパティ値

TurnContextStateCollection

このコンテキスト オブジェクトに登録されているサービス。

注釈

ミドルウェア、その他のコンポーネント、サービスでは、通常、これを使用して、ターン中にボットから複数回要求される可能性がある情報をキャッシュします。 このキャッシュを使用して、ボットのコンポーネント間で情報を渡すことができます。

次に例を示します。

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

ヒント

ミドルウェアまたはサードパーティコンポーネントを作成する場合は、キャッシュ キーに一意のシンボルを使用して、ボットまたはその他のミドルウェアまたはコンポーネントとの状態の名前付けの競合を回避します。

メソッドの詳細

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 アクティビティを受信アクティビティとして扱う場合。ボットは受信者です。それ以外の場合は false。 既定値は で false、アクティビティにはボットが送信者として表示されます。

戻り値

Partial<Activity>

このアクティビティは、配信情報で更新されました。

注釈

受信アクティビティで getConversationReference メソッドを呼び出して会話参照を取得します。この参照を使用して、正しい配信情報で送信アクティビティを更新できます。

deleteActivity(string | Partial<ConversationReference>)

以前に送信されたアクティビティを非同期的に削除します。

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

パラメーター

idOrReference

string | Partial<ConversationReference>

削除するアクティビティの ID または会話参照。

戻り値

Promise<void>

非同期操作を表す promise。

注釈

ID が指定されている場合は、現在の要求の会話参照を使用して、必要な残りの情報を取得します。

以下に例を示します。

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

アクティビティに含まれるすべての言及時エンティティ。

注釈

アクティビティの entities プロパティには、このアクティビティに関連するメタデータ オブジェクトのフラット なリストが含まれており、 メンション エンティティを含めることができます。 このメソッドは、特定のアクティビティに対してこのようなエンティティをすべて返します。

以下に例を示します。

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)

アクティビティのテキストから特定の ID のメンションを削除し、更新されたテキストを返します。 注意して使用してください。この関数は、アクティビティの text プロパティを変更します。

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

パラメーター

activity

Partial<Activity>

メンション時に削除するアクティビティ。

id

string

メンション時に削除するユーザーまたはボットの ID。

戻り値

string

更新されたアクティビティのテキスト。

注釈

Microsoft Teams などの一部のチャネルでは、メッセージ アクティビティのテキストに @メンションを追加します。

このヘルパー メソッドを使用して、アクティビティの text プロパティを変更します。 指定されたボットまたはユーザー ID のメンションをすべて削除し、更新されたプロパティ値を返します。

たとえば、"@echoBot Hi Bot" というテキストを含むアクティビティから echoBot のメンションを削除すると、アクティビティ テキストが更新され、メソッドは "Hi Bot" を返します。

メンション エンティティ の形式はチャネルに依存します。 ただし、メンションの text プロパティには、アクティビティ テキストに表示されるユーザーの正確なテキストが含まれている必要があります。

たとえば、チャネルで "username" と "@username" のどちらを使用する場合でも、この文字列はアクティビティのテキスト内にあり、このメソッドはテキストからその文字列のすべての出現箇所を削除します。

以下に例を示します。

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

参照

• removeRecipientMention

removeRecipientMention(Partial<Activity>)

アクティビティの 受信者 のメンションをアクティビティのテキストから削除し、更新されたテキストを返します。 注意して使用してください。この関数は、アクティビティの text プロパティを変更します。

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

パラメーター

activity

Partial<Activity>

メンション時に削除するアクティビティ。

戻り値

string

更新されたアクティビティのテキスト。

注釈

Microsoft Teams などの一部のチャネルでは、メッセージ アクティビティのテキストに@メンションの詳細を追加します。

このヘルパー メソッドを使用して、アクティビティの text プロパティを変更します。 アクティビティの 受信者 のメンションをすべて削除し、更新されたプロパティ値を返します。

以下に例を示します。

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

参照

• removeMentionText

sendActivities(Partial<Activity>[])

受信アクティビティの送信者に一連のアクティビティを非同期に送信します。

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

パラメーター

activities

Partial<Activity>[]

送信するアクティビティ。

戻り値

Promise<ResourceResponse[]>

ResourceResponse との約束。

注釈

アクティビティが正常に送信されると、受信チャネルがアクティビティに割り当てた ID を含む 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

省略可能。 ボットが音声対応チャネルで読み上げるテキスト。

inputHint

string

省略可能。 メッセージがクライアントに配信された後、ボットがユーザー入力を受け入れるか、予期しているか、無視しているかを示します。 次のいずれか: 'acceptingInput'、'ignoringInput'、または 'expectingInput'。 既定値は 'acceptingInput' です。

戻り値

Promise<ResourceResponse | undefined>

ResourceResponse との約束。

注釈

アクティビティが正常に送信されると、受信チャネルがアクティビティに割り当てた ID を含む ResourceResponse オブジェクトが作成されます。

activityOrText パラメーターの内容に課される制限については、チャネルのドキュメントを参照してください。

音声、速度、音量、発音、ピッチなど、ボットの音声のさまざまな特性を制御するには、音声合成マークアップ言語 (SSML) 形式で speak を指定します。

以下に例を示します。

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

省略可能。 ボットが音声対応チャネルで読み上げるテキスト。

valueType

string

省略可能。 ボットがユーザーを受け入れるか、期待しているか、無視しているかを示します

label

string

省略可能。 ボットがユーザーを受け入れるか、期待しているか、無視しているかを示します

戻り値

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 との約束。

注釈

置換アクティビティの ID は、置き換える会話内のアクティビティを示します。

以下に例を示します。

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

参照

• Sendactivity
• deleteActivity
• getReplyConversationReference