Bagikan melalui

Penyedia Pencarian Windows

  • Artikel

Catatan

Beberapa informasi berkaitan dengan produk yang telah dirilis sebelumnya, yang mungkin dimodifikasi secara substansial sebelum dirilis secara komersial. Microsoft tidak memberikan jaminan, tersirat maupun tersurat, sehubungan dengan informasi yang diberikan di sini.

Penting

Fitur yang dijelaskan dalam topik ini tersedia dalam build pratinjau Windows yang dimulai dengan build 22631.2787 untuk Windows 11 dan build 19045.3758 untuk Windows 10, meskipun build yang lebih baru direkomendasikan karena berisi peningkatan stabilitas. Untuk informasi tentang build pratinjau Windows, lihat Pratinjau Orang Dalam Windows 10.

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

Cuplikan layar UI Pencarian Windows dengan integrasi penyedia pencarian pihak ke-3.

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. Pengguna dapat menambahkan penyedia pencarian ke Windows dengan menginstal paket aplikasi terkait dan dapat menghapus penyedia pencarian melalui halaman Tambahkan atau hapus program di aplikasi Pengaturan Windows.

Untuk pengembangan dan pengujian, ketika Mode Pengembang diaktifkan dan aplikasi penyedia pencarian telah dimuat samping pada perangkat, itu akan muncul dalam daftar penyedia pencarian yang tersedia. Untuk informasi selengkapnya, lihat Fitur dan penelusuran kesalahan Mode 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 didokumentasikan dalam referensi skema 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 membutuhkan 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

  Endpoint

  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.

DynamicContentEndpoint

URL titik akhir HTTPS tempat OS akan mengirim permintaan agar ikon gleam ditampilkan di kotak pencarian. Untuk informasi selengkapnya, lihat Menerapkan titik akhir ikon gleam. Fitur ini didukung dimulai dengan windows 10 build 19045.4233 dan Windows 11 build 22621.3371.

Contoh file manifes paket

Berikut ini adalah contoh appmanifest.xml file manifes paket 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>
        <DynamicContentEndpoint>https://sub.contoso.com/dynamic</DynamicContentEndpoint>
		  </uap3:Properties>
	  </uap3:AppExtension>
  </uap3:Extension>
  <uap:Extension Category="windows.protocol">
	  <uap:Protocol Name="customsearch"/>
  </uap:Extension>

Menerapkan titik akhir saran penyedia Windows Search

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 saran

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.

Parameter Deskripsi
setlang Lokal yang terkait dengan kueri.
cc Kode negara yang terkait dengan kueri.
qry Kueri yang disediakan 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. CATATAN OS tidak melakukan sanitasi string kueri. Penyedia pencarian dapat menerapkan sanitasi mereka sendiri saat kueri diterima.

Header respons HTTPS saran

Penyedia pencarian harus menyertakan header berikut dalam respons dari titik akhir HTTPS saran.

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

Format JSON respons 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.
Atribut Berisi atribut saran.
url URL untuk saran pencarian di situs web penyedia.
pertanyaan Kueri pengguna yang terkait dengan saran pencarian.
previewPaneUrl URL titik akhir pratinjau tempat pratinjau HTML 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 Windows Search

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.

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

Pratinjau header respons HTTPS

  • Access-Control-Allow-Origin: https://www.bing.com
  • Access-Control-Allow-Credentials: true
  • 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)

Penyedia pencarian harus mendukung metode permintaan OPTIONS dan merespons permintaan ini dengan HTTP OK. Jika titik akhir penyedia pencarian menggunakan CORS, klien pencarian Windows akan mengirimkan permintaan HTTP OPTIONS sebelum setiap permintaan GET.

Menerapkan titik akhir ikon berkilau

