OAuthPrompt class

Referência

Pacote:: botbuilder-dialogs

Cria um novo prompt que solicita que o usuário entre usando o serviço SSO (Logon Único) do Bot Frameworks.

Extends: Dialog

Comentários

O prompt tentará recuperar o token atual dos usuários e, se o usuário não estiver conectado, ele enviará um OAuthCard contendo um botão que poderá pressionar para entrar. Dependendo do canal, o usuário será enviado por meio de um dos dois fluxos de entrada possíveis:

O fluxo de entrada automática em que, depois que o usuário entrar e o serviço de SSO encaminhar o bot, os usuários acessarão o token usando uma atividade de event ou invoke.
O fluxo de "código mágico" em que, quando o usuário entrar, ele será solicitado pelo serviço de SSO a enviar ao bot um código de seis dígitos confirmando sua identidade. Esse código será enviado como uma atividade de message padrão.

Ambos os fluxos são automaticamente compatíveis com o OAuthPrompt e a única coisa que você precisa ter cuidado é que você não bloqueia as atividades de event e invoke que o prompt pode estar aguardando.

Nota

Você deve evitar persistir o token de acesso com outros estados de bots. O serviço SSO do Bot Frameworks armazenará com segurança o token em seu nome. Se você armazená-lo no estado de bots, ele poderá expirar ou ser revogado entre turnos.

Ao chamar o prompt de dentro de uma etapa de cascata, você deve usar o token dentro da etapa após o prompt e, em seguida, deixar o token sair do escopo no final da função.

Uso de prompt

Quando usado com seus bots DialogSet você pode simplesmente adicionar uma nova instância do prompt como uma caixa de diálogo nomeada usando DialogSet.add(). Em seguida, você pode iniciar o prompt de uma etapa de cascata usando DialogContext.beginDialog() ou DialogContext.prompt(). O usuário será solicitado a entrar conforme necessário e seu token de acesso será passado como um argumento para os chamadores na próxima etapa de cascata:

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

Construtores

OAuthPrompt(string, OAuthPromptSettings, PromptValidator<TokenResponse>)

Cria uma nova instância OAuthPrompt.

Propriedades

id	ID exclusiva da caixa de diálogo. Define a ID exclusiva da caixa de diálogo.
telemetryClient	Obtém o cliente de telemetria para esta caixa de diálogo. Define o cliente de telemetria para essa caixa de diálogo.

Propriedades herdadas

EndOfTurn

Obtém um resultado de fim de turno padrão.

Métodos

beginDialog(DialogContext, PromptOptions)	Chamado quando uma caixa de diálogo de prompt é enviada por push para a pilha de diálogo e está sendo ativada.
continueDialog(DialogContext)	Chamado quando uma caixa de diálogo de prompt é a caixa de diálogo ativa e o usuário respondeu com uma nova atividade.
getUserToken(TurnContext, string)	Tenta recuperar o token armazenado para o usuário atual.
recognizeToken(DialogContext)	Implementação compartilhada da função RecognizeTokenAsync. Isso destina-se ao uso interno, para consolidar a implementação do OAuthPrompt e do OAuthInput. A lógica do aplicativo deve usar essas classes de diálogo.
sendOAuthCard(OAuthPromptSettings, TurnContext, string \| Partial<Activity>)	Envia um cartão OAuth.
signOutUser(TurnContext)	Desconscreve o usuário do serviço.

Métodos herdados

configure(Record<string, unknown>)	Método fluente para configurar o objeto.
endDialog(TurnContext, DialogInstance, DialogReason)	Quando substituído em uma classe derivada, executa a limpeza da caixa de diálogo antes de terminar.
getConverter(string)
getVersion()	Uma cadeia de caracteres codificada usada para ajudar na detecção de alterações de bot na re-implantação.
onDialogEvent(DialogContext, DialogEvent)	Chamado quando um evento foi gerado, usando `DialogContext.emitEvent()`, pela caixa de diálogo atual ou por uma caixa de diálogo iniciada pela caixa de diálogo atual.
repromptDialog(TurnContext, DialogInstance)	Quando substituído em uma classe derivada, reprompta o usuário para entrada.
resumeDialog(DialogContext, DialogReason, any)	Quando substituído em uma classe derivada, retoma a caixa de diálogo após a caixa de diálogo acima dela na pilha ser concluída.

Detalhes do construtor

OAuthPrompt(string, OAuthPromptSettings, PromptValidator<TokenResponse>)

Cria uma nova instância OAuthPrompt.

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

Parâmetros

dialogId: string

ID exclusiva da caixa de diálogo em seu DialogSet pai ou ComponentDialog.

settings: OAuthPromptSettings

Configurações usadas para configurar o prompt.

validator: PromptValidator<TokenResponse>

(Opcional) validador que será chamado sempre que o usuário responder ao prompt.

Detalhes da propriedade

id

ID exclusiva da caixa de diálogo. Define a ID exclusiva da caixa de diálogo.

string id

