Szybki start: dodawanie bota do aplikacji do czatu

  • Artykuł

Dowiedz się, jak tworzyć konwersacyjne środowiska sztucznej inteligencji w aplikacji do czatu przy użyciu kanału obsługi komunikatów czatu usług Azure Communication Services, który jest dostępny w usłudze Azure Bot Service. W tym przewodniku Szybki start utworzysz bota przy użyciu zestawu BotFramework SDK. Następnie zintegrujesz bota z aplikacją czatu utworzoną przy użyciu zestawu SDK czatu usług komunikacyjnych.

W tym przewodniku Szybki start zawarto informacje na temat wykonywania następujących czynności:

Wymagania wstępne

Tworzenie i wdrażanie bota na platformie Azure

Aby użyć czatu usług Azure Communication Services jako kanału w usłudze Azure Bot Service, najpierw wdróż bota. Aby wdrożyć bota, wykonaj następujące kroki:

  • Tworzenie zasobu usługi Azure Bot Service
  • Uzyskiwanie identyfikatora i hasła aplikacji bota
  • Tworzenie aplikacji internetowej do przechowywania logiki bota
  • Tworzenie punktu końcowego obsługi komunikatów dla bota

Tworzenie zasobu usługi Azure Bot Service

Najpierw użyj witryny Azure Portal, aby utworzyć zasób usługi Azure Bot Service. Kanał czatu usług komunikacyjnych obsługuje boty z jedną dzierżawą, boty tożsamości zarządzanej i boty z wieloma dzierżawami. Na potrzeby tego przewodnika Szybki start użyjemy bota z wieloma dzierżawami .

Aby skonfigurować bota tożsamości z jedną dzierżawą lub tożsamością zarządzaną, zapoznaj się z informacjami o tożsamości bota.

W przypadku bota tożsamości zarządzanej może być konieczne zaktualizowanie tożsamości usługi bota.

Pobieranie identyfikatora aplikacji i hasła aplikacji bota

Następnie pobierz identyfikator aplikacji i hasło firmy Microsoft przypisane do bota po jego wdrożeniu. Te wartości są używane do późniejszej konfiguracji.

Tworzenie aplikacji internetowej do przechowywania logiki bota

Aby utworzyć aplikację internetową dla bota, możesz skorygować przykłady narzędzia Bot Builder dla danego scenariusza lub użyć zestawu SDK bot builder do utworzenia aplikacji internetowej. Jednym z najprostszych przykładów jest Echo Bot.

Usługa Azure Bot Service zwykle oczekuje, że kontroler aplikacji internetowej bota uwidoczni punkt końcowy w formularzu /api/messages. Punkt końcowy obsługuje wszystkie komunikaty wysyłane do bota.

Aby utworzyć aplikację bota, użyj interfejsu wiersza polecenia platformy Azure, aby utworzyć zasób usługi aplikacja systemu Azure lub utworzyć aplikację w witrynie Azure Portal.

Aby utworzyć aplikację internetową bota przy użyciu witryny Azure Portal:

  1. W portalu wybierz pozycję Utwórz zasób. W polu wyszukiwania wprowadź ciąg aplikacja internetowa. Wybierz kafelek Aplikacja internetowa.

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

  2. W obszarze Tworzenie aplikacji internetowej wybierz lub wprowadź szczegóły aplikacji, w tym region, w którym chcesz wdrożyć aplikację.

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

  3. Wybierz pozycję Przejrzyj i utwórz , aby zweryfikować wdrożenie i przejrzeć szczegóły wdrożenia. Następnie wybierz przycisk Utwórz.

  4. Po utworzeniu zasobu aplikacji internetowej skopiuj adres URL nazwy hosta wyświetlany w szczegółach zasobu. Adres URL jest częścią punktu końcowego utworzonego dla aplikacji internetowej.

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

Tworzenie punktu końcowego obsługi komunikatów dla bota

Następnie w zasobie bota utwórz punkt końcowy obsługi komunikatów aplikacji internetowej:

  1. W witrynie Azure Portal przejdź do zasobu usługi Azure Bot. W menu zasobów wybierz pozycję Konfiguracja.

  2. W obszarze Konfiguracja w polu Punkt końcowy obsługi komunikatów wklej adres URL nazwy hosta aplikacji internetowej skopiowanej w poprzedniej sekcji. Dołącz adres URL za pomocą /api/messagespolecenia .

  3. Wybierz pozycję Zapisz.

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

Wdrażanie aplikacji internetowej

