OAuthPrompt class

Paket:

botbuilder-dialogs

Erstellt eine neue Eingabeaufforderung, die den Benutzer auffordert, sich mit dem Bot Frameworks Single Sign On (SSO)-Dienst anzumelden.

Extends

Dialog

Hinweise

Die Eingabeaufforderung versucht, das aktuelle Token der Benutzer abzurufen, und wenn der Benutzer nicht angemeldet ist, sendet er ihnen eine OAuthCard mit einer Schaltfläche, die sie drücken können, um sich anzumelden. Je nach Kanal wird der Benutzer über einen von zwei möglichen Anmeldeflüssen gesendet:

• Der automatische Anmeldefluss, bei dem der Benutzer sich anmeldet und der SSO-Dienst den Bot über ein event- oder invoke-Aktivität an den Bot weiterleite.
• Der "Magische Code"-Fluss, in dem, wo sich der Benutzer anmeldet, vom SSO-Dienst aufgefordert wird, dem Bot einen sechsstelligen Code zu senden, der seine Identität bestätigt. Dieser Code wird als Standard-message Aktivität gesendet.

Beide Flüsse werden automatisch vom OAuthPrompt unterstützt, und das einzige, was Sie beachten müssen, besteht darin, dass Sie die event und invoke Aktivitäten, auf die die Eingabeaufforderung wartet, nicht blockieren.

Anmerkung

Sie sollten verhindern, dass das Zugriffstoken mit Ihren Bots in einem anderen Zustand beibehalten wird. Der Bot Frameworks-SSO-Dienst speichert das Token sicher in Ihrem Auftrag. Wenn Sie sie in Ihrem Bots speichern, kann sie ablaufen oder zwischeneinander widerrufen werden.

Wenn Sie die Eingabeaufforderung innerhalb eines Wasserfallschritts aufrufen, sollten Sie das Token innerhalb des Schritts verwenden, der auf die Eingabeaufforderung folgt, und lassen Sie das Token dann am Ende der Funktion außer Reichweite gehen.

Eingabeaufforderungsverwendung

Bei Verwendung mit Ihren Bots DialogSet können Sie einfach eine neue Instanz der Eingabeaufforderung als benanntes Dialogfeld mithilfe von DialogSet.add()hinzufügen. Anschließend können Sie die Eingabeaufforderung aus einem Wasserfallschritt mit DialogContext.beginDialog() oder DialogContext.prompt()starten. Der Benutzer wird aufgefordert, sich nach Bedarf anzumelden, und sein Zugriffstoken wird als Argument an die Aufrufer als nächster Wasserfallschritt übergeben:

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

Konstruktoren

OAuthPrompt(string, OAuthPromptSettings, PromptValidator<TokenResponse>)

Erstellt eine neue OAuthPrompt-Instanz.

Eigenschaften

id	Eindeutige ID des Dialogfelds. Legt die eindeutige ID des Dialogfelds fest.
telemetryClient	Ruft den Telemetrieclient für dieses Dialogfeld ab. Legt den Telemetrieclient für dieses Dialogfeld fest.

Geerbte Eigenschaften

EndOfTurn

Ruft ein Standardmäßiges End-of-Turn-Ergebnis ab.

Methoden

beginDialog(DialogContext, PromptOptions)	Wird aufgerufen, wenn ein Eingabeaufforderungsdialogfeld auf den Dialogstapel verschoben wird und aktiviert wird.
continueDialog(DialogContext)	Wird aufgerufen, wenn ein Eingabeaufforderungsdialogfeld das aktive Dialogfeld ist und der Benutzer mit einer neuen Aktivität geantwortet hat.
getUserToken(TurnContext, string)	Versucht, das gespeicherte Token für den aktuellen Benutzer abzurufen.
recognizeToken(DialogContext)	Gemeinsame Implementierung der RecognizeTokenAsync-Funktion. Dies ist für die interne Verwendung vorgesehen, um die Implementierung von OAuthPrompt und OAuthInput zu konsolidieren. Anwendungslogik sollte diese Dialogfeldklassen verwenden.
sendOAuthCard(OAuthPromptSettings, TurnContext, string | Partial<Activity>)	Sendet eine OAuth-Karte.
signOutUser(TurnContext)	Meldet den Benutzer vom Dienst ab.