Valor da propriedade

string

A ID da caixa de diálogo.

Comentários

Isso será gerado automaticamente se não for especificado.

telemetryClient

Obtém o cliente de telemetria para esta caixa de diálogo. Define o cliente de telemetria para essa caixa de diálogo.

BotTelemetryClient telemetryClient

Valor da propriedade

BotTelemetryClient

O BotTelemetryClient a ser usado para registro em log.

Detalhes das propriedades herdadas

EndOfTurn

Obtém um resultado de fim de turno padrão.

static EndOfTurn: DialogTurnResult

Valor da propriedade

DialogTurnResult

Comentários

Esse resultado indica que uma caixa de diálogo (ou uma etapa lógica em uma caixa de diálogo) concluiu o processamento para a curva atual, ainda está ativa e está aguardando mais entrada.

herdado doDialog.EndOfTurn

Detalhes do método

beginDialog(DialogContext, PromptOptions)

Chamado quando uma caixa de diálogo de prompt é enviada por push para a pilha de diálogo e está sendo ativada.

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

Parâmetros

dc: DialogContext

O DialogContext para a virada atual da conversa.

options: PromptOptions

Opcional. promptOptions, informações adicionais a serem passadas para o prompt que está sendo iniciado.

Retornos

Promise<DialogTurnResult>

Um Promise que representa a operação assíncrona.

Comentários

Se a tarefa for bem-sucedida, o resultado indicará se o prompt ainda está ativo após a curva ter sido processada pelo prompt.

continueDialog(DialogContext)

Chamado quando uma caixa de diálogo de prompt é a caixa de diálogo ativa e o usuário respondeu com uma nova atividade.

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

Parâmetros

dc: DialogContext

O DialogContext para a virada atual da conversa.

Retornos

Promise<DialogTurnResult>

Um Promise que representa a operação assíncrona.

Comentários

Se a tarefa for bem-sucedida, o resultado indicará se a caixa de diálogo ainda estará ativa depois que a curva tiver sido processada pela caixa de diálogo. O prompt geralmente continua a receber as respostas do usuário até aceitar a resposta do usuário como entrada válida para o prompt.

getUserToken(TurnContext, string)

Tenta recuperar o token armazenado para o usuário atual.

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

Parâmetros

context: TurnContext

Referência de contexto do usuário que está sendo pesquisado.

code: string

(Opcional) código de logon recebido do usuário.

Retornos

Promise<TokenResponse | undefined>

A resposta do token.

recognizeToken(DialogContext)

Implementação compartilhada da função RecognizeTokenAsync. Isso destina-se ao uso interno, para consolidar a implementação do OAuthPrompt e do OAuthInput. A lógica do aplicativo deve usar essas classes de diálogo.

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

Parâmetros

dc: DialogContext

O DialogContext para a virada atual da conversa.

Retornos

Promise<PromptRecognizerResult<TokenResponse>>

Uma promessa que resolve para o resultado

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

Envia um cartão OAuth.

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

Parâmetros

settings: OAuthPromptSettings

Configurações do OAuth.

turnContext: TurnContext

Transforme o contexto.

prompt: string | Partial<Activity>

Atividade de mensagem.

Retornos

Promise<void>

signOutUser(TurnContext)

Desconscreve o usuário do serviço.

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

Parâmetros

context: TurnContext

Contexto que faz referência ao usuário que está sendo desconscrevido.

Retornos

Promise<void>

Uma promessa que representa a operação assíncrona.

Comentários

Este exemplo mostra a criação de uma instância do prompt e, em seguida, a assinatura do usuário.

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

Detalhes do método herdado

configure(Record<string, unknown>)

Método fluente para configurar o objeto.

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

Parâmetros

config: Record<string, unknown>

Configurações a serem aplicadas.

Retornos

this

O configurável após a conclusão da operação.

Herdado deConfigurble.configure

endDialog(TurnContext, DialogInstance, DialogReason)

Quando substituído em uma classe derivada, executa a limpeza da caixa de diálogo antes de terminar.

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

Parâmetros

_context: TurnContext

O objeto de contexto para a curva.

_instance: DialogInstance

Informações de estado atuais para essa caixa de diálogo.

_reason: DialogReason

O motivo pelo qual a caixa de diálogo está terminando.

Retornos

Promise<void>

Comentários

As caixas de diálogo derivadas que precisam executar o registro em log ou a limpeza antes de terminar devem substituir esse método. Por padrão, esse método não tem efeito.

O dialogContext chama esse método quando a caixa de diálogo atual está terminando.

Consulte também

herdado dedialog.endDialog

getConverter(string)

function getConverter(_property: string): Converter | ConverterFactory

Parâmetros

_property: string

A chave da configuração do seletor condicional.

Retornos

Converter | ConverterFactory

O conversor para a configuração do seletor.

herdado deconfigurable.getConverter

getVersion()

Uma cadeia de caracteres codificada usada para ajudar na detecção de alterações de bot na re-implantação.

