Comprendre la structure d’un echo bot

S'APPLIQUE À : SDK v4

Les modèles et échantillons Bot Framework sont écrits pour ASP.NET (C#), restify (JavaScript) et aiohttp (Python). Toutefois, les caractéristiques du service Web ne sont pas incluses dans le kit de développement logiciel (SDK) Bot Framework, mais font partie du cadre Web que vous choisissez d'utiliser.

Toutes les applications de bot partagent certaines caractéristiques communes.

Fonctionnalité	Description
Provisionnement des ressources	Le bot en tant qu'application Web doit créer un service Web, un adaptateur et un objet de bot.
Point de terminaison de messagerie	L'application Web doit mettre en œuvre un point de terminaison de messagerie sur lequel recevoir des activités et les transférer à l'adaptateur de bot.
Adaptateur de bot	L'adaptateur reçoit des activités du point de terminaison de messagerie, les transfère au gestionnaire de tour du bot et intercepte les erreurs ou exceptions que la logique du bot n'intercepte pas.
Objet de bot	Les poignées d'objet de bot gèrent le raisonnement ou la logique du bot pour le tour.

Vous pouvez créer un bot d'écho à partir des modèles, comme décrit dans l'onglet Créer un bot, ou copier un projet de bot d'écho à partir du référentiel Microsoft/BotBuilder-Samples.

Les modèles C# et JavaScript prédéfinissent le support de diffusion en continu de connections. Toutefois, cet article ne dispose pas des caractéristiques de diffusion en continu. Pour plus d'informations sur la diffusion en continu de connections, découvrez comment connecter un bot à Direct Line Speech.

Remarque

Les kits SDK JavaScript, C# et Python Bot Framework continueront d’être pris en charge. Toutefois, le kit de développement logiciel (SDK) Java est mis hors service avec une prise en charge finale à long terme se terminant en novembre 2023.

Les bots existants créés avec le kit de développement logiciel (SDK) Java continueront de fonctionner.

Pour la nouvelle génération de bots, envisagez d’utiliser Microsoft Copilot Studio et lisez-en plus sur le choix de la solution copilote appropriée.

Pour plus d’informations, consultez Les futures versions de bot.

Prérequis

• Connaissances des concepts de base des bots.
• Une copie de l'échantillon d'echo bot en C#, JavaScript, Java, ou Python.

Modèles de bot

Un bot est une application web, et des modèles sous fournis pour chaque langage.

C#

Bot Framework inclut à la fois des modèles VSIX et .NET.

Les modèles génèrent une application Web ASP.NET MVC centrale. Si vous étudiez les notions de base d’ASP.NET, vous découvrez qu’il existe un code similaire dans les fichiers tels que Program.cs et Startup.cs. Ces fichiers sont requis pour toutes les applications Web et ne sont pas spécifiques à un bot.

Remarque

Vous pouvez installer les modèles à partir de Visual Studio.

1. Dans le menu, sélectionnez extensions puis Gérer les extensions.
2. Dans la boîte de dialogue gérer les extensions, recherchez et installez les modèles kit de développement logiciel (SDK) de Bot Framework v4 pour Visual Studio.

Pour plus d'informations sur le déploiement de bots .NET sur Azure, consultez Comment approvisionner et publier un bot.

Le fichier appsettings.json spécifie les informations de configuration de votre bot, notamment son ID d'application et le mot de passe, entre autres. Si vous utilisez certaines technologies ou ce bot en production, vous devrez ajouter vos propres clés ou URL à cette configuration. Toutefois, pour les besoins de ce bot écho, vous n'avez rien à faire à ce stade ; l'ID de l'application et le mot de passe peuvent rester non définis pour l'instant.

Le fichier Maven EchoBot.csproj spécifie les dépendances et leurs versions associées pour votre bot. Toutes ces informations sont configurées par le modèle et par votre système. Des dépendances supplémentaires peuvent être installées à l'aide du gestionnaire de package NuGet ou de la commande dotnet add package.

JavaScript

Le générateur Yeoman crée un type d’application web restify. Si vous consultez le démarrage rapide dédié à restify dans la documentation, vous pouvez voir une application similaire au fichier index.js généré. Certains des fichiers clés générés par le modèle sont décrits dans cet article. Le code de certains fichiers ne sera pas copié. Mais, vous pouvez le consultez en exécutant le bot. Vous pouvez également consulter l'échantillon Node.js echobot.

Le fichier package.json spécifie les dépendances et leurs versions associées pour votre bot. Toutes ces informations sont configurées par le modèle et par votre système. Des dépendances supplémentaires peuvent être installées à l'aide de npm install.

Le fichier .env spécifie les informations de configuration de votre bot, notamment le numéro de port, l’ID de l’application et le mot de passe. Si vous utilisez certaines technologies ou ce bot en production, vous devrez ajouter vos propres clés ou URL à cette configuration. Toutefois, pour les besoins de ce bot Echo, vous n’avez rien à faire à ce stade ; l’ID de l’application et le mot de passe peuvent rester non définis pour l’instant.

Pour utiliser le fichier de configuration .env, le bot nécessite un package dotenv à partir de npm. Il est déjà inclus en tant que dépendance dans le fichier package.json.

Java

Le générateur Yeoman crée une application Web basée sur Spring avec un fichier de build à l'aide de Maven.

Le fichier Maven pom.xml spécifie les dépendances et leurs versions associées pour votre bot. Toutes ces informations sont configurées par le modèle et par votre système. Des dépendances supplémentaires peuvent être installées en ajoutant des entrées au fichier pom.xml.

Le fichier application.properties spécifie les informations de configuration de votre bot, notamment le numéro de port, l'ID de l'application et le mot de passe, entre autres. Si vous utilisez certaines technologies ou ce bot en production, vous devrez ajouter vos propres clés ou URL à cette configuration. Toutefois, pour les besoins de ce bot Echo, vous n’avez rien à faire à ce stade ; l’ID de l’application et le mot de passe peuvent rester non définis pour l’instant.

Python

Les modèles Cookiecutter Python créent une application Web aiohttp.

Le fichier requirements.txt spécifie les dépendances et leurs versions associées pour votre bot. Tout cela est configuré par le modèle et votre système. Des dépendances supplémentaires peuvent être installées à l'aide de pip install -r requirements.txt

Le fichier config.py spécifie les informations de configuration de votre bot, notamment le numéro de port, l’ID de l’application et le mot de passe. Si vous utilisez certaines technologies ou ce bot en production, vous devrez ajouter vos propres clés ou URL à cette configuration. Toutefois, pour les besoins de ce bot Echo, vous n’avez rien à faire à ce stade ; l’ID de l’application et le mot de passe peuvent rester non définis pour l’instant.

Provisionnement des ressources

Pour fonctionner en tant qu'application Web, votre bot doit créer un service Web, un adaptateur et un objet de bot.

Pour la plupart des bots, vous créez également des objets de gestion de la couche de stockage et de la mémoire pour le bot. Toutefois, le bot écho n'a pas besoin de conserver l'état entre les tours. Pour certains bots, vous devrez peut-être créer d'autres objets dont l'objet ou l'adaptateur de bot aura besoin.

C#

Dans ASP.NET, vous inscrivez des objets et des méthodes de création d'objets dans le fichier Startup.cs. La méthode ConfigureServices charge les services connectés et leurs clés (le cas échéant) à partir d'appsettings.json, connecte l'état, et ainsi de suite. Ici, l'adaptateur et le bot sont définis pour être disponibles via l'injection de dépendances. Ensuite, la méthode Configure termine la configuration de votre application.

ConfigureServices et Configure sont appelés par le runtime au démarrage de l’application.

JavaScript

Dans restify, vous configurez le service Web et les objets dont il a besoin dans le fichier index.js. Le service, l'adaptateur et le bot sont présentés séparément dans les sections suivantes.

Java

Dans Spring, vous configurez le service Web et les objets dont il a besoin dans le fichier de l'application.java. L'application.java contient des commentaires qui indiquent les différents composants et classes d'infrastructure utilisés par l'application bot. Le service, l'adaptateur et le bot sont présentés séparément dans les sections suivantes.

Python

Dans aiohttp, vous configurez le service Web et les objets dont il a besoin dans le fichier app.py. Le service, l'adaptateur et le bot sont présentés séparément dans les sections suivantes.

Point de terminaison de messagerie

Le modèle mets en œuvre un service Web avec un point de terminaison de messagerie. Lorsqu'il reçoit une demande, le service extrait l'en-tête d'authentification et la charge utile de la demande et les transfère à l'adaptateur.

Les kits de développement logiciel (SDK) C# et JavaScript prennent en charge la diffusion en continu de connections. Bien que le bot écho n'utilise aucune des caractéristiques de diffusion en continu, l'adaptateur dans les modèles C# et JavaScript est conçu pour les prendre en charge.

Chaque requête entrante représente le début d'un nouveau tour.

C#

Controllers\BotController.cs

// This ASP Controller is created to handle a request. Dependency Injection will provide the Adapter and IBot
// implementation at runtime. Multiple different IBot implementations running at different endpoints can be
// achieved by specifying a more specific type for the bot constructor argument.
[Route("api/messages")]
[ApiController]
public class BotController : ControllerBase
{
    private readonly IBotFrameworkHttpAdapter _adapter;
    private readonly IBot _bot;

    public BotController(IBotFrameworkHttpAdapter adapter, IBot bot)
    {
        _adapter = adapter;
        _bot = bot;
    }

    [HttpPost, HttpGet]
    public async Task PostAsync()
    {
        // Delegate the processing of the HTTP POST to the adapter.
        // The adapter will invoke the bot.
        await _adapter.ProcessAsync(Request, Response, _bot);
    }
}

JavaScript

index.js

const { EchoBot } = require('./bot');

// Create HTTP server
const server = restify.createServer();
server.use(restify.plugins.bodyParser());

// Create an adapter scoped to this WebSocket connection to allow storing session data.
const streamingAdapter = new CloudAdapter(botFrameworkAuthentication);
// Set onTurnError for the CloudAdapter created for each connection.
streamingAdapter.onTurnError = onTurnErrorHandler;

Java

Application.java

@Import({BotController.class})

Python

app.py

    return await ADAPTER.process(req, BOT)


APP = web.Application(middlewares=[aiohttp_error_middleware])
APP.router.add_post("/api/messages", messages)

if __name__ == "__main__":
    try:
        web.run_app(APP, host="localhost", port=CONFIG.PORT)
    except Exception as error:
        raise error

Adaptateur de bot

L'adaptateur reçoit des activités du point de terminaison de messagerie, les transfère au gestionnaire de tour du bot et intercepte les erreurs ou exceptions que la logique du bot n'intercepte pas. L'adaptateur transfère également les activités de votre bot vers la chaîne de l'utilisateur.

L'adaptateur vous permet d'ajouter votre propre gestionnaire d'erreurs d'activation.

C#

Startup.cs

Le bot à utiliser est défini dans la méthode ConfigureServices.

// Create the Bot Framework Authentication to be used with the Bot Adapter.
services.AddSingleton<BotFrameworkAuthentication, ConfigurationBotFrameworkAuthentication>();

AdapterWithErrorHandler.cs

public class AdapterWithErrorHandler : CloudAdapter
{
    public AdapterWithErrorHandler(BotFrameworkAuthentication auth, ILogger<IBotFrameworkHttpAdapter> logger)
        : base(auth, logger)
    {
        OnTurnError = async (turnContext, exception) =>
        {
            // Log any leaked exception from the application.
            // NOTE: In production environment, you should consider logging this to
            // Azure Application Insights. Visit https://aka.ms/bottelemetry to see how
            // to add telemetry capture to your bot.
            logger.LogError(exception, $"[OnTurnError] unhandled error : {exception.Message}");

            // Send a message to the user
            await turnContext.SendActivityAsync("The bot encountered an error or bug.");
            await turnContext.SendActivityAsync("To continue to run this bot, please fix the bot source code.");

            // Send a trace activity, which will be displayed in the Bot Framework Emulator
            await turnContext.TraceActivityAsync("OnTurnError Trace", exception.Message, "https://www.botframework.com/schemas/error", "TurnError");
        };
    }
}

JavaScript

index.js

    //       application insights. See https://aka.ms/bottelemetry for telemetry
    //       configuration instructions.
    console.error(`\n [onTurnError] unhandled error: ${ error }`);

    // Send a trace activity, which will be displayed in Bot Framework Emulator
    await context.sendTraceActivity(
        'OnTurnError Trace',
        `${ error }`,
        'https://www.botframework.com/schemas/error',
        'TurnError'
    );

    // Send a message to the user
    await context.sendActivity('The bot encountered an error or bug.');
    await context.sendActivity('To continue to run this bot, please fix the bot source code.');
};

// Set the onTurnError for the singleton CloudAdapter.
adapter.onTurnError = onTurnErrorHandler;

// Create the main dialog.
const myBot = new EchoBot();

// Listen for incoming requests.
server.post('/api/messages', async (req, res) => {
    // Route received a request to adapter for processing
    await adapter.process(req, res, (context) => myBot.run(context));

Java

Application.java

Le bot à utiliser est défini dans la méthode getBotFrameworkAdapter.

/**
 * Returns a custom Adapter that provides error handling.
 *
 * @param configuration The Configuration object to use.
 * @return An error handling BotFrameworkHttpAdapter.
 */
@Override
public BotFrameworkHttpAdapter getBotFrameworkHttpAdaptor(Configuration configuration) {
    return new AdapterWithErrorHandler(configuration);
}

L'adaptateur avec gestionnaire d'erreurs est défini dans le code du kit de développement logiciel (SDK) Java, dans le package com.microsoft.bot.integration. Cette classe peut être examinée dans le code source du kit de développement logiciel (SDK) Java.

Python

app.py

from botbuilder.core import (
    TurnContext,
)
from botbuilder.core.integration import aiohttp_error_middleware
from botbuilder.integration.aiohttp import CloudAdapter, ConfigurationBotFrameworkAuthentication

# Create adapter.
# See https://aka.ms/about-bot-adapter to learn more about how bots work.
ADAPTER = CloudAdapter(ConfigurationBotFrameworkAuthentication(CONFIG))


# Catch-all for errors.
    # This check writes out errors to console log .vs. app insights.
    # NOTE: In production environment, you should consider logging this to Azure
    #       application insights.
    print(f"\n [on_turn_error] unhandled error: {error}", file=sys.stderr)
    traceback.print_exc()

    # Send a message to the user
    await context.send_activity("The bot encountered an error or bug.")
    await context.send_activity(
        "To continue to run this bot, please fix the bot source code."
    )
    # Send a trace activity if we're talking to the Bot Framework Emulator
    if context.activity.channel_id == "emulator":
        # Create a trace activity that contains the error object
        trace_activity = Activity(
            label="TurnError",
            name="on_turn_error Trace",
            timestamp=datetime.utcnow(),
            type=ActivityTypes.trace,
            value=f"{error}",
            value_type="https://www.botframework.com/schemas/error",
        )
        # Send a trace activity, which will be displayed in Bot Framework Emulator
        await context.send_activity(trace_activity)


ADAPTER.on_turn_error = on_error
# Create the Bot
BOT = EchoBot()

Logique du bot

Le bot echo utilise un gestionnaire d'activités et met en œuvre des gestionnaires pour les types d'activités qu'il reconnaît et réagit, dans le cas échéant, aux activités de mise à jour de conversation et de message.

• Une activité de mise à jour de conversation comprend des informations sur les personnes qui ont rejoint ou quitté la conversation. Pour les conversations hors groupe, le bot et l'utilisateur rejoignent la conversation au démarrage. Pour les conversations de groupe, une mise à jour de conversation est générée chaque fois qu'une personne rejoint ou quitte la conversation, qu'il s'agisse du bot ou d'un utilisateur.
• Une activité de message représente un message envoyé par l'utilisateur au bot.

Le bot écho accueille un utilisateur lorsqu'il rejoint la conversation et renvoie tous les messages qu'il envoie au bot.

C#

Startup.cs

Le bot à utiliser est défini dans la méthode ConfigureServices.

// Create the Bot Adapter with error handling enabled.
services.AddSingleton<IBotFrameworkHttpAdapter, AdapterWithErrorHandler>();

Bots\EchoBot.cs

public class EchoBot : ActivityHandler
{
    protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
    {
        var replyText = $"Echo: {turnContext.Activity.Text}";
        await turnContext.SendActivityAsync(MessageFactory.Text(replyText, replyText), cancellationToken);
    }

    protected override async Task OnMembersAddedAsync(IList<ChannelAccount> membersAdded, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
    {
        var welcomeText = "Hello and welcome!";
        foreach (var member in membersAdded)
        {
            if (member.Id != turnContext.Activity.Recipient.Id)
            {
                await turnContext.SendActivityAsync(MessageFactory.Text(welcomeText, welcomeText), cancellationToken);
            }
        }
    }
}

JavaScript

index.js

const { EchoBot } = require('./bot');

});

// Listen for Upgrade requests for Streaming.

bot.js

const { ActivityHandler, MessageFactory } = require('botbuilder');

class EchoBot extends ActivityHandler {
    constructor() {
        super();
        // See https://aka.ms/about-bot-activity-message to learn more about the message and other activity types.
        this.onMessage(async (context, next) => {
            const replyText = `Echo: ${ context.activity.text }`;
            await context.sendActivity(MessageFactory.text(replyText, replyText));
            // By calling next() you ensure that the next BotHandler is run.
            await next();
        });

        this.onMembersAdded(async (context, next) => {
            const membersAdded = context.activity.membersAdded;
            const welcomeText = 'Hello and welcome!';
            for (let cnt = 0; cnt < membersAdded.length; ++cnt) {
                if (membersAdded[cnt].id !== context.activity.recipient.id) {
                    await context.sendActivity(MessageFactory.text(welcomeText, welcomeText));
                }
            }
            // By calling next() you ensure that the next BotHandler is run.
            await next();
        });
    }
}

Java

Application.java

Le bot à utiliser est défini dans la méthode getBot.

/**
 * Returns the Bot for this application.
 *
 * <p>
 *     The @Component annotation could be used on the Bot class instead of this method
 *     with the @Bean annotation.
 * </p>
 *
 * @return The Bot implementation for this application.
 */
@Bean
public Bot getBot() {
    return new EchoBot();
}

EchoBot.cs

public class EchoBot extends ActivityHandler {

    @Override
    protected CompletableFuture<Void> onMessageActivity(TurnContext turnContext) {
        return turnContext.sendActivity(
            MessageFactory.text("Echo: " + turnContext.getActivity().getText())
        ).thenApply(sendResult -> null);
    }

    @Override
    protected CompletableFuture<Void> onMembersAdded(
        List<ChannelAccount> membersAdded,
        TurnContext turnContext
    ) {
        String welcomeText = "Hello and welcome!";
        return membersAdded.stream()
            .filter(
                member -> !StringUtils
                    .equals(member.getId(), turnContext.getActivity().getRecipient().getId())
            ).map(channel -> turnContext.sendActivity(MessageFactory.text(welcomeText, welcomeText, null)))
            .collect(CompletableFutures.toFutureList()).thenApply(resourceResponses -> null);
    }
}

Python

app.py

from botbuilder.core import (
    TurnContext,
)
from botbuilder.core.integration import aiohttp_error_middleware
from botbuilder.integration.aiohttp import CloudAdapter, ConfigurationBotFrameworkAuthentication

bots/bot.py

from botbuilder.core import ActivityHandler, MessageFactory, TurnContext
from botbuilder.schema import ChannelAccount


class EchoBot(ActivityHandler):
    async def on_members_added_activity(
        self, members_added: [ChannelAccount], turn_context: TurnContext
    ):
        for member in members_added:
            if member.id != turn_context.activity.recipient.id:
                await turn_context.send_activity("Hello and welcome!")

    async def on_message_activity(self, turn_context: TurnContext):
        return await turn_context.send_activity(
            MessageFactory.text(f"Echo: {turn_context.activity.text}")
        )

Étapes suivantes

• Découvrez comment envoyer et à recevoir des SMS
• Découvrez comment envoyer des messages de bienvenue aux utilisateurs