Поставщики поиска Windows

В настоящее время Поиск Windows использует веб-поиск из приложения Microsoft Bing для возврата веб-содержимого и результатов поиска. В Европейской экономической зоне (EEA) можно включить установленные приложения, которые реализуют поставщик веб-поиска для возврата веб-содержимого и результатов поиска в Поиске Windows с помощью параметров.

Поставщики поиска интегрируются с интерфейсом поиска, создавая пакет MSIX с файлом манифеста пакета, который предоставляет необходимые сведения для регистрации поставщика поиска ос. Пользователи могут добавить поставщика поиска в Windows, установив связанный пакет приложения и удалив поставщик поиска с помощью страницы "Добавление или удаление программ " в приложении "Параметры Windows".

Для разработки и тестирования, если режим разработчика включен и приложение поставщика поиска было загружено на устройстве, оно появится в списке доступных поставщиков поиска. Дополнительные сведения см. в разделе "Режим разработчика" и "Отладка".

После регистрации поставщика поиска в ОС запросы пользователей передаются в конечную точку HTTP, указанную поставщиком в манифесте пакета, используя стандартизованную строку запроса. Конечная точка возвращает предлагаемые результаты в документе JSON. С каждым предлагаемым URL-адресом в документе ответа поставщик поиска включает URL-адрес конечной точки предварительного просмотра, который возвращает HTML-документ, отображаемый в области предварительного просмотра в пользовательском интерфейсе результатов поиска.

В этой статье приводятся рекомендации по созданию пакета приложения поставщика поиска и сведения о протоколах для реализации конечных точек HTTP поставщика поиска.

Создание пакета приложения расширения поиска

Поставщики поиска регистрируются в ОС, предоставляя пакет MSIX, содержащий необходимые сведения о поставщике, например имя поставщика поиска и конечные точки HTTP для предложений и предварительных версий.

Расширение приложения поставщика поиска

Файл манифеста пакета приложения поддерживает множество различных расширений и функций для приложений Windows. Формат манифеста пакета приложения определяется набором схем, которые описаны в справочнике по схеме манифеста пакета. Поставщики поиска объявляют свои сведения о регистрации в uap3:AppExtension. Атрибут Name расширения должен иметь значение com.microsoft.windows.websearchprovider.

Поставщики поиска должны включать uap3:Properties в качестве дочернего элемента uap3:AppExtension. Схема манифеста пакета не применяет структуру элемента uap3:Properties, отличного от необходимости хорошо сформированного XML. В остальной части этого раздела описывается формат XML, который ос ожидает для успешной регистрации поставщика поиска.

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

Иерархия элементов

uap3:Properties

  EndPoint

  Протокол

Конечная точка

URL-адрес конечной точки HTTPS, в которую ОС отправляет запросы поиска.

Протокол

Схема протокола, которая будет использоваться при запуске предоставленных результатов поиска в Интернете. Если указанный протокол не зарегистрирован приложением в ОС, браузер по умолчанию будет запущен для результатов поиска. Дополнительные сведения о регистрации схем протокола см. в разделе uap:Protocol.

DynamicContentEndpoint

URL-адрес конечной точки HTTPS, в которую ОС отправляет запрос на отображение значка блеска в поле поиска. Дополнительные сведения см. в разделе "Реализация конечной точки значка блеска". Эта функция поддерживается начиная с сборки Windows 10 19045.4233 и Windows 11 сборки 22621.3371.

Пример файла манифеста пакета

Ниже приведен пример appmanifest.xml файла манифеста пакета для регистрации поставщика поиска 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>

Реализация конечной точки предложения поставщика поиска Windows

Поставщики поиска должны предоставлять и регистрировать конечную точку HTTPS, вызываемую ОС, когда пользователь вводит в поле поиска Windows. Эта конечная точка должна возвращать строку в формате JSON, содержащую предложения поиска для предоставленного пользовательского запроса. Содержимое должно быть доставлено по протоколу HTTPS. Интеграция поиска не поддерживает содержимое, доставленное по протоколу HTTP.

Формат запроса HTTPS предложения

HTTPS-запрос к конечной точке предложения использует следующий формат.

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

Параметры строки запроса, передаваемые конечной точке предложения, приведены ниже.

Предложения заголовков ответов HTTPS

Поставщик поиска должен содержать следующие заголовки в ответе от конечной точки HTTPS предложения.

• 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
• Длина содержимого: [должна быть точной длиной ответа]

Формат JSON ответа предложения

Конечная точка HTTPS поставщика поиска для предложений должна возвращать документ JSON со следующим форматом. Имена ключей должны точно соответствовать формату.

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

Поставщики поиска возвращают URL-адрес конечной точки HTTPS, которая предоставляет html-предварительный просмотр страницы, связанной с каждым предложением в результатах поиска. Ответ конечной точки предварительной версии должен возвращать HTML-код для работающей страницы.

Предварительный просмотр формата запроса HTTPS

HTTPS-запрос к конечной точке предварительной версии использует следующий формат.

https://contoso.com?Darkschemeovr=1

Параметры строки запроса, передаваемые конечной точке предложения, приведены ниже.

Предварительный просмотр заголовков ответов HTTPS

• Access-Control-Allow-Origin: https://www.bing.com
• Access-Control-Allow-Credentials: true
• Access-Control-Allow-Methods: GET
• Content-Type: text/html; charset=utf-8
• Длина содержимого: [должна быть точной длиной предварительного просмотра html]

Запрос OPTIONS и общий доступ к ресурсам между источниками (CORS)

Поставщики поиска должны поддерживать метод запроса OPTIONS и отвечать на этот запрос с помощью HTTP OK. Если конечная точка поставщика поиска использует CORS, клиент поиска Windows отправит HTTP-запрос OPTIONS перед каждым запросом GET.

Реализация конечной точки значка блеска

Поставщики поиска могут при необходимости предоставлять светлые и темные значки блеска режима, отображаемые в строке поиска при включении поставщика поиска. Если элемент DynamicContentEndpoint указан в манифесте приложения, запрос будет отправлен на указанный URL-адрес, а поставщик поиска отвечает с json-файлом в формате, определенном ниже, который содержит URL-адреса файлов изображений значков и другие метаданные. Запрос значка блеска будет отправляться периодически, пока поставщик поиска является самым последним поставщиком, активным в Поиске Windows. Частота этого запроса составляет каждые 6 часов. Запрос также будет отправлен при каждом запуске поиска и разблокировке устройства.

Формат запроса HTTPS значка глама

HTTPS-запрос к конечной точке значка блеска использует следующий формат.

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

Параметры строки запроса, передаваемые конечной точке предложения, приведены ниже.

Формат JSON ответа значка глама

Конечная точка HTTPS поставщика поиска для значков блеска должна возвращать документ JSON со следующим форматом. Имена ключей должны точно соответствовать формату. Текущая версия схемы — 1.0.0.

{
  "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>"
        }
      }
    }
  }
}

Проверка ответа на значок глама

Ответ должен указать URL-адрес светлого ресурса и URL-адрес темного ресурса. Домены для URL-адресов изображения значков должны использовать HTTPS, а поддомен должен соответствовать поддомену, указанному в элементе DynamicContentEndpoint в файле манифеста приложения.

Файлы изображений должны находиться в формате SVG, а максимальный размер файла — 300 кб. Блеск должен находиться в рамке 240x120px внутри SVG.

Если получена пустая полезные данные, это приведет к очистке активного значка блеска и не будет отображаться блеск.

Связанные статьи