Freigeben über

Schnellstart: Hinzufügen eines Bots zu Ihrer Chat-App

  • Artikel

Erfahren Sie, wie Sie KI-gestützte Unterhaltungsfunktionen in einer Chatanwendung mithilfe des Messagingkanals „Azure Communication Services Chat“ erstellen, der in Azure Bot Service verfügbar ist. In dieser Schnellstartanleitung erstellen Sie einen Bot mithilfe des BotFramework SDK. Anschließend integrieren Sie den Bot in eine Chatanwendung, die Sie mithilfe des Communication Services Chat SDK erstellen.

In dieser Schnellstartanleitung wird Folgendes vermittelt:

Voraussetzungen

Erstellen und Bereitstellen eines Bots in Azure

Um den Azure Communication Services Chat als Kanal in Azure Bot Service zu verwenden, stellen Sie zuerst einen Bot bereit. Führen Sie diese Schritte aus, um einen Bot bereitzustellen:

Erstellen einer Azure Bot Service-Ressource

Zuerst erstellen Sie im Azure-Portal eine Azure Bot Service-Ressource. Der Communication Services-Chatkanal unterstützt auch Bots für Einzelmandanten, Bots für verwaltete Identitäten und mehrinstanzenfähige Bots.

Abrufen der App-ID und des App-Kennworts des Bots

Als Nächstes rufen Sie die Microsoft-App-ID und das Kennwort ab, die Ihrem Bot zugewiesen werden, wenn er bereitgestellt wird. Sie verwenden diese Werte für spätere Konfigurationen.

Erstellen einer Bot-App und Veröffentlichen dieser in einer Web-App

Zum Erstellen eines Bots können Sie eine der folgenden Aktionen ausführen:

  • Überarbeiten Sie die Bot Builder-Beispiele für Ihr Szenario, erstellen Sie eine Web-App, und stellen Sie Ihr Bot-Beispiel dann darin bereit.
  • Verwenden Sie das Bot Builder SDK, um einen Bot zu erstellen und in einer Web-App zu veröffentlichen.

Für diesen Schnellstart verwenden Sie das Echo Bot-Beispiel aus den Bot Builder-Beispielen.

Erstellen einer Web-App für die Bot-App

Verwenden Sie zum Erstellen der Web-App entweder die Azure-Befehlszeilenschnittstelle, um eine Azure App Service-Ressource zu erstellen, oder erstellen Sie die App im Azure-Portal.

So erstellen Sie eine Bot-Web-App im Azure-Portal:

  1. Wählen Sie im Portal Ressource erstellen aus. Geben Sie in das Suchfeld web app ein. Wählen Sie die Kachel Web-App aus.

    Screenshot: Erstellen einer Web-App-Ressource im Azure-Portal.

  2. Wählen Sie unter Web-App erstellen Details für die App aus, oder geben Sie sie ein, einschließlich der Region, in der Sie die App bereitstellen möchten.

    Screenshot: Festzulegende Details zum Erstellen einer Web-App-Bereitstellung.

  3. Wählen Sie Überprüfen und erstellen aus, um die Bereitstellung und die Bereitstellungsdetails zu überprüfen. Wählen Sie anschließend Erstellen.

  4. Wenn die Web-App-Ressource erstellt wird, kopieren Sie die Hostnamen-URL, die in den Ressourcendetails angezeigt wird. Die URL ist Teil des Endpunkts, den Sie für die Web-App erstellen.

    Screenshot: Kopieren der Web-App-Endpunkt-URL.

Erstellen eines Messagingendpunkts für den Bot

Azure Bot Service erwartet normalerweise, dass der Bot Application Web App Controller einen Endpunkt in der Form /api/messages verfügbar macht. Der Endpunkt verarbeitet alle Nachrichten, die an den Bot gesendet werden.

Erstellen Sie als Nächstes in der Botressource einen Web-App-Messagingendpunkt:

  1. Wechseln Sie im Azure-Portal zu Ihrer Azure Bot-Ressource. Wählen Sie im Ressourcenmenü die Option Konfiguration aus.

  2. Fügen Sie unter Konfiguration für Messagingendpunkt die Hostnamen-URL der Web-App ein, die Sie im vorherigen Abschnitt kopiert haben. Fügen Sie der URL /api/messages an.

  3. Wählen Sie Speichern aus.

Screenshot: Erstellen eines Bot-Messagingendpunkts mithilfe des Web-App-Hostnamens.

Bereitstellen der Web-App

