Koneksi bot ke Pencarian (pratinjau)

Artikel ini menjelaskan cara membuat penyedia pencarian federasi kustom (didukung oleh bot Anda) dan menyambungkannya ke saluran Pencarian. Setelah administrator penyewa mengaktifkan penyedia Anda di penyewa mereka, pencarian pengguna perusahaan, dari Office.com, SharePoint.com, dan Bing.com, dapat menyertakan hasil dari penyedia pencarian kustom Anda.

Platform Pencarian Federasi Microsoft memungkinkan Anda membangun penyedia pencarian federasi kustom untuk memungkinkan informasi Anda berpartisipasi dalam pengalaman Jawaban & Vertikal Microsoft Search tanpa perlu menggabungkan informasi tersebut dengan indeks Microsoft 365 Anda. Untuk informasi selengkapnya, lihat Mengumumkan pratinjau pengembang Platform Pencarian Federasi Microsoft dan pencarian federasi Dynamics 365 (pratinjau).

Catatan

Saluran Pencarian berada dalam pratinjau privat. Untuk meminta akses, gunakan formulir Pratinjau Privat Pengembang Pencarian Microsoft. Pada pertanyaan 7, pilih Pencarian Federasi.

Langkah-langkah berikut diperlukan untuk menyambungkan bot Anda ke saluran Pencarian. Langkah-langkah ini dijelaskan secara lebih rinci nanti di artikel ini.

1. Terapkan bot Anda untuk bekerja sebagai penyedia pencarian.
2. Jika bot Anda akan mengharuskan pengguna untuk masuk:
   1. Di portal Azure, ekspos API bot ke platform pencarian.
   2. Dalam kode bot Anda, gunakan URI cakupan yang dihasilkan untuk menghasilkan token pengguna.
3. Sebarkan bot Anda ke Azure.
4. Tambahkan saluran Pencarian ke bot Anda.
5. Minta administrator TI Anda untuk meninjau pendaftaran bot Anda dan menerbitkan bot Anda di penyewa.

Tip

Kami menyarankan agar Anda mengaktifkan penyedia pencarian di penyewa pengujian sebelum mengaktifkannya dalam produksi.

Prasyarat

• Pengetahuan tentang Dasar-Dasar Bot Framework Service dan cara Membuat bot dengan Bot Framework SDK.
• Bot untuk terhubung ke saluran.
• Jika Anda tidak memiliki akun Azure, buat akun gratis sebelum memulai.

Anda dapat mengimplementasikan bot Anda dalam salah satu bahasa yang didukung oleh Bot Framework SDK. Artikel ini menggunakan bot pencarian gabungan C# sebagai contoh.

Mengekspos API bot ke Pencarian

Tip

Langkah ini hanya diperlukan jika bot Anda memerlukan akses ke sumber daya pengguna yang dilindungi.

Dalam beberapa alur kerja bisnis, bot mungkin memerlukan kredensial pengguna untuk melakukan tindakan atas nama pengguna. Untuk membuat pengalaman akses menyeluruh (SSO) untuk bot Anda di saluran Pencarian, Anda harus mengizinkan platform pencarian untuk mengamankan token akses dari ID Microsoft Entra atas nama pengguna.

Untuk menghasilkan URI cakupan dan ID aplikasi untuk bot Anda:

1. Buka portal Microsoft Azure.
2. Jika Anda belum memiliki sumber daya bot, buat sumber daya Azure Bot.
3. Buka layanan ID Microsoft Entra.
4. Buka panel Pendaftaran aplikasi.
5. Pilih aplikasi yang terkait dengan bot Anda.
6. Buka panel Mengekspos API .
7. Pilih Tambahkan cakupan.
   1. Pada panel Tambahkan cakupan, kami sarankan Anda menyimpan URI ID Aplikasi yang dibuat secara otomatis. Klik Simpan dan lanjutkan.
   2. Masukkan nama Cakupan.
   3. Untuk Siapa dapat menyetujui?, Admin dan pengguna lebih disukai, tetapi kedua opsi akan berfungsi.
   4. Masukkan nama tampilan persetujuan Admin dan deskripsi persetujuan Admin.
   5. Secara opsional, masukkan Nama tampilan persetujuan pengguna dan deskripsi persetujuan Pengguna.
   6. Verifikasi bahwa Status diatur ke Diaktifkan.
   7. Pilih Tambahkan cakupan.
