BotFrameworkAdapter class

Crée une instance de la classe BotFrameworkAdapter .

new BotFrameworkAdapter(settings?: Partial<BotFrameworkAdapterSettings>)

Paramètres

Remarques

Si le settings paramètre n’inclut pas les valeurs channelService ou openIdMetadata , le constructeur vérifie les variables d’environnement du processus pour ces valeurs. Ces valeurs peuvent être définies lorsqu’un bot est approvisionné sur Azure et, le cas échéant, elles sont nécessaires pour que le bot fonctionne correctement dans le cloud global ou dans un cloud national.

La classe BotFrameworkAdapterSettings définit les paramètres d’adaptateur disponibles.

Utilisé dans les contextes de streaming pour vérifier si la connexion de streaming est toujours ouverte pour que le bot envoie des activités.

boolean isStreamingConnectionOpen

Valeur de propriété

True si la connexion de streaming est ouverte, sinon false.

TokenApiClientCredentialsKey: symbol

Valeur de propriété

BotIdentityKey: symbol

Valeur de propriété

Hérité de BotAdapter.BotIdentityKey

ConnectorClientKey: symbol

Valeur de propriété

Hérité de BotAdapter.ConnectorClientKey

OAuthScopeKey: symbol

Valeur de propriété

Hérité de BotAdapter.OAuthScopeKey

onTurnError: (context: TurnContext, error: Error) => Promise<void>

Valeur de propriété

Hérité de BotAdapter.onTurnError

Reprend de façon asynchrone une conversation avec un utilisateur, peut-être après un certain temps.

function continueConversation(reference: Partial<ConversationReference>, logic: (context: TurnContext) => Promise<void>): Promise<void>

Paramètres

Retours

Remarques

Il s’agit souvent d’une notification proactive. Le bot peut envoyer de manière proactive un message à une conversation ou à un utilisateur sans attendre un message entrant. Par exemple, un bot peut utiliser cette méthode pour envoyer des notifications ou des coupons à un utilisateur.

Pour envoyer un message proactif :

1. Enregistrez une copie d’une conversationReference à partir d’une activité entrante. Par exemple, vous pouvez stocker la référence de conversation dans une base de données.
2. Appelez cette méthode pour reprendre la conversation ultérieurement. Utilisez la référence enregistrée pour accéder à la conversation.
3. En cas de réussite, l’adaptateur génère un objet TurnContext et appelle le gestionnaire de fonction logic . Utilisez la logic fonction pour envoyer le message proactif.

Pour copier la référence à partir d’une activité entrante dans la conversation, utilisez la méthode TurnContext.getConversationReference .

Cette méthode est similaire à la méthode processActivity . L’adaptateur crée un TurnContext et l’achemine via son intergiciel avant d’appeler le logic gestionnaire. L’activité créée aura le type « event » et le nom « continueConversation ».

Par exemple :

server.post('/api/notifyUser', async (req, res) => {
   // Lookup previously saved conversation reference.
   const reference = await findReference(req.body.refId);

   // Proactively notify the user.
   if (reference) {
      await adapter.continueConversation(reference, async (context) => {
         await context.sendActivity(req.body.message);
      });
      res.send(200);
   } else {
      res.send(404);
   }
});

Reprend de façon asynchrone une conversation avec un utilisateur, peut-être après un certain temps.

function continueConversation(reference: Partial<ConversationReference>, oAuthScope: string, logic: (context: TurnContext) => Promise<void>): Promise<void>

Paramètres

Retours

Crée un client de connecteur.

function createConnectorClient(serviceUrl: string): ConnectorClient

Paramètres

Retours

Instance ConnectorClient .

Remarques

Remplacez ce paramètre dans une classe dérivée pour créer un client de connecteur fictif pour les tests unitaires.

Créez un ConnectorClient avec un ClaimsIdentity.

function createConnectorClientWithIdentity(serviceUrl: string, identity: ClaimsIdentity): Promise<ConnectorClient>

Paramètres

Retours

Remarques

Si ClaimsIdentity contient les revendications d’une demande skills, créez un ConnectorClient à utiliser avec Skills. Dérive l’audience correcte de la propriété ClaimsIdentity ou des informations d’identification de l’instance.

