Создание файла описания OpenSearch в федеративном поиске Windows

Описывает, как создать osdx-файл описания OpenSearch для подключения внешних хранилищ данных к клиенту Windows по протоколу OpenSearch . Федеративный поиск позволяет пользователям выполнять поиск в удаленном хранилище данных и просматривать результаты в windows Обозреватель.

Этот раздел состоит из следующих подразделов.

• Файл описания OpenSearch
  • Минимальные обязательные дочерние элементы
• Стандартные элементы в федеративном поиске Windows
  • Короткое имя
  • Описание
  • Шаблон URL-адреса для результатов RSS/Atom
  • Шаблон URL-адреса для веб-результатов
  • Параметры шаблона URL-адреса
  • Страничные результаты
  • Разбиение по страницам с помощью индекса элемента
  • Разбиение по страницам с использованием индекса страницы
  • Page Size
• Расширенные элементы в федеративном поиске Windows
  • Максимальное число результатов
  • Сопоставление свойств
• Предварительные версии
• Пункт меню "Открыть расположение файла"
• Дополнительные ресурсы
• Связанные темы

Файл описания OpenSearch

Файл описания OpenSearch (OSDX) для федеративного поиска Windows должен соответствовать следующим правилам:

• Быть допустимым документом описания OpenSearch, как определено в спецификации OpenSearch 1.1.
• Укажите шаблон URL-адреса с типом формата RSS или Atom.
• Используйте расширение OSDX или при скачивании из Интернета. Например, для использования OSDX сервер не требуется. Сервер может вернуть файл с любым расширением имени файла, например .xml, и обрабатывать его как OSDX-файл, если он использует правильный тип MIME для документов описания OpenSearch (OSDX-файлы).
• Укажите значение элемента ShortName (рекомендуется).

Минимальные обязательные дочерние элементы

Следующий пример OSDX-файла состоит из элементов ShortName и Url , которые являются минимальными обязательными дочерними элементами.

<OpenSearchDescription xmlns="https://a9.com/-/spec/opensearch/1.1/">
    <ShortName>My web Service</ShortName>
    <Url format="application/rss+xml" 
        template="https://example.com/rss.php?query=
        {searchTerms}&amp;start={startIndex}&amp;cnt={count}" />
</OpenSearchDescription>

Стандартные элементы в федеративном поиске Windows

Помимо минимальных дочерних элементов федеративный поиск поддерживает следующие стандартные элементы.

Короткое имя

Windows использует значение элемента ShortName , чтобы присвоить имя файлу .searchconnector-ms (соединитель поиска), который создается при открытии OSDX-файла пользователем. Windows гарантирует, что в созданном имени файла используются только символы, допустимые в именах файлов Windows. Если значение ShortName не указано, файл .searchconnector-ms пытается использовать имя osdx-файла.

В следующем коде показано, как использовать элемент ShortName в OSDX-файле.

<OpenSearchDescription xmlns="https://a9.com/-/spec/opensearch/1.1/">
    <ShortName>My web Service</ShortName>
    ...
</OpenSearchDescription>

Описание

Windows использует значение элемента Description для заполнения описания файла, отображаемого в области сведений Обозреватель Windows, когда пользователь выбирает файл SEARCHCONNECTOR-MS.

<OpenSearchDescription xmlns="https://a9.com/-/spec/opensearch/1.1/">
    ...
    <Description>Searches the example company book catalog</Description>
</OpenSearchDescription>

Шаблон URL-адреса для результатов RSS/Atom

OSDX-файл должен содержать один элемент формата URL-адреса и атрибут шаблона (шаблон URL-адреса), который возвращает результаты в формате RSS или Atom. Атрибут format должен иметь значение application/rss+xml для результатов в формате RSS или application/atom+xml для результатов в формате Atom, как показано в следующем коде.

Примечание

Элемент формата URL и атрибут шаблона обычно называются шаблоном URL-адреса.

 

