OAuthPrompt class

建立新的提示，要求使用者使用 Bot Frameworks 單一登錄（SSO）服務登入。

備註

提示會嘗試擷取使用者目前的令牌，如果使用者未登入，則會傳送 OAuthCard，其中包含他們可以按下以登入的按鈕。視通道而定，使用者將會透過兩個可能的登入流程之一傳送：

自動登入流程，一旦使用者登入和 SSO 服務，就會使用 event 或 invoke 活動轉送使用者存取令牌。
「魔術程式代碼」流程，其中一旦使用者登入，SSO 服務就會提示他們傳送確認其身分識別的六位數程式代碼給 Bot。此程式代碼會以標準 message 活動的形式傳送。

這兩個流程都會由 OAuthPrompt 自動支援，唯一需要注意的是，您不會封鎖提示可能正在等候的 event 和 invoke 活動。

注意

您應該避免使用 Bot 的其他狀態儲存存取令牌。 Bot Frameworks SSO 服務會代表您安全地儲存令牌。如果您將其儲存在 Bot 中，表示它可能會過期或會在兩次之間撤銷。

從瀑布式步驟中呼叫提示時，您應該在提示之後的步驟內使用令牌，然後讓令牌超出函式結尾的範圍。

提示使用方式

搭配 Bot 使用時 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	對話框的唯一標識碼。設定對話框的唯一標識符。
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()	編碼字串，用來協助在重新部署時偵測 Bot 變更。
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內的唯一標識符。

settings: OAuthPromptSettings

用來設定提示的設定。

validator: PromptValidator<TokenResponse>

（選擇性）驗證程式，會在每次用戶回應提示時呼叫。

id

對話框的唯一標識碼。設定對話框的唯一標識符。

string id

屬性值

string

對話框的識別碼。

備註

如果未指定，系統就會自動產生此專案。

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>

代表異步操作的承諾。

備註

此範例示範如何建立提示的實例，然後註銷使用者。

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

選取器組態的轉換器。

繼承自可設定.getConverter

getVersion()

編碼字串，用來協助在重新部署時偵測 Bot 變更。

function getVersion(): string

傳回

string

唯一的字串，只有在對話框以應該重新啟動對話框的方式變更時才會變更。

備註

這預設會傳回對話框標識子，但可以覆寫以提供更精確的變更偵測邏輯。堆疊上具有其版本變更的任何對話框都會引發 versionChanged 事件。如果 Bot 未處理此事件，則會擲回錯誤，導致 Bot 錯誤處理程式邏輯正在執行。

傳回空字串將會一起停用元件的版本追蹤。

繼承自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>

解決對話框回合結果的承諾。

備註

支援多回合交談的衍生對話應該覆寫此方法。根據預設，這個方法會發出對話框已完成並傳回的訊號。

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)

參數

傳回

備註