function getVersion(): string

Retornos

string

Cadeia de caracteres exclusiva que só deve ser alterada quando a caixa de diálogo foi alterada de uma maneira que deve reiniciar a caixa de diálogo.

Comentários

Esse padrão é retornar as caixas de diálogo id mas pode ser substituído para fornecer uma lógica de detecção de alterações mais precisa. Qualquer caixa de diálogo na pilha que tenha sua alteração de versão resultará em um evento versionChanged será gerado. Se esse evento não for tratado pelo bot, um erro será gerado, resultando na execução da lógica do manipulador de erros de bots.

Retornar uma cadeia de caracteres vazia desabilitará o acompanhamento de versão para o componente.

herdado dedialog.getVersion

onDialogEvent(DialogContext, DialogEvent)

Chamado quando um evento foi gerado, usando DialogContext.emitEvent(), pela caixa de diálogo atual ou por uma caixa de diálogo iniciada pela caixa de diálogo atual.

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

Parâmetros

dc: DialogContext

O contexto da caixa de diálogo para a virada atual da conversa.

e: DialogEvent

O evento que está sendo gerado.

Retornos

Promise<boolean>

True se o evento for tratado pela caixa de diálogo atual e o borbulhamento deve parar.

herdado da caixa de diálogo.onDialogEvent

repromptDialog(TurnContext, DialogInstance)

Quando substituído em uma classe derivada, reprompta o usuário para entrada.

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

Parâmetros

_context: TurnContext

O objeto de contexto para a curva.

_instance: DialogInstance

Informações de estado atuais para essa caixa de diálogo.

Retornos

Promise<void>

Comentários

Caixas de diálogo derivadas que dão suporte à validação e à lógica de nova solicitação devem substituir esse método. Por padrão, esse método não tem efeito.

O DialogContext chama esse método quando a caixa de diálogo atual deve solicitar novamente a entrada do usuário. Esse método é implementado para caixas de diálogo de prompt.

Consulte também

Herdado deDialog.repromptDialog

resumeDialog(DialogContext, DialogReason, any)

Quando substituído em uma classe derivada, retoma a caixa de diálogo após a caixa de diálogo acima dela na pilha ser concluída.

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

Parâmetros

dc: DialogContext

O contexto da curva de diálogo atual.

reason: DialogReason

O motivo pelo qual a caixa de diálogo está sendo retomada. Normalmente, isso será dialogReason.endCalled

result: any

Opcional. O valor retornado, se houver, da caixa de diálogo que terminou.

Retornos

Promise<DialogTurnResult>

Uma promessa de resolução para o resultado da curva da caixa de diálogo.

Comentários

Caixas de diálogo derivadas que dão suporte a conversas de várias voltas devem substituir esse método. Por padrão, esse método sinaliza que a caixa de diálogo está concluída e retorna.

O DialogContext chama esse método quando ele retoma a caixa de diálogo. Se a caixa de diálogo anterior na pilha retornar um valor, esse valor estará no parâmetro result.

Para iniciar uma caixa de diálogo filho , use DialogContext.beginDialog ou DialogContext.prompt; no entanto, essa caixa de diálogo não será necessariamente a que iniciou a caixa de diálogo filho. Para sinalizar para o contexto da caixa de diálogo que essa caixa de diálogo foi concluída, aguarde DialogContext.endDialog antes de sair desse método.

Consulte também

dialogContext.endDialog

Herdado deDialog.resumeDialog

Compartilhar via

OAuthPrompt class

Comentários

Uso de prompt

Construtores

Propriedades

Propriedades herdadas

Métodos

Métodos herdados

Detalhes do construtor

OAuthPrompt(string, OAuthPromptSettings, PromptValidator<TokenResponse>)

Parâmetros

Detalhes da propriedade

id

Valor da propriedade

Comentários

telemetryClient

Valor da propriedade

Detalhes das propriedades herdadas

EndOfTurn

Valor da propriedade

Comentários

Detalhes do método

beginDialog(DialogContext, PromptOptions)

Parâmetros

Retornos

Comentários

continueDialog(DialogContext)

Parâmetros

Retornos

Comentários

getUserToken(TurnContext, string)

Parâmetros

Retornos

recognizeToken(DialogContext)

Parâmetros

Retornos

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

Parâmetros

Retornos

signOutUser(TurnContext)

Parâmetros

Retornos

Comentários

Detalhes do método herdado

configure(Record<string, unknown>)

Parâmetros

Retornos

endDialog(TurnContext, DialogInstance, DialogReason)

Parâmetros

Retornos

Comentários

getConverter(string)

Parâmetros

Retornos

getVersion()

Retornos

Comentários

onDialogEvent(DialogContext, DialogEvent)

Parâmetros

Retornos

repromptDialog(TurnContext, DialogInstance)

Parâmetros

Retornos

Comentários

resumeDialog(DialogContext, DialogReason, any)

Parâmetros

Retornos

Comentários

Recursos adicionais