Windows Arama web araması sağlayıcıları

Windows Arama şu anda web içeriğini ve arama sonuçlarını döndürmek için Microsoft Bing uygulamasından Web Araması'nı kullanıyor. Avrupa Ekonomik Alanı'nda (EEA), Windows Arama'da web içeriği ve arama sonuçları döndürmek için bir web arama sağlayıcısı uygulayan uygulamalar yükleyebilirsiniz.

Windows Arama Kullanıcı Arabirimi Ekran Görüntüsü ve 3. taraf arama sağlayıcısı entegrasyonu.

Arama sağlayıcıları, arama sağlayıcısını kaydetmek için işletim sistemi için gerekli bilgileri sağlayan bir paket bildirim dosyasıyla bir MSIX paketi oluşturarak Arama deneyimiyle tümleşir. Yüklemeden sonra, arama sağlayıcısı Windows Arama deneyimlerinde varsayılan olarak etkinleştirilir. Windows Ayarları'nda kullanıcılar yüklü arama sağlayıcılarını etkinleştirebilir ve devre dışı bırakabilir ve arama sonuçlarında sağlayıcıların sırasını yönetebilir. Kullanıcılar, Windows Ayarları'ndaki Settings > Apps > Yüklü uygulamalar sayfasından bir arama sağlayıcısını kaldırabilir.

Geliştirme ve test için Geliştirici Modu etkinleştirildiğinde ve arama sağlayıcısı uygulaması cihaza dışarıdan yüklendiğinde, kullanılabilir arama sağlayıcıları listesinde görünür. Daha fazla bilgi için bkz. Geliştiriciler için ayarlar.

Arama sağlayıcısı işletim sistemine kaydedildikten sonra, kullanıcı sorguları standartlaştırılmış bir sorgu dizesi kullanılarak sağlayıcı tarafından paket bildiriminde belirtilen HTTP uç noktasına geçirilir. Uç nokta, JSON belgesinde önerilen sonuçları döndürür. Yanıt belgesinde önerilen her URL ile arama sağlayıcısı, arama sonuçları kullanıcı arabirimindeki önizleme bölmesinde görüntülenen bir HTML belgesi döndüren önizleme uç noktası URL'sini içerir.

Bu makalede arama sağlayıcısı uygulama paketi oluşturmaya yönelik yönergeler ve arama sağlayıcısı HTTP uç noktalarını uygulamaya yönelik protokoller hakkında ayrıntılar sağlanır.

Arama genişletilebilirliği uygulama paketi oluşturma

Arama sağlayıcıları, arama sağlayıcısının adı ve öneriler ve önizlemeler için HTTP uç noktaları gibi sağlayıcı hakkında gerekli bilgileri içeren bir MSIX paketi sağlayarak işletim sistemine kaydolur.

Arama sağlayıcısı uygulama uzantısı

Uygulama paketi bildirim dosyası, Windows uygulamalar için birçok farklı uzantıyı ve özelliği destekler. Uygulama paketi bildirim biçimi, Paket bildirim şeması referansı belgelenen bir dizi şema tarafından tanımlanır. Arama sağlayıcıları kayıt bilgilerini uap3:AppExtension içinde bildirir. Uzantının Name özniteliği "com.microsoft.windows.websearchprovider" olarak ayarlanmalıdır.

Arama sağlayıcıları uap3:Properties öğesini uap3:AppExtension öğesinin alt öğesi olarak içermelidir. Paket bildirimi şeması, iyi biçimlendirilmiş XML gerektirme dışında uap3:Properties öğesinin yapısını zorlamaz. Bu bölümün geri kalanında, bir arama sağlayıcısını başarıyla kaydetmek için işletim sisteminin beklediği XML biçimi açıklanmaktadır.

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

Öğe hiyerarşisi

uap3:Özellikler

  Bitiş noktası

  Protokol

Bitiş noktası

İşletim sisteminin arama sorgusu istekleri göndereceği HTTPS uç noktasının URL'si.

Protokol

Sağlanan web arama sonuçları başlatılırken kullanılacak protokol şeması. Belirtilen protokol işletim sistemindeki bir uygulama tarafından kaydedilmediyse, arama sonuçları için varsayılan tarayıcı başlatılır. Protokol şemalarını kaydetme hakkında daha fazla bilgi için bkz. uap:Protocol.

Dinamik İçerik Uç Noktası

Bu özellik artık desteklenmiyor. Daha fazla bilgi için, bkz. Bir parıldama simgesi uç noktasını yapılandırma. İşletim sisteminin arama kutusunda parıldama simgesinin görüntülenmesi için istek göndereceği HTTPS uç noktasının URL'si.

Örnek paket bildirim dosyası

Aşağıda, Windows Arama sağlayıcısını kaydetmek için örnek bir appmanifest.xml paket bildirim dosyası verilmiştir.

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

Windows Arama sağlayıcısı öneri uç noktası uygulama

Arama sağlayıcıları, bir kullanıcı Windows Arama kutusuna yazdığınızda işletim sistemi tarafından çağrılan bir HTTPS uç noktasını kullanıma sunmalı ve kaydedmelidir. Bu uç nokta, sağlanan kullanıcı sorgusu için arama önerilerini içeren JSON biçimli bir dize döndürmelidir. İçerik HTTPS üzerinden teslim edilmelidir. Arama tümleştirmesi HTTP üzerinden teslim edilen içeriği desteklemez.

Öneri HTTPS isteği biçimi

Öneri uç noktasına yapılan HTTPS isteği aşağıdaki biçimi kullanır.

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

Öneri uç noktasına geçirilen sorgu dizesi parametreleri şunlardır.

Parametre Açıklama
setlang Sorguyla ilişkilendirilmiş yerel ayar.
bilgi Sorguyla ilişkili ülke kodu.
qry Kullanıcı tarafından sağlanan sorgu. Parametresinin değeri yoksa, yani sorgu dizesinde olarak qry=görünürse, kullanıcı sorgusu boş olur. Arama sağlayıcıları boş bir sorguya yanıt olarak öneriler ve önizleme sayfaları sağlamaya devam edebilir. NOT İşletim sistemi, sorgu dizelerini temizleme işlemi gerçekleştirmez. Arama sağlayıcıları, sorgu alındığında kendi temizleme işlemlerini gerçekleştirebilir.

HTTPS yanıt üst bilgileri için öneriler

Arama sağlayıcısı, öneri HTTPS uç noktasından gelen yanıta aşağıdaki üst bilgileri içermelidir.

  • Access-Control-Allow-Origin: https://www.bing.com
  • Erişim-Kontrol-Izin-Kimlik-Bilgileri: true
  • Yöntemlere İzin Verildi - Access-Control-Allow-Methods: GET
  • İçerik Türü: application/json; charset=utf-8
  • İçerik Uzunluğu: [Yanıtın tam uzunluğu olmalıdır]

Öneri yanıtı JSON biçimi

Öneriler için arama sağlayıcısı HTTPS uç noktası aşağıdaki biçime sahip bir JSON belgesi döndürmelidir. Anahtar adları biçimle tam olarak eşleşmelidir.

Anahtar Açıklama
Öneriler Kullanıcı sorgusuyla ilişkili önerileri temsil eden anahtara Attributes sahip JSON nesnelerinin listesini içerir.
Özellikler Bir önerinin özniteliklerini içerir.
URL Sağlayıcı web sitesindeki arama önerisinin URL'si.
sorgu Arama önerisiyle ilişkili kullanıcı sorgusu.
previewPaneUrl Önerinin HTML önizlemesinin alınabildiği önizleme uç noktasının URL'si.
Metin Önerinin metin açıklaması. 
{"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"}
    ] 
}

Windows Arama sağlayıcısı için önizleme uç noktasını uygula.

Arama sağlayıcıları, arama sonuçlarındaki her öneriyle ilişkili sayfanın HTML önizlemesini sağlayan bir HTTPS uç noktasının URL'sini döndürür. Önizleme uç noktası yanıtı, işlevli bir sayfanın HTML kodunu döndürmelidir.

Önizleme HTTPS istek formatı

Önizleme uç noktasına yapılan HTTPS isteği aşağıdaki biçimi kullanır.

https://contoso.com?Darkschemeovr=1

Öneri uç noktasına geçirilen sorgu dizesi parametreleri şunlardır.

Parametre Açıklama
Darkschemeovr Çağrı Windows sisteminde koyu temanın etkinleştirilip etkinleştirilmediğini belirtir. Koyu tema etkinse değer 1, koyu tema devre dışıysa 0 olur.

HTTPS yanıt üst bilgilerini önizleme

  • Access-Control-Allow-Origin: https://www.bing.com
  • Erişim-Kontrol-Izin-Kimlik-Bilgileri: true
  • Yöntemlere İzin Verildi - Access-Control-Allow-Methods: GET
  • İçerik Türü: metin/html; charset=utf-8
  • İçerik Uzunluğu: [Önizleme html'sinin tam uzunluğu olmalıdır]

OPTIONS isteği ve Kökenler Arası Kaynak Paylaşımı (CORS)

Arama sağlayıcıları OPTIONS istek yöntemini desteklemeli ve HTTP Tamam ile bu isteğe yanıt vermelidir. Arama sağlayıcısı uç noktası CORS kullanıyorsa, Windows arama istemcisi her GET isteğinden önce bir HTTP OPTIONS isteği gönderir.

Parıldama simgesi uç noktasını oluştur

Uyarı

Bu parıldama özelliği artık etkin değil. Parıldama simgeleri artık Avrupa Ekonomik Alanı'ndaki tüm web hizmet sağlayıcıları için görüntülenmiyor. Belgelerin bu bölümündeki içerik kullanımdan kaldırılmıştır.

Arama sağlayıcıları isteğe bağlı olarak, arama sağlayıcısı şu anda etkin olduğunda arama çubuğunda görüntülenen açık ve koyu mod parıldama simgeleri sağlayabilir. Uygulama bildiriminde DynamicContentEndpoint öğesi sağlandığında, belirtilen URL'ye bir istek gönderilir ve arama sağlayıcısı simge görüntüsü dosyalarının ve diğer meta verilerin URL'lerini içeren aşağıda tanımlanan biçimde bir json dosyasıyla yanıt verir. Arama sağlayıcısı Windows Arama'da etkin olan en son sağlayıcıyken, parıldama simgesi isteği düzenli aralıklarla gönderilir. Bu isteğin gerçekleştirilme sıklığı 6 saatte birdir. Her Arama başlatması ve cihaz kilidi açma sırasında da bir istek gönderilir.

HTTPS istek biçimi için Parıldama simgesi

Parıldama simgesi uç noktasına yapılan HTTPS isteği aşağıdaki biçimi kullanır.

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

Öneri uç noktasına geçirilen sorgu dizesi parametreleri şunlardır.

Parametre Açıklama
setlang Sorguyla ilişkilendirilmiş yerel ayar.
bilgi Sorguyla ilişkili ülke kodu.
tarih ve saat İstemci cihazından url ile kodlanmış geçerli tarih ve saat.
cihaz işletim sistemi İstemci cihazının işletim sistemi. Bu parametrenin değeri "Windows10" veya "Windows11" olabilir. Windows 10'de parıldama simgesi boyutu 30x60'tır. Windows 11'de parıldama simgesinin boyutu 20x36'dır
schemaversion Gleam şeması sürümü.

Gleam simgesi yanıt JSON biçimi

Parıldama simgeleri için arama sağlayıcısı HTTPS uç noktası aşağıdaki biçime sahip bir JSON belgesi döndürmelidir. Anahtar adları biçimle tam olarak eşleşmelidir. Geçerli şema sürümü 1.0.0'dır.

Anahtar Açıklama
şema versiyonu Gleam şeması sürümü. Bu, istekteki schemaVersion sorgu dizesi parametresiyle eşleşmelidir.
telemetriKimliği Parıldama simgesi için benzersiz bir tanımlayıcı. Yanıttaki değer geçerli parıldama simgesinin değeriyle aynıysa, işletim sistemi simgeyi güncelleştirmez.
son kullanma zamanı Parıldama simgesinin son kullanma süresi. Gelecekte bir zaman olmalı.
içerik Yanıtın içerik bölümü.
görev çubuğu arama kutusu Arama kutusunun ayarlarını içerir.
parıltı Parıldama simgesinin ayarlarını içerir.
altText Parıldama simgesi için alternatif metin.
DimensionEnum İstek bir Windows 10 cihazdan gönderildiyse "30x60" değeri. İstek bir Windows 11 cihazından gönderildiyse "20x36" değeri.
simge URL'si Açık ve koyu parıldama simgesi görüntü dosyalarının URL'lerini içerir.
ışık Işık yansıması simgesi görüntü dosyasının URL'si.
karanlık Koyu parıldama simgesi resim dosyasının URL'si. 
{
  "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>"
        }
      }
    }
  }
}

Parıldama simgesi yanıt doğrulaması

Yanıt hem açık varlık URL'sini hem de koyu varlık URL'sini belirtmelidir. Simge görüntüsü URL'lerinin etki alanları HTTPS kullanmalıdır ve alt etki alanı, uygulama bildirim dosyasındaki DynamicContentEndpoint öğesinde belirtilen alt etki alanıyla eşleşmelidir.

Görüntü dosyalarının SVG biçiminde olması ve en büyük dosya boyutunun 300 kB olması gerekir. Parıldama, SVG'nin içinde 240x120px boyutlarında bir çerçevede olmalıdır.

Boş bir yük alınırsa, etkin parıldama simgesini temizler ve hiçbir parıldama görüntülenmez.

  • Last updated on