OAuthPrompt class

参考

包:: botbuilder-dialogs

创建一个新提示，要求用户使用 Bot Frameworks 单一登录 (SSO) 服务登录。

Extends: Dialog

注解

提示将尝试检索用户当前令牌，如果用户未登录，它将向他们发送一个 OAuthCard 包含他们可以按下以登录的按钮。根据通道，用户将通过两个可能的登录流之一发送：

自动登录流，用户登录后，SSO 服务将使用或 invoke 活动转发机器人访问令牌event。
“神奇代码”流，用户登录后，SSO 服务将提示他们向机器人发送六位数代码，确认其身份。此代码将作为标准 message 活动发送。

这两个流都由 OAuthPrompt 自动支持，你唯一需要注意的是，你不会阻止 event 提示可能正在等待的和 invoke 活动。

注意

应避免将访问令牌与机器人的其他状态一起保留。 Bot Frameworks SSO 服务将代表你安全地存储令牌。如果将其存储在机器人状态中，则它可能会过期或两轮之间撤销。

从瀑布步骤中调用提示时，应按照提示在步骤中使用令牌，然后让令牌超出函数末尾的范围。

提示使用情况

与机器人 DialogSet 一起使用时，只需使用 DialogSet.add()将提示的新实例添加为命名对话框。然后，可以使用或 DialogContext.prompt()从瀑布步骤DialogContext.beginDialog()启动提示。系统将根据需要提示用户登录，其访问令牌将作为参数传递给调用方下一个瀑布步骤：

const { ConversationState, MemoryStorage, OAuthLoginTimeoutMsValue } = require('botbuilder');
const { DialogSet, OAuthPrompt, WaterfallDialog } = require('botbuilder-dialogs');

const convoState = new ConversationState(new MemoryStorage());
const dialogState = convoState.createProperty('dialogState');
const dialogs = new DialogSet(dialogState);

dialogs.add(new OAuthPrompt('loginPrompt', {
   connectionName: 'GitConnection',
   title: 'Login To GitHub',
   timeout: OAuthLoginTimeoutMsValue   // User has 15 minutes to login
}));

dialogs.add(new WaterfallDialog('taskNeedingLogin', [
     async (step) => {
         return await step.beginDialog('loginPrompt');
     },
     async (step) => {
         const token = step.result;
         if (token) {

             // ... continue with task needing access token ...

         } else {
             await step.context.sendActivity(`Sorry... We couldn't log you in. Try again later.`);
             return await step.endDialog();
         }
     }
]));

构造函数

OAuthPrompt(string, OAuthPromptSettings, PromptValidator<TokenResponse>)

创建新的 OAuthPrompt 实例。

属性

id	对话框的唯一 ID。设置对话框的唯一 ID。
telemetryClient	获取此对话框的遥测客户端。设置此对话框的遥测客户端。

继承属性

EndOfTurn

获取默认的轮次结束结果。

方法

beginDialog(DialogContext, PromptOptions)	在将提示对话推送到对话堆栈并激活时调用。
continueDialog(DialogContext)	当提示对话为活动对话且用户使用新活动进行答复时调用。
getUserToken(TurnContext, string)	尝试检索当前用户的存储令牌。
recognizeToken(DialogContext)	RecognizeTokenAsync 函数的共享实现。这供内部使用，用于合并 OAuthPrompt 和 OAuthInput 的实现。应用程序逻辑应使用这些对话框类。
sendOAuthCard(OAuthPromptSettings, TurnContext, string \| Partial<Activity>)	发送 OAuth 卡。
signOutUser(TurnContext)	将用户从服务中注销。

继承的方法

configure(Record<string, unknown>)	用于配置对象的 Fluent 方法。
endDialog(TurnContext, DialogInstance, DialogReason)	在派生类中重写时，在对话结束之前对对话执行清理。
getConverter(string)
getVersion()	一个编码字符串，用于帮助在重新部署时检测机器人更改。
onDialogEvent(DialogContext, DialogEvent)	在引发事件时调用，使用 `DialogContext.emitEvent()`由当前对话或当前对话启动的对话调用。
repromptDialog(TurnContext, DialogInstance)	在派生类中重写时，将重新调用用户作为输入。
resumeDialog(DialogContext, DialogReason, any)	在派生类中重写时，在堆栈上对话框完成之后继续对话。

构造函数详细信息

OAuthPrompt(string, OAuthPromptSettings, PromptValidator<TokenResponse>)

创建新的 OAuthPrompt 实例。

