Sdílet prostřednictvím

Rychlý start: Přidání robota do chatovací aplikace

  • Článek

Naučte se vytvářet konverzační prostředí umělé inteligence v chatovací aplikaci pomocí kanálu zasílání zpráv chatu v Azure Communication Services, který je k dispozici ve službě Azure Bot Service. V tomto rychlém startu vytvoříte robota pomocí sady BotFramework SDK. Pak robota integrujete do chatovací aplikace, kterou vytvoříte pomocí sady SDK chatu komunikačních služeb.

V tomto rychlém startu se naučíte:

Požadavky

  • Účet Azure a aktivní předplatné. Vytvořte si bezplatný účet.
  • Visual Studio 2019 nebo novější
  • Nejnovější verze .NET Core. V tomto rychlém startu používáme .NET Core 3.1. Nezapomeňte nainstalovat verzi, která odpovídá vaší instanci sady Visual Studio, 32bitovou nebo 64bitovou.
  • Sada SDK služby Bot Framework

Vytvoření a nasazení robota v Azure

Pokud chcete chat azure Communication Services použít jako kanál ve službě Azure Bot Service, nejprve nasaďte robota. Pokud chcete nasadit robota, proveďte tyto kroky:

  • Vytvoření prostředku Azure Bot Service
  • Získání ID a hesla aplikace robota
  • Vytvoření webové aplikace pro uložení logiky robota
  • Vytvoření koncového bodu zasílání zpráv pro robota

Vytvoření prostředku Azure Bot Service

Nejprve pomocí webu Azure Portal vytvořte prostředek Azure Bot Service. Chatovací kanál komunikačních služeb podporuje roboty s jedním tenantem, roboty spravovaných identit a roboty s více tenanty. Pro účely tohoto rychlého startu použijeme robota s více tenanty .

Pokud chcete nastavit robota s jednou tenantem nebo spravovanou identitou, projděte si informace o identitě robota.

U robota spravované identity možná budete muset aktualizovat identitu služby Bot Service.

Získání ID aplikace a hesla aplikace robota

Dále získejte ID a heslo aplikace Microsoftu, které jsou přiřazené vašemu robotovi při nasazení. Tyto hodnoty použijete pro pozdější konfigurace.

Vytvoření webové aplikace pro uložení logiky robota

Pokud chcete vytvořit webovou aplikaci pro robota, můžete zkontrolovat ukázky Bot Builderu pro váš scénář nebo pomocí sady SDK bot Builderu vytvořit webovou aplikaci. Jednou z nejjednodušších ukázek je Echo Bot.

Služba Azure Bot Service obvykle očekává, že řadič webové aplikace robota zveřejní koncový bod ve formuláři /api/messages. Koncový bod zpracovává všechny zprávy odeslané robotovi.

Pokud chcete vytvořit aplikaci robota, vytvořte pomocí Azure CLI prostředek služby Aplikace Azure nebo vytvořte aplikaci na webu Azure Portal.

Vytvoření webové aplikace robota pomocí webu Azure Portal:

  1. Na portálu vyberte Vytvořit prostředek. Do vyhledávacího pole zadejte webovou aplikaci. Vyberte dlaždici webové aplikace .

    Screenshot that shows creating a web app resource in the Azure portal.

  2. V části Vytvořit webovou aplikaci vyberte nebo zadejte podrobnosti o aplikaci, včetně oblasti, do které chcete aplikaci nasadit.

    Screenshot that shows details to set to create a web app deployment.

  3. Výběrem možnosti Zkontrolovat a vytvořit ověřte nasazení a zkontrolujte podrobnosti o nasazení. Potom vyberte Vytvořit.

  4. Po vytvoření prostředku webové aplikace zkopírujte adresu URL názvu hostitele, která se zobrazí v podrobnostech o prostředku. Adresa URL je součástí koncového bodu, který vytvoříte pro webovou aplikaci.

    Screenshot that shows how to copy the web app endpoint URL.

Vytvoření koncového bodu zasílání zpráv pro robota

Dále v prostředku robota vytvořte koncový bod zasílání zpráv webové aplikace:

  1. Na webu Azure Portal přejděte k prostředku robota Azure. V nabídce prostředků vyberte Konfigurace.

  2. V části Konfigurace vložte do koncového bodu zasílání zpráv adresu URL názvu hostitele webové aplikace, kterou jste zkopírovali v předchozí části. Připojte adresu URL pomocí /api/messages.

  3. Zvolte Uložit.

Screenshot that shows how to create a bot messaging endpoint by using the web app hostname.

Nasazení webové aplikace

