OAuthPrompt class

Paquete:

botbuilder-dialogs

Crea un mensaje que pide al usuario que inicie sesión con el servicio Bot Frameworks Single Sign On (SSO).

Extends

Dialog

Comentarios

El mensaje intentará recuperar el token actual de los usuarios y, si el usuario no ha iniciado sesión, los enviará un OAuthCard que contiene un botón que pueden presionar para iniciar sesión. Dependiendo del canal, el usuario se enviará a través de uno de los dos flujos de inicio de sesión posibles:

• El flujo de inicio de sesión automático en el que, una vez que el usuario inicia sesión y el servicio SSO reenvía el bot, el token de acceso de los usuarios mediante una actividad de event o invoke.
• El flujo de "código mágico" donde una vez que el usuario inicie sesión, el servicio SSO le pedirá que envíe al bot un código de seis dígitos que confirme su identidad. Este código se enviará como una actividad message estándar.

Ambos flujos son compatibles automáticamente con el OAuthPrompt y lo único que debe tener cuidado es que no se bloquean los event y invoke actividades en las que el mensaje podría estar esperando.

Nota

Debe evitar conservar el token de acceso con los bots de otro estado. El servicio bot Frameworks SSO almacenará de forma segura el token en su nombre. Si lo almacena en el estado de los bots, podría expirar o revocarse entre turnos.

Al llamar al símbolo del sistema desde un paso de cascada, debe usar el token en el paso siguiente al símbolo del sistema y, a continuación, dejar que el token salga del ámbito al final de la función.

Uso de la solicitud

Cuando se usa con los bots DialogSet simplemente puede agregar una nueva instancia del símbolo del sistema como un cuadro de diálogo con nombre mediante DialogSet.add(). A continuación, puede iniciar el mensaje desde un paso de cascada mediante DialogContext.beginDialog() o DialogContext.prompt(). Se le pedirá al usuario que inicie sesión según sea necesario y su token de acceso se pasará como argumento al siguiente paso de cascada:

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

Constructores

OAuthPrompt(string, OAuthPromptSettings, PromptValidator<TokenResponse>)

Crea una nueva instancia de OAuthPrompt.

Propiedades

id	Identificador único del cuadro de diálogo. Establece el identificador único del cuadro de diálogo.
telemetryClient	Obtiene el cliente de telemetría para este cuadro de diálogo. Establece el cliente de telemetría para este cuadro de diálogo.

Propiedades heredadas

EndOfTurn

Obtiene un resultado predeterminado de fin de turno.

Métodos

beginDialog(DialogContext, PromptOptions)	Se llama cuando se inserta un cuadro de diálogo de solicitud en la pila de diálogos y se activa.
continueDialog(DialogContext)	Se llama cuando un cuadro de diálogo de solicitud es el diálogo activo y el usuario respondió con una nueva actividad.
getUserToken(TurnContext, string)	Intenta recuperar el token almacenado para el usuario actual.
recognizeToken(DialogContext)	Implementación compartida de la función RecognizeTokenAsync. Esto está pensado para uso interno, para consolidar la implementación de OAuthPrompt y OAuthInput. La lógica de la aplicación debe usar esas clases de diálogo.
sendOAuthCard(OAuthPromptSettings, TurnContext, string | Partial<Activity>)	Envía una tarjeta OAuth.
signOutUser(TurnContext)	Cierra la sesión del usuario del servicio.

Métodos heredados

configure(Record<string, unknown>)	Método Fluent para configurar el objeto.
endDialog(TurnContext, DialogInstance, DialogReason)	Cuando se invalida en una clase derivada, realiza la limpieza del cuadro de diálogo antes de que finalice.
getConverter(string)
getVersion()	Cadena codificada que se usa para ayudar a detectar los cambios del bot en la reimplempleción.
onDialogEvent(DialogContext, DialogEvent)	Se llama cuando se ha generado un evento, mediante DialogContext.emitEvent(), mediante el cuadro de diálogo actual o un diálogo que inició el diálogo actual.
repromptDialog(TurnContext, DialogInstance)	Cuando se invalida en una clase derivada, reprote el usuario para la entrada.
resumeDialog(DialogContext, DialogReason, any)	Cuando se invalida en una clase derivada, reanuda el cuadro de diálogo después de que se complete el cuadro de diálogo encima de ella en la pila.

Detalles del constructor

OAuthPrompt(string, OAuthPromptSettings, PromptValidator<TokenResponse>)

Crea una nueva instancia de OAuthPrompt.

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

