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

Описывает создание файла OpenSearch Description (OSDX) для подключения внешних хранилищ данных к клиенту Windows с помощью протокола OpenSearch . Федеративный поиск позволяет пользователям выполнять поиск в удаленном хранилище данных и просматривать результаты из проводника Windows.

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

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

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

Файл OpenSearch Description (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>

Description

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. Атрибут формата должен быть задан application/rss+xml для форматированных результатов RSS или application/atom+xml для отформатированных результатов Atom, как показано в следующем коде.

<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-адреса=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-адреса ="text/html" и атрибут шаблона , кнопка появится на панели команд Проводника Windows, как показано на следующем снимке экрана, что позволяет пользователю открывать веб-браузер для просмотра результатов поиска при выполнении пользователем запроса.

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

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

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

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

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

Возможно, потребуется ограничить количество возвращаемых результатов для каждого запроса. Вы можете выбрать возвращение "страницы" результатов за раз, или же предоставить провайдеру 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 элементов.

Постраничная навигация с использованием индекса страниц

Индекс страницы определяет указанную страницу результатов. Если вы хотите, чтобы клиенты отправляли запросы с указанием номера страницы, можно использовать {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

Размер страницы

Может потребоваться настроить веб-службу, чтобы разрешить запросу указать размер страниц с помощью определенного параметра в 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 v1.1.

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

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

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

Сопоставления XML-элементов RSS по умолчанию со свойствами системы Windows Shell перечислены в следующей таблице. XML-пути относятся к элементу item. Префикс "media:" определяется пространством имен Yahoo Search Namespace.

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

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

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

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

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

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

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

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

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

В следующем примере .osdx файл элемент XML email сопоставляется со свойством Windows Shell 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-адреса, предоставленного в элементах ссылки или корпуса.

Эскизы

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 Windows Shell значение "https://example.com/".

Настройка представлений проводника Windows со списками описаний свойств

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

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

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

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

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 proplists , определяет, что отображается в режиме представления контента. Дополнительные сведения о списках свойств см. в разделе 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", свойство отображается как просто значение без метки.

Previews

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

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

1. Если для элемента задано свойство System.WebPreviewUrl Windows Shell, используйте этот 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