TurnContext class

Paket:

botbuilder-core

Menyediakan konteks untuk pergantian bot.

Keterangan

Konteks menyediakan informasi yang diperlukan untuk memproses aktivitas masuk. Objek konteks dibuat oleh BotAdapter dan bertahan selama pergantian.

Konstruktor

TurnContext(BotAdapter, Partial<Activity>)	Membuat instans baru kelas TurnContext.
TurnContext(TurnContext)	Membuat instans baru kelas TurnContext.

Properti

activity	Mendapatkan aktivitas yang terkait dengan giliran ini.
adapter	Mendapatkan adaptor bot yang membuat objek konteks ini.
bufferedReplyActivities	Daftar aktivitas yang akan dikirim saat context.activity.deliveryMode == 'expectReplies'.
locale	Mendapatkan lokal yang disimpan di turnState. Mengatur lokal yang disimpan di turnState.
responded	Menunjukkan apakah bot telah membalas pengguna pada giliran ini. Mengatur bendera respons pada konteks giliran saat ini.
turnState	Mendapatkan layanan yang terdaftar pada objek konteks ini.

Metode

applyConversationReference(Partial<Activity>, Partial<ConversationReference>, boolean)	Memperbarui aktivitas dengan informasi pengiriman dari referensi percakapan yang ada.
deleteActivity(string | Partial<ConversationReference>)	Secara asinkron menghapus aktivitas yang dikirim sebelumnya.
getConversationReference(Partial<Activity>)	Menyalin informasi referensi percakapan dari aktivitas.
getMentions(Partial<Activity>)	Mendapatkan semua entitas yang disebutkan yang disertakan dalam aktivitas.
getReplyConversationReference(Partial<Activity>, ResourceResponse)	Menyalin informasi referensi percakapan dari respons sumber daya untuk aktivitas terkirim.
onDeleteActivity(DeleteActivityHandler)	Menambahkan handler respons untuk menghapus operasi aktivitas.
onSendActivities(SendActivitiesHandler)	Menambahkan handler respons untuk operasi aktivitas pengiriman.
onUpdateActivity(UpdateActivityHandler)	Menambahkan handler respons untuk operasi aktivitas pembaruan.
removeMentionText(Partial<Activity>, string)	Menghapus pada penyebutan untuk ID tertentu dari teks aktivitas dan mengembalikan teks yang diperbarui. Gunakan dengan hati-hati; fungsi ini mengubah properti teks aktivitas.
removeRecipientMention(Partial<Activity>)	Menghapus pada penyebutan untuk penerima aktivitas dari teks aktivitas dan mengembalikan teks yang diperbarui. Gunakan dengan hati-hati; fungsi ini mengubah properti teks aktivitas.
sendActivities(Partial<Activity>[])	Secara asinkron mengirimkan serangkaian aktivitas ke pengirim aktivitas masuk.
sendActivity(string | Partial<Activity>, string, string)	Secara asinkron mengirimkan aktivitas ke pengirim aktivitas masuk.
sendTraceActivity(string, any, string, string)	Secara asinkron mengirimkan aktivitas ke pengirim aktivitas masuk.
updateActivity(Partial<Activity>)	Memperbarui aktivitas yang dikirim sebelumnya secara asinkron.

Detail Konstruktor

TurnContext(BotAdapter, Partial<Activity>)

Membuat instans baru kelas TurnContext.

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

Parameter

adapterOrContext

BotAdapter

Adaptor yang membuat konteks.

request

Partial<Activity>

Aktivitas masuk untuk giliran.

TurnContext(TurnContext)

Membuat instans baru kelas TurnContext.

new TurnContext(adapterOrContext: TurnContext)

Parameter

adapterOrContext

TurnContext

Adaptor yang membuat konteks.

Detail Properti

activity

Mendapatkan aktivitas yang terkait dengan giliran ini.

Activity activity

Nilai Properti

Activity

Aktivitas yang terkait dengan giliran ini.

Keterangan

Contoh ini menunjukkan cara mendapatkan ungkapan yang dipangkas pengguna dari aktivitas:

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

adapter

Mendapatkan adaptor bot yang membuat objek konteks ini.

BotAdapter adapter

Nilai Properti

BotAdapter

Adaptor bot yang membuat objek konteks ini.

bufferedReplyActivities

Daftar aktivitas yang akan dikirim saat context.activity.deliveryMode == 'expectReplies'.