8. Pilih Tambahkan aplikasi klien.
   1. Di panel Tambahkan aplikasi klien, atur ID Klien ke 81473081-50b9-469a-b9d8-303109583ecb, ID klien platform Pencarian.
   2. Di bawah Cakupan resmi, pilih URI cakupan yang Anda buat di langkah sebelumnya.
   3. Pilih Tambahkan aplikasi.
9. Buka panel Gambaran Umum . Menyalin URI ID Aplikasi. Anda akan memerlukannya saat mendaftarkan bot di saluran Pencarian.

Menerapkan bot Anda

Saluran Pencarian mengirimkan setiap kueri pengguna ke bot Anda sebagai aktivitas pemanggilan dengan nama "aplikasi/pencarian". Bot Anda mengembalikan hasil kueri dalam respons pemanggilan. Gunakan format Kartu Adaptif untuk hasil kueri yang dikirim kembali ke saluran Pencarian.

1. Perbarui paket Bot Framework dan Adaptive Cards apa pun di proyek Anda ke versi terbaru.
2. Secara opsional, tambahkan kode autentikasi untuk menghasilkan token pengguna.
3. Terapkan metode pencarian data untuk disertakan oleh setiap sumber data.
4. Buat Kartu Adaptif untuk menampilkan hasilnya.

Mendapatkan ID pelacakan platform Pencarian

Platform Pencarian menetapkan ID pelacakan unik untuk setiap kueri yang dikirim ke bot Anda. Platform menambahkan ini ke data saluran aktivitas pemanggilan. Anda dapat memutuskan untuk mencatat ID pelacakan permintaan. Gunakan properti data traceId saluran untuk mendapatkan ID pelacakan.

Dalam sampel pencarian federasi, SearchHelper.GetSearchTraceId metode menunjukkan cara mendapatkan ID pelacakan dari aktivitas pemanggilan.

Tambahkan autentikasi

Jika Anda mengekspos API bot ke Pencarian dan meminta autentikasi saat menyambungkan bot ke Pencarian, Anda bisa mendapatkan token autentikasi pengguna dari data saluran aktivitas.

Properti data authorizations saluran dapat berisi daftar token autentikasi. Jika Anda mengekspos API bot Anda ke Pencarian, daftar akan berisi token atas nama. Token dalam daftar akan memiliki struktur berikut:

Nama Properti	Jenis	Deskripsi
authType	Integer	Jenis token autentikasi: 0 untuk tidak diketahui atau default, atau 2 untuk atas nama token.
token	string	Token autentikasi itu sendiri.

Dalam sampel pencarian federasi:

• Kelas SearchBotAuthenticationToken dan AuthenticationTypes enumerasi mewakili informasi ini.
• Metode ini SearchHelper.GetSearchOboToken menunjukkan cara mendapatkan token dari aktivitas pemanggilan.

Setelah memiliki token, Anda dapat menggunakannya saat meminta sumber daya yang dilindungi untuk pengguna. Untuk informasi tentang menggunakan token atas nama, lihat alur On-Behalf-Of platform identitas Microsoft dan OAuth 2.0.

Mengkueri setiap penyimpanan data

Saluran Pencarian mengirimkan kueri ke bot sebagai invoke aktivitas, dengan detail kueri di properti aktivitas value , yang mewakili objek JSON dengan struktur berikut:

Nama Properti	Jenis	Deskripsi
queryText	string	Teks kueri.
jenis	string	Jenis kueri: "cari" ketika hasil akan ditampilkan di tab vertikal kustom, atau "searchAnswer" ketika hasil akan ditampilkan sebagai jawaban di tab Semua.
queryOptions	object	Opsi kueri tambahan yang digunakan untuk penomoran halaman.
queryOptions.skip	Integer	Indeks hasil pertama yang akan dikirim.
queryOptions.top	Integer	Jumlah maksimum hasil yang akan dikirim.