Penyedia pencarian dapat secara opsional menyediakan ikon cahaya dan mode gelap yang ditampilkan di bilah pencarian saat penyedia pencarian saat ini diaktifkan. Ketika elemen DynamicContentEndpoint disediakan dalam manifes aplikasi, permintaan akan dikirim ke URL yang ditentukan dan penyedia pencarian merespons dengan file json dalam format yang ditentukan di bawah ini yang mencakup URL file gambar ikon dan metadata lainnya. Permintaan ikon gleam akan dikirim secara berkala sementara penyedia pencarian adalah penyedia terbaru yang aktif di Windows Search. Irama untuk permintaan ini adalah setiap 6 jam. Permintaan juga akan dikirim pada setiap peluncuran Pencarian dan pada buka kunci perangkat.

Format permintaan HTTPS ikon Gleam

Permintaan HTTPS ke titik akhir ikon cahaya menggunakan format berikut.

https://www.contoso.com/Gleam?cc=FR&setlang=en-us&dateTime=3%2F29%2F2024%2C%208%3A33%3A56%20PM&deviceOs=windows10&schemaversion=1.0.0

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

Parameter Deskripsi
setlang Lokal yang terkait dengan kueri.
cc Kode negara yang terkait dengan kueri.
tanggalWaktu Tanggal dan waktu saat ini dari perangkat klien, dikodekan url.
deviceOs OS perangkat klien. Nilai parameter ini dapat berupa "Windows10" atau "Windows11". Pada Windows 10, ukuran ikon gleam adalah 30x60. Pada Windows 11, ukuran ikon gleam adalah 20x36
skemaversi Versi skema gleam.

Format JSON respons ikon Gleam

Titik akhir HTTPS penyedia pencarian untuk ikon gleam harus mengembalikan dokumen JSON dengan format berikut. Nama kunci harus sama persis dengan format. Versi skema saat ini adalah 1.0.0.

Kunci Deskripsi
schemaVersion Versi skema gleam. Ini harus cocok dengan parameter string kueri schemaVersion dalam permintaan.
telemetryId Pengidentifikasi unik untuk ikon gleam. Jika nilai dalam respons sama dengan nilai untuk ikon gleam saat ini, OS tidak akan memperbarui ikon.
expirationTime Waktu kedaluwarsa untuk ikon gleam. Harus waktu di masa depan.
konten Bagian konten respons.
taskbarSearchBox Berisi pengaturan untuk kotak pencarian.
berkilau Berisi pengaturan untuk ikon gleam.
altText Teks alternatif untuk ikon gleam.
dimensionEnum Nilai "30x60" jika permintaan dikirim dari perangkat Windows 10. Nilai "20x36" jika permintaan dikirim dari perangkat Windows 11.
iconUrl Berisi URL untuk file gambar ikon cahaya dan gelap.
terang URL untuk file gambar ikon cahaya berkilau.
gelap URL untuk file gambar ikon cahaya gelap. 
{
  "schemaVersion":"1.0.0",
  "telemetryId":"<unique gleam Id>",
  "expirationTime":"2025-12-09T20:37:13Z",
  "content": {
    "taskbarSearchBox": {
      "gleam":{
        "altText": "<alt text of the gleam>",
        "dimensionEnum": "(30x60 for Windows 10, 20x36 for Windows 11)",
        "iconUrl": {
          "light":"<3p's light gleam url>",
          "dark": "<3p's dark gleam url>"
        }
      }
    }
  }
}

Validasi respons ikon Gleam

Respons harus menentukan URL aset terang dan URL aset gelap. Domain untuk URL gambar ikon harus menggunakan HTTPS dan subdomain harus cocok dengan subdomain yang ditentukan dalam elemen DynamicContentEndpoint dalam file manifes aplikasi.

File gambar harus dalam format SVG dan ukuran file maksimum adalah 300 kB. Gleam harus berada dalam bingkai 240x120px di dalam SVG.

Jika payload kosong diterima, itu akan menghapus ikon gleam aktif dan tidak ada gleam yang akan ditampilkan.