Einen Copiloten an mobile oder benutzerdefinierte Apps veröffentlichen

Artikel
09/27/2024

Sie können Ihren Copiloten mit einer benutzerdefinierten App verbinden, damit die Benutzenden der App direkt aus Ihrer App heraus mit dem Copiloten interagieren können.

In den meisten Fällen handelt es sich bei Ihrer benutzerdefinierten App um eine App für mobile Geräte, die entweder eine webbasierte App oder eine native App oder ein Adapter für andere Dienste ist, die Ihr Unternehmen benötigt.

Es gibt verschiedene Verfahren zum Herstellen einer Verbindung zu Ihrer mobilen App, je nachdem, ob es sich bei Ihrer App um eine webbasierte App oder eine native App handelt.

Das Verbinden Ihres Copiloten mit einer webbasierten App ist relativ einfach, da ein Codeschnipsel in Ihre App kopiert werden muss. Sowohl webbasierte Apps als auch native oder benutzerdefinierte Apps erfordern jedoch noch beträchtliche Entwicklerkenntnisse, um den Copiloten vollständig in Ihre App zu integrieren. Beide Verfahren werden in diesem Artikel beschrieben.

Anforderungen

.NET Core SDK Version 2.1.
Nuget-Paket Microsoft.Bot.Connector.DirectLine.
Ein in Copilot Studio erstellter Copilot, mit dem Sie eine Verbindung zu Ihrer App herstellen möchten.

Ihren Copiloten mit einer webbasierten App verbinden

In Copilot Studio, im Navigationsmenü, Auswählen Kanäle.
Wählen Sie die Kachel mobile App aus, um das Konfigurationsfenster zu öffnen.
Kopieren Sie den Code unter dem Abschnitt Webbasierte Apps und stellen Sie es Ihren App-Entwicklern zur Verfügung, um es Ihrer webbasierten App hinzuzufügen.

Ihren Copiloten mit einer nativen oder benutzerdefinierten App verbinden

Tipp

Während in diesem Abschnitt beschrieben wird, wie eine Verbindung zu einer mobilen App hergestellt wird, kann der gleiche Vorgang für benutzerdefinierte oder native Apps angewendet werden, z. B. für IoT-Apps (Internet of Things).

Wenn Sie eine Verbindung zu Azure Bot Service-Kanälen herstellen möchten, können Ihre Entwickler unter Befolgen der Anweisungen hier weitere Informationen erhalten Einen Copiloten an einen Azure Bot Service-Kanälen veröffentlichen.

Wichtig

Anweisungen in diesem Abschnitt erfordern Softwareentwicklung von Ihnen oder Ihren Entwicklern. Es richtet sich an erfahrene IT-Experten wie IT-Administratoren oder -Entwickler, die ein solides Verständnis für Entwicklertools, Dienstprogramme und IDEs haben.

Codebeispiele

In diesem Dokument verwendete Codefragmente stammen von:

Connector-Beispielcode

Referenzen

Die Anweisungen in diesem Dokument beziehen sich auf folgendes Quellmaterial:

Copilot Studio-Copilot-Parameter abrufen

Um eine Verbindung zu dem Copiloten herzustellen, den Sie erstellt haben, müssen Sie den Namen und den Token-Endpunkt Ihres Copiloten abrufen, um ihn zu identifizieren.

Navigieren Sie in Copilot Studio zur Übersichtsseite Ihres Copiloten und kopieren Sie den Namen Ihres Copiloten.
Auswählen Kanäle>Mobile App.
Auf der Seite der Mobilen App neben Token Endpunkt, Auswählen Kopieren. Sie benötigen diesen Endpunk für den Schritt Direct Line-Token erhalten.

Direct Line-Token erhalten

Um ein Gespräch mit Ihrem Copiloten zu beginnen, benötigen Sie ein Direct Line-Token. Dieses Token kann durch eine GET-Anforderung an den im Copilot Studio-Bildschirm angegebenen Endpunkt bezogen werden. Dieses Token muss dann als Header für nachfolgende Aufrufe der Directline-API verwendet werden.

Beispiel:

GET <BOT TOKEN ENDPOINT>

Wenn die Anforderung erfolgreich ist, wird ein Direct Line-Token, eine Ablaufzeit und eine „conversationId“ für den angeforderten Copiloten zurückgegeben. Beispiel:

{
    "token": "RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn",
    "expires_in": 3600,
    "conversationId": "abc123"
}

Beispielcodebeispiel

Das folgende Beispiel verwendet Beispiele aus dem Beispielcode für den Konnektor, um ein Direct Line-Token für einen Copilot Studio-Copiloten abzurufen.

/// <summary>
/// Get directline token for connecting bot
/// </summary>
/// <returns>directline token as string</returns>
public async Task<DirectLineToken> GetTokenAsync(string url)
{
    try
    {
        return await _httpClient.GetFromJsonAsync<DirectLineToken>(url);
    }
    catch (HttpRequestException ex)
    {
        throw ex;
    }        
}

/// <summary>
/// class for serialization/deserialization DirectLineToken
/// </summary>
public class DirectLineToken
{
  public string Token { get; set; }
  public int Expires_in { get; set; }
  public string ConversationId { get; set; }
}

Das Objekt Antwort ist dasselbe wie die GET Anfrage, die wir zuvor gesehen haben.