Der letzte Schritt zum Erstellen eines Bots ist das Bereitstellen der Web-App. Für diesen Schnellstart verwenden Sie das Echo Bot-Beispiel. Die Funktionalität des Echo Bots ist auf das Echo der Benutzereingabe beschränkt. So stellen Sie ihn in Ihrer Web-App in Azure bereit:

  1. Klonen Sie dieses GitHub-Repository mit Git:

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

  2. Öffnen Sie in Visual Studio das Echo Bot-Projekt.

  3. Öffnen Sie im Visual Studio-Projekt die Datei Appsettings.json. Fügen Sie Microsoft-App-ID und App-Kennwort ein, die sie zuvor kopiert haben:

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

    Stellen Sie den Bot als Nächstes mit Visual Studio oder VS Code für C#-Bots bereit.

    Sie können auch ein Eingabeaufforderungsfenster verwenden, um einen Azure-Bot bereitzustellen.

  4. Klicken Sie in Visual Studio im Projektmappen-Explorer mit der rechten Maustaste auf das EchoBot-Projekt, und wählen Sie Veröffentlichen aus:

    Screenshot: Veröffentlichung Ihrer Web-App über Visual Studio.

  5. Wählen Sie Neu aus, um ein neues Veröffentlichungsprofil zu erstellen. Wählen Sie für Ziel die Option Azure aus:

    Screenshot: Auswählen von Azure als Ziel in einem neuen Veröffentlichungsprofil.

    Wählen Sie als spezifisches Ziel Azure App Service aus.

    Screenshot: Auswählen von Azure App Service als spezifisches Ziel.

  6. Wählen Sie in der Bereitstellungskonfiguration die Web-App in den Ergebnissen aus, die nach der Anmeldung bei Ihrem Azure-Konto angezeigt werden. Um das Profil zu vervollständigen, wählen Sie Fertig stellen und dann Veröffentlichen aus, um die Bereitstellung zu starten.

    Screenshot: Festlegen der Bereitstellungskonfiguration mit dem Namen der Web-App.

Abrufen einer Communication Services-Ressource

Ihr Bot ist nun erstellt und bereitgestellt. Erstellen Sie jetzt eine Communication Services-Ressource zum Einrichten eines Communication Services-Kanals:

  1. Führen Sie die Schritte zum Erstellen einer Communication Services-Ressource aus.

  2. Erstellen Sie einen Communication Services-Benutzer, und stellen Sie ein Benutzerzugriffstoken aus. Legen Sie den Bereich unbedingt auf chat fest. Kopieren Sie die Tokenzeichenfolge und die Benutzer-ID-Zeichenfolge.

Aktivieren des Communication Services-Chatkanals

Wenn Sie über eine Communication Services-Ressource verfügen, können Sie einen Communication Services-Kanal in der Botressource einrichten. In diesem Prozess wird eine Benutzer-ID für den Bot generiert.

  1. Wechseln Sie im Azure-Portal zu Ihrer Azure Bot-Ressource. Wählen Sie im Ressourcenmenü die Option Kanäle aus. Wählen Sie in der Liste der verfügbaren Kanäle Azure Communications Services – Chat aus.

    Screenshot: Öffnen des Communication Services-Chatkanals.

  2. Wählen Sie Verbinden aus, um eine Liste der Communication Services-Ressourcen anzuzeigen, die in Ihrem Abonnement verfügbar sind.

    Screenshot: Herstellen der Verbindung einer Communication Services-Ressource mit dem Bot.

  3. Wählen Sie im Bereich Neue Verbindung die Communication Services-Chatressource und dann Anwenden aus.

    Screenshot: Speichern der ausgewählten Communication Services-Ressource zum Erstellen einer neuen Communication Services-Benutzer-ID.

  4. Wenn die Ressourcendetails überprüft werden, wird eine Bot-ID in der Spalte Bot Azure Communication Services-ID angezeigt. Um den Bot mithilfe einer Bot-ID in einem Chatthread darzustellen, können Sie die Communication Services-Chat-AddParticipant-API verwenden. Nachdem Sie den Bot einem Chat als Teilnehmer hinzugefügt haben, empfängt der Bot chatbezogene Aktivitäten und kann im Chatthread antworten.

    Screenshot der neuen Azure Communication Services-Benutzer-ID, die dem Bot zugewiesen wurde.

Erstellen einer Chat-App und Hinzufügen des Bots als Teilnehmer

Da Sie nun über die Communication Services-ID des Bots verfügen, können Sie einen Chatthread mit dem Bot als Teilnehmer erstellen.

Befolgen des Schnellstarts „Hinzufügen von Chatfunktionen zu Ihrer App“