Créez un ConnectorClient avec un ClaimsIdentity et une audience explicite.

function createConnectorClientWithIdentity(serviceUrl: string, identity: ClaimsIdentity, audience: string): Promise<ConnectorClient>

Paramètres

Retours

Remarques

Si l’audience supprimée n’est pas une chaîne de longueur différente de zéro, l’audience est dérivée de la propriété ClaimsIdentity ou des informations d’identification de l’instance.

Crée et démarre de manière asynchrone une conversation avec un utilisateur sur un canal.

function createConversation(reference: Partial<ConversationReference>, logic: (context: TurnContext) => Promise<void>): Promise<void>

Paramètres

Retours

promesse représentant l’opération asynchrone

Crée et démarre de manière asynchrone une conversation avec un utilisateur sur un canal.

function createConversation(reference: Partial<ConversationReference>, parameters: Partial<ConversationParameters>, logic: (context: TurnContext) => Promise<void>): Promise<void>

Paramètres

Retours

promesse représentant l’opération asynchrone

Supprime de façon asynchrone une activité existante. Cette interface prend en charge le framework et n’est pas destinée à être appelée directement pour votre code. Utilisez TurnContext.deleteActivity pour supprimer une activité de votre code de bot.

function deleteActivity(context: TurnContext, reference: Partial<ConversationReference>): Promise<void>

Paramètres

Retours

Remarques

Tous les canaux ne prennent pas en charge cette opération. Pour les canaux qui ne le font pas, cet appel peut lever une exception.

Supprime de façon asynchrone un membre de la conversation actuelle.

function deleteConversationMember(context: TurnContext, memberId: string): Promise<void>

Paramètres

Retours

Remarques

Supprimez les informations d’identité d’un membre de la conversation.

Tous les canaux ne prennent pas en charge cette opération. Pour les canaux qui ne le font pas, cet appel peut lever une exception.

Envoie de façon asynchrone une carte OAuth émulée pour un canal. Cette méthode prend en charge l’infrastructure et n’est pas destinée à être appelée directement pour votre code.

function emulateOAuthCards(contextOrServiceUrl: TurnContext | string, emulate: boolean): Promise<void>

Paramètres

Retours

Remarques

Lors du test d’un bot dans le Bot Framework Emulator, cette méthode peut émuler l’interaction de carte OAuth.

Effectue de manière asynchrone une opération d’échange de jetons, par exemple pour l’authentification unique.

function exchangeToken(context: TurnContext, connectionName: string, userId: string, tokenExchangeRequest: TokenExchangeRequest, appCredentials?: CoreAppCredentials): Promise<TokenResponse>

Paramètres

Retours

Déconnecte de façon asynchrone l’utilisateur du serveur de jetons.

function getAadTokens(context: TurnContext, connectionName: string, resourceUrls: string[]): Promise<[key: string]: TokenResponse>

Paramètres

Retours

Mappage des objets TokenResponse par URL de ressource.

function getAadTokens(context: TurnContext, connectionName: string, resourceUrls: string[], oAuthAppCredentials?: CoreAppCredentials): Promise<[key: string]: TokenResponse>

Paramètres

Retours

Répertorie de manière asynchrone les membres d’une activité donnée.

function getActivityMembers(context: TurnContext, activityId?: string): Promise<ChannelAccount[]>

Paramètres

Retours

Tableau d’objets ChannelAccount pour les utilisateurs impliqués dans une activité donnée.

Remarques

Retourne un tableau d’objets ChannelAccount pour les utilisateurs impliqués dans une activité donnée.

Cela est différent de getConversationMembers en ce qu’il retourne uniquement les utilisateurs directement impliqués dans l’activité, pas tous les membres de la conversation.

Répertorie de façon asynchrone les membres de la conversation actuelle.

function getConversationMembers(context: TurnContext): Promise<ChannelAccount[]>

Paramètres

Retours

Tableau d’objets ChannelAccount pour tous les utilisateurs actuellement impliqués dans une conversation.

Remarques

Retourne un tableau d’objets ChannelAccount pour tous les utilisateurs actuellement impliqués dans une conversation.

