Windows Cari penyedia pencarian web

Windows Search saat ini menggunakan Web Search dari aplikasi Microsoft Bing untuk mengembalikan konten web dan hasil pencarian. Di Area Ekonomi Eropa (EEA), Anda dapat menginstal aplikasi yang mengimplementasikan penyedia pencarian web untuk mengembalikan konten web dan hasil pencarian di pencarian Windows.

Penyedia pencarian terintegrasi dengan pengalaman Pencarian dengan membuat paket MSIX dengan file manifes paket yang menyediakan informasi yang diperlukan bagi OS untuk mendaftarkan penyedia pencarian. Setelah penginstalan, penyedia pencarian diaktifkan secara default dalam pengalaman pencarian Windows. Di Pengaturan Windows, pengguna dapat mengaktifkan dan menonaktifkan penyedia pencarian yang diinstal dan mengelola urutan penyedia dalam hasil pencarian. Pengguna dapat menghapus penyedia pencarian melalui halaman Settings > Apps > Terinstal di Pengaturan Windows.

Untuk pengembangan dan pengujian, ketika Mode Pengembang diaktifkan dan aplikasi penyedia pencarian telah diunduh langsung pada perangkat, aplikasi tersebut akan muncul dalam daftar penyedia pencarian yang tersedia. Untuk informasi selengkapnya, lihat Pengaturan untuk pengembang.

Setelah penyedia pencarian terdaftar dengan OS, kueri pengguna diteruskan ke titik akhir HTTP yang ditentukan oleh penyedia dalam manifes paket mereka menggunakan string kueri standar. Titik akhir mengembalikan hasil yang disarankan dalam dokumen JSON. Dengan setiap URL yang disarankan dalam dokumen respons, penyedia pencarian menyertakan URL titik akhir pratinjau, yang mengembalikan dokumen HTML yang ditampilkan di panel pratinjau di UI hasil pencarian.

Artikel ini menyediakan panduan untuk membuat paket aplikasi penyedia pencarian dan detail tentang protokol untuk menerapkan titik akhir HTTP penyedia pencarian.

Membuat paket aplikasi ekstensibilitas pencarian

Penyedia pencarian mendaftar dengan OS dengan menyediakan paket MSIX yang berisi informasi yang diperlukan tentang penyedia, seperti nama penyedia pencarian dan titik akhir HTTP untuk saran dan pratinjau.

Ekstensi aplikasi penyedia pencarian

File manifes paket aplikasi mendukung banyak ekstensi dan fitur yang berbeda untuk aplikasi Windows. Format manifes paket aplikasi didefinisikan oleh sekumpulan skema yang terdapat pada skema referensi manifes paket. Penyedia pencarian menyatakan informasi pendaftaran mereka dalam uap3:AppExtension. Atribut Nama ekstensi harus diatur ke "com.microsoft.windows.websearchprovider".

Penyedia pencarian harus menyertakan uap3:Properties sebagai anak dari uap3:AppExtension. Skema manifes paket tidak memberlakukan struktur elemen uap3:Properties selain memerlukan XML yang terbentuk dengan baik. Bagian lainnya menjelaskan format XML yang diharapkan OS agar berhasil mendaftarkan penyedia pencarian.

<uap3:Extension Category="windows.appExtension">
  <uap3:AppExtension Name="com.microsoft.windows.websearchprovider" DisplayName="SearchExampleApp" Id="ContosoSearchApp" PublicFolder="Public">
    <uap3:Properties>
    <!-- Search provider registration content goes here -->
    </uap3:Properties>
  </uap3:AppExtension>
</uap3:Extension>

Hierarki elemen

uap3:Properties

  Titik Akhir

  Protokol

Titik akhir

URL titik akhir HTTPS tempat OS akan mengirim permintaan kueri pencarian.

Protokol

Skema protokol yang akan digunakan saat meluncurkan hasil pencarian web yang disediakan. Jika protokol yang ditentukan tidak didaftarkan oleh aplikasi pada OS, maka browser default akan diluncurkan untuk hasil pencarian. Untuk informasi selengkapnya tentang mendaftarkan skema protokol, lihat uap:Protocol.

Contoh file manifes paket

Berikut ini adalah contoh file manifes paket appmanifest.xml untuk mendaftarkan penyedia Pencarian Windows.

<!-- appxmanifest.xml -->

  <uap3:Extension Category="windows.appExtension">
	  <uap3:AppExtension Name="com.microsoft.windows.websearchprovider" DisplayName="CustomSearch" Id="CustomSearchApp" PublicFolder="Public">
		  <uap3:Properties>
			  <Endpoint>https://customsearchendpoint</Endpoint>
			  <Protocol>customsearch</Protocol>
		  </uap3:Properties>
	  </uap3:AppExtension>
  </uap3:Extension>
  <uap:Extension Category="windows.protocol">
	  <uap:Protocol Name="customsearch"/>
  </uap:Extension>

Menerapkan titik akhir saran penyedia pencarian Windows

Penyedia pencarian harus mengekspos dan mendaftarkan titik akhir HTTPS yang dipanggil oleh OS saat pengguna mengetik ke dalam kotak pencarian Windows. Titik akhir ini harus mengembalikan string berformat JSON yang berisi saran pencarian untuk kueri pengguna yang disediakan. Konten harus dikirimkan melalui HTTPS. Integrasi pencarian tidak mendukung konten yang dikirimkan melalui HTTP.

Format permintaan HTTPS yang disarankan

Permintaan HTTPS ke titik akhir saran menggunakan format berikut.

https://contoso.com?setlang=en-US&cc=US&qry=

Parameter string kueri yang diteruskan ke titik akhir saran adalah sebagai berikut.

Pengaturan	Deskripsi
setlang	Lokasi terkait kueri
Cc	Kode negara yang terkait dengan kueri.
qry	Pertanyaan yang diberikan oleh pengguna. Jika parameter tidak memiliki nilai, yaitu muncul dalam string kueri sebagai qry=, maka kueri pengguna kosong. Penyedia pencarian masih dapat memberikan saran dan halaman pratinjau sebagai respons terhadap kueri kosong. NOTA OS tidak melakukan sanitasi string kueri apa pun. Penyedia pencarian dapat menerapkan sanitasi mereka sendiri saat kueri diterima.

Saran header respons HTTPS

Penyedia pencarian harus menyertakan header berikut dalam respons dari endpoint HTTPS sugesti.

• Access-Control-Allow-Origin: https://www.bing.com
• Access-Control-Allow-Credentials: benar
• Access-Control-Allow-Methods: GET
• Jenis Konten: aplikasi/json; charset=utf-8
• Panjang Konten: [Harus panjang respons yang tepat]

Format JSON tanggapan saran

Titik akhir HTTPS penyedia pencarian untuk saran harus mengembalikan dokumen JSON dengan format berikut. Nama kunci harus sama persis dengan format.

Kunci	Deskripsi
Saran	Berisi daftar objek JSON dengan kunci Attributes yang mewakili saran yang terkait dengan kueri pengguna.
Atributs	Berisi atribut dari saran.
URL	URL untuk saran pencarian di situs web penyedia.
kueri	Kueri pengguna yang terkait dengan saran pencarian.
previewPaneUrl	Alamat titik akhir untuk pratinjau dari mana pratinjau HTML dari saran dapat diambil.
Teks	Deskripsi teks saran.

{"Suggestions": 
   [{"Attributes": 
     {"url":"https://www.contoso.com/search?q=projection+matrix","query":"projection matrix","previewPaneUrl":"http://www.contoso.com/preview"} ,"Text":"projection matrix"}, 
    {"Attributes": 
     {"url":"https://www.contoso.com/search?q=rotation+matrix","query":"rotation matrix","previewPaneUrl":"http://www.contoso.com/preview"} ,"Text":"rotation matrix"}
    ] 
} 

Menerapkan titik akhir pratinjau penyedia Pencarian Windows

Penyedia pencarian mengembalikan URL titik akhir HTTPS yang menyediakan pratinjau HTML halaman yang terkait dengan setiap saran dalam hasil pencarian. Respons titik akhir pratinjau harus mengembalikan kode HTML untuk halaman yang berfungsi.

Pratinjau format permintaan HTTPS

Permintaan HTTPS ke titik akhir pratinjau menggunakan format berikut.

https://contoso.com?Darkschemeovr=1

Parameter string kueri yang diteruskan ke titik akhir saran adalah sebagai berikut.

Pengaturan	Deskripsi
Darkschemeovr	Menentukan apakah sistem Windows panggilan mengaktifkan tema gelap. Nilainya adalah 1 jika tema gelap diaktifkan dan 0 jika tema gelap dinonaktifkan.

Pratinjau respons header HTTPS

• Access-Control-Allow-Origin: https://www.bing.com
• Access-Control-Allow-Credentials: benar
• Access-Control-Allow-Methods: GET
• Tipe Konten: teks/html; charset=utf-8
• Panjang Konten: [Harus panjang html pratinjau yang tepat]

Permintaan OPTIONS dan Berbagi Sumber Daya Lintas Asal (CORS)

Klien Windows Search mengirimkan permintaan HTTP OPTIONS (CORS preflight) sebelum setiap permintaan GET. Penyedia pencarian harus mendukung metode permintaan OPTIONS dan merespons dengan HTTP 200 OK.

Artikel terkait