new OAuthPrompt(dialogId: string, settings: OAuthPromptSettings, validator?: PromptValidator<TokenResponse>)

参数

dialogId: string

对话在其父 DialogSet 或 ComponentDialog中的唯一 ID。

settings: OAuthPromptSettings

用于配置提示的设置。

validator: PromptValidator<TokenResponse>

(用户每次响应提示时都会调用的可选) 验证程序。

属性详细信息

id

对话框的唯一 ID。设置对话框的唯一 ID。

string id

属性值

string

对话框的 ID。

注解

如果未指定，将自动生成此代码。

telemetryClient

获取此对话框的遥测客户端。设置此对话框的遥测客户端。

BotTelemetryClient telemetryClient

属性值

BotTelemetryClient

用于日志记录的 BotTelemetryClient 。

继承属性详细信息

EndOfTurn

获取默认的轮次结束结果。

static EndOfTurn: DialogTurnResult

属性值

DialogTurnResult

注解

此结果指示对话 (或对话中的逻辑步骤) 已完成当前轮次的处理，仍处于活动状态，并且正在等待更多输入。

继承自Dialog.EndOfTurn

方法详细信息

beginDialog(DialogContext, PromptOptions)

在将提示对话推送到对话堆栈并激活时调用。

function beginDialog(dc: DialogContext, options?: PromptOptions): Promise<DialogTurnResult>

参数

dc: DialogContext

对话当前轮次的 DialogContext 。

options: PromptOptions

可选。 PromptOptions，要传递给正在启动的提示的其他信息。

Promise<DialogTurnResult>

表示异步操作的 Promise。

注解

如果任务成功，则结果指示在提示处理轮次后提示是否仍处于活动状态。

continueDialog(DialogContext)

当提示对话为活动对话且用户使用新活动进行答复时调用。

function continueDialog(dc: DialogContext): Promise<DialogTurnResult>

参数

dc: DialogContext

对话当前轮次的 DialogContext 。

Promise<DialogTurnResult>

表示异步操作的 Promise。

注解

如果任务成功，则结果指示在对话处理轮次后对话是否仍然处于活动状态。提示通常继续接收用户的答复，直到它接受用户的回复作为提示的有效输入。

getUserToken(TurnContext, string)

尝试检索当前用户的存储令牌。

function getUserToken(context: TurnContext, code?: string): Promise<TokenResponse | undefined>

参数

context: TurnContext

上下文引用正在查找的用户。

code: string

(从用户收到的可选) 登录代码。

Promise<TokenResponse | undefined>

令牌响应。

recognizeToken(DialogContext)

RecognizeTokenAsync 函数的共享实现。这供内部使用，用于合并 OAuthPrompt 和 OAuthInput 的实现。应用程序逻辑应使用这些对话框类。

function recognizeToken(dc: DialogContext): Promise<PromptRecognizerResult<TokenResponse>>

参数

dc: DialogContext

对话当前轮次的 DialogContext 。

Promise<PromptRecognizerResult<TokenResponse>>

解析结果的承诺

sendOAuthCard(OAuthPromptSettings, TurnContext, string | Partial<Activity>)

发送 OAuth 卡。

static function sendOAuthCard(settings: OAuthPromptSettings, turnContext: TurnContext, prompt?: string | Partial<Activity>): Promise<void>

参数

settings: OAuthPromptSettings

OAuth 设置。

turnContext: TurnContext

轮次上下文。

prompt: string | Partial<Activity>

消息活动。

Promise<void>

signOutUser(TurnContext)

将用户从服务中注销。

function signOutUser(context: TurnContext): Promise<void>

参数

context: TurnContext

引用正在注销的用户的上下文。

Promise<void>

表示异步操作的承诺。

注解

此示例演示如何创建提示的实例，然后注销用户。

const prompt = new OAuthPrompt({
   connectionName: 'GitConnection',
   title: 'Login To GitHub'
});
await prompt.signOutUser(context);

继承的方法详细信息

configure(Record<string, unknown>)

用于配置对象的 Fluent 方法。

function configure(config: Record<string, unknown>): this

参数

config: Record<string, unknown>

要应用的配置设置。

this

操作完成后可配置的。

继承自Configure.configure

endDialog(TurnContext, DialogInstance, DialogReason)

在派生类中重写时，在对话结束之前对对话执行清理。

function endDialog(_context: TurnContext, _instance: DialogInstance, _reason: DialogReason): Promise<void>

参数

_context: TurnContext

轮次的上下文对象。

_instance: DialogInstance

此对话框的当前状态信息。

_reason: DialogReason

对话结束的原因。

Promise<void>

注解

需要在结束前执行日志记录或清理的派生对话应替代此方法。默认情况下，此方法不起作用。

当当前对话结束时， DialogContext 将调用此方法。

另请参阅

继承自Dialog.endDialog

getConverter(string)

function getConverter(_property: string): Converter | ConverterFactory

参数

_property: string

条件选择器配置的键。

Converter | ConverterFactory

选择器配置的转换器。

继承自可配置.getConverter

getVersion()

一个编码字符串，用于帮助在重新部署时检测机器人更改。

function getVersion(): string

string

唯一字符串，仅当对话已以应重启对话框的方式更改时才应更改。

注解

这默认返回对话 ID ，但可以重写以提供更精确的更改检测逻辑。堆栈上具有其版本更改的任何对话都将导致 versionChanged 引发事件。如果机器人未处理此事件，则会引发错误，从而导致运行机器人错误处理程序逻辑。

返回空字符串将一起禁用组件的版本跟踪。

继承自Dialog.getVersion

onDialogEvent(DialogContext, DialogEvent)

在引发事件时调用，使用 DialogContext.emitEvent()由当前对话或当前对话启动的对话调用。

function onDialogEvent(dc: DialogContext, e: DialogEvent): Promise<boolean>

参数

dc: DialogContext

当前会话轮次的对话上下文。

e: DialogEvent

正在引发的事件。

Promise<boolean>

如此如果事件由当前对话框处理，并且浮泡应停止。

继承自Dialog.onDialogEvent

repromptDialog(TurnContext, DialogInstance)

在派生类中重写时，将重新调用用户作为输入。

function repromptDialog(_context: TurnContext, _instance: DialogInstance): Promise<void>

参数

_context: TurnContext

轮次的上下文对象。

_instance: DialogInstance

此对话框的当前状态信息。

Promise<void>

注解

支持验证和重新提示逻辑的派生对话应重写此方法。默认情况下，此方法不起作用。

当当前对话应重新请求用户输入时， DialogContext 将调用此方法。此方法是针对提示对话实现的。

另请参阅

继承自Dialog.repromptDialog

resumeDialog(DialogContext, DialogReason, any)

在派生类中重写时，在堆栈上对话框完成之后继续对话。

function resumeDialog(dc: DialogContext, reason: DialogReason, result?: any): Promise<DialogTurnResult>

参数

dc: DialogContext

当前对话轮次的上下文。

reason: DialogReason

对话恢复的原因。这通常是 DialogReason.endCalled

result: any

可选。结束的对话框中的返回值（如果有）。

Promise<DialogTurnResult>

解析为对话轮次结果的承诺。

注解

支持多轮次对话的派生对话应替代此方法。默认情况下，此方法发出对话框已完成并返回的信号。

DialogContext 在恢复对话时调用此方法。如果堆栈上的上一个对话框返回值，则该值位于参数中 result 。

若要启动子对话，请使用 DialogContext.beginDialog 或 DialogContext.prompt;但是，此对话不一定是启动子对话的对话。若要向对话上下文发出此对话已完成的信号，请在退出此方法之前等待 DialogContext.endDialog 。

另请参阅

DialogContext.endDialog

继承自Dialog.resumeDialog

通过

OAuthPrompt class

注解

提示使用情况

构造函数

属性

继承属性

方法

继承的方法

构造函数详细信息

OAuthPrompt(string, OAuthPromptSettings, PromptValidator<TokenResponse>)

参数

属性详细信息

id

属性值

注解

telemetryClient

属性值

继承属性详细信息

EndOfTurn

属性值

注解

方法详细信息

beginDialog(DialogContext, PromptOptions)

参数

返回

注解

continueDialog(DialogContext)

参数

返回

注解

getUserToken(TurnContext, string)

参数

返回

recognizeToken(DialogContext)

参数

返回

sendOAuthCard(OAuthPromptSettings, TurnContext, string | Partial<Activity>)

参数

返回

signOutUser(TurnContext)

参数

返回

注解

继承的方法详细信息

configure(Record<string, unknown>)

参数

返回

endDialog(TurnContext, DialogInstance, DialogReason)

参数

返回

注解

getConverter(string)

参数

返回

getVersion()

返回

注解

onDialogEvent(DialogContext, DialogEvent)

参数

返回

repromptDialog(TurnContext, DialogInstance)

参数

返回

注解

resumeDialog(DialogContext, DialogReason, any)

参数

返回

注解

其他资源