Ostatnim krokiem tworzenia bota jest wdrożenie aplikacji internetowej. W tym przewodniku Szybki start użyj przykładu Echo Bot. Funkcja Echo Bot jest ograniczona do echa danych wejściowych użytkownika. Poniżej przedstawiono sposób wdrażania jej w aplikacji internetowej na platformie Azure:

  1. Użyj narzędzia Git, aby sklonować to repozytorium GitHub:

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

  2. W programie Visual Studio otwórz projekt Echo Bot.

  3. W projekcie programu Visual Studio otwórz plik Appsettings.json . Wklej skopiowany wcześniej identyfikator aplikacji i hasło aplikacji firmy Microsoft:

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

    Następnie użyj programu Visual Studio dla botów języka C#, aby wdrożyć bota.

    Do wdrożenia bota platformy Azure można również użyć okna wiersza polecenia.

  4. W programie Visual Studio w Eksplorator rozwiązań kliknij prawym przyciskiem myszy projekt EchoBot i wybierz polecenie Publikuj:

    Screenshot that shows publishing your web app from Visual Studio.

  5. Wybierz pozycję Nowy , aby utworzyć nowy profil publikowania. W polu Cel wybierz pozycję Azure:

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

    Dla określonego miejsca docelowego wybierz pozycję aplikacja systemu Azure Service:

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

  6. W konfiguracji wdrożenia wybierz aplikację internetową w wynikach wyświetlanych po zalogowaniu się na koncie platformy Azure. Aby ukończyć profil, wybierz pozycję Zakończ, a następnie wybierz pozycję Publikuj , aby rozpocząć wdrażanie.

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

Pobieranie zasobu usług komunikacyjnych

Teraz, po utworzeniu i wdrożeniu bota, utwórz zasób usług komunikacyjnych do użycia w celu skonfigurowania kanału usług komunikacyjnych:

  1. Wykonaj kroki tworzenia zasobu usług komunikacyjnych.

  2. Tworzenie użytkownika usług Communication Services i wystawianie tokenu dostępu użytkownika. Pamiętaj, aby ustawić zakres czatu. Skopiuj ciąg tokenu i ciąg identyfikatora użytkownika.

Włączanie kanału czatu usług komunikacyjnych

Jeśli masz zasób usług komunikacyjnych, możesz skonfigurować kanał usług komunikacyjnych w zasobie bota. W tym procesie jest generowany identyfikator użytkownika dla bota.

  1. W witrynie Azure Portal przejdź do zasobu usługi Azure Bot. W menu zasobów wybierz pozycję Kanały. Na liście dostępnych kanałów wybierz pozycję Azure Communications Services — Czat.

    Screenshot that shows opening the Communication Services Chat channel.

  2. Wybierz Połączenie, aby wyświetlić listę zasobów usług komunikacyjnych, które są dostępne w ramach subskrypcji.

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

  3. W okienku Nowa Połączenie ion wybierz zasób czatu usług komunikacyjnych, a następnie wybierz pozycję Zastosuj.

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

  4. Po zweryfikowaniu szczegółów zasobu identyfikator bota jest wyświetlany w kolumnie Identyfikator usług Bot Azure Communication Services. Identyfikator bota służy do reprezentowania bota w wątku czatu przy użyciu interfejsu API AddParticipant czatu usług komunikacyjnych. Po dodaniu bota do czatu jako uczestnik bot zaczyna otrzymywać działania związane z czatem i może on odpowiedzieć w wątku czatu.

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

Tworzenie aplikacji do czatu i dodawanie bota jako uczestnika

Teraz, gdy masz identyfikator usług komunikacyjnych bota, możesz utworzyć wątek czatu z botem jako uczestnik.

Tworzenie nowej aplikacji w języku C#

  1. Uruchom następujące polecenie, aby utworzyć aplikację w języku C#:

    dotnet new console -o ChatQuickstart

  2. Zmień katalog na nowy folder aplikacji i użyj dotnet build polecenia , aby skompilować aplikację:

    cd ChatQuickstart
dotnet build

Instalowanie pakietu

Zainstaluj zestaw SDK czatu usług komunikacyjnych dla platformy .NET:

dotnet add package Azure.Communication.Chat

Tworzenie klienta czatu

Aby utworzyć klienta czatu, użyj punktu końcowego usług Komunikacyjnych i wygenerowanego wcześniej tokenu dostępu użytkownika. CommunicationIdentityClient Użyj klasy z zestawu Identity SDK, aby utworzyć użytkownika i wydać token do przekazania do klienta czatu. Tokeny dostępu można wygenerować w portalu, korzystając z poniższych instrukcji.

Skopiuj następujący kod i wklej go w pliku źródłowym 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);
        }
    }
}

Rozpoczynanie wątku czatu za pomocą bota

Użyj metody w poleceniu createChatThreadchatClient , aby utworzyć wątek czatu. Zastąp identyfikator identyfikatorem usług komunikacyjnych bota.

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;

Uzyskiwanie klienta wątku czatu

Metoda GetChatThreadClient zwraca klienta wątku dla wątku, który już istnieje:

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