Geerbte Methoden

configure(Record<string, unknown>)	Fluent-Methode zum Konfigurieren des Objekts.
endDialog(TurnContext, DialogInstance, DialogReason)	Wenn sie in einer abgeleiteten Klasse überschrieben wird, wird das Dialogfeld vor dem Beenden bereinigt.
getConverter(string)
getVersion()	Eine codierte Zeichenfolge zur Unterstützung der Erkennung von Bot-Änderungen bei der erneuten Bereitstellung.
onDialogEvent(DialogContext, DialogEvent)	Wird aufgerufen, wenn ein Ereignis mit DialogContext.emitEvent()ausgelöst wurde, entweder durch das aktuelle Dialogfeld oder ein Dialogfeld, das das aktuelle Dialogfeld gestartet hat.
repromptDialog(TurnContext, DialogInstance)	Wenn sie in einer abgeleiteten Klasse überschrieben wird, wird der Benutzer erneut zur Eingabe aufgefordert.
resumeDialog(DialogContext, DialogReason, any)	Wenn sie in einer abgeleiteten Klasse überschrieben wird, wird das Dialogfeld nach Abschluss des Dialogfelds auf dem Stapel fortgesetzt.

Details zum Konstruktor

OAuthPrompt(string, OAuthPromptSettings, PromptValidator<TokenResponse>)

Erstellt eine neue OAuthPrompt-Instanz.

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

Parameter

dialogId

string

Eindeutige ID des Dialogfelds innerhalb des übergeordneten DialogSet oder ComponentDialog.

settings

OAuthPromptSettings

Einstellungen, die zum Konfigurieren der Eingabeaufforderung verwendet werden.

validator

PromptValidator<TokenResponse>

(Optional) Validator, der jedes Mal aufgerufen wird, wenn der Benutzer auf die Eingabeaufforderung antwortet.

Details zur Eigenschaft

id

Eindeutige ID des Dialogfelds. Legt die eindeutige ID des Dialogfelds fest.

string id

Eigenschaftswert

string

Die ID für das Dialogfeld.

Hinweise

Dies wird automatisch generiert, wenn nicht angegeben.

telemetryClient

Ruft den Telemetrieclient für dieses Dialogfeld ab. Legt den Telemetrieclient für dieses Dialogfeld fest.

BotTelemetryClient telemetryClient

Eigenschaftswert

BotTelemetryClient

Der BotTelemetryClient für die Protokollierung verwendet werden.

Geerbte Eigenschaftsdetails

EndOfTurn

Ruft ein Standardmäßiges End-of-Turn-Ergebnis ab.

static EndOfTurn: DialogTurnResult

Eigenschaftswert

DialogTurnResult

Hinweise

Dieses Ergebnis gibt an, dass ein Dialogfeld (oder ein logischer Schritt innerhalb eines Dialogfelds) die Verarbeitung für die aktuelle Drehung abgeschlossen hat, noch aktiv ist und auf weitere Eingaben wartet.

vonDialog.EndOfTurn geerbt

Details zur Methode

beginDialog(DialogContext, PromptOptions)

Wird aufgerufen, wenn ein Eingabeaufforderungsdialogfeld auf den Dialogstapel verschoben wird und aktiviert wird.

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

Parameter

dc

DialogContext

Die DialogContext- für die aktuelle Unterhaltung.

options

PromptOptions

Wahlfrei. PromptOptions-, zusätzliche Informationen, die an die zu startende Eingabeaufforderung übergeben werden sollen.

Gibt zurück

Promise<DialogTurnResult>

Eine Promise, die den asynchronen Vorgang darstellt.

Hinweise

Wenn der Vorgang erfolgreich ist, gibt das Ergebnis an, ob die Eingabeaufforderung noch aktiv ist, nachdem die Aufforderung von der Eingabeaufforderung verarbeitet wurde.

continueDialog(DialogContext)

Wird aufgerufen, wenn ein Eingabeaufforderungsdialogfeld das aktive Dialogfeld ist und der Benutzer mit einer neuen Aktivität geantwortet hat.

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

Parameter

dc

DialogContext

Die DialogContext- für die aktuelle Unterhaltung.

