Szybki start: dodawanie bota do aplikacji do czatu

Artykuł
11/05/2024

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:

Tworzenie i wdrażanie bota na platformie Azure
Pobieranie zasobu usług komunikacyjnych
Włączanie kanału czatu usług komunikacyjnych dla bota
Tworzenie aplikacji do czatu i dodawanie bota jako uczestnika
Eksplorowanie dodatkowych funkcji bota

Wymagania wstępne

Konto platformy Azure i aktywna subskrypcja. Utwórz bezpłatne konto.
Program Visual Studio 2019 lub nowszy.
Najnowsza wersja platformy .NET Core. (https://dotnet.microsoft.com/download/dotnet/).
Zestaw SDK platformy botów

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 aplikacji 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 wielodostępne.

Na potrzeby tego przewodnika Szybki start użyjemy bota multitenant .
Aby skonfigurować bota single-tenant lub managed identity , zapoznaj się z informacjami o tożsamości bota.
W przypadku bota managed identity 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 bota i publikowanie jej w aplikacji internetowej

Aby utworzyć bota, możesz wykonać jedną z następujących czynności:

Popraw przykłady narzędzia Bot Builder dla danego scenariusza, utwórz aplikację internetową, a następnie wdróż w nim przykład bota.
Użyj zestawu SDK bota, aby utworzyć i opublikować bota w aplikacji internetowej.

W tym przewodniku Szybki start użyjemy przykładu Echo Bot z przykładów narzędzia Bot Builder.

Tworzenie aplikacji internetowej do przechowywania aplikacji bota

Aby utworzyć aplikację internetową, 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:

W portalu wybierz pozycję Utwórz zasób. W polu wyszukiwania wprowadź ciąg aplikacja internetowa. Wybierz kafelek Aplikacja internetowa.
W obszarze Tworzenie aplikacji internetowej wybierz lub wprowadź szczegóły aplikacji, w tym region, w którym chcesz wdrożyć aplikację.
Wybierz pozycję Przejrzyj i utwórz , aby zweryfikować wdrożenie i przejrzeć szczegóły wdrożenia. Następnie wybierz przycisk Utwórz.
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.

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

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.

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

W witrynie Azure Portal przejdź do zasobu usługi Azure Bot. W menu zasobów wybierz pozycję Konfiguracja.
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 .
Wybierz pozycję Zapisz.

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:

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

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

W programie Visual Studio otwórz projekt Echo Bot.
W projekcie programu Visual Studio otwórz plik Appsettings.json . Wklej skopiowany wcześniej identyfikator aplikacji i hasło aplikacji firmy Microsoft:
```
   {
     "MicrosoftAppType": "",
     "MicrosoftAppId": "<App-registration-ID>",
     "MicrosoftAppPassword": "<App-password>",
       "MicrosoftAppTenantId": ""
   }
```
Następnie użyj programu Visual Studio lub VS Code 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.
W programie Visual Studio w Eksplorator rozwiązań kliknij prawym przyciskiem myszy projekt EchoBot i wybierz polecenie Publikuj:
Wybierz pozycję Nowy , aby utworzyć nowy profil publikowania. W polu Cel wybierz pozycję Azure:

Dla określonego miejsca docelowego wybierz pozycję aplikacja systemu Azure Service:
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.

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:

Wykonaj kroki tworzenia zasobu usług komunikacyjnych.
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.

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.
Wybierz pozycję Połącz , aby wyświetlić listę zasobów usług komunikacyjnych, które są dostępne w ramach subskrypcji.
W okienku Nowe połączenie wybierz zasób czatu usług komunikacyjnych, a następnie wybierz pozycję Zastosuj.
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.

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.

Postępuj zgodnie z przewodnikiem Szybki start "Dodawanie czatu do aplikacji"

Wykonaj kroki opisane w przewodniku Szybki start Dodawanie czatu do aplikacji , aby utworzyć aplikację do czatu.

Zastąp <Resource_Endpoint> punktem końcowym usług komunikacyjnych w kroku Pobieranie zasobu usługi komunikacyjnej.
Zastąp <Access_Token> tokenem dostępu użytkownika z kroku Pobieranie zasobu usługi komunikacji.
Zastąp <Access_ID> botami ACS_ID z kroku Włącz kanał czatu usług komunikacyjnych.

Uruchamianie aplikacji czatu w języku C# lokalnie

Aby uruchomić aplikację czatu lokalnie, użyj dotnet run polecenia :

dotnet run

Powinien zostać wyświetlony komunikat z bota w konsoli z komunikatem "Hello World".

Przykładowe wyjście:

1730405535010:Hello World

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

Komunikat
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

Komunikat
- 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.

Udostępnij za pośrednictwem