Parámetros

dialogId

string

Identificador único del cuadro de diálogo dentro de su DialogSet primario o ComponentDialog.

settings

OAuthPromptSettings

Configuración que se usa para configurar el símbolo del sistema.

validator

PromptValidator<TokenResponse>

(Opcional) validador al que se llamará cada vez que el usuario responda al mensaje.

Detalles de las propiedades

id

Identificador único del cuadro de diálogo. Establece el identificador único del cuadro de diálogo.

string id

Valor de propiedad

string

Identificador del cuadro de diálogo.

Comentarios

Se generará automáticamente si no se especifica.

telemetryClient

Obtiene el cliente de telemetría para este cuadro de diálogo. Establece el cliente de telemetría para este cuadro de diálogo.

BotTelemetryClient telemetryClient

Valor de propiedad

BotTelemetryClient

BotTelemetryClient que se va a usar para el registro.

Detalles de las propiedades heredadas

EndOfTurn

Obtiene un resultado predeterminado de fin de turno.

static EndOfTurn: DialogTurnResult

Valor de propiedad

DialogTurnResult

Comentarios

Este resultado indica que un cuadro de diálogo (o un paso lógico dentro de un diálogo) ha completado el procesamiento del turno actual, sigue activo y está esperando más entradas.

heredado dedialog.EndOfTurn

Detalles del método

beginDialog(DialogContext, PromptOptions)

Se llama cuando se inserta un cuadro de diálogo de solicitud en la pila de diálogos y se activa.

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

Parámetros

dc

DialogContext

El dialogContext de para el turno actual de la conversación.

options

PromptOptions

Opcional. PromptOptions, información adicional para pasar al símbolo del sistema que se está iniciando.

Devoluciones

Promise<DialogTurnResult>

Un Promise que representa la operación asincrónica.

Comentarios

Si la tarea se realiza correctamente, el resultado indica si la solicitud sigue activa después de que el aviso haya sido procesado por el aviso.

continueDialog(DialogContext)

Se llama cuando un cuadro de diálogo de solicitud es el diálogo activo y el usuario respondió con una nueva actividad.

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

Parámetros

dc

DialogContext

El dialogContext de para el turno actual de la conversación.

Devoluciones

Promise<DialogTurnResult>

Un Promise que representa la operación asincrónica.

Comentarios

Si la tarea se realiza correctamente, el resultado indica si el cuadro de diálogo sigue activo después de que el diálogo haya procesado el turno. Por lo general, la solicitud sigue recibiendo las respuestas del usuario hasta que acepta la respuesta del usuario como entrada válida para el mensaje.

getUserToken(TurnContext, string)

Intenta recuperar el token almacenado para el usuario actual.

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

Parámetros

context

TurnContext

El contexto hace referencia al usuario que se está buscando.

code

string

(Opcional) código de inicio de sesión recibido del usuario.

Devoluciones

Promise<TokenResponse | undefined>

Respuesta del token.

recognizeToken(DialogContext)

Implementación compartida de la función RecognizeTokenAsync. Esto está pensado para uso interno, para consolidar la implementación de OAuthPrompt y OAuthInput. La lógica de la aplicación debe usar esas clases de diálogo.

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

Parámetros

dc

DialogContext

El dialogContext de para el turno actual de la conversación.

Devoluciones

Promise<PromptRecognizerResult<TokenResponse>>

Promesa que se resuelve en el resultado

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

Envía una tarjeta OAuth.

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

Parámetros

settings

OAuthPromptSettings

Configuración de OAuth.

turnContext

TurnContext

Contexto de turno.

prompt

string | Partial<Activity>

Actividad de mensaje.

Devoluciones

Promise<void>

signOutUser(TurnContext)

Cierra la sesión del usuario del servicio.

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

Parámetros

context

TurnContext

Contexto que hace referencia al usuario que se va a cerrar la sesión.

Devoluciones

Promise<void>

Promesa que representa la operación asincrónica.

Comentarios

En este ejemplo se muestra cómo crear una instancia del símbolo del sistema y, a continuación, cerrar la sesión del usuario.

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

Detalles de los métodos heredados

configure(Record<string, unknown>)

Método Fluent para configurar el objeto.

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

Parámetros

config

Record<string, unknown>

Opciones de configuración que se van a aplicar.

Devoluciones

this

configurable una vez completada la operación.

heredado deconfigurable.configure

endDialog(TurnContext, DialogInstance, DialogReason)