Gibt zurück

Promise<DialogTurnResult>

Eine Promise, die den asynchronen Vorgang darstellt.

Hinweise

Wenn die Aufgabe erfolgreich ist, gibt das Ergebnis an, ob das Dialogfeld noch aktiv ist, nachdem die Drehung vom Dialogfeld verarbeitet wurde. Die Eingabeaufforderung empfängt in der Regel weiterhin die Antworten des Benutzers, bis sie die Antwort des Benutzers als gültige Eingabe für die Eingabeaufforderung akzeptiert.

getUserToken(TurnContext, string)

Versucht, das gespeicherte Token für den aktuellen Benutzer abzurufen.

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

Parameter

context

TurnContext

Der Kontext verweist auf den Benutzer, der nachschlagen wird.

code

string

(Optional) Vom Benutzer empfangener Anmeldecode.

Gibt zurück

Promise<TokenResponse | undefined>

Die Tokenantwort.

recognizeToken(DialogContext)

Gemeinsame Implementierung der RecognizeTokenAsync-Funktion. Dies ist für die interne Verwendung vorgesehen, um die Implementierung von OAuthPrompt und OAuthInput zu konsolidieren. Anwendungslogik sollte diese Dialogfeldklassen verwenden.

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

Parameter

dc

DialogContext

Die DialogContext- für die aktuelle Unterhaltung.

Gibt zurück

Promise<PromptRecognizerResult<TokenResponse>>

Eine Zusage, die zum Ergebnis aufgelöst wird

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

Sendet eine OAuth-Karte.

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

Parameter

settings

OAuthPromptSettings

OAuth-Einstellungen.

turnContext

TurnContext

Kontext drehen.

prompt

string | Partial<Activity>

Nachrichtenaktivität.

Gibt zurück

Promise<void>

signOutUser(TurnContext)

Meldet den Benutzer vom Dienst ab.

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

Parameter

context

TurnContext

Kontext, der auf den Benutzer verweist, der abgemeldet wird.

Gibt zurück

Promise<void>

Eine Zusage, die den asynchronen Vorgang darstellt.

Hinweise

Dieses Beispiel zeigt das Erstellen einer Instanz der Eingabeaufforderung und anschließendes Abmelden des Benutzers.

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

Details zur geerbten Methode

configure(Record<string, unknown>)

Fluent-Methode zum Konfigurieren des Objekts.

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

Parameter

config

Record<string, unknown>

Anzuwendende Konfigurationseinstellungen.

Gibt zurück

this

Die konfigurierbaren nach Abschluss des Vorgangs.

geerbt vonKonfigurierbar.configure

endDialog(TurnContext, DialogInstance, DialogReason)

Wenn sie in einer abgeleiteten Klasse überschrieben wird, wird das Dialogfeld vor dem Beenden bereinigt.

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

Parameter

_context

TurnContext

Das Kontextobjekt für die Drehung.

_instance

DialogInstance

Aktuelle Statusinformationen für dieses Dialogfeld.

_reason

DialogReason

Der Grund, warum das Dialogfeld beendet wird.

Gibt zurück

Promise<void>

Hinweise

Abgeleitete Dialogfelder, die vor dem Beenden Protokollierung oder Bereinigung durchführen müssen, sollten diese Methode überschreiben. Standardmäßig hat diese Methode keine Auswirkung.

Die DialogContext- ruft diese Methode auf, wenn das aktuelle Dialogfeld beendet wird.

Siehe auch

• DialogContext.cancelAllDialogs
• DialogContext.endDialog-
• DialogContext.replaceDialog

vonDialog.endDialog geerbt

getConverter(string)

function getConverter(_property: string): Converter | ConverterFactory

Parameter

_property

string

Der Schlüssel der Konfiguration der bedingten Auswahl.

Gibt zurück

Converter | ConverterFactory

Der Konverter für die Selektorkonfiguration.

Geerbt vonKonfigurierbar.getConverter

getVersion()

Eine codierte Zeichenfolge zur Unterstützung der Erkennung von Bot-Änderungen bei der erneuten Bereitstellung.

function getVersion(): string

Gibt zurück

string

Eindeutige Zeichenfolge, die sich nur ändern sollte, wenn sich das Dialogfeld auf eine Weise geändert hat, die das Dialogfeld neu starten soll.