Posledním krokem k vytvoření robota je nasazení webové aplikace. Pro účely tohoto rychlého startu použijte ukázku Echo Bota. Funkce Echo Bot je omezená na ozvěnu vstupu uživatele. Tady je postup, jak ho nasadit do webové aplikace v Azure:

  1. Pomocí Gitu naklonujte toto úložiště GitHubu:

    git clone https://github.com/Microsoft/BotBuilder-Samples.git
cd BotBuilder-Samples

  2. V sadě Visual Studio otevřete projekt Echo Bot.

  3. V projektu sady Visual Studio otevřete soubor Appsettings.json . Vložte ID aplikace a heslo aplikace Microsoftu, které jste si zkopírovali dříve:

       {
     "MicrosoftAppId": "<App-registration-ID>",
     "MicrosoftAppPassword": "<App-password>"
   }

    Dále pomocí sady Visual Studio pro roboty v jazyce C# nasaďte robota.

    K nasazení robota Azure můžete použít také okno příkazového řádku.

  4. V sadě Visual Studio v Průzkumník řešení klikněte pravým tlačítkem na projekt EchoBot a vyberte Publikovat:

    Screenshot that shows publishing your web app from Visual Studio.

  5. Vyberte Nový a vytvořte nový profil publikování. Jako cíl vyberte Azure:

    Screenshot that shows how to select Azure as target in a new publishing profile.

    Pro konkrétní cíl vyberte Aplikace Azure Service:

    Screenshot that shows how to select Azure App Service as the specific target.

  6. V konfiguraci nasazení vyberte ve výsledcích webovou aplikaci, která se zobrazí po přihlášení ke svému účtu Azure. Pokud chcete profil dokončit, vyberte Dokončit a pak výběrem možnosti Publikovat spusťte nasazení.

    Screenshot that shows setting the deployment configuration with the web app name.

Získání prostředku Komunikační služby

Teď, když je robot vytvořený a nasazený, vytvořte prostředek komunikační služby, který se použije k nastavení kanálu Komunikační služby:

  1. Dokončete kroky pro vytvoření prostředku služby Communication Services.

  2. Vytvoření uživatele komunikační služby a vystavení přístupového tokenu uživatele Nezapomeňte nastavit obor chatu. Zkopírujte řetězec tokenu a řetězec ID uživatele.

Povolení kanálu chatu komunikačních služeb

Pokud máte prostředek Komunikační služby, můžete v prostředku robota nastavit kanál komunikační služby. V tomto procesu se pro robota vygeneruje ID uživatele.

  1. Na webu Azure Portal přejděte k prostředku robota Azure. V nabídce prostředků vyberte Kanály. V seznamu dostupných kanálů vyberte Azure Communications Services – Chat.

    Screenshot that shows opening the Communication Services Chat channel.

  2. Výběrem Připojení zobrazíte seznam prostředků komunikačních služeb, které jsou dostupné ve vašem předplatném.

    Screenshot that shows how to connect a Communication Service resource to the bot.

  3. V podokně Nový Připojení ion vyberte prostředek chatu Komunikační služby a pak vyberte Použít.

    Screenshot that shows how to save the selected Communication Service resource to create a new Communication Services user ID.

  4. Po ověření podrobností o prostředku se ID robota zobrazí ve sloupci ID služby Bot Azure Communication Services. ID robota můžete použít k reprezentaci robota ve vlákně chatu pomocí rozhraní API AddParticipant služby Communication Services. Jakmile robota přidáte do chatu jako účastníka, robot začne přijímat aktivity související s chatem a může reagovat ve vlákně chatu.

    Screenshot that shows the new Communication Services user ID assigned to the bot.

Vytvoření chatovací aplikace a přidání robota jako účastníka

Teď, když máte ID komunikační služby robota, můžete vytvořit chatovací vlákno s robotem jako účastníkem.

Vytvoření nové aplikace jazyka C#

  1. Spuštěním následujícího příkazu vytvořte aplikaci v jazyce C#:

    dotnet new console -o ChatQuickstart

  2. Změňte adresář na novou složku aplikace a pomocí dotnet build příkazu zkompilujte aplikaci:

    cd ChatQuickstart
dotnet build

Nainstalujte balíček .

Nainstalujte sadu SDK chatu komunikačních služeb pro .NET:

dotnet add package Azure.Communication.Chat

Vytvoření chatovacího klienta

K vytvoření chatovacího klienta použijte koncový bod komunikační služby a přístupový token uživatele, který jste vygenerovali dříve. CommunicationIdentityClient Pomocí třídy ze sady SDK identity vytvořte uživatele a zadejte token, který se má předat chatovacímu klientovi. Přístupové tokeny je možné vygenerovat na portálu pomocí následujících pokynů.