Cela est différent de getActivityMembers en ce qu’il retourne tous les membres de la conversation, pas seulement ceux directement impliqués dans une activité spécifique.

Pour le canal spécifié, obtient de manière asynchrone une page des conversations auxquelles ce bot a participé.

function getConversations(contextOrServiceUrl: TurnContext | string, continuationToken?: string): Promise<ConversationsResult>

Paramètres

Retours

Objet ConversationsResult contenant une page de résultats et un jeton de continuation.

Remarques

La propriété conversations de la valeur de retour contient une page d’objets ConversationMembers . L’ID de chaque objet est l’ID d’une conversation à laquelle le bot a participé sur ce canal. Cette méthode peut être appelée en dehors du contexte d’une conversation, car seules l’URL du service et les informations d’identification du bot sont requises.

Les lots de canaux donnent des pages. Si la propriété continuationToken du résultat n’est pas vide, il y a d’autres pages à obtenir. Utilisez le jeton retourné pour obtenir la page de résultats suivante. Si le contextOrServiceUrl paramètre est un TurnContext, l’URL du serveur de canal est récupérée à partir de contextOrServiceUrl. activité. serviceUrl.

Obtient de manière asynchrone un lien de connexion à partir du serveur de jetons qui peut être envoyé dans le cadre d’une signinCard.

function getSignInLink(context: TurnContext, connectionName: string, oAuthAppCredentials?: AppCredentials, userId?: string, finalRedirect?: string): Promise<string>

Paramètres

Retours

function getSignInLink(context: TurnContext, connectionName: string, oAuthAppCredentials?: CoreAppCredentials, userId?: string, finalRedirect?: string): Promise<string>

Paramètres

Retours

Obtenez de manière asynchrone la ressource de connexion brute à envoyer à l’utilisateur pour la connexion.

function getSignInResource(context: TurnContext, connectionName: string, userId?: string, finalRedirect?: string, appCredentials?: CoreAppCredentials): Promise<SignInUrlResponse>

Paramètres

Retours

Objet BotSignInGetSignInResourceResponse .

Récupère de manière asynchrone l’état du jeton pour chaque connexion configurée pour l’utilisateur donné.

function getTokenStatus(context: TurnContext, userId?: string, includeFilter?: string): Promise<TokenStatus[]>

Paramètres

Retours

Objets TokenStatus récupérés.

function getTokenStatus(context: TurnContext, userId?: string, includeFilter?: string, oAuthAppCredentials?: CoreAppCredentials): Promise<TokenStatus[]>

Paramètres

Retours

Tente de manière asynchrone de récupérer le jeton d’un utilisateur qui se trouve dans un flux de connexion.

function getUserToken(context: TurnContext, connectionName: string, magicCode?: string): Promise<TokenResponse>

Paramètres

Retours

Objet TokenResponse qui contient le jeton utilisateur.

function getUserToken(context: TurnContext, connectionName: string, magicCode?: string, oAuthAppCredentials?: CoreAppCredentials): Promise<TokenResponse>

Paramètres

Retours

Gérez une connexion de socket web en appliquant une fonction logique à chaque demande de streaming.

function process(req: Request, socket: INodeSocket, head: INodeBuffer, logic: (context: TurnContext) => Promise<void>): Promise<void>

Paramètres

Retours

promesse représentant l’opération asynchrone.

Traiter une requête web en appliquant une fonction logique.

function process(req: Request, res: Response, logic: (context: TurnContext) => Promise<void>): Promise<void>

Paramètres

Retours

promesse représentant l’opération asynchrone.

Crée de manière asynchrone un contexte de tour et exécute le pipeline d’intergiciel pour une activité entrante.

function processActivity(req: WebRequest, res: WebResponse, logic: (context: TurnContext) => Promise<any>): Promise<void>

Paramètres

Retours

Remarques

Il s’agit de la principale façon dont un bot reçoit les messages entrants et définit un tour dans la conversation. Cette méthode :