Hinweise

Dadurch werden standardmäßig die Dialogfelder ID- zurückgegeben, können jedoch außer Kraft gesetzt werden, um präzisere Änderungserkennungslogik bereitzustellen. Jedes Dialogfeld im Stapel, das seine Versionsänderung hat, führt zu einem versionChanged Ereignis wird ausgelöst. Wenn dieses Ereignis nicht vom Bot behandelt wird, wird ein Fehler ausgelöst, der dazu führt, dass die Bots-Fehlerhandlerlogik ausgeführt wird.

Durch zurückgeben einer leeren Zeichenfolge wird die Versionsnachverfolgung für die Komponente insgesamt deaktiviert.

geerbt vonDialog.getVersion

onDialogEvent(DialogContext, DialogEvent)

Wird aufgerufen, wenn ein Ereignis mit DialogContext.emitEvent()ausgelöst wurde, entweder durch das aktuelle Dialogfeld oder ein Dialogfeld, das das aktuelle Dialogfeld gestartet hat.

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

Parameter

dc

DialogContext

Der Dialogkontext für die aktuelle Unterhaltungswende.

e

DialogEvent

Das ausgelöste Ereignis.

Gibt zurück

Promise<boolean>

True, wenn das Ereignis vom aktuellen Dialogfeld behandelt wird und Bubbling beendet werden soll.

geerbt vonDialog.onDialogEvent

repromptDialog(TurnContext, DialogInstance)

Wenn sie in einer abgeleiteten Klasse überschrieben wird, wird der Benutzer erneut zur Eingabe aufgefordert.

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

Parameter

_context

TurnContext

Das Kontextobjekt für die Drehung.

_instance

DialogInstance

Aktuelle Statusinformationen für dieses Dialogfeld.

Gibt zurück

Promise<void>

Hinweise

Abgeleitete Dialogfelder, die validierungs- und erneute Aufforderungslogik unterstützen, sollten diese Methode überschreiben. Standardmäßig hat diese Methode keine Auswirkung.

Die DialogContext- ruft diese Methode auf, wenn das aktuelle Dialogfeld eingaben vom Benutzer erneut anfordern soll. Diese Methode wird für Eingabeaufforderungsdialoge implementiert.

Siehe auch

• DialogContext.repromptDialog
• Aufforderung

geerbt vonDialog.repromptDialog-

resumeDialog(DialogContext, DialogReason, any)

Wenn sie in einer abgeleiteten Klasse überschrieben wird, wird das Dialogfeld nach Abschluss des Dialogfelds auf dem Stapel fortgesetzt.

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

Parameter

dc

DialogContext

Der Kontext für die aktuelle Dialogdrehung.

reason

DialogReason

Der Grund, warum das Dialogfeld fortgesetzt wird. Dies wird in der Regel DialogReason.endCalled-

result

any

Wahlfrei. Der Rückgabewert (falls vorhanden) aus dem dialogfeld, das beendet wurde.

Gibt zurück

Promise<DialogTurnResult>

Eine Zusage, die in das Dialogdrehergebnis aufgelöst wird.

Hinweise

Abgeleitete Dialogfelder, die Mehrfachwechselunterhaltungen unterstützen, sollten diese Methode überschreiben. Standardmäßig signalisiert diese Methode, dass das Dialogfeld abgeschlossen ist und zurückgegeben wird.

Die DialogContext- ruft diese Methode auf, wenn das Dialogfeld fortgesetzt wird. Wenn das vorherige Dialogfeld im Stapel einen Wert zurückgegeben hat, befindet sich dieser Wert im result-Parameter.

Um ein untergeordnetes dialogfeld zu starten, verwenden Sie DialogContext.beginDialog oder DialogContext.prompt; Dieses Dialogfeld ist jedoch nicht unbedingt das Dialogfeld, das das untergeordnete Dialogfeld gestartet hat. Um dem Dialogfeldkontext zu signalisieren, dass dieses Dialogfeld abgeschlossen wurde, warten Sie DialogContext.endDialog, bevor Sie diese Methode beenden.

Siehe auch

• DialogContext.endDialog-

geerbt vonDialog.resumeDialog