Zkopírujte následující kód a vložte ho do zdrojového souboru Program.cs :

using Azure;
using Azure.Communication;
using Azure.Communication.Chat;
using System;

namespace ChatQuickstart
{
    class Program
    {
        static async System.Threading.Tasks.Task Main(string[] args)
        {
            // Your unique Communication Services endpoint
            Uri endpoint = new Uri("https://<RESOURCE_NAME>.communication.azure.com");

            CommunicationTokenCredential communicationTokenCredential = new CommunicationTokenCredential(<Access_Token>);
            ChatClient chatClient = new ChatClient(endpoint, communicationTokenCredential);
        }
    }
}

Spuštění vlákna chatu s robotem

Použijte metodu createChatThread k chatClient vytvoření vlákna chatu. Nahraďte ID ID komunikační služby robota.

var chatParticipant = new ChatParticipant(identifier: new CommunicationUserIdentifier(id: "<BOT_ID>"))
{
    DisplayName = "BotDisplayName"
};
CreateChatThreadResult createChatThreadResult = await chatClient.CreateChatThreadAsync(topic: "Hello Bot!", participants: new[] { chatParticipant });
ChatThreadClient chatThreadClient = chatClient.GetChatThreadClient(threadId: createChatThreadResult.ChatThread.Id);
string threadId = chatThreadClient.Id;

Získání klienta vlákna chatu

Metoda GetChatThreadClient vrátí klienta vlákna pro vlákno, které již existuje:

string threadId = "<THREAD_ID>";
ChatThreadClient chatThreadClient = chatClient.GetChatThreadClient(threadId: threadId);

Odeslání zprávy do vlákna chatu

SendMessage Použití k odeslání zprávy do vlákna:

SendChatMessageOptions sendChatMessageOptions = new SendChatMessageOptions()
{
    Content = "Hello World",
    MessageType = ChatMessageType.Text
};

SendChatMessageResult sendChatMessageResult = await chatThreadClient.SendMessageAsync(sendChatMessageOptions);

string messageId = sendChatMessageResult.Id;

Příjem zpráv chatu z vlákna chatu

Chatové zprávy můžete získat dotazováním GetMessages metody na klientovi vlákna chatu v nastavených intervalech:

AsyncPageable<ChatMessage> allMessages = chatThreadClient.GetMessagesAsync();
await foreach (ChatMessage message in allMessages)
{
    Console.WriteLine($"{message.Id}:{message.Content.Message}");
}

Zkontrolujte seznam zpráv pro odpověď robota na odpověď na "Hello World".

K přihlášení k odběru oznámení příchozích zpráv můžete použít JavaScript nebo mobilní sady SDK Azure:

// Open notifications channel
await chatClient.startRealtimeNotifications();
// Subscribe to new notifications
chatClient.on("chatMessageReceived", (e) => {
  console.log("Notification chatMessageReceived!");
  // Your code here
});

Vyčištění vlákna chatu

Po dokončení používání vlákna chatu odstraňte vlákno:

chatClient.DeleteChatThread(threadId);

Nasazení chatovací aplikace v C#

Nasazení chatovací aplikace:

  1. V sadě Visual Studio otevřete projekt chatu.

  2. Klikněte pravým tlačítkem na projekt ChatQuickstart a vyberte Publikovat:

    Screenshot that shows deploying the chat application to Azure from Visual Studio.

  3. Jakmile řešení publikujete, spusťte ho a zkontrolujte, jestli echobot ozve zprávu uživatele na příkazovém řádku. Teď, když máte řešení, můžete pokračovat v hraní s různými aktivitami, které jsou potřeba pro obchodní scénáře, pro které potřebujete vyřešit.

Další možnosti, které můžete dělat s robotem

Robot může obdržet více než zprávu ve formátu prostého textu od uživatele v kanálu chatu služby Communications Services. Mezi aktivity, které robot může od uživatele přijímat, patří:

  • Aktualizace konverzací
  • Aktualizace zprávy
  • Odstranění zprávy
  • Indikátor psaní
  • Aktivita události
  • Různé přílohy, včetně adaptivních karet
  • Data kanálu robota

Další části ukazují některé ukázky, které ilustrují tyto funkce.

Odeslání uvítací zprávy při přidání nového uživatele do vlákna

Aktuální logika Echo Bot přijímá vstup od uživatele a vrací ho zpět. Pokud chcete přidat další logiku, například reagování na událost Komunikační služby přidanou účastníkem, zkopírujte následující kód a vložte ho do zdrojového souboru EchoBot.cs :