Anda mengembalikan hasil pencarian dalam respons pemanggilan:

• Selalu atur properti objek Status respons pemanggilan ke 200, yang menunjukkan bahwa koneksi jaringan baik-baik saja. Properti objek Body memiliki kode status terpisah.

• Properti Body mewakili objek JSON dengan struktur berikut:

  Nama Properti	Jenis	Deskripsi
  statusCode	Integer	Kode status HTTP yang digunakan untuk menunjukkan apakah bot berhasil menjalankan kueri.
  jenis	string	Jenis respons pemanggilan, menentukan format bidang nilai. Gunakan "application/vnd.microsoft.search.searchResponse" untuk hasil pencarian, atau "application/vnd.microsoft.error" untuk pesan kesalahan.
  value	object	Nilai yang sesuai dengan nilai type.

  Untuk pesan kesalahan, value objek berisi:

  Nama Properti	Jenis	Deskripsi
  kode	string	Kode kesalahan yang ditentukan oleh bot, atau null jika tidak ditentukan.
  pesan	string	Pesan kesalahan, atau null jika tidak ditentukan.

  Untuk hasil pencarian, value objek berisi:

  Nama Properti	Jenis	Deskripsi
  hasil	array objek hasil pencarian	Hasilnya, atau null jika tidak ada.
  displayLayouts	array objek tata letak tampilan	Tata letak tampilan, atau null jika tidak ada.
  totalResultCount	Integer	Total hasil yang tersedia, jika penomoran halaman didukung; jika tidak, null.
  moreResultsAvailable	Boolean	Menunjukkan apakah lebih banyak hasil tersedia.

  Objek hasil pencarian berisi:

  Nama Properti	Jenis	Deskripsi
  value	string	Pengidentifikasi atau nilai unik untuk hasil pencarian ini.
  layoutId	string	ID tata letak tampilan yang akan digunakan untuk hasil ini.
  data.searchResultText	string	Teks untuk hasil ini.

  Tampilkan objek tata letak berisi:

  Nama Properti	Jenis	Deskripsi
  layoutId	string	ID tata letak.
  layoutBody	string	Isi tata letak sebagai objek JSON Kartu Adaptif.

Dalam sampel pencarian federasi, SearchHelper.RunFederatedSearch metode menunjukkan cara mendapatkan informasi kueri dari aktivitas pemanggilan dan cara memformat respons pemanggilan.

Menampilkan hasil pencarian

Anda bisa membuat vertikal pencarian dan tipe hasil untuk mengkustomisasi hasil pencarian yang dilihat pengguna saat mereka mencari di SharePoint, Office, dan Bing. Vertikal memudahkan pengguna untuk menemukan informasi yang mereka miliki izinnya untuk dilihat. Untuk informasi selengkapnya, lihat bagian Elemen Kartu Adaptif yang Didukung.

Jika bot Anda menerima kueri yang tidak memiliki respons, balasannya harus berisi respons kosong.

Mendaftarkan bot Anda di Azure

Untuk menyambungkan bot Anda ke saluran Pencarian, Anda harus memiliki sumber daya bot yang disediakan di Azure. Untuk informasi selengkapnya, lihat cara Mendaftarkan bot dengan Azure atau cara Menyebarkan bot Anda di Azure.

Koneksi bot Anda ke Pencarian

Instruksi berikut menunjukkan cara menyambungkan bot ke Pencarian.

Tip

Kami menyarankan agar Anda mengaktifkan penyedia pencarian di penyewa pengujian sebelum mengaktifkannya dalam produksi.

1. Buka portal Microsoft Azure.

2. Buka sumber daya bot Anda.

3. Buka panel Saluran (Pratinjau) .

4. Pilih Telusuri.