Cuando se invalida en una clase derivada, realiza la limpieza del cuadro de diálogo antes de que finalice.

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

Parámetros

_context

TurnContext

Objeto de contexto del turno.

_instance

DialogInstance

Información de estado actual para este cuadro de diálogo.

_reason

DialogReason

Motivo por el que finaliza el cuadro de diálogo.

Devoluciones

Promise<void>

Comentarios

Los diálogos derivados que necesitan realizar el registro o la limpieza antes de finalizar deben invalidar este método. De forma predeterminada, este método no tiene ningún efecto.

El DialogContext llama a este método cuando finaliza el diálogo actual.

Consulte también

• DialogContext.cancelAllDialogs
• dialogContext.endDialog
• dialogContext.replaceDialog

heredado dedialog.endDialog

getConverter(string)

function getConverter(_property: string): Converter | ConverterFactory

Parámetros

_property

string

Clave de la configuración del selector condicional.

Devoluciones

Converter | ConverterFactory

Convertidor para la configuración del selector.

heredado deconfigurable.getConverter

getVersion()

Cadena codificada que se usa para ayudar a detectar los cambios del bot en la reimplempleción.

function getVersion(): string

Devoluciones

string

Cadena única que solo debe cambiar cuando el cuadro de diálogo ha cambiado de una manera que debe reiniciar el diálogo.

Comentarios

Este valor predeterminado es devolver los cuadros de diálogo id, pero se puede invalidar para proporcionar lógica de detección de cambios más precisa. Cualquier cuadro de diálogo de la pila que tenga su cambio de versión producirá un evento versionChanged. Si el bot no controla este evento, se producirá un error que dará lugar a la ejecución de la lógica del controlador de errores de bots.

Al devolver una cadena vacía, se deshabilitará el seguimiento de versiones para el componente en conjunto.

Heredado deDialog.getVersion

onDialogEvent(DialogContext, DialogEvent)

Se llama cuando se ha generado un evento, mediante DialogContext.emitEvent(), mediante el cuadro de diálogo actual o un diálogo que inició el diálogo actual.

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

Parámetros

dc

DialogContext

Contexto del cuadro de diálogo para el turno actual de conversación.

e

DialogEvent

Evento que se está generando.

Devoluciones

Promise<boolean>

True si el diálogo actual controla el evento y se debe detener la propagación.

Heredado deDialog.onDialogEvent

repromptDialog(TurnContext, DialogInstance)

Cuando se invalida en una clase derivada, reprote el usuario para la entrada.

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

Parámetros

_context

TurnContext

Objeto de contexto del turno.

_instance

DialogInstance

Información de estado actual para este cuadro de diálogo.

Devoluciones

Promise<void>

Comentarios

Los diálogos derivados que admiten la validación y la lógica de nueva solicitud deben invalidar este método. De forma predeterminada, este método no tiene ningún efecto.

El DialogContext llama a este método cuando el diálogo actual debe volver a solicitar la entrada del usuario. Este método se implementa para los cuadros de diálogo de solicitud.

Consulte también

• dialogContext.repromptDialog
• prompt

heredado dedialog.repromptDialog

resumeDialog(DialogContext, DialogReason, any)

Cuando se invalida en una clase derivada, reanuda el cuadro de diálogo después de que se complete el cuadro de diálogo encima de ella en la pila.

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

Parámetros

dc

DialogContext

Contexto del turno del cuadro de diálogo actual.

reason

DialogReason

La razón por la que se reanuda el cuadro de diálogo. Normalmente, se dialogReason.endCalled

result

any

Opcional. Valor devuelto, si existe, del cuadro de diálogo que finalizó.

Devoluciones

Promise<DialogTurnResult>

Promesa que resuelve el resultado del turno del cuadro de diálogo.

Comentarios

Los diálogos derivados que admiten conversaciones de varios turnos deben invalidar este método. De forma predeterminada, este método indica que el cuadro de diálogo está completo y devuelve.

El DialogContext llama a este método cuando reanuda el cuadro de diálogo. Si el cuadro de diálogo anterior de la pila devolvió un valor, ese valor se encuentra en el parámetro result.

Para iniciar un cuadro de diálogo de secundario de , use DialogContext.beginDialog o DialogContext.prompt; sin embargo, este diálogo no será necesariamente el que inició el diálogo secundario. Para indicar al contexto de diálogo que ha completado este diálogo, espere dialogContext.endDialog antes de salir de este método.

Consulte también

• dialogContext.endDialog

heredado dedialog.resumeDialog