Wysyłanie wiadomości do wątku czatu

Aby użyć SendMessage polecenia , aby wysłać wiadomość do wątku:

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

SendChatMessageResult sendChatMessageResult = await chatThreadClient.SendMessageAsync(sendChatMessageOptions);

string messageId = sendChatMessageResult.Id;

Odbieranie wiadomości czatu z wątku czatu

Wiadomości czatu można uzyskać, sondując metodę GetMessages na kliencie wątku czatu w ustalonych odstępach czasu:

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

Sprawdź listę komunikatów dla odpowiedzi echa bota na "Hello World".

Możesz użyć języka JavaScript lub zestawów SDK dla urządzeń przenośnych platformy Azure, aby subskrybować przychodzące powiadomienia o wiadomościach:

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

Czyszczenie wątku czatu

Po zakończeniu korzystania z wątku czatu usuń wątek:

chatClient.DeleteChatThread(threadId);

Wdrażanie aplikacji do czatu w języku C#

Aby wdrożyć aplikację czatu:

  1. W programie Visual Studio otwórz projekt czatu.

  2. Kliknij prawym przyciskiem myszy projekt ChatQuickstart i wybierz pozycję Publikuj:

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

  3. Po opublikowaniu rozwiązania uruchom je i sprawdź, czy echobot wysyła komunikat użytkownika w wierszu polecenia. Teraz, gdy masz już rozwiązanie, możesz przejść do różnych działań, które są potrzebne w scenariuszach biznesowych, które należy rozwiązać.

Więcej rzeczy, które można wykonać za pomocą bota

Bot może odbierać więcej niż wiadomość w postaci zwykłego tekstu od użytkownika w kanale czatu usług komunikacyjnych. Niektóre działania, które bot może otrzymać od użytkownika, obejmują:

  • Aktualizacja konwersacji
  • Aktualizacja komunikatów
  • Usuwanie wiadomości
  • Wskaźnik wpisywania
  • Działanie zdarzenia
  • Różne załączniki, w tym karty adaptacyjne
  • Dane kanału bota

W następnych sekcjach przedstawiono kilka przykładów ilustrujących te funkcje.

Wyślij wiadomość powitalną po dodaniu nowego użytkownika do wątku

Bieżąca logika echo bota akceptuje dane wejściowe od użytkownika i powtarza je z powrotem. Jeśli chcesz dodać więcej logiki, na przykład odpowiadanie na zdarzenie usług Communication Services dodanych przez uczestnika, skopiuj następujący kod i wklej go w pliku źródłowym 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);
                        }
                    }
                }
            }
        }
    }
}

Wysyłanie karty adaptacyjnej

Uwaga

Karty adaptacyjne są obsługiwane tylko w przypadku użycia usług Azure Communication Services, w których wszyscy uczestnicy czatu są użytkownikami usług Azure Communication Services, a nie w przypadku przypadków użycia międzyoperacyjnego usługi Teams.

Możesz wysłać kartę adaptacyjną do wątku czatu, aby zwiększyć zaangażowanie i wydajność. Karta adaptacyjna pomaga również komunikować się z użytkownikami na różne sposoby. Kartę adaptacyjną można wysłać z bota, dodając kartę jako załącznik działania bota.

Oto przykład wysyłania karty adaptacyjnej:

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

Pobierz przykładowe ładunki dla kart adaptacyjnych na stronie Przykłady i szablony.

W przypadku użytkownika czatu kanał czatu usług komunikacyjnych dodaje pole do metadanych wiadomości, które wskazuje, że wiadomość ma załącznik. W metadanych właściwość jest ustawiona microsoft.azure.communication.chat.bot.contenttype na azurebotservice.adaptivecard.

Oto przykład wiadomości na czacie z dołączoną kartą adaptacyjną:

{
    "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"
}

Wysyłanie wiadomości od użytkownika do bota

Możesz wysłać podstawową wiadomość SMS od użytkownika do bota w taki sam sposób, jak wysyłasz wiadomość SMS do innego użytkownika.

Jednak po wysłaniu wiadomości zawierającej załącznik od użytkownika do bota dodaj tę flagę do metadanych czatu usług komunikacyjnych:

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

Aby wysłać działanie zdarzenia od użytkownika do bota, dodaj tę flagę do metadanych czatu usług komunikacyjnych:

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

W poniższych sekcjach przedstawiono przykładowe formaty wiadomości czatu od użytkownika do bota.

Prosta wiadomość SMS

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

Wiadomość z załącznikiem

{
    "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"
}

Komunikat z działaniem zdarzenia

Ładunek zdarzenia zawiera wszystkie pola JSON w zawartości komunikatu z wyjątkiem Name. Pole Name zawiera nazwę zdarzenia.