<OpenSearchDescription xmlns="https://a9.com/-/spec/opensearch/1.1/">
   ...
        <Url format="application/rss+xml" template="https://example.com/rss.php?query=
            {searchTerms}&amp;start={startIndex}&amp;cnt={count}" />
</OpenSearchDescription>

Шаблон URL-адреса для веб-результатов

Если имеется версия результатов поиска, которую можно просмотреть в веб-браузере, необходимо указать элемент Url format=text/html и атрибут шаблона , как показано в следующем коде.

<OpenSearchDescription xmlns="https://a9.com/-/spec/opensearch/1.1/">
    ...
    <Url format="text/html" template="https://example.com/html.php?query={searchTerms}" />
</OpenSearchDescription>

Если указать элемент Url format="text/html" и атрибут шаблона, на панели команд Windows Обозреватель появится кнопка, как показано на следующем снимке экрана, которая позволяет пользователю открыть веб-браузер для просмотра результатов поиска, когда пользователь выполняет запрос.

В некоторых сценариях важно выполнить накат запроса обратно в пользовательский веб-интерфейс хранилища данных. Например, пользователю может потребоваться просмотреть более 100 результатов (количество элементов по умолчанию, запрашиваемых поставщиком OpenSearch). В этом случае пользователю также может потребоваться использовать функции поиска, доступные только на веб-сайте хранилища данных, такие как повторный запрос с другим порядком сортировки или свертывание и фильтрация запроса с соответствующими метаданными.

Параметры шаблона URL-адреса

Поставщик OpenSearch всегда выполняет следующие действия:

1. Использует шаблон URL-адреса для отправки запроса в веб-службу.
2. Пытается заменить маркеры, найденные в шаблоне URL-адреса, перед отправкой запроса в веб-службу следующим образом:
   • Заменяет стандартные маркеры OpenSearch, перечисленные в следующей таблице.
   • Удаляет все маркеры, не перечисленные в следующей таблице.

Поддерживаемый маркер	Использование поставщиком OpenSearch
{searchTerms}	Заменены поисковыми терминами, введенными пользователем в поле ввода Обозреватель поиска Windows.
{startIndex}	Используется при получении результатов в "pages". Заменен индексом для первого возвращаемого элемента результата.
{startPage}	Используется при получении результатов в "pages". Заменен номером страницы возвращаемого набора результатов поиска.
{count}	Используется при получении результатов в "pages". Заменено числом результатов поиска на странице, запрашиваемых Windows Обозреватель.
{language}	Заменяется строкой, указывающей язык отправляемого запроса.
{inputEncoding}	Заменяется строкой (например, UTF-16), которая указывает кодировку символов отправляемого запроса.
{outputEncoding}	Заменяется строкой (например, "UTF-16"), которая указывает нужную кодировку символов для ответа от веб-службы.

 

Страничные результаты

Вы можете ограничить количество возвращаемых результатов для каждого запроса. Вы можете вернуть "страницу" результатов за один раз или предоставить поставщику OpenSearch дополнительные страницы результатов либо по номеру элемента, либо по номеру страницы. Например, если вы отправляете двадцать результатов на страницу, первая отправляемая страница начинается с индекса элемента 1 и на странице 1; вторая отправляемая страница начинается с индекса элемента 21 и со страницы 2. Вы можете определить, как поставщик OpenSearch будет запрашивать элементы, используя {startItem} маркер или {startPage} в шаблоне URL-адреса.

Разбиение по страницам с помощью индекса элемента

Индекс элемента идентифицирует первый элемент результата на странице результатов. Если вы хотите, чтобы клиенты отправляли запросы с помощью индекса элемента, можно использовать {startIndex} маркер в атрибуте шаблонаэлемента URL, как показано в следующем коде.

<Url format="application/rss+xml" 
    template="https://example.com/rss.php?query={searchTerms}&amp;start={startIndex}" />

Затем поставщик OpenSearch заменяет маркер в URL-адресе начальным значением индекса. Первый запрос начинается с первого элемента, как показано в следующем примере:

