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에 대한 멘션을 제거하고 업데이트된 텍스트를 반환합니다. 주의해서 사용; 이 함수는 활동의 텍스트 속성을 변경합니다.
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

이 컨텍스트 개체를 만든 봇 어댑터를 가져옵니다.

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이면 현재 턴에 대해 하나 이상의 응답이 전송되었습니다. 그렇지 않으면 false입니다.

설명

현재 턴에 대해 하나 이상의 응답이 전송된 경우 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>

비동기 작업을 나타내는 프라미스입니다.

설명

ID를 지정하면 현재 요청에 대한 대화 참조를 사용하여 필요한 나머지 정보를 가져옵니다.

예:

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

참고 항목

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);

참고 항목

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에 대한 멘션을 제거하고 업데이트된 텍스트를 반환합니다. 주의해서 사용; 이 함수는 활동의 텍스트 속성을 변경합니다.

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

매개 변수

activity: Partial<Activity>

멘션에서 제거할 활동입니다.

id: string

멘션에서 제거할 사용자 또는 봇의 ID입니다.

반환

string

업데이트된 활동의 텍스트입니다.

설명

일부 채널(예: Microsoft Teams)은 메시지 활동의 텍스트에 멘션을 추가합니다.

이 도우미 메서드를 사용하여 활동의 텍스트 속성을 수정합니다. 지정된 봇 또는 사용자 ID에 대한 멘션을 모두 제거한 다음 업데이트된 속성 값을 반환합니다.

예를 들어 "@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를 사용하는 약속입니다.

설명

작업이 성공적으로 전송되면 수신 채널이 활동에 할당한 ID를 포함하는 ResourceResponse 개체의 배열이 생성됩니다.

전송되기 전에 각 아웃바운드 활동의 배달 정보는 인바운드 인바운드 활동의 배달 정보에 따라 업데이트됩니다.

예:

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

참고 항목

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(Speech Synthesis Markup Language) 형식으로 말하기 를 지정합니다.

예:

await context.sendActivity(`Hello World`);

참고 항목

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);
}

참고 항목

다음을 통해 공유

TurnContext class

설명

생성자

속성

메서드

생성자 세부 정보

TurnContext(BotAdapter, Partial<Activity>)

매개 변수

TurnContext(TurnContext)

매개 변수

속성 세부 정보

activity

속성 값

설명

adapter

속성 값

bufferedReplyActivities

속성 값

locale

속성 값

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)

매개 변수

반환

설명

removeRecipientMention(Partial<Activity>)

매개 변수

반환

설명

sendActivities(Partial<Activity>[])

매개 변수

반환

설명

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

매개 변수

반환

설명

sendTraceActivity(string, any, string, string)

매개 변수

반환

설명