Δημοσίευση εκπρόσωπος σε εφαρμογές για κινητά ή προσαρμοσμένες εφαρμογές

Άρθρο
12/09/2024

Μπορείτε να συνδέσετε το εκπρόσωπος σας σε μια προσαρμοσμένη εφαρμογή, έτσι ώστε οι χρήστες της εφαρμογής να μπορούν να αλληλεπιδρούν με το εκπρόσωπος απευθείας μέσα από την εφαρμογή σας.

Στις περισσότερες περιπτώσεις, η προσαρμοσμένη εφαρμογή σας είναι μια εφαρμογή για κινητές συσκευές που είναι είτε μια εφαρμογή που βασίζεται στο Web είτε μια εγγενής εφαρμογή ή προσαρμογέας σε άλλες υπηρεσίες που απαιτεί η επιχείρησή σας.

Υπάρχουν διαφορετικές διαδικασίες για τη σύνδεση στην εφαρμογή για κινητές συσκευές, ανάλογα με το αν η εφαρμογή σας είναι εφαρμογή που βασίζεται στο Web ή εγγενής εφαρμογή.

Η σύνδεση του εκπρόσωπος σας σε μια εφαρμογή που βασίζεται στον ιστό είναι σχετικά απλή, καθώς περιλαμβάνει την αντιγραφή ενός τμήμα κώδικα στην εφαρμογή σας. Ωστόσο, τόσο οι εφαρμογές που βασίζονται στον ιστό όσο και οι εγγενείς ή προσαρμοσμένες εφαρμογές εξακολουθούν να απαιτούν σημαντική εμπειρία προγραμματιστών για την πλήρη ενσωμάτωση του εκπρόσωπος στην εφαρμογή σας. Και οι δύο διαδικασίες περιγράφονται σε αυτό το άρθρο.

Προϋποθέσεις

.NET Core SDK έκδοση 2.1.
Πακέτο Nuget Microsoft.Bot.Connector.DirectLine.
Ένα εκπρόσωπος δημιουργήθηκε στο ότι θέλετε να συνδεθείτε στην Copilot Studio εφαρμογή σας.

Συνδέστε το εκπρόσωπος σας σε μια εφαρμογή που βασίζεται στον ιστό

Στο Copilot Studio, επιλέξτε Κανάλια στο μενού πλοήγησης.
Επιλέξτε το πλακίδιο Εφαρμογή για κινητές συσκευές για να ανοίξετε το παράθυρο ρύθμισης παραμέτρων.
Αντιγράψτε τον κώδικα στην ενότητα Εφαρμογής που βασίζονται στο web και δώστε τον στους προγραμματιστές εφαρμογών σας ώστε να τον προσθέσουν στην εφαρμογή σας που βασίζεται στο Web.

Συνδέστε το εκπρόσωπος σας σε μια εγγενή ή προσαρμοσμένη εφαρμογή

Φιλοδώρημα

Αν και σε αυτήν την ενότητα περιγράφεται ο τρόπος σύνδεσης σε μια εφαρμογή για κινητές συσκευές, η ίδια διαδικασία θα μπορούσε να εφαρμοστεί σε προσαρμοσμένες ή εγγενείς εφαρμογές, όπως οι εφαρμογές IoT (Internet of things).

Εάν ο στόχος σας είναι να συνδεθείτε σε κανάλια υπηρεσίας Azure bot, εκτός από τις οδηγίες εδώ, οι προγραμματιστές σας μπορούν να μάθουν περισσότερα στο θέμα Δημοσίευση καναλιών υπηρεσίας εκπρόσωπος έως Azure bot.

Σημαντικό

Οι οδηγίες σε αυτήν την ενότητα απαιτούν ανάπτυξη λογισμικού από εσάς ή από τους προγραμματιστές σας. Απευθύνονται σε έμπειρους επαγγελματίες IT, όπως διαχειριστές IT ή προγραμματιστές που έχουν κατανοήσει πολύ καλά τα εργαλεία για προγραμματιστές, τα βοηθητικά προγράμματα και τα IDE.

Δείγματα κώδικα

Τα τμήματα κώδικα που χρησιμοποιούνται σε αυτό το έγγραφο προέρχονται από:

Δείγμα κώδικα σύνδεσης

Αναφορές

Οι οδηγίες σε αυτό το έγγραφο αναφέρουν το εξής υλικό προέλευσης:

Ανάκτηση Copilot Studio των παραμέτρων εκπρόσωπος

Για να συνδεθείτε στο εκπρόσωπος που δημιουργήσατε, πρέπει να ανακτήσετε το όνομα και το διακριτικό του εκπρόσωπος σας τελικό σημείο για να το αναγνωρίσετε.

Στο Copilot Studio, μεταβείτε στη σελίδα Επισκόπηση του εκπρόσωπος σας και αντιγράψτε το όνομα του εκπρόσωπος σας.
Επιλέξτε Κανάλια>Εφαρμογή για κινητές συσκευές.
Στη σελίδα Εφαρμογή για κινητές συσκευές, δίπλα στο στοιχείο Τελικό σημείο διακριτικού, επιλέξτε Αντιγραφή. Χρειάζεστε αυτό το τελικό σημείο για το βήμα Λήψη διακριτικού Direct Line.