5. Di tab Cari Pengaturan, masukkan informasi untuk bot Anda.

   

   1. Di bawah Metadata Penyedia Pencarian, masukkan nama untuk ditampilkan di antarmuka pengguna pencarian.

   2. Di bawah Frasa Pemicu, tentukan frasa yang mewakili kueri yang dapat dijawab bot Anda.

      Catatan

      Untuk rilis awal, hanya bahasa Inggris (en-US) yang tersedia.

      • .csv Unggah file yang berisi frasa. File harus berisi satu kolom data, tanpa header.
      • Dari daftar Preferensi bahasa, pilih bahasa tempat frasa pemicu ditulis.

   3. Di bawah Autentikasi, tunjukkan apakah penyedia pencarian Anda memerlukan autentikasi pengguna.

      • Jika autentikasi diperlukan, masukkan URL autentikasi. Gunakan URI ID Aplikasi yang Anda salin saat Mengekspos API untuk bot Anda.

   4. Pilih Selanjutnya.

6. Di tab Vertikal , jika Anda ingin hasil dari penyedia pencarian Anda muncul dalam vertikal kustomnya sendiri di halaman hasil pencarian, masukkan nama vertikal di bidang ; jika tidak, biarkan bidang ini kosong. Kemudian, pilih Berikutnya.
   Halaman hasil pencarian adalah untuk Office.com, SharePoint.com, dan Bing.com.

7. Di tab Penerbitan Penyewa, tinjau pengaturan Anda dan tambahkan informasi penerbitan.

   1. Tinjau nama penyedia pencarian dan kueri sampel. Kembali ke tab sebelumnya untuk mengubah informasi ini, jika perlu.
   2. Masukkan deskripsi penyedia pencarian Anda.
   3. Masukkan email kontak dukungan. Gunakan email pengembang atau grup pengembang yang memiliki akses ke penyedia pencarian.

8. Pilih Tambahkan untuk meminta persetujuan dari administrator TI Anda.

Menyetujui penyedia pencarian di penyewa

Persetujuan penyedia pencarian di penyewa dibuat oleh administrator TI di halaman Pencarian & Kecerdasan di pusat admin Microsoft 365.

Menguji koneksi

Kami menyarankan agar Anda mengaktifkan penyedia pencarian di penyewa pengujian sebelum mengaktifkannya dalam produksi.

Mengubah penyedia pencarian

Anda dapat mengedit penyedia pencarian sebelum mengirimkannya untuk ditinjau oleh administrator TI. Anda mungkin perlu melakukannya jika permintaan awal Anda ditolak atau layanan Anda dinonaktifkan.

1. Di portal Azure, buka sumber daya bot yang berisi penyedia pencarian yang ingin Anda edit.
2. Buka panel Saluran (Pratinjau) .
3. Pilih saluran Pencarian, dan pilih Edit.
   1. Azure menampilkan panel Saluran Pencarian. Di panel ini, Anda bisa mengedit pengaturan Anda.
   2. Untuk mengubah frasa pemicu, unduh file, edit secara lokal, dan unggah file.
   3. Setelah Anda menyelesaikan pengeditan, pilih Tambahkan lagi untuk mengirimkan penyedia pencarian untuk ditinjau oleh administrator TI.

Menghapus penyedia pencarian

Penyedia pencarian Anda akan dihapus jika Anda menghapus saluran Pencarian dari sumber daya bot.

Untuk menghapus saluran Pencarian dari bot Anda:

1. Di portal Azure, buka sumber daya bot Anda.
2. Buka panel Saluran (Pratinjau) .
3. Pilih saluran Pencarian.
4. Di bagian atas panel Saluran Pencarian, pilih Hapus saluran.
5. Pilih Ya untuk mengonfirmasi operasi.

Untuk menghapus sumber daya bot Anda:

1. Di portal Azure, buka sumber daya bot Anda.
2. Jika Anda belum melakukannya, hapus saluran Pencarian dari bot Anda.
3. Di bagian atas panel Gambaran Umum, pilih Hapus.
4. Pilih OK untuk mengonfirmasi operasi.