https://example.com/rss.php?query=frogs&start=1

Поставщик OpenSearch может получить дополнительные элементы, изменив {startIndex} значение параметра и отправив новый запрос. Поставщик повторяет этот процесс до тех пор, пока не получит достаточно результатов для удовлетворения предела или не достигнет конца результатов. Поставщик OpenSearch проверяет количество элементов, возвращаемых веб-службой на первой странице результатов, и устанавливает ожидаемый размер страницы в это число. Он использует это число для увеличения {startIndex} значения для последующих запросов. Например, если веб-служба возвращает 20 результатов в первом запросе, поставщик устанавливает ожидаемый размер страницы равным 20. Для следующего запроса поставщик заменяет {startIndex} значением 21, чтобы получить следующие 20 элементов.

Примечание

Если страница результатов, возвращаемая веб-службой, содержит меньше элементов, чем ожидаемый размер страницы, то поставщик OpenSearch предполагает, что он получил последнюю страницу результатов и перестает выполнять запросы.

 

Разбиение по страницам с использованием индекса страницы

Индекс страницы определяет указанную страницу результатов. Если вы хотите, чтобы клиенты отправляли запросы с помощью номера страницы, можно использовать {startPage} маркер в атрибуте шаблона элемента формата URL, чтобы указать это, как показано в следующем примере:

<Url format="application/rss+xml" 
    template="https://example.com/rss.php?query={searchTerms}&amp;page={startPage}" />

Затем поставщик OpenSearch заменяет маркер в URL-адресе параметром номера страницы. Первый запрос начинается с первой страницы, как показано в следующем примере:

https://example.com/rss.php?query=frogs&page=1

Примечание

Если страница результатов, возвращаемая веб-службой, содержит меньше элементов, чем ожидаемый размер страницы, то поставщик OpenSearch предполагает, что он получил последнюю страницу результатов и перестает выполнять запросы.

 

Page Size

Вы можете настроить веб-службу, чтобы разрешить запросу указать размер страниц с помощью параметра в URL-адресе. Запрос должен быть указан в OSDX-файле с помощью маркера {count} следующим образом:

<Url format="application/rss+xml" 
    template="https://example.com/rss.php?query={searchTerms}&amp;start={startIndex}&amp;cnt={count}" />

Затем поставщик OpenSearch может задать требуемый размер страницы в виде количества результатов на странице, как показано в следующем примере:

https://example.com/rss.php?query=frogs&start=1&cnt=50

По умолчанию поставщик OpenSearch отправляет запросы с размером страницы 50. Если вам нужен другой размер страницы, не предоставляйте {count} маркер и вместо этого поместите нужное число непосредственно в элемент шаблона URL.

Поставщик OpenSearch определяет размер страницы на основе количества результатов, возвращенных при первом запросе. Если на первой странице полученных результатов меньше элементов, чем запрошено, поставщик сбрасывает размер страницы для всех последующих запросов страницы. Если последующие запросы страницы возвращают меньше элементов, чем запрошено, поставщик OpenSearch предполагает, что он достиг конца результатов.

Расширенные элементы в федеративном поиске Windows

Помимо стандартных элементов федеративный поиск поддерживает следующие расширенные элементы: MaximumResultCount и ResultsProcessing.

Так как эти расширенные дочерние элементы не поддерживаются в спецификации OpenSearch версии 1.1, их необходимо добавить с помощью следующего пространства имен:

http://schemas.microsoft.com/opensearchext/2009/

Максимальное число результатов

По умолчанию соединители поиска ограничены 100 результатами на запрос пользователя. Это ограничение можно настроить, включив элемент MaximumResultCount в OSD-файл, как показано в следующем примере:

<OpenSearchDescription xmlns="https://a9.com/-/spec/opensearch/1.1/" 
    xmlns:ms-ose="http://schemas.microsoft.com/opensearchext/2009/">
        ...
        <ms-ose:MaximumResultCount>200</ms-ose:MaximumResultCount>
</OpenSearchDescription>

В предыдущем примере префикс ms-ose пространства имен объявляется в элементе OpenSearchDescription верхнего уровня, а затем используется в качестве префикса в имени элемента. Это объявление является обязательным, так как MaximumResultCount не поддерживается в спецификации OpenSearch версии 1.1.

Сопоставление свойств

Если веб-служба возвращает результаты в виде RSS-канала или веб-канала Atom, поставщик OpenSearch должен сопоставить метаданные элемента в веб-каналах со свойствами, которые может использовать оболочка Windows. На следующем снимке экрана показано, как поставщик OpenSearch сопоставляет некоторые элементы RSS по умолчанию.

Сопоставления по умолчанию

В следующей таблице перечислены сопоставления элементов RSS XML по умолчанию с системными свойствами оболочки Windows. ПУТИ XML относятся к элементу item. Префикс "media:" определяется пространством имен пространства имен поиска Yahoo .

Путь RSS XML	Свойство оболочки Windows (каноническое имя)
Ссылка	System.ItemUrl
Заголовок	System.ItemName
Автор	System.Author
pubDate	System.DateModified
Описание	System.AutoSummary
Категория	System.Keywords
корпус/@type	System.MIMEType
корпус/@length	System.Size
корпус/@url	System.ContentUrl
media:category	System.Keywords
media:content/@fileSize	System.Size
media:content/@type	System.MIMEType
media:content/@url	System.ContentUrl
media:group/content/@fileSize	System.Size
media:group/content/@type	System.MIMEType
media:group/content/@url	System.ContentUrl
media:thumbnail/@url	System.ItemThumbnailUrl

 

Примечание

В дополнение к сопоставлениям стандартных элементов RSS или Atom по умолчанию можно сопоставить другие системные свойства оболочки Windows, включив дополнительные XML-элементы в пространство имен Windows для каждого из свойств. Вы также можете сопоставить элементы из других существующих пространств имен XML, таких как MediaRSS, iTunes и т. д., добавив пользовательское сопоставление свойств в OSDX-файле.

 

Настраиваемые сопоставления свойств

Вы можете настроить сопоставление элементов из выходных RSS-данных с системными свойствами оболочки Windows, указав сопоставление в OSDX-файле.

Выходные данные RSS указывают:

• Пространство имен XML, и
• Для любого дочернего элемента элемента — имя элемента для сопоставления.

OSDX-файл определяет свойство оболочки Windows для каждого имени элемента в пространстве имен. Сопоставления свойств, определенные в OSDX-файле, переопределяют сопоставления по умолчанию, если они существуют, для указанных свойств.

На следующей схеме показано, как расширение RSS сопоставляется со свойствами Windows (каноническим именем).

Примеры результатов RSS и сопоставление свойств OSD

В следующем примере выходные https://example.com/schema/2009 данные RSS идентифицируются как пространство имен XML с префиксом "example". Этот префикс должен снова появиться перед элементом email .

<rss version="2.0" xmlns:example="https://example.com/schema/2009">
   ...
    <item>
      <title>Someone</title>
      <example:email>Someone@example.com</example:email>
    </item>

В следующем примере OSDX-файл XML-элемент электронной почты сопоставляется со свойством оболочки Windows System.Contact.EmailAddress.

<OpenSearchDescription xmlns="https://a9.com/-/spec/opensearch/1.1/"
    xmlns:ms-ose="http://schemas.microsoft.com/opensearchext/2009/">
...
 <ms-ose:ResultsProcessing format="application/rss+xml">
   <ms-ose:PropertyMapList>
     <ms-ose:PropertyMap sourceNamespaceURI="https://example.com/schema/2009/" >
       <ms-ose:Source path="email">
         <ms-ose:Property schema="http://schemas.microsoft.com/windows/2008/propertynamespace" name="System.Contact.EmailAddress" />
       </ms-ose:Source>
     </ms-ose:PropertyMap>
   </ms-ose:PropertyMapList>
 </ms-ose:ResultsProcessing>
...
</OpenSearchDescription>

Некоторые свойства не могут быть сопоставлены, так как значения для них либо переопределяются позже, либо недоступны для редактирования. Например, нельзя сопоставить System.ItemFolderPathDisplay или System.ItemPathDisplayNarrow , так как они вычисляются на основе значения URL-адреса, указанного в элементах link или enclosure.

Эскизы

URL-адреса эскизов можно указать для любого элемента с помощью элемента media:thumbnail url="". Идеальное разрешение — 150 x 150 пикселей. Самые большие поддерживаемые эскизы — 256 x 256 пикселей. Предоставление больших изображений требует большей пропускной способности, что не дает пользователю дополнительных преимуществ.

Открыть контекстное меню расположения файла

Windows предоставляет контекстное меню с именем Открыть расположение файла для элементов результатов. Если пользователь выбирает элемент в этом меню, открывается "родительский" URL-адрес выбранного элемента. Если URL-адрес является веб-URL-адресом, например https://..., открывается веб-браузер и переходит по его url-адресу. Ваш веб-канал должен предоставлять настраиваемый URL-адрес для каждого элемента, чтобы убедиться, что Windows открывает допустимый URL-адрес. Это можно сделать, включив URL-адрес в элемент в XML-код элемента, как показано в следующем примере:

<rss version="2.0" xmlns:example="https://example.com/schema/2009" 
    xmlns:win="http://schemas.microsoft.com/windows/2008/propertynamespace">
...
   <item>
      <title>Someone</title>
      <link>https://example.com/pictures.aspx?id=01</link>
      <win:System.ItemFolderPathDisplay>https://example.com/pictures_list.aspx
   </win:System.ItemFolderPathDisplay>
   </item>
...

Если это свойство не задано явным образом в XML-коде элемента, поставщик OpenSearch присваивает ему родительскую папку URL-адреса элемента. В приведенном выше примере поставщик OpenSearch будет использовать значение ссылки и задать для свойства System.ItemFolderPathDisplay значение "https://example.com/".

Настройка представлений Windows Обозреватель со списками описания свойств

Некоторые макеты представлений Windows Обозреватель определяются списками описания свойств или proplists. Proplist — это разделенный точкой с запятой список свойств, например "prop:System.ItemName; System.Author", который используется для управления тем, как результаты отображаются в Windows Обозреватель.

Области пользовательского интерфейса Windows Обозреватель, которые можно настроить с помощью proplists, показаны на следующем снимке экрана:

Каждая область Windows Обозреватель имеет связанный набор проплистов, которые сами указываются как свойства. Можно указать пользовательские проплисты для отдельных элементов в результирующем наборе или для всех элементов в наборе результатов.

Область пользовательского интерфейса для настройки	Свойство оболочки Windows, реализующее настройку
Режим просмотра содержимого (при поиске)	System.PropList.ContentViewModeForSearch
Режим просмотра содержимого (при просмотре)	System.PropList.ContentViewModeForBrowse
Режим представления плитки	System.PropList.TileInfo
Область сведений	System.PropList.PreviewDetails
Информационная подсказка (подсказка при наведении элемента)	System.PropList.Infotip

 

 

Чтобы указать уникальный proplist для отдельного элемента, выполните следующие действия.

1. В выходных данных RSS добавьте пользовательский элемент, представляющий список proplist, который вы хотите настроить. Например, в следующем примере задается список для области сведений:

   <win:System.PropList.PreviewDetails>
       prop:System.ItemName;System.Author</win:System.PropList.PreviewDetails>
   

