Omówienie struktury bota echa

DOTYCZY: ZESTAW SDK w wersji 4

Szablony i przykłady platformy Bot Framework są napisane dla ASP.NET (C#), restify (JavaScript) i aiohttp (Python). Jednak funkcje usługi internetowej nie są częścią zestawu Sdk platformy Bot Framework, ale część platformy internetowej, której chcesz użyć.

Wszystkie aplikacje botów współdzielą niektóre typowe funkcje.

Funkcja	opis
Aprowizowanie zasobów	Bot jako aplikacja internetowa musi utworzyć usługę internetową, kartę bota i obiekt bota.
Punkt końcowy obsługi komunikatów	Aplikacja internetowa musi zaimplementować punkt końcowy obsługi komunikatów, na którym będą odbierać działania i przekazywać działania do karty bota.
Karta bota	Karta odbiera działania z punktu końcowego obsługi komunikatów, przekazuje je do procedury obsługi kolei bota i przechwytuje błędy lub wyjątki, których logika bota nie przechwytuje.
Obiekt bota	Obiekt bota obsługuje rozumowanie lub logikę bota dla kolei.

Bot echo można utworzyć na podstawie szablonów zgodnie z opisem w artykule Tworzenie bota lub skopiować projekt echo bota z repozytorium Microsoft/BotBuilder-Samples .

Szablony języka C# i JavaScript mają wbudowaną obsługę połączeń przesyłanych strumieniowo. Jednak ten artykuł nie obejmuje funkcji przesyłania strumieniowego. Aby uzyskać informacje na temat połączeń przesyłania strumieniowego, zobacz, jak połączyć bota z usługą Direct Line Speech.

Uwaga

Zestawy SDK języka JavaScript, C# i Python platformy Bot Framework będą nadal obsługiwane, jednak zestaw SDK języka Java jest wycofywany z ostatecznym długoterminowym wsparciem kończącym się w listopadzie 2023 r.

Istniejące boty utworzone za pomocą zestawu JAVA SDK będą nadal działać.

W przypadku tworzenia nowych botów rozważ użycie programu Microsoft Copilot Studio i przeczytaj o wyborze odpowiedniego rozwiązania copilot.

Aby uzyskać więcej informacji, zobacz Przyszłość tworzenia botów.

Wymagania wstępne

• Znajomość podstaw bota.
• Kopia przykładu echo bota w języku C#, JavaScript, Java lub Python.

Szablony botów

Bot to aplikacja internetowa, a szablony są udostępniane dla każdego języka.

C#

Platforma Bot Framework zawiera zarówno szablony VSIX, jak i .NET.

Szablony generują ASP.NET aplikację internetową MVC Core . Jeśli przyjrzysz się podstawom ASP.NET, zobaczysz podobny kod w plikach, takich jak Program.cs i Startup.cs. Te pliki są wymagane dla wszystkich aplikacji internetowych i nie są specyficzne dla bota.

Uwaga

Szablony można zainstalować z poziomu programu Visual Studio.

1. W menu wybierz pozycję Rozszerzenia, a następnie zarządzaj rozszerzeniami.
2. W oknie dialogowym Zarządzanie rozszerzeniami wyszukaj i zainstaluj szablony zestawu Bot Framework w wersji 4 zestawu SDK dla programu Visual Studio.

Aby uzyskać informacje na temat wdrażania botów platformy .NET na platformie Azure, zobacz jak aprowizować i publikować bota.

Plik appsettings.json określa informacje o konfiguracji bota, takie jak jego identyfikator aplikacji i hasło. Jeśli korzystasz z niektórych technologii lub korzystasz z tego bota w środowisku produkcyjnym, musisz dodać określone klucze lub adres URL do tej konfiguracji. Jednak w przypadku tego bota echo nie musisz teraz wykonywać żadnych czynności; Identyfikator aplikacji i hasło mogą być obecnie niezdefiniowane.

Plik EchoBot.csproj określa zależności i skojarzone z nimi wersje bota. Wszystko to jest skonfigurowane przez szablon i system. Dodatkowe zależności można zainstalować za pomocą menedżera pakietów NuGet lub dotnet add package polecenia.

JavaScript

Generator Yeoman tworzy typ aplikacji internetowej restify . Jeśli zapoznasz się z przewodnikiem Szybki start restify w dokumentacji, zobaczysz aplikację podobną do wygenerowanego pliku index.js . Niektóre pliki kluczy wygenerowane przez szablon zostały opisane w tym artykule. Kod w niektórych plikach nie zostanie skopiowany, ale zobaczysz go podczas uruchamiania bota i możesz odwołać się do przykładu echobota Node.js.

Plik package.json określa zależności i skojarzone z nimi wersje bota. Wszystko to jest skonfigurowane przez szablon i system. Dodatkowe zależności można zainstalować przy użyciu polecenia npm install.

Plik env określa informacje o konfiguracji bota, takie jak numer portu, identyfikator aplikacji i hasło. Jeśli korzystasz z niektórych technologii lub korzystasz z tego bota w środowisku produkcyjnym, musisz dodać określone klucze lub adres URL do tej konfiguracji. Jednak w przypadku tego bota echo nie musisz teraz wykonywać żadnych czynności; Identyfikator aplikacji i hasło mogą być obecnie niezdefiniowane.

Aby użyć pliku konfiguracji env , bot wymaga dotenv pakietu z narzędzia npm. Jest to już uwzględnione jako zależność w pliku package.json .

Java

Generator Yeoman tworzy aplikację internetową opartą na platformie Spring z plikiem kompilacji przy użyciu narzędzia Maven.

Plik pom.xml maven określa zależności i skojarzone z nimi wersje bota. Wszystko to jest skonfigurowane przez szablon i system. Dodatkowe zależności można zainstalować, dodając wpisy do pliku pom.xml.

Plik application.properties określa informacje o konfiguracji bota, takie jak numer portu, identyfikator aplikacji i hasło. Jeśli korzystasz z niektórych technologii lub korzystasz z tego bota w środowisku produkcyjnym, musisz dodać określone klucze lub adres URL do tej konfiguracji. Jednak w przypadku tego bota echo nie musisz teraz wykonywać żadnych czynności; Identyfikator aplikacji i hasło mogą być obecnie niezdefiniowane.

Python

Szablony cookiecutter języka Python tworzą aplikację internetową aiohttp .

Plik requirements.txt określa zależności i skojarzone z nimi wersje bota. To wszystko jest skonfigurowane przez szablon i system. Dodatkowe zależności można zainstalować przy użyciu polecenia pip install -r requirements.txt

Plik config.py określa informacje o konfiguracji bota, takie jak numer portu, identyfikator aplikacji i hasło. Jeśli korzystasz z niektórych technologii lub korzystasz z tego bota w środowisku produkcyjnym, musisz dodać określone klucze lub adres URL do tej konfiguracji. Jednak w przypadku tego bota echo nie musisz teraz wykonywać żadnych czynności; Identyfikator aplikacji i hasło mogą być obecnie niezdefiniowane.

Aprowizowanie zasobów

Aby działać jako aplikacja internetowa, bot musi utworzyć usługę internetową, kartę bota i obiekt bota.

W przypadku większości botów należy również utworzyć obiekty zarządzania warstwą magazynu i pamięcią dla bota. Jednak bot echo nie musi utrwalać stanu między zakrętami. W przypadku niektórych botów może być konieczne utworzenie innych obiektów, których będzie wymagał obiekt bota lub adapter.

C#

W ASP.NET rejestrujesz obiekty i metody tworzenia obiektów w pliku Startup.cs . Metoda ConfigureServices ładuje połączone usługi i ich klucze (jeśli istnieją) z appsettings.json, nawiązuje połączenie i tak dalej. W tym miejscu adapter i bot są definiowane jako dostępne za pośrednictwem wstrzykiwania zależności. Configure Następnie metoda kończy konfigurację aplikacji.

ConfigureServices i Configure są wywoływane przez środowisko uruchomieniowe podczas uruchamiania aplikacji.

JavaScript

W funkcji restify skonfigurujesz usługę internetową i obiekty, których potrzebuje w pliku index.js . Usługa, adapter i bot są omówione oddzielnie w poniższych sekcjach.

Java

Na platformie Spring skonfigurujesz usługę internetową i obiekty, których potrzebuje w pliku application.java . Application.java zawiera komentarze, które oznaczają różne składniki i klasy struktury używane przez aplikację bota. Usługa, adapter i bot są omówione oddzielnie w poniższych sekcjach.

Python

W aiohttp skonfigurujesz usługę internetową i obiekty, których potrzebuje w pliku app.py . Usługa, adapter i bot są omówione oddzielnie w poniższych sekcjach.

Punkt końcowy obsługi komunikatów

Szablon implementuje usługę internetową z punktem końcowym obsługi komunikatów. Po odebraniu żądania usługa wyodrębnia nagłówek uwierzytelniania i ładunek żądania i przekazuje je do karty.

Zestawy SDK języka C# i JavaScript obsługują połączenia przesyłane strumieniowo. Chociaż bot echo nie korzysta z żadnych funkcji przesyłania strumieniowego, karta w szablonach języka C# i JavaScript jest przeznaczona do ich obsługi.

Każde żądanie przychodzące reprezentuje początek nowego kolei.

C#

Kontrolery\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

Adapter bota

Karta odbiera działania z punktu końcowego obsługi komunikatów, przekazuje je do procedury obsługi kolei bota i przechwytuje błędy lub wyjątki, których logika bota nie przechwytuje. Karta przekazuje również działania z bota do kanału użytkownika.

Karta umożliwia dodanie własnego programu obsługi błędów przy włączaniu .

C#

Startup.cs

Karta do użycia jest zdefiniowana w metodzie 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

Karta do użycia jest zdefiniowana w metodzie 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);
}