Führen Sie die Schritte im Schnellstart Hinzufügen von Chatfunktionen zu Ihrer App aus, um eine Chat-App zu erstellen.

  1. Ersetzen Sie <Resource_Endpoint> durch den Communication Services-Endpunkt aus dem Schritt Abrufen einer Communication Services-Ressource.
  2. Ersetzen Sie <Access_Token> durch das Benutzerzugriffstoken aus dem Schritt Abrufen einer Communication Services-Ressource.
  3. Ersetzen Sie <Access_ID> durch die ACS_ID des Bots aus dem Schritt Aktivieren des Communication Services-Chatkanals.

Lokales Ausführen der C#-Chatanwendung

Verwenden Sie den Befehl dotnet run, um die Chatanwendung lokal auszuführen:

dotnet run

Sie sollten eine Nachricht vom Bot an der Konsole mit der Meldung „Hello World“ erhalten.

Beispielausgabe:

1730405535010:Hello World

Weitere von einem Bot gebotene Möglichkeiten

Ein Bot kann von einem Benutzer in einem Communications Services-Chatkanal mehr empfangen als eine Nur-Text-Nachricht. Zu den Aktivitäten, die ein Bot von einem Benutzer empfangen kann, gehören:

  • Konversationsaktualisierung
  • Nachrichtenaktualisierung
  • Nachrichtenlöschung
  • Eingabeindikator
  • event-Aktivität
  • Verschiedene Anlagen einschließlich adaptiver Karten
  • Botkanaldaten

Die nächsten Abschnitte zeigen einige Beispiele, um diese Features zu veranschaulichen.

Senden einer Begrüßungsnachricht, wenn dem Thread ein neuer Benutzer hinzugefügt wird

Die aktuelle Echo Bot-Logik akzeptiert Eingaben vom Benutzer und gibt sie als Echo zurück. Wenn Sie zusätzliche Logik hinzufügen möchten, z. B. zum Reagieren auf ein Communication Services-Ereignis, das von einem Teilnehmer hinzugefügt wurde, kopieren Sie den folgenden Code, und fügen Sie ihn in die Quelldatei EchoBot.cs ein:

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

Senden einer adaptiven Karte

Hinweis

Adaptive Karten werden nur in Azure Communication Services-Anwendungsfällen unterstützt, bei denen alle Chatteilnehmer Azure Communication Services-Benutzer sind, und nicht für Interoperabilitäts-Anwendungsfälle in Teams.

Sie können eine adaptive Karte an den Chatthread senden, um das Engagement und die Effizienz zu erhöhen. Eine adaptive Karte unterstützt Sie auch dabei, auf verschiedene Weise mit Benutzern zu kommunizieren. Sie können eine adaptive Karte von einem Bot aus senden, indem Sie die Karte als Botaktivitätsanlage hinzufügen.

Hier sehen Sie ein Beispiel für das Senden einer adaptiven Karte:

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

Beispielnutzlasten für adaptive Karten finden Sie unter Beispiele und Vorlagen.

Für einen Chatbenutzer fügt der Communication Services-Chatkanal den Nachrichtenmetadaten ein Feld hinzu, das angibt, dass die Nachricht über eine Anlage verfügt. In den Metadaten ist die microsoft.azure.communication.chat.bot.contenttype-Eigenschaft auf azurebotservice.adaptivecard festgelegt.

Hier sehen Sie ein Beispiel für eine Chatnachricht mit einer adaptiven Karte:

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

Senden einer Nachricht vom Benutzer an den Bot

Sie können eine einfache Textnachricht von einem Benutzer an den Bot senden, genauso wie Sie eine Textnachricht an einen anderen Benutzer senden.

Wenn Sie jedoch eine Nachricht mit einer Anlage von einem Benutzer an einen Bot senden, fügen Sie den Metadaten des Communication Services-Chats dieses Flag hinzu:

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

Um eine Ereignisaktivität von einem Benutzer an einen Bot zu senden, fügen Sie den Communication Services-Chatmetadaten dieses Flag hinzu:

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

Die folgenden Abschnitte zeigen Beispielformate für Chatnachrichten von einem Benutzer an einen Bot.

Einfache Textnachricht

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

Nachricht mit einer Anlage

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

Nachricht mit einer Ereignisaktivität

Eine Ereignisnutzlast enthält alle JSON-Felder im Nachrichteninhalt mit Ausnahme von Name. Das Name-Feld enthält den Namen des Ereignisses.

Im folgenden Beispiel wird der Ereignisname endOfConversation mit der Nutzlast "{field1":"value1", "field2": { "nestedField":"nestedValue" }} an den Bot gesendet:

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

Das Metadatenfeld microsoft.azure.communication.chat.bot.contenttype ist nur in einer Nachricht erforderlich, die von einem Benutzer an einen Bot gesendet wird.

Unterstützte Botaktivitätsfelder

