OAuthPrompt class

リファレンス

パッケージ:: botbuilder-dialogs

Bot Frameworks シングルサインオン (SSO) サービスを使用してサインインするようにユーザーに求める新しいプロンプトを作成します。

Extends: Dialog

注釈

プロンプトはユーザーの現在のトークンの取得を試み、ユーザーがサインインしていない場合は、ユーザーがサインインするために押すことができるボタンを含む OAuthCard をユーザーに送信します。チャネルに応じて、ユーザーは次の 2 つの可能なサインインフローのいずれかを通じて送信されます。

自動サインインフロー。ユーザーがサインインし、SSO サービスがボットを転送すると、ユーザーは event または invoke アクティビティを使用してトークンにアクセスします。
"マジックコード" フロー。ユーザーがサインインすると、SSO サービスから、自分の ID を確認する 6 桁のコードをボットに送信するように求められます。このコードは、標準の 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

操作が完了した後の構成可能な。

継承構成可能。構成

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>

True の場合は、イベントが現在のダイアログで処理され、バブルを停止する必要があります。

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>

ダイアログターンの結果を解決する Promise。

注釈

複数ターンの会話をサポートする派生ダイアログは、このメソッドをオーバーライドする必要があります。既定では、このメソッドはダイアログが完了したことを通知し、返します。

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)

パラメーター

戻り値

注釈

その他のリソース