Program AdapterWithErrorHandler jest zdefiniowany w kodzie zestawu JAVA SDK w pakiecie com.microsoft.bot.integration. Tę klasę można przejrzeć w kodzie źródłowym zestawu JAVA SDK.

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()

Logika bota

Bot echo używa programu obsługi działań i implementuje programy obsługi dla typów działań, które rozpoznaje i reaguje, w tym przypadku aktualizacja konwersacji i działania komunikatów .

• Działanie aktualizacji konwersacji zawiera informacje o tym, kto dołączył lub opuścił konwersację. W przypadku konwersacji innych niż grupy bot i użytkownik dołączają do konwersacji po rozpoczęciu. W przypadku konwersacji grupowych aktualizacja konwersacji jest generowana za każdym razem, gdy ktoś dołącza lub opuszcza konwersację, niezależnie od tego, czy jest to bot, czy użytkownik.
• Działanie komunikatu reprezentuje komunikat, który użytkownik wysyła do bota.

Bot echo wita użytkownika podczas dołączania do konwersacji i powtarza z powrotem wszystkie wiadomości wysyłane do bota.

C#

Startup.cs

Bot do użycia jest zdefiniowany w metodzie ConfigureServices .

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

Boty\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

Bot do użycia jest zdefiniowany w metodzie 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

boty/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}")
        )

Następne kroki

• Dowiedz się, jak wysyłać i odbierać wiadomości SMS
• Dowiedz się, jak wysyłać wiadomości powitalne do użytkowników