In den folgenden Abschnitten werden unterstützte Botaktivitätsfelder für Bot-zu-Benutzer-Flows und Benutzer-zu-Bot-Flows beschrieben.

Bot-zu-Benutzer-Flow

Die folgenden Botaktivitätsfelder werden für Bot-zu-Benutzer-Flows unterstützt.

activities

  • `Message`
  • Eingabe

Nachrichtenaktivitätsfelder

  • Text
  • Attachments
  • AttachmentLayout
  • SuggestedActions
  • From.Name (Konvertiert in Communication Services SenderDisplayName.)
  • ChannelData (Konvertiert in Communication Services Chat Metadata. Wenn es sich bei Zuordnungswerten für ChannelData um Objekte handelt, werden sie im JSON-Format serialisiert und als Zeichenfolge gesendet.)

Benutzer-zu-Bot-Flow

Diese Botaktivitätsfelder werden für Benutzer-zu-Bot-Flows unterstützt.

Aktivitäten und Felder

  • `Message`

    • Id (Communication Services-Chatnachrichten-ID)
    • TimeStamp
    • Text
    • Attachments

  • Konversationsaktualisierung

    • MembersAdded
    • MembersRemoved
    • TopicName

  • Nachrichtenaktualisierung

    • Id (Aktualisierte Communication Services-Chatnachrichten-ID)
    • Text
    • Attachments

  • Nachrichtenlöschung

    • Id (Gelöschte Communication Services-Chatnachrichten-ID)

  • Ereignis

    • Name
    • Value

  • Eingabe

Andere gängige Felder

  • Recipient.Id und Recipient.Name (Communication Services-Chatbenutzer-ID und Anzeigename)
  • From.Id und From.Name (Communication Services-Chatbenutzer-ID und Anzeigename)
  • Conversation.Id (Communication Services-Chatthread-ID)
  • ChannelId (Communication Services-Chat, falls leer)
  • ChannelData (Metadaten für Communication Services-Chatnachrichten)

Übergabemuster für Bots

Manchmal versteht ein Bot eine Frage nicht oder kann eine Frage nicht beantworten. Ein Kunde könnte im Chat darum bitten, mit einem menschlichen Agenten verbunden zu werden. In diesen Szenarien muss der Chatthread vom Bot an einen menschlichen Agenten übergeben werden. Für solche Fälle können Sie Ihre Anwendung so entwerfen, dass die Unterhaltung vom Bot zu einer Person umgestellt wird.

Handhaben der Kommunikation zwischen Bots

In manchen Fällen müssen zwei Bots demselben Chatthread hinzugefügt werden, um verschiedene Dienste bereitzustellen. In diesem Szenario müssen Sie möglicherweise sicherstellen, dass ein Bot keine automatisierten Antworten auf die Nachrichten eines anderen Bots sendet. Wenn dies nicht ordnungsgemäß gehandhabt wird, könnte die automatisierte Interaktion der Bots untereinander zu einer Endlosschleife von Nachrichten führen.

Sie können die Communication Services-Benutzeridentität eines Nachrichtensenders in der Eigenschaft From.Id der Aktivität überprüfen. Überprüfen Sie, ob sie zu einem anderen Bot gehört. Führen Sie dann die erforderlichen Maßnahmen aus, um einen Bot-zu-Bot-Kommunikationsfluss zu verhindern. Wenn diese Art von Szenario zu hohen Aufrufvolumen führt, drosselt der Communication Services-Chatkanal die Anforderungen, und ein Bot kann weder Nachrichten senden noch empfangen.

Erfahren Sie mehr über Drosselungslimits.

Problembehandlung

In den folgenden Abschnitten werden Methoden zur Problembehandlung bei allgemeinen Szenarien beschrieben.

Chatkanal kann nicht hinzugefügt werden

Wechseln Sie im Microsoft Bot Framework-Entwicklerportal zu Konfiguration>Bot-Messaging, um zu überprüfen, ob der Endpunkt ordnungsgemäß festgelegt wurde.

Bot erhält beim Antworten auf eine Nachricht die Ausnahme „Unzulässig“

Vergewissern Sie sich, dass die Microsoft-App-ID und das Kennwort des Bots ordnungsgemäß in der in die Web-App hochgeladenen Konfigurationsdatei des Bots gespeichert sind.

Bot kann nicht als Teilnehmer hinzugefügt werden

Überprüfen Sie, ob die Communication Services-ID des Bots ordnungsgemäß verwendet wird, wenn eine Anforderung zum Hinzufügen eines Bots zu einem Chatthread gesendet wird.

Nächste Schritte

Erste Schritte mit dem Chat

Das könnte Sie auch interessieren: