Поделиться через

Поставщики веб-поиска для Windows Search

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

Снимок экрана: пользовательский интерфейс поиска Windows с интеграцией сторонних поставщиков поиска.

Поставщики поиска интегрируются с системой поиска, создавая пакет MSIX с файлом манифеста пакета, который предоставляет необходимые сведения для регистрации поставщика поиска операционной системой. После установки поставщик поиска включен по умолчанию в интерфейсах поиска Windows. В приложении параметров 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:Свойства

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

  Протокол

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

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

Протокол

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

ДинамическоеСодержимоеКонечнаяТочка

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

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

Ниже приведен пример 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=

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

Параметр Описание
setlang Локаль, ассоциированная с запросом.
копия Код страны, связанный с запросом.
qry Запрос, предоставленный пользователем. Если параметр не имеет значения, т. е. отображается в строке запроса как 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 со следующим форматом. Имена ключей должны точно соответствовать формату.

Ключ Описание
Предложения Содержит список объектов JSON с ключом Attributes , представляющим предложения, связанные с запросом пользователя.
Атрибуты Содержит атрибуты предложения.
URL-адрес URL-адрес предложения поиска на веб-сайте поставщика.
запрос Запрос пользователя, связанный с предложением поиска.
URL окна предварительного просмотра URL-адрес конечной точки предварительной версии, из которой можно получить HTML-предварительную версию предложения.
Текст Текстовое описание предложения. 
{"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

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

Параметр Описание
Darkschemeovr Указывает, включен ли темный режим на вызываемой системе Windows. Значение равно 1, если темная тема включена и 0, если темная тема отключена.

Предварительный просмотр заголовков ответов 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.

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

Замечание

Эта функция блеска больше не включена. Значки gleam больше не отображаются для всех веб-поставщиков в EEA. Содержимое этого раздела документации устарело.

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

Формат запроса HTTPS для значка Gleam

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

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

Параметр Описание
setlang Локаль, ассоциированная с запросом.
копия Код страны, связанный с запросом.
дата и время Текущие дата и время с клиентского устройства, закодированные в формате URL.
операционная система устройства ОС клиентского устройства. Значение этого параметра может быть "Windows10" или "Windows11". В Windows 10 размер значка блеска составляет 30x60. В Windows 11 размер значка блеска составляет 20x36
schemaversion Версия схемы блеска.

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

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

Ключ Описание
schemaVersion Версия схемы блеска. Это должно соответствовать параметру строки запроса schemaVersion в запросе.
идентификатор телеметрии Уникальный идентификатор значка блеска. Если значение в ответе совпадает со значением для текущего значка блеска, ОС не обновит значок.
время истечения срока Время окончания срока действия значка блеска. Должно быть время в будущем.
содержимое Раздел содержимого ответа.
поисковая строка панели задач Содержит параметры для поля поиска.
проблеск Содержит параметры значка блеска.
альтТекст Альтернативный текст для значка блеска.
dimensionEnum Значение "30x60", если запрос был отправлен с устройства Windows 10. Значение "20x36", если запрос был отправлен с устройства Windows 11.
iconUrl Содержит URL-адреса для файлов изображений значков светлого и темного блеска.
свет URL-адрес файла изображения значка светлого блеска.
темный URL файла изображения значка с темным отблеском. 
{
  "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>"
        }
      }
    }
  }
}

Проверка реакции на значок Gleam

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

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

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