1. Analyse et authentifie une requête entrante.
   • L’activité est lue à partir du corps de la requête entrante. Une erreur est retournée si l’activité ne peut pas être analysée.
   • L’identité de l’expéditeur est authentifiée en tant qu’émulateur ou serveur Microsoft valide, à l’aide des données du appId bot et appPasswordde . La demande est rejetée si l’identité de l’expéditeur n’est pas vérifiée.
2. Crée un objet TurnContext pour l’activité reçue.
   • Cet objet est encapsulé avec un proxy révocable.
   • Une fois cette méthode terminée, le proxy est révoqué.
3. Envoie le contexte de tour par le biais du pipeline middleware de l’adaptateur.
4. Envoie le contexte de tour à la logic fonction.
   • Le bot peut effectuer un routage ou un traitement supplémentaire pour le moment. Le retour d’une promesse (ou la fourniture d’un async gestionnaire) entraîne l’attente de l’adaptateur jusqu’à la fin des opérations asynchrones.
   • Une fois la logic fonction terminée, la chaîne de promesse configurée par le middleware est résolue.

L’intergiciel peut court-circuiter un tour. Dans ce cas, le middleware suivant et la logic fonction ne sont pas appelés ; toutefois, tous les middlewares antérieurs à ce point s’exécutent toujours jusqu’à l’achèvement. Pour plus d’informations sur le pipeline d’intergiciels, consultez les articles fonctionnement des bots et middleware . Utilisez la méthode use de l’adaptateur pour ajouter un intergiciel à l’adaptateur.

Par exemple :

server.post('/api/messages', (req, res) => {
   // Route received request to adapter for processing
   adapter.processActivity(req, res, async (context) => {
       // Process any messages received
       if (context.activity.type === ActivityTypes.Message) {
           await context.sendActivity(`Hello World`);
       }
   });
});

Crée de manière asynchrone un contexte de tour et exécute le pipeline d’intergiciel pour une activité entrante.

function processActivityDirect(activity: Activity, logic: (context: TurnContext) => Promise<any>): Promise<void>

Paramètres

Retours

Remarques

Il s’agit de la principale façon dont un bot reçoit les messages entrants et définit un tour dans la conversation. Cette méthode :

1. Crée un objet TurnContext pour l’activité reçue.
   • Cet objet est encapsulé avec un proxy révocable.
   • Une fois cette méthode terminée, le proxy est révoqué.
2. Envoie le contexte de tour par le biais du pipeline d’intergiciel de l’adaptateur.
3. Envoie le contexte de tour à la logic fonction.
   • Le bot peut effectuer un routage ou un traitement supplémentaire à ce stade. Le retour d’une promesse (ou la fourniture d’un async gestionnaire) entraîne l’attente de l’adaptateur jusqu’à la fin des opérations asynchrones.
   • Une fois la logic fonction terminée, la chaîne de promesse configurée par l’intergiciel est résolue.

L’intergiciel peut court-circuiter un tour. Dans ce cas, les intergiciels suivants et la logic fonction ne sont pas appelés ; toutefois, tous les intergiciels antérieurs à ce point s’exécutent toujours jusqu’à la fin. Pour plus d’informations sur le pipeline d’intergiciels, consultez les articles fonctionnement des bots et intergiciels . Utilisez la méthode use de l’adaptateur pour ajouter un intergiciel à l’adaptateur.

Vérifie la validité de la demande et tente de la mapper le point de terminaison virtuel approprié, puis génère et retourne une réponse, le cas échéant.

function processRequest(request: IReceiveRequest): Promise<StreamingResponse>

Paramètres

Retours

Réponse créée par le BotAdapter à envoyer au client à l’origine de la demande.

Envoie de façon asynchrone un ensemble d’activités sortantes à un serveur de canal. Cette méthode prend en charge l’infrastructure et n’est pas destinée à être appelée directement pour votre code. Utilisez la méthode sendActivity ou sendActivities du contexte de tour à partir de votre code de bot.

function sendActivities(context: TurnContext, activities: Partial<Activity>[]): Promise<ResourceResponse[]>

Paramètres

Retours

Tableau de ResourceResponse

Remarques

Les activités sont envoyées les unes après les autres dans l’ordre dans lequel elles sont reçues. Un objet response est retourné pour chaque activité envoyée. Pour message les activités, il contient l’ID du message remis.