Λήψη διακριτικού Direct Line

Για να ξεκινήσετε μια συνομιλία με το εκπρόσωπος σας, χρειάζεστε ένα Direct Line διακριτικό. Αυτό το διακριτικό μπορεί να ληφθεί με την υποβολή ενός αιτήματος GET στο τελικό σημείο υποδεικνύεται στην οθόνη του Copilot Studio. Αυτό το διακριτικό πρέπει στη συνέχεια να χρησιμοποιηθεί ως κεφαλίδα για επόμενες κλήσεις στο API απευθείας γραμμής.

Παράδειγμα:

GET <BOT TOKEN ENDPOINT>

Εάν το αίτημα είναι επιτυχές, θα επιστραφεί ένα διακριτικό, χρόνος Direct Line λήξης και ένα conversationId για το ζητούμενο εκπρόσωπος. Παράδειγμα:

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

Παράδειγμα δείγματος κώδικα

Το παρακάτω παράδειγμα χρησιμοποιεί δείγματα από το δείγμα κώδικα σύνδεσης για να λάβετε ένα Direct Line διακριτικό για το a Copilot Studio εκπρόσωπος.

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

Το αντικείμενο απάντησης είναι ίδιο με το αίτημα GET που είχαμε προηγουμένως.

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

Χρησιμοποιήστε το Direct Line για να επικοινωνήσετε με το εκπρόσωπος

Μετά την ανάκτηση του διακριτικού, είστε έτοιμοι να συνομιλήσετε με Direct Line το Copilot Studio εκπρόσωπος σας Direct Line. Για να ξεκινήσετε μια συνομιλία και να στείλετε και να λάβετε μηνύματα, ακολουθήστε τις οδηγίες στο Bot Framework Direct Line API.

Το παρακάτω παράδειγμα χρησιμοποιεί δείγματα από το δείγμα κώδικα σύνδεσης για να ξεκινήσει μια συνομιλία και να στείλει και να λάβει μηνύματα από το a Copilot Studio εκπρόσωπος.

Προετοιμασία μιας παρουσίας DirectLineClient με διακριτικό Direct Line και έναρξη μιας συνομιλίας:

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

Μόλις ξεκινήσει, κάθε συνομιλία μπορεί να αναγνωριστεί και να συνδεθεί χρησιμοποιώντας τον συνδυασμό του token και του conversationtId. Αποστολή μηνύματος χρήστη σε μια υπάρχουσα συνομιλία:

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

Ανακτήστε το απάντηση του εκπρόσωπος χρησιμοποιώντας το ίδιο token και conversationId. Οι ανακτημένες Direct Line απάντηση δραστηριότητες περιέχουν μηνύματα χρήστη και εκπρόσωπος. Μπορείτε να φιλτράρετε τις δραστηριότητές απάντηση με το όνομα του εκπρόσωπος σας για να λάβετε μόνο το απάντηση μήνυμα του εκπρόσωπος.

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

Ίσως χρειαστεί να προσθέσετε κώδικα για να ανανεώσετε το διακριτικό, εάν η Direct Line εφαρμογή σας έχει μια μακρά συνομιλία με το εκπρόσωπος. Το διακριτικό λήγει αλλά μπορεί να ανανεωθεί πριν λήξει. Μάθετε περισσότερα στον Έλεγχο ταυτότητας Direct Line.

Στο παρακάτω παράδειγμα χρησιμοποιούνται δείγματα από τον κώδικα δείγματος Connector για ανανέωση του διακριτικού για μια υφιστάμενη συνομιλία Copilot Studio:

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

Ανάλυση ωφέλιμου φορτίου συνομιλίας από το εκπρόσωπος

Αφού ξεκινήσετε μια συνομιλία με το εκπρόσωπος, το φορτίο JSON συνομιλίας χρησιμοποιεί την τυπική Microsoft Bot Framework Direct Line δραστηριότητα. Μπορείτε να μάθετε περισσότερα στο Bot Framework Direct Line API.

Χειρισμός δραστηριότητας παράδοσης

Εάν η εφαρμογή σας πρέπει να παραδοθεί σε έναν εκπρόσωπο ζωντανής υποστήριξης, πρέπει να διαχειριστείτε τη δραστηριότητα παράδοσης. Η δραστηριότητα παράδοσης αποστέλλεται όταν κάντε κλικ στον κόμβο "Σύνδεση με εκπρόσωπο". Μπορείτε να μάθετε περισσότερα για το ωφέλιμο φορτίο της δραστηριότητας παράδοσης.

Ενεργοποίηση μηνύματος καλωσορίσματος

Εάν θέλετε το εκπρόσωπος σας να στέλνει αυτόματα το θέμα συστήματος χαιρετισμού όταν ένας χρήστης ξεκινά μια συνομιλία, μπορείτε να στείλετε μια δραστηριότητα με Type=event και Name=startConversation.

Κοινή χρήση μέσω