2. Чтобы применить свойство к каждому элементу в результатах поиска без изменения выходных данных RSS, укажите proplist в элементе ms-ose:PropertyDefaultValues в OSDX-файле , как показано в следующем примере:

   <ms-ose:ResultsProcessing format="application/rss+xml">
       <ms-ose:PropertyDefaultValues>
         <ms-ose:Property schema="http://schemas.microsoft.com/windows/2008/propertynamespace"
           name="System.PropList.ContentViewModeForSearch">prop:~System.ItemNameDisplay;System.Photo.DateTaken;
           ~System.ItemPathDisplay;~System.Search.AutoSummary;System.Size;System.Author;System.Keywords</ms-ose:Property>
       </ms-ose:PropertyDefaultValues>
     </ms-ose:ResultsProcessing>
   

Макет свойств в режиме просмотра содержимого

Список свойств, указанных в элементах управления System.PropList.ContentViewModeForSearch и System.PropList.ContentViewModeForBrowse , определяет, что отображается в режиме просмотра содержимого. Дополнительные сведения о списках свойств см. в разделе PropList.

Свойства располагаются в соответствии с числами, показанными в следующем шаблоне макета:

Если мы используем следующий список свойств,

prop:~System.ItemNameDisplay;System.Author;System.ItemPathDisplay;~System.Search.AutoSummary;
    System.Size;System.Photo.DateTaken;System.Keywords

Затем отображается следующее:

Примечание

Для наилучшей удобочитаемости свойства, отображаемые в правом столбце, должны быть помечены.

 

Флаги списка свойств

Только один из флагов, определенных в документации proplists, применяется к отображению элементов в макетах режима просмотра содержимого: "~" . В предыдущих примерах представление Windows Обозреватель помечает некоторые свойства, например Tags: animals; zoo; lion. Это поведение по умолчанию при указании свойства в списке. Например, список proplist имеет "System.Author" значение , которое отображается как "Authors: value". Если вы хотите скрыть метку свойства, поместите "~" перед именем свойства . Например, если proplist содержит "~System.Size", свойство отображается как просто значение без метки.

Предварительные версии

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

Содержимое, отображаемое в режиме предварительного просмотра, задается URL-адресом, который определяется следующим образом:

1. Если для элемента задано свойство Оболочка Windows System.WebPreviewUrl , используйте этот URL-адрес.

   Примечание

   Свойство должно быть предоставлено в RSS с помощью пространства имен оболочки Windows или явно сопоставлено в OSDX-файле.

    

2. В противном случае используйте URL-адрес ссылки.

Эта логика показана на следующей блок-схеме.

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

Как Windows Обозреватель определяет, какой URL-адрес следует использовать:

1. Если вы предоставляете сопоставление с System.ItemFolderPathDisplay, windows Обозреватель использует этот URL-адрес.

2. Если сопоставление не указано, windows Обозреватель определяет, отличаются ли URL-адреса ссылки и корпуса. В этом случае Windows Обозреватель использует URL-адрес ссылки.

3. Если URL-адреса совпадают или есть только URL-адрес ссылки, windows Обозреватель анализирует ссылку, чтобы найти родительский контейнер, удалив имя файла из полного URL-адреса.

   Примечание

   Если вы понимаете, что анализ URL-адресов приведет к созданию неработающих ссылок для вашей службы, следует предоставить явное сопоставление для свойства .

    

Пункт меню "Открыть расположение файла"

При щелчке правой кнопкой мыши появляется команда Открыть расположение файла . Эта команда переносит пользователя в контейнер для этого элемента или его расположение. Например, при поиске SharePoint при выборе этого параметра для файла в библиотеке документов откроется корень библиотеки документов в веб-браузере.

Когда пользователь нажимает кнопку Открыть расположение файла, Windows Обозреватель пытается найти родительский контейнер, используя логику, показанную на следующей блок-схеме:

Дополнительные ресурсы

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

Связанные темы

Федеративный поиск в Windows

начало работы с федеративного поиска в Windows

Подключение веб-службы в федеративном поиске Windows

Включение хранилища данных в федеративном поиске Windows

Рекомендации по использованию федеративного поиска Windows

Развертывание соединителей поиска в федеративном поиске Windows