Publikasikan copilot ke aplikasi seluler atau kustom

Artikel
09/19/2024

Anda dapat menghubungkan copilot Anda ke aplikasi kustom sehingga pengguna aplikasi dapat berinteraksi dengan copilot langsung dari dalam aplikasi Anda.

Dalam kebanyakan kasus, aplikasi kustom Anda adalah aplikasi perangkat seluler yang merupakan aplikasi berbasis web atau aplikasi native atau adaptor ke layanan lain yang diperlukan bisnis Anda.

Terdapat prosedur yang berbeda untuk menyambung ke aplikasi seluler, tergantung apakah aplikasi Anda adalah aplikasi berbasis web atau aplikasi asli.

Menghubungkan copilot Anda ke aplikasi berbasis web relatif mudah karena melibatkan penyalinan cuplikan kode ke dalam aplikasi Anda. Namun, aplikasi berbasis web dan aplikasi native atau kustom masih memerlukan keahlian pengembang yang cukup besar untuk mengintegrasikan copilot sepenuhnya ke dalam aplikasi Anda. Kedua prosedur dijelaskan dalam artikel ini.

Prasyarat

.NET Core SDK versi 2.1.
Paket Nuget Microsoft.Bot.Connector.DirectLine.
Copilot yang dibuat di mana Copilot Studio Anda ingin terhubung ke aplikasi Anda.

Hubungkan kopilot Anda ke aplikasi berbasis web

Dalam Copilot Studio, di menu navigasi, pilih Saluran.
Pilih ubin Aplikasi seluler untuk membuka jendela konfigurasi.
Salin kode di bagian Aplikasi berbasis web dan berikan kepada pengembang aplikasi Anda untuk ditambahkan ke aplikasi berbasis web Anda.

Hubungkan copilot Anda ke aplikasi asli atau kustom

Tip

Meskipun bagian ini menjelaskan cara menyambung ke aplikasi seluler, proses yang sama dapat diterapkan untuk aplikasi kustom atau asli, seperti aplikasi IoT (Internet of Things).

Jika tujuan Anda adalah untuk menyambungkan ke saluran Azure bot Service, selain mengikuti instruksi di sini, pengembang Anda dapat mempelajari selengkapnya di Menerbitkan copilot ke saluran Azure bot Service.

Penting

Petunjuk di bagian ini memerlukan pengembangan perangkat lunak dari Anda atau pengembang Anda. Ini ditujukan untuk profesional TI berpengalaman, seperti admin atau pengembang TI yang memiliki pemahaman solid tentang alat pengembang, utilitas, dan IDE.

Sampel kode

Cuplikan kode yang digunakan dalam dokumen ini berasal dari:

Kode sampel konektor

Referensi

Petunjuk dalam dokumen ini merujuk pada materi sumber berikut:

Ambil parameter kopilot Anda Copilot Studio

Untuk menyambungkan ke copilot yang Anda buat, Anda perlu mengambil nama copilot dan titik akhir token untuk mengidentifikasinya.

Di dalamnya Copilot Studio, buka halaman Ringkasan kopilot Anda, dan salin nama kopilot Anda.
Pilih Aplikasi Saluran>Seluler.
Pada halaman Aplikasi seluler, di samping titik akhir Token, pilih Salin. Anda memerlukan titik akhir ini untuk langkah Dapatkan Direct Line token .

Dapatkan token Direct Line

Untuk memulai percakapan dengan kopilot Anda, Anda memerlukan Direct Line token. Token ini dapat diperoleh dengan membuat permintaan GET ke titik akhir yang ditunjukkan di dalam Copilot Studio layar. Token ini kemudian harus digunakan sebagai header untuk panggilan berikutnya ke API directline.

Contoh:

GET <BOT TOKEN ENDPOINT>

Jika permintaan berhasil, akan dikembalikan token Direct Line , waktu kedaluwarsa, dan conversationId untuk copilot yang diminta. Contoh:

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

Contoh Kode Sampel

Contoh berikut menggunakan sampel dari kode sampel Konektor untuk mendapatkan token untuk kopilot Direct Line . 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; }
}

Objek respons sama dengan permintaan yang GET kita lihat sebelumnya.

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

Gunakan Direct Line untuk berkomunikasi dengan kopilot

Setelah mengambil Direct Line token, Anda siap untuk melakukan percakapan dengan kopilot Anda Copilot Studio Direct Line. Untuk memulai percakapan dan mengirim dan menerima pesan, ikuti petunjuk di Bot Framework Direct Line API.

Contoh berikut menggunakan sampel dari kode sampel Konektor untuk memulai percakapan dan mengirim dan menerima pesan dari Copilot Studio kopilot.

Inisialisasi instans DirectLineClient dengan Direct Line token dan mulai percakapan:

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

Setelah dimulai, setiap percakapan dapat diidentifikasi dan dihubungkan menggunakan kombinasi dan token conversationtId. Kirim pesan pengguna ke percakapan yang ada:

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

Ambil respons kopilot menggunakan yang sama token dan conversationId. Aktivitas respons yang diambil berisi Direct Line pesan pengguna dan kopilot. Anda dapat memfilter aktivitas respons berdasarkan nama kopilot Anda untuk hanya mendapatkan pesan respons kopilot.

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

Segarkan token Direct Line

Anda mungkin perlu menambahkan kode untuk me-refresh Direct Line token jika aplikasi Anda memiliki percakapan panjang dengan copilot. Token kedaluwarsa tetapi dapat disegarkan sebelum kedaluwarsa; Pelajari selengkapnya di Direct Line Autentikasi.

Contoh berikut menggunakan sampel dari kode sampel Konektor untuk me-refresh token untuk percakapan yang ada 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

Mengurai payload percakapan dari copilot

Setelah Anda memulai percakapan dengan copilot, payload JSON percakapan menggunakan aktivitas standar Microsoft Bot Framework Direct Line . Anda dapat mempelajari lebih lanjut di Bot Framework Direct Line API.

Menangani aktivitas penyerahan

Jika aplikasi Anda perlu diserahkan ke penyedia agen langsung, Anda perlu menangani aktivitas penyerahan. Aktivitas penyerahan dikirim saat simpul "Alihkan ke agen" terkena. Anda dapat mempelajari selengkapnya tentang muatan aktivitas penyerahan.

Memicu pesan pembuka

Jika Anda ingin kopilot mengirim topik sistem Salam secara otomatis saat pengguna memulai percakapan, Anda dapat mengirim aktivitas dengan Type=event dan Name=startConversation.

Bagikan melalui