using System.Threading;
using System.Threading.Tasks;
using Microsoft.Bot.Builder;
using Microsoft.Bot.Schema;

namespace Microsoft.BotBuilderSamples.Bots
{
    public class EchoBot : ActivityHandler
    {
        public override async Task OnTurnAsync(ITurnContext turnContext, CancellationToken cancellationToken)
        {
            if (turnContext.Activity.Type == ActivityTypes.Message)
            {
                var replyText = $"Echo: {turnContext.Activity.Text}";
                await turnContext.SendActivityAsync(MessageFactory.Text(replyText, replyText), cancellationToken);
            }
            else if (ActivityTypes.ConversationUpdate.Equals(turnContext.Activity.Type))
            {
                if (turnContext.Activity.MembersAdded != null)
                {
                    foreach (var member in turnContext.Activity.MembersAdded)
                    {
                        if (member.Id != turnContext.Activity.Recipient.Id)
                        {
                            await turnContext.SendActivityAsync(MessageFactory.Text("Hello and welcome to chat with EchoBot!"), cancellationToken);
                        }
                    }
                }
            }
        }
    }
}

Odeslání adaptivní karty

Poznámka:

Adaptivní karty jsou podporovány pouze v případech použití služeb Azure Communication Services, kdy všichni účastníci chatu jsou uživatelé služeb Azure Communication Services, a ne pro případy použití interoprability Teams.

Pokud chcete zvýšit zapojení a efektivitu, můžete do vlákna chatu odeslat adaptivní kartu. Adaptivní karta také pomáhá komunikovat s uživateli různými způsoby. Adaptivní kartu můžete odeslat z robota tak, že kartu přidáte jako přílohu aktivity robota.

Tady je příklad odeslání adaptivní karty:

var reply = Activity.CreateMessageActivity();
var adaptiveCard = new Attachment()
{
    ContentType = "application/vnd.microsoft.card.adaptive",
    Content = {/* the adaptive card */}
};
reply.Attachments.Add(adaptiveCard);   
await turnContext.SendActivityAsync(reply, cancellationToken);

Získejte ukázkové datové části pro adaptivní karty v ukázkách a šablonách.

Pro chatovacího uživatele přidá kanál chatu komunikační služby do metadat zprávy pole, které označuje, že zpráva obsahuje přílohu. V metadatech microsoft.azure.communication.chat.bot.contenttype je vlastnost nastavena na azurebotservice.adaptivecard.

Tady je příklad zprávy chatu s připojenou adaptivní kartou:

{
    "content": "{\"attachments\":[{\"contentType\":\"application/vnd.microsoft.card.adaptive\",\"content\":{/* the adaptive card */}}]}",
    "senderDisplayName": "BotDisplayName",
    "metadata": {
    "microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.adaptivecard"
    },
 "messageType": "Text"
}

Odeslání zprávy od uživatele do robota

Základní textovou zprávu můžete odeslat uživateli do robota stejným způsobem, jakým posíláte textovou zprávu jinému uživateli.

Když ale odešlete zprávu s přílohou od uživatele do robota, přidejte tento příznak do metadat chatu služby Communication Services:

"microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.adaptivecard"

Pokud chcete odeslat aktivitu události od uživatele do robota, přidejte tento příznak do metadat chatu služby Communication Services:

"microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.event"

Následující části ukazují ukázkové formáty chatovacích zpráv od uživatele k robotovi.

Jednoduchá textová zpráva

{
    "content":"Simple text message",
    "senderDisplayName":"Acs-Dev-Bot",
    "metadata":{
        "text":"random text",
        "key1":"value1",
        "key2":"{\r\n  \"subkey1\": \"subValue1\"\r\n
        "}, 
    "messageType": "Text"
}

Zpráva s přílohou

{
    "content": "{
                        \"text\":\"sample text\", 
                        \"attachments\": [{
                            \"contentType\":\"application/vnd.microsoft.card.adaptive\",
                            \"content\": { \"*adaptive card payload*\" }
                        }]
        }",
    "senderDisplayName": "Acs-Dev-Bot",
    "metadata": {
        "microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.adaptivecard",
        "text": "random text",
        "key1": "value1",
        "key2": "{\r\n  \"subkey1\": \"subValue1\"\r\n}"
    },
        "messageType": "Text"
}

Zpráva s aktivitou události

Datová část události obsahuje všechna pole JSON v obsahu zprávy s výjimkou Name. Pole Name obsahuje název události.

V následujícím příkladu se do robota odešle název endOfConversation události s datovou částí "{field1":"value1", "field2": { "nestedField":"nestedValue" }} :