Déconnecte de façon asynchrone l’utilisateur du serveur de jetons.

function signOutUser(context: TurnContext, connectionName?: string, userId?: string): Promise<void>

Paramètres

Retours

function signOutUser(context: TurnContext, connectionName?: string, userId?: string, oAuthAppCredentials?: CoreAppCredentials): Promise<void>

Paramètres

Retours

Remplace de manière asynchrone une activité précédente par une version mise à jour. Cette interface prend en charge le framework et n’est pas destinée à être appelée directement pour votre code. Utilisez TurnContext.updateActivity pour mettre à jour une activité à partir du code de votre bot.

function updateActivity(context: TurnContext, activity: Partial<Activity>): Promise<ResourceResponse | void>

Paramètres

Retours

Promise représentant resourceResponse pour l’opération.

Remarques

Tous les canaux ne prennent pas en charge cette opération. Pour les canaux qui ne le font pas, cet appel peut lever une exception.

Connecte le gestionnaire à un serveur de canal nommé et commence à écouter les demandes entrantes.

function useNamedPipe(logic: (context: TurnContext) => Promise<any>, pipeName?: string, retryCount?: number, onListen?: () => void): Promise<void>

Paramètres

Retours

Traitez la demande initiale pour établir une connexion de longue durée via un serveur de streaming.

function useWebSocket(req: WebRequest, socket: INodeSocket, head: INodeBuffer, logic: (context: TurnContext) => Promise<any>): Promise<void>

Paramètres

Retours

Reprend de façon asynchrone une conversation avec un utilisateur, peut-être après un certain temps.

function continueConversationAsync(claimsIdentity: ClaimsIdentity, reference: Partial<ConversationReference>, logic: (context: TurnContext) => Promise<void>): Promise<void>

Paramètres

Retours

promesse représentant l’opération asynchrone

Hérité de BotAdapter.continueConversationAsync

Reprend de façon asynchrone une conversation avec un utilisateur, peut-être après un certain temps.

function continueConversationAsync(claimsIdentity: ClaimsIdentity, reference: Partial<ConversationReference>, audience: string, logic: (context: TurnContext) => Promise<void>): Promise<void>

Paramètres

Retours

promesse représentant l’opération asynchrone

Hérité de BotAdapter.continueConversationAsync

Reprend de façon asynchrone une conversation avec un utilisateur, peut-être après un certain temps.

function continueConversationAsync(botAppId: string, reference: Partial<ConversationReference>, logic: (context: TurnContext) => Promise<void>): Promise<void>

Paramètres

Retours

promesse représentant l’opération asynchrone

Hérité de BotAdapter.continueConversationAsync

Crée une conversation sur le canal spécifié.

function createConversationAsync(_botAppId: string, _channelId: string, _serviceUrl: string, _audience: string, _conversationParameters: ConversationParameters, _logic: (context: TurnContext) => Promise<void>): Promise<void>

Paramètres

Retours

Promesse qui représente l’opération asynchrone

Remarques

Pour démarrer une conversation, votre bot doit connaître ses informations de compte et les informations de compte de l’utilisateur sur ce canal. La plupart des _channels prennent uniquement en charge le lancement d’une conversation par message direct (non de groupe).

L’adaptateur tente de créer une conversation sur le canal, puis envoie une conversationUpdate activité via son pipeline d’intergiciel (middleware) à la méthode logique.

Si la conversation est établie avec les utilisateurs spécifiés, l’ID de la conversation de l’activité contient l’ID de la nouvelle conversation.

Hérité de BotAdapter.createConversationAsync

Ajoute un intergiciel (middleware) au pipeline de l’adaptateur.

function use(middlewares: (context: TurnContext, next: () => Promise<void>) => Promise<void> | Middleware[]): this

Paramètres

Retours

Objet adaptateur mis à jour.

Remarques

L’intergiciel est ajouté à l’adaptateur au moment de l’initialisation. À chaque tour, l’adaptateur appelle son intergiciel dans l’ordre dans lequel vous l’avez ajouté.

Hérité de BotAdapter.use