OAuthPrompt class

参考

包:: botbuilder-dialogs

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

扩展: Dialog

注解

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

自动登录流，用户登录和 SSO 服务后，将使用 event 或 invoke 活动转发机器人访问令牌。
“magic code”流，一旦用户登录，SSO 服务就会提示他们发送一个确认其标识的六位数代码。此代码将作为标准 message 活动发送。

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

注意

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

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

提示使用情况

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

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

解析为结果的 Promise

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>

表示异步操作的 promise。

注解

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

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

选择器配置的转换器。

继承自Configurable.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)

参数

返回

注解

其他资源