{
  "token": "RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn",
  "expires_in": 3600,
  "conversationId": "abc123"
}

Verwenden von Direct Line zur Konversation mit dem Copiloten

Nachdem Sie das Direct Line Token abgerufen haben, können Sie ein Gespräch mit Ihrem Copilot Studio Copiloten Direct Line führen. Um eine Unterhaltung zu beginnen und Nachrichten zu senden und zu empfangen, folgen Sie den Anweisungen unter Bot Framework Direct Line-API.

Das folgende Beispiel verwendet Beispiele aus dem Konnektor-Beispielcode, um eine Unterhaltung zu beginnen und Nachrichten von einem Copilot Studio-Copiloten zu senden und zu empfangen.

Initialisieren Sie eine DirectLineClient-Instanz mit dem Direct Line-Token und beginnen Sie ein Gespräch:

   // Use the retrieved token to create a DirectLineClient instance
   using (var directLineClient = new DirectLineClient(token))
   {
       var conversation = await directLineClient.Conversations.StartConversationAsync();
       string conversationtId = conversation.ConversationId;
   }

Einmal gestartet, kann jedes Gespräch mithilfe der Kombination von token und conversationtId identifiziert und verbunden werden. Senden Sie eine Benutzernachricht an eine vorhandene Konversation:

   // Use the retrieved token to create a DirectLineClient instance
   // Use the conversationId from above step
   // endConversationMessage is your predefined message indicating that user wants to quit the chat
   while (!string.Equals(inputMessage = /*Get_User_Input()*/, endConversationMessage, StringComparison.OrdinalIgnoreCase))
   {
       using (var directLineClient = new DirectLineClient(token))
       {
           // Send user message using directlineClient
           // Payload is a Microsoft.Bot.Connector.DirectLine.Activity
           await directLineClient.Conversations.PostActivityAsync(conversationtId, new Activity()
           {
               Type = ActivityTypes.Message,
               From = new ChannelAccount { Id = "userId", Name = "userName" },
               Text = inputMessage,
               TextFormat = "plain",
               Locale = "en-Us",
           });
       }
   }

Rufen Sie die Antwort des Copiloten mit derselben token und conversationId ab. Die abgerufenen Direct Line Antwort-Aktivitäten enthalten sowohl Nachrichten des Benutzers als auch des Copiloten. Sie können Antwortaktivitäten nach dem Namen Ihres Copiloten filtern, um nur die Antwortnachricht des Copiloten zu erhalten.

   // Use the same token to create a directLineClient
   using (var directLineClient = new DirectLineClient(token))
   {
       // To get the first response set string watermark = null
       // More information about watermark is available at
       // https://learn.microsoft.com/azure/bot-service/rest-api/bot-framework-rest-direct-line-1-1-receive-messages?view=azure-bot-service-4.0

       // response from bot is of type Microsoft.Bot.Connector.DirectLine.ActivitySet
       ActivitySet response = await directLineClient.Conversations.GetActivitiesAsync(conversationtId, watermark);

       // update watermark from response
       watermark = response?.Watermark;

       // response contains set of Activity from both user and bot
       // To display bot response only, filter Activity.From.Name equals to your bot name
       List<Activity> botResponses = response?.Activities?.Where(x =>
                 x.Type == ActivityTypes.Message &&
                   string.Equals(x.From.Name, /*Bot_Name*/, StringComparison.Ordinal)).ToList();

       // Display botResponses
   }

Direct Line-Token aktualisieren

Sie müssen möglicherweise Code zum Aktualisieren des Direct Line Tokens hinzufügen, wenn Ihre Anwendung eine längere Konversation mit dem Copiloten führt. Das Token läuft ab, kann jedoch vor Ablauf aktualisiert werden. Weitere Informationen finden Sie unter Direct Line-Authentifizierung.

Das folgende Beispiel verwendet Beispiele aus dem Connector-Beispielcode, um das Token für eine bestehende Copilot Studio-Unterhaltung zu aktualisieren:

  // DirectLine provides a token refresh method
  // Requires the currentToken valid when refreshing
  string refreshToken = new DirectLineClient(currentToken).Tokens.RefreshToken().Token;
  // create a new directline client with refreshToken
  directLineClient = new DirectLineClient(refreshToken);
  // use new directLineClient to communicate to your bot

Analysieren der Konversationsnutzdaten vom Copiloten

Nachdem Sie eine Konversation mit dem Copiloten begonnen haben, verwendet die JSON-Nutzlast der Konversation die Standardaktivität Microsoft Bot Framework Direct Line . Weitere Informationen finden Sie unter Bot Framework Direct Line-API.

Übergabe-Aktivität handhaben

Wenn Ihre Anwendung an einen Live-Agent-Anbieter übergeben werden muss, müssen Sie die Übergabeaktivität ausführen. Die Die Übergabe-Aktivität wird gesendet, wenn der Knoten „Übertragen an Agent“ getroffen wird. Weitere Informationen finden Sie unter Informationen zur Nutzlast der Übergabe-Aktivität.

Eine Willkommensnachricht auslösen

Wenn Ihr Copilot das Begrüßungssystemthema automatisch senden soll, wenn ein Benutzender eine Konversation startet, können Sie eine Aktivität mit Type=event und Name=startConversation senden.

Freigeben über