bufferedReplyActivities: Partial<Activity>[]

Nilai Properti

Partial<Activity>[]

locale

Mendapatkan lokal yang disimpan di turnState. Mengatur lokal yang disimpan di turnState.

string | undefined locale

Nilai Properti

string | undefined

Lokal yang disimpan di turnState.

responded

Menunjukkan apakah bot telah membalas pengguna pada giliran ini. Mengatur bendera respons pada konteks giliran saat ini.

boolean responded

Nilai Properti

boolean

Benar jika setidaknya satu respons dikirim untuk giliran saat ini; jika tidak, salah.

Keterangan

benar jika setidaknya satu respons dikirim untuk giliran saat ini; jika tidak, palsu . Gunakan ini untuk menentukan apakah bot Anda perlu menjalankan logika fallback setelah pemrosesan normal lainnya.

Aktivitas pelacakan tidak mengatur bendera ini.

misalnya:

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

turnState

Mendapatkan layanan yang terdaftar pada objek konteks ini.

TurnContextStateCollection turnState

Nilai Properti

TurnContextStateCollection

Layanan yang terdaftar pada objek konteks ini.

Keterangan

Middleware, komponen lain, dan layanan biasanya akan menggunakan ini untuk menyimpan informasi yang dapat diminta oleh bot beberapa kali selama giliran. Anda dapat menggunakan cache ini untuk meneruskan informasi antar komponen bot Anda.

Misalnya:

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

Ujung

Saat membuat middleware atau komponen pihak ketiga, gunakan simbol unik untuk kunci cache Anda untuk menghindari tabrakan penamaan status dengan bot atau middleware atau komponen lainnya.

Detail Metode

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

Memperbarui aktivitas dengan informasi pengiriman dari referensi percakapan yang ada.

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

Parameter

activity

Partial<Activity>

Aktivitas yang akan diperbarui.

reference

Partial<ConversationReference>

Referensi percakapan untuk menyalin informasi pengiriman.

isIncoming

boolean

Fakultatif. true memperlakukan aktivitas sebagai aktivitas masuk, di mana bot adalah penerima; jika tidak, false. Defaultnya adalah false, dan aktivitas akan menampilkan bot sebagai pengirim.

Mengembalikan

Partial<Activity>

Aktivitas ini, diperbarui dengan informasi pengiriman.

Keterangan

Panggil metode getConversationReference pada aktivitas masuk untuk mendapatkan referensi percakapan yang kemudian dapat Anda gunakan untuk memperbarui aktivitas keluar dengan informasi pengiriman yang benar.

deleteActivity(string | Partial<ConversationReference>)

Secara asinkron menghapus aktivitas yang dikirim sebelumnya.

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

Parameter

idOrReference

string | Partial<ConversationReference>

ID atau referensi percakapan untuk aktivitas yang akan dihapus.

Mengembalikan

Promise<void>

Janji yang mewakili operasi asinkron.

Keterangan

Jika ID ditentukan, referensi percakapan untuk permintaan saat ini digunakan untuk mendapatkan informasi lainnya yang diperlukan.

Misalnya:

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

Lihat juga

• sendActivity
• updateActivity
• getReplyConversationReference

getConversationReference(Partial<Activity>)

Menyalin informasi referensi percakapan dari aktivitas.

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

Parameter

activity

Partial<Activity>

Aktivitas untuk mendapatkan informasi dari.

Mengembalikan

Partial<ConversationReference>

Referensi percakapan untuk percakapan yang berisi aktivitas ini.

Keterangan

Anda dapat menyimpan referensi percakapan sebagai objek JSON dan menggunakannya nanti untuk mengirim pesan kepada pengguna secara proaktif.

Misalnya:

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

Lihat juga

• BotAdapter.continueConversation

getMentions(Partial<Activity>)

Mendapatkan semua entitas yang disebutkan yang disertakan dalam aktivitas.

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

Parameter

activity

Partial<Activity>

Aktivitas.

Mengembalikan

Mention[]

Semua entitas yang disebutkan termasuk dalam aktivitas.

Keterangan

Entitas aktivitas berisi daftar datar objek metadata yang berkaitan dengan aktivitas ini dan dapat berisi menyebutkan entitas. Metode ini mengembalikan semua entitas tersebut untuk aktivitas tertentu.

Misalnya:

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