W poniższym przykładzie nazwa endOfConversation zdarzenia z ładunkiem "{field1":"value1", "field2": { "nestedField":"nestedValue" }} jest wysyłana do bota:

{
    "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 metadanych jest wymagane tylko w komunikacie wysyłanym od użytkownika do bota.

Obsługiwane pola działań bota

W poniższych sekcjach opisano obsługiwane pola działań bota dla przepływów typu bot-użytkownik i przepływów typu użytkownik-bot.

Przepływ bota do użytkownika

Następujące pola działań bota są obsługiwane w przypadku przepływów typu bot-użytkownik.

Działania

  • Wiadomość
  • Wpisywanie

Pola działań komunikatów

  • Text
  • Attachments
  • AttachmentLayout
  • SuggestedActions
  • From.Name (Przekonwertowane na usługi SenderDisplayNamekomunikacyjne ).
  • ChannelData (Przekonwertowano na usługi Chat Metadatakomunikacyjne . Jeśli jakiekolwiek ChannelData wartości mapowania są obiektami, są serializowane w formacie JSON i wysyłane jako ciąg).

Przepływ użytkownika do bota

Te pola działań bota są obsługiwane w przypadku przepływów typu użytkownik-bot.

Działania i pola

  • Wiadomość

    • Id (Identyfikator komunikatu czatu usług komunikacyjnych)
    • TimeStamp
    • Text
    • Attachments

  • Aktualizacja konwersacji

    • MembersAdded
    • MembersRemoved
    • TopicName

  • Aktualizacja komunikatów

    • Id (Zaktualizowany identyfikator wiadomości czatu usług komunikacyjnych)
    • Text
    • Attachments

  • Usuwanie wiadomości

    • Id (Usunięty identyfikator wiadomości czatu usług komunikacyjnych)

  • Zdarzenie

    • Name
    • Value

  • Wpisywanie

Inne typowe pola

  • Recipient.Id i Recipient.Name (Identyfikator użytkownika czatu usługi Communication Services i nazwa wyświetlana)
  • From.Id i From.Name (Identyfikator użytkownika czatu usługi Communication Services i nazwa wyświetlana)
  • Conversation.Id (Identyfikator wątku czatu usług komunikacyjnych)
  • ChannelId (Czat usług komunikacyjnych, jeśli jest pusty)
  • ChannelData (Metadane wiadomości czatu w usługach Komunikacyjnych)

Wzorce przekazywania bota

Czasami bot nie rozumie pytania lub nie może odpowiedzieć na pytanie. Klient może poprosić w rozmowie o połączenie z agentem ludzkim. W tych scenariuszach wątek czatu musi zostać przekazany z bota do agenta ludzkiego. Możesz zaprojektować aplikację, aby przenieść konwersację z bota do człowieka.

Obsługa komunikacji między botami

W niektórych przypadkach użycia dwa boty muszą zostać dodane do tego samego wątku czatu, aby zapewnić różne usługi. W tym scenariuszu może być konieczne upewnienie się, że bot nie wysyła automatycznych odpowiedzi do komunikatów innego bota. Jeśli nie jest prawidłowo obsługiwana, automatyczna interakcja botów między sobą może spowodować nieskończoną pętlę komunikatów.

Tożsamość użytkownika usług Communication Services dla nadawcy wiadomości można sprawdzić we właściwości działania From.Id . Sprawdź, czy należy on do innego bota. Następnie wykonaj wymaganą akcję, aby zapobiec przepływowi komunikacji bot-bot-bot. Jeśli ten typ scenariusza powoduje duże liczby wywołań, kanał czatu usług komunikacyjnych ogranicza żądania, a bot nie może wysyłać i odbierać wiadomości.

Dowiedz się więcej o limitach ograniczania przepustowości.

Rozwiązywanie problemów

W poniższych sekcjach opisano sposoby rozwiązywania typowych scenariuszy.

Nie można dodać kanału czatu

W portalu deweloperów programu Microsoft Bot Framework przejdź do pozycji Configuration Bot Messaging (Obsługa komunikatów bota konfiguracji>), aby sprawdzić, czy punkt końcowy został poprawnie ustawiony.

Bot otrzymuje wyjątek zabroniony podczas odpowiadania na wiadomość

Sprawdź, czy identyfikator i hasło aplikacji firmy Microsoft bota są poprawnie zapisywane w pliku konfiguracji bota przekazanym do aplikacji internetowej.

Nie można dodać bota jako uczestnika

Sprawdź, czy identyfikator usług komunikacyjnych bota jest używany poprawnie, gdy żądanie jest wysyłane w celu dodania bota do wątku czatu.

Następne kroki

Wypróbuj aplikację demonstracyjną czatbota na potrzeby czatu 1:1 między użytkownikiem czatu i botem za pośrednictwem składnika interfejsu użytkownika BotFramework WebChat.