Informasi tambahan

Saluran pencarian menggunakan pencarian federasi dan skema Kartu Adaptif:

Untuk informasi selengkapnya tentang skema Kartu Adaptif, lihat Kartu Adaptif untuk pengembang bot.

Tentang frasa pemicu

Frasa pemicu adalah frasa yang digunakan platform pencarian untuk merutekan kueri ke penyedia pencarian kustom Anda yang didukung oleh bot Anda. Pencarian federasi meneruskan ucapan pengguna ke penyedia pencarian Anda saat ucapan tersebut hampir cocok dengan salah satu frasa pemicu.

Tip

Jika tersedia lebih dari satu penyedia pencarian, pencarian federasi hanya memilih satu, berdasarkan frasa pemicu yang disediakan dan kueri pengguna.

Sebagai contoh, pikirkan bot yang mengelola jadwal dan status penerbangan.

1. Pikirkan beberapa cara umum yang akan dirujuk pengguna atau manfaatkan bot Anda. Pastikan untuk membedakan bot Anda dari yang lain.

   Alih-alih istilah generik, seperti "jadwal" yang dapat berlaku untuk sekolah dan program TV, gunakan frasa yang lebih spesifik, seperti "tabel waktu penerbangan" dan "jadwal penerbangan".

2. Sertakan beragam frasa yang mencakup cakupan fitur bot Anda, seperti waktu keberangkatan dan status saat ini.

   Misalnya, sertakan kueri tentang: waktu kedatangan atau keberangkatan dan bandara.

Frasa pemicu untuk jadwal penerbangan dan bot status tersebut mungkin meliputi:

• Jadwal penerbangan
• Status penerbangan
• Waktu keberangkatan Penerbangan 675
• Kapan penerbangan saya akan berangkat
• Waktu kedatangan Penerbangan 468
• Status penerbangan Seattle Tacoma
• Status penerbangan Heathrow

Sebagai contoh lain, frasa pemicu untuk bot prakiraan cuaca mungkin meliputi:

• Prakiraan cuaca lokal
• Info cuaca
• Cuaca besok
• Prakiraan cuaca 10 hari
• Hari ini tinggi
• Hari ini kemungkinan hujan
• Akankah salju besok
• Kecepatan angin besok
• Apakah berangin di luar
• Cuaca London

Elemen Kartu Adaptif yang Didukung

Subset skema Kartu Adaptif didukung dalam pencarian gabungan. Untuk informasi tentang memformat hasil pencarian Anda, lihat Mengkustomisasi halaman hasil pencarian.

Dukungan mencakup elemen Kartu Adaptif berikut: TextBlock, RichTextBlock, Image, ColumnSet, ImageSet, dan FactSet. Untuk informasi selengkapnya, lihat Tata letak Kelola hasil pencarian Microsoft Search dan Penjelajah Skema Kartu Adaptif.

Anda dapat menulis setiap kartu secara langsung sebagai JSON, atau Anda dapat menggunakan paket AdaptiveCards NuGet.

Pencarian gabungan tidak mendukung HTML

Penting

Pencarian gabungan tidak akan merender teks Kartu Adaptif yang berisi HTML.

Platform Pencarian tidak menyertakan pengurai HTML. Namun, Anda dapat menghilangkan beberapa tag dan menggunakan paket Html2Markdown NuGet untuk mengonversi HTML ke Markdown:

1. Hapus <span> dan <u> elemen.
2. Ganti <div> dan <br> elemen dengan elemen paragraf (<p>).
3. Konversi html yang tersisa menjadi Markdown.

Langkah berikutnya

• Untuk informasi tentang dukungan saluran di Bot Koneksi or Service, lihat Koneksi bot ke saluran.
• Untuk informasi tentang membangun bot, lihat Cara kerja bot dan mulai cepat Membuat bot dengan Bot Framework SDK .
• Untuk informasi tentang menyebarkan bot, lihat Menyebarkan bot Anda dan Menyiapkan penyebaran berkelanjutan.