{
    "content":"{
                   \"name\":\"endOfConversation\",
                   \"field1\":\"value1\",
                   \"field2\": {  
                       \"nestedField\":\"nestedValue\"
                    }
               }",
    "senderDisplayName":"Acs-Dev-Bot",
    "metadata":{  
                   "microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.event",
                   "text":"random text",
                   "key1":"value1",
                   "key2":"{\r\n  \"subkey1\": \"subValue1\"\r\n}"
               },
    "messageType": "Text"
}

Pole microsoft.azure.communication.chat.bot.contenttype metadat se vyžaduje jenom ve zprávě odeslané od uživatele do robota.

Pole podporovaných aktivit robota

Následující části popisují podporovaná pole aktivit robota pro toky mezi uživateli a toky mezi uživateli.

Tok mezi roboty a uživatelem

Pro toky mezi uživateli jsou podporována následující pole aktivit robota.

Aktivity

  • Message
  • Psaní

Pole aktivit zpráv

  • Text
  • Attachments
  • AttachmentLayout
  • SuggestedActions
  • From.Name (Převedeno na Komunikační služby SenderDisplayName.)
  • ChannelData (Převedeno na komunikační služby Chat Metadata. Pokud jsou nějaké ChannelData hodnoty mapování objekty, serializují se ve formátu JSON a odesílají se jako řetězec.)

Tok uživatele k robotovi

Tato pole aktivit robota jsou podporovaná pro toky mezi uživateli.

Aktivity a pole

  • Message

    • Id (ID zprávy chatu služby Communication Services)
    • TimeStamp
    • Text
    • Attachments

  • Aktualizace konverzací

    • MembersAdded
    • MembersRemoved
    • TopicName

  • Aktualizace zprávy

    • Id (Aktualizované ID chatové zprávy komunikační služby)
    • Text
    • Attachments

  • Odstranění zprávy

    • Id (ID zprávy chatu odstraněné komunikační služby)

  • Událost

    • Name
    • Value

  • Psaní

Další běžná pole

  • Recipient.Id a Recipient.Name (ID uživatele chatu komunikačních služeb a zobrazované jméno)
  • From.Id a From.Name (ID uživatele chatu komunikačních služeb a zobrazované jméno)
  • Conversation.Id (ID vlákna chatu komunikačních služeb)
  • ChannelId (Chat komunikačních služeb, pokud je prázdný)
  • ChannelData (Metadata zpráv chatu služby Communication Services)

Vzory předání robota

Někdy robot nerozumí otázce nebo nemůže odpovědět na otázku. Zákazník se může v chatu zeptat, aby byl připojený k lidskému agentu. V těchto scénářích musí být vlákno chatu předáno z robota do lidského agenta. Aplikaci můžete navrhnout tak, aby přecháděla konverzaci z robota na člověka.

Zpracování komunikace mezi roboty

V některých případech použití je potřeba přidat dva roboty do stejného chatovacího vlákna, aby mohli poskytovat různé služby. V tomto scénáři možná budete muset zajistit, aby robot neodesílal automatizované odpovědi do zpráv jiného robota. Pokud se roboti nezpracují správně, může automatizovaná interakce mezi sebou vést k nekonečné smyčce zpráv.

Identitu uživatele komunikační služby odesílatele zprávy můžete ověřit ve vlastnosti aktivity From.Id . Zkontrolujte, jestli patří jinému robotovi. Pak proveďte požadovanou akci, která zabrání toku komunikace mezi roboty. Pokud tento typ scénáře vede k vysokému počtu volání, kanál chatu komunikační služby omezí požadavky a robot nemůže odesílat a přijímat zprávy.

Přečtěte si další informace o omezeních limitů.

Odstranění potíží

Následující části popisují způsoby řešení běžných scénářů.

Kanál chatu nejde přidat.

Na portálu pro vývojáře Microsoft Bot Framework přejděte do> části Zasílání zpráv konfiguračního robota a ověřte, že je koncový bod správně nastavený.

Robot při odpovídání na zprávu dostane výjimku zakázáno.

Ověřte, že id a heslo aplikace Microsoftu robota jsou správně uložené v konfiguračním souboru robota, který nahrajete do webové aplikace.

Robota nejde přidat jako účastníka

Ověřte, že se ID komunikační služby robota používá správně, když se odešle požadavek na přidání robota do vlákna chatu.

Další kroky

Vyzkoušejte ukázkovou aplikaci chatbota chatbota pro chat 1:1 mezi uživatelem chatu a robotem prostřednictvím komponenty Uživatelského rozhraní BotFramework WebChat.