getReplyConversationReference(Partial<Activity>, ResourceResponse)

Menyalin informasi referensi percakapan dari respons sumber daya untuk aktivitas terkirim.

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

Parameter

activity

Partial<Activity>

Aktivitas yang dikirim.

reply

ResourceResponse

Respons sumber daya untuk aktivitas, dikembalikan oleh metode sendActivity atau sendActivities.

Mengembalikan

Partial<ConversationReference>

ConversationReference yang dapat disimpan dan digunakan nanti untuk menghapus atau memperbarui aktivitas.

Keterangan

Anda dapat menyimpan referensi percakapan sebagai objek JSON dan menggunakannya nanti untuk memperbarui atau menghapus pesan.

Misalnya:

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

Lihat juga

• deleteActivity
• updateActivity

onDeleteActivity(DeleteActivityHandler)

Menambahkan handler respons untuk menghapus operasi aktivitas.

function onDeleteActivity(handler: DeleteActivityHandler): this

Parameter

handler

DeleteActivityHandler

Handler untuk ditambahkan ke objek konteks.

Mengembalikan

this

Objek konteks yang diperbarui.

Keterangan

Metode ini mengembalikan referensi ke objek konteks giliran.

Ketika metode deleteActivity dipanggil, handler terdaftar dipanggil dalam urutan ditambahkan ke objek konteks sebelum aktivitas dihapus.

Contoh ini menunjukkan cara mendengarkan dan mencatat penghapusan aktivitas.

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

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

onSendActivities(SendActivitiesHandler)

Menambahkan handler respons untuk operasi aktivitas pengiriman.

function onSendActivities(handler: SendActivitiesHandler): this

Parameter

handler

SendActivitiesHandler

Handler untuk ditambahkan ke objek konteks.

Mengembalikan

this

Objek konteks yang diperbarui.

Keterangan

Metode ini mengembalikan referensi ke objek konteks giliran.

Ketika metode sendActivity atau sendActivities dipanggil, handler terdaftar dipanggil dalam urutan ditambahkan ke objek konteks sebelum aktivitas dikirim.

Contoh ini menunjukkan cara mendengarkan dan mencatat aktivitas message keluar.

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)

Menambahkan handler respons untuk operasi aktivitas pembaruan.

function onUpdateActivity(handler: UpdateActivityHandler): this

Parameter

handler

UpdateActivityHandler

Handler untuk ditambahkan ke objek konteks.

Mengembalikan

this

Objek konteks yang diperbarui.

Keterangan

Metode ini mengembalikan referensi ke objek konteks giliran.

Ketika metode updateActivity dipanggil, handler terdaftar dipanggil dalam urutan ditambahkan ke objek konteks sebelum aktivitas diperbarui.

Contoh ini menunjukkan cara mendengarkan dan mencatat pembaruan aktivitas.

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

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

removeMentionText(Partial<Activity>, string)

Menghapus pada penyebutan untuk ID tertentu dari teks aktivitas dan mengembalikan teks yang diperbarui. Gunakan dengan hati-hati; fungsi ini mengubah properti teks aktivitas.

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

Parameter

activity

Partial<Activity>

Aktivitas yang akan dihapus sebagaimana disebutkan.

id

string

ID pengguna atau bot yang akan dihapus sebagaimana disebutkan.

Mengembalikan

string

Teks aktivitas yang diperbarui.

Keterangan

Beberapa saluran, misalnya Microsoft Teams, menambahkan penyebutan ke teks aktivitas pesan.

Gunakan metode pembantu ini untuk mengubah properti teks aktivitas. Ini menghapus semua pada penyebutan untuk bot atau ID pengguna yang diberikan lalu mengembalikan nilai properti yang diperbarui.

Misalnya, saat Anda menghapus penyebutan echoBot dari aktivitas yang berisi teks "@echoBot Hi Bot", teks aktivitas diperbarui, dan metode mengembalikan "Hai Bot".

Format entitas yang disebutkan bergantung pada saluran. Namun, properti teks penyebutan harus berisi teks yang tepat untuk pengguna seperti yang muncul dalam teks aktivitas.

Misalnya, apakah saluran menggunakan "nama pengguna" atau "@username", string ini berada dalam teks aktivitas, dan metode ini akan menghapus semua kemunculan string tersebut dari teks.

Misalnya:

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

Lihat juga

• removeRecipientMention

removeRecipientMention(Partial<Activity>)

Menghapus pada penyebutan untuk penerima aktivitas dari teks aktivitas dan mengembalikan teks yang diperbarui. Gunakan dengan hati-hati; fungsi ini mengubah properti teks aktivitas.

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

Parameter

activity

Partial<Activity>

Aktivitas yang akan dihapus sebagaimana disebutkan.

Mengembalikan

string

Teks aktivitas yang diperbarui.

Keterangan

Beberapa saluran, misalnya Microsoft Teams, menambahkan detail yang disebutkan ke teks aktivitas pesan.

Gunakan metode pembantu ini untuk mengubah properti teks aktivitas. Ini menghapus semua pada penyebutan penerima aktivitas lalu mengembalikan nilai properti yang diperbarui.

Misalnya:

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

Lihat juga

• removeMentionText

sendActivities(Partial<Activity>[])

Secara asinkron mengirimkan serangkaian aktivitas ke pengirim aktivitas masuk.

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

Parameter

activities

Partial<Activity>[]

Kegiatan yang akan dikirim.

Mengembalikan

Promise<ResourceResponse[]>

Janji dengan ResourceResponse.

Keterangan

Jika aktivitas berhasil dikirim, menghasilkan array objek ResourceResponse yang berisi ID yang ditetapkan saluran penerima untuk aktivitas.

Sebelum dikirim, informasi pengiriman setiap aktivitas keluar diperbarui berdasarkan informasi pengiriman aktivitas masuk.

Misalnya:

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

Lihat juga

• sendActivity
• updateActivity
• deleteActivity

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

Secara asinkron mengirimkan aktivitas ke pengirim aktivitas masuk.

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

Parameter

activityOrText

string | Partial<Activity>

Aktivitas atau teks yang akan dikirim.

speak

string

Fakultatif. Teks yang akan diucapkan oleh bot Anda di saluran yang mendukung ucapan.

inputHint

string

Fakultatif. Menunjukkan apakah bot Anda menerima, mengharapkan, atau mengabaikan input pengguna setelah pesan dikirimkan ke klien. Salah satu: 'acceptingInput', 'ignoringInput', atau 'expectingInput'. Defaultnya adalah 'acceptingInput'.

Mengembalikan

Promise<ResourceResponse | undefined>

Janji dengan ResourceResponse.

Keterangan

Jika aktivitas berhasil dikirim, menghasilkan objek ResourceResponse yang berisi ID yang ditetapkan saluran penerima ke aktivitas.

Lihat dokumentasi saluran untuk batasan yang diberlakukan pada konten parameter activityOrText .

Untuk mengontrol berbagai karakteristik ucapan bot Anda seperti suara, laju, volume, pengucapan, dan nada, tentukan berbicara dalam format Speech Synthesis Markup Language (SSML).

Misalnya:

await context.sendActivity(`Hello World`);

Lihat juga

• mengirim Aktivitas
• updateActivity
• deleteActivity

sendTraceActivity(string, any, string, string)

Secara asinkron mengirimkan aktivitas ke pengirim aktivitas masuk.

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

Parameter

name

string

Aktivitas atau teks yang akan dikirim.

value

any

Fakultatif. Teks yang akan diucapkan oleh bot Anda di saluran yang mendukung ucapan.

valueType

string

Fakultatif. Menunjukkan apakah bot Anda menerima, mengharapkan, atau mengabaikan pengguna

label

string

Fakultatif. Menunjukkan apakah bot Anda menerima, mengharapkan, atau mengabaikan pengguna

Mengembalikan

Promise<ResourceResponse | undefined>

Janji dengan ResourceResponse.

Keterangan

Membuat dan mengirim aktivitas Pelacakan. Aktivitas pelacakan hanya dikirim saat saluran adalah emulator.

Misalnya:

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

Lihat juga

• mengirim Aktivitas

updateActivity(Partial<Activity>)

Memperbarui aktivitas yang dikirim sebelumnya secara asinkron.

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

Parameter

activity

Partial<Activity>

Penggantian untuk aktivitas asli.

Mengembalikan

Promise<ResourceResponse | void>

Janji dengan ResourceResponse.

Keterangan

Id aktivitas penggantian menunjukkan aktivitas dalam percakapan untuk diganti.

Misalnya:

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

Lihat juga

• sendActivity
• deleteActivity
• getReplyConversationReference