Publicere en copilot til mobilapps eller brugerdefinerede apps

Artikel
09/27/2024

Du kan finde din copilot med en brugerdefineret app, så appens brugere kan arbejde sammen med copiloten direkte fra din app.

I de fleste tilfælde er din brugerdefinerede app en app til en mobilenhed og er enten en webbaseret app eller en oprindelig app eller kort til andre tjenester, som din virksomhed har brug for.

Der er forskellige procedurer for at oprette forbindelse til mobilappen, afhængigt af om appen er en webbaseret app eller en oprindelig app.

Det er forholdsvis ligetil at oprette forbindelse mellem din copilot og en webbaseret app, da det involverer kopiere et kodestykke over i din app. Men både webbaserede apps og oprindelige apps eller brugerdefinerede apps kræver dog alligevel betydelig udviklingsekspertise for at kunne integrere copiloten fuldt ud i din app. Begge procedurer er beskrevet i denne artikel.

Forudsætninger

.NET Core SDK version 2.1.
Nuget-pakken Microsoft.Bot.Connector.DirectLine.
En copilot, der er oprettet i Copilot Studio, og som du vil forbinde med din app.

Forbind din copilot med en webbaseret app

I Copilot Studio navigationsmenuen skal du vælge Kanaler.
Vælg feltet Mobilapp for at åbne konfigurationsvinduet.
Kopiér koden under sektionen Webbaserede apps, og giv den til app-udviklerne, så de kan tilføje den til din webbaserede app.

Forbind din copilot med en oprindelig eller brugerdefineret app

Tip

Dette afsnit indeholder en beskrivelse af, hvordan du forbinder til en mobilapp, men den samme proces kan dog også anvendes til brugerdefinerede eller oprindelige apps, f.eks. IoT-apps (Tingenes internet).

Hvis dit mål er at oprette forbindelse til Azure Bot Service-kanaler, kan dine udviklere, udover at følge instruktionerne her, få mere at vide under Publicere en copilot til Azure Bot Service-kanaler.

Vigtigt!

Instruktionerne i dette afsnit kræver udvikling af software fra dig eller dine udviklere. Det er udviklet til erfarne IT-medarbejdere, såsom IT-administratorer eller udviklere, der har en solid forståelse for udviklerværktøjer, værktøjer og IDE'er.

Kodeeksempler

Kodestykker, der bruges i dette dokument, er fra:

Eksempelkode for connector

Referencer

Instruktionerne i dette dokument refererer til følgende kildemateriale:

Hent dine Copilot Studio-copilotparametre

Hvis du vil oprette forbindelse til den copilot, du har oprettet med , skal du hente din copilots navn og token-slutpunkt for at identificere den.

Gå Copilot Studio til siden Oversigt for din copilot, og kopier din copilots navn.
Vælg Channels>Mobile-appen.
På siden Mobilapp skal du ud for Token-slutpunkt vælge Kopiér. Du skal bruge dette slutpunkt til trinnet Hent Direct Line-token.

Hent Direct Line-token

Hvis du vil starte en samtale med din copilot, skal du bruge et Direct Line-token. Dette token kan angives ved at anmode den bruger, der slutpunkt GET, på Copilot Studio skærmen. Dette token skal derefter bruges som header for efterfølgende kald til directline-API'en.

Eksempel:

GET <BOT TOKEN ENDPOINT>

Hvis anmodningen lykkes, returneres et Direct Line-token, udløbstidspunkt og et samtale-id for den ønskede copilot. Eksempel:

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

Eksempel på eksempelkode

I følgende eksempel bruges prøver fra Connector-prøveeksempelkoden til at hente et Direct Line-token til en Copilot Studio-copilot.

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

Objektet svar er det samme som den anmodning, GET vi så tidligere.

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

Brug Direct Line til at kommunikere med copiloten

Når du har hentet tokenet Direct Line , er du klar til at have en samtale med din Copilot Studio copilot med Direct Line. Følg instruktionerne i Bot Framework Direct Line-API for at starte en samtale og sende og modtage meddelelser.

I følgende eksempel bruges eksempler fra Connector-eksempelkoden til at starte en samtale og sende og modtage meddelelser fra en Copilot Studio-copilot.

Initialiser en DirectLineClient-forekomst med Direct Line-tokenet, og start en samtale:

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

Når en samtale er startet, kan hver samtale identificeres og forbindes ved hjælp af kombinationen af token og conversationtId. Send en brugermeddelelse til en eksisterende samtale:

   // 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",
           });
       }
   }

Hent copilotens svar ved hjælp af samme token og conversationId. De hentede Direct Line svar-aktiviteter indeholder både brugerens og copilotens meddelelser. Du kan filtrere svaraktiviteter efter din copilots navn for kun at få copilotens svarmeddelelser.

   // 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
   }

Opdater et Direct Line-token

Du skal muligvis tilføje kode for at opdatere tokenet Direct Line , hvis dit program har en lang samtale med copiloten. Tokenet udløber, men kan opdateres, før det udløber. Få mere at vide i Direct Line-godkendelse.

I følgende eksempel bruges eksempler fra Connector-eksempelkoden til at opdatere tokenet til en eksisterende Copilot Studio-samtale:

  // 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

Fortolk samtalenyttedata fra copiloten

Når du har startet en samtale med copiloten, bruger JSON-dataene i samtalen standardaktiviteten Microsoft Bot Framework Direct Line . Du kan få mere at vide på Bot Framework Direct Line-API.

Håndtering af afleveringsaktivitet

Hvis din applikation skal aflevere til en udbyder af live helpdesk-medarbejdere, skal du håndtere afleveringsaktiviteten. Der sendes en afleveringsaktivitet, når noden "Overførsel til medarbejder" rammes. Du kan få mere at vide om nyttedataene for afleveringsaktivitet.

Udløs en velkomstmeddelelse

Hvis du ønsker, at din copilot skal sende en hilsen til systememnet automatisk, når en bruger starter en samtale, kan du sende en aktivitet med Type=event og Name=startConversation.

Del via