在 Windows 联合搜索中创建 OpenSearch 说明文件

介绍如何创建 OpenSearch Description (.osdx) 文件，以通过 OpenSearch 协议将外部数据存储连接到 Windows 客户端。 联合搜索使用户能够搜索远程数据存储并从 Windows 资源管理器中查看结果。

本主题包含以下各节：

• OpenSearch 说明文件
  • Mininum 必需子元素
• Windows 联合搜索中的标准元素
  • Shortname
  • 描述
  • RSS/Atom 结果的 URL 模板
  • Web 结果的 URL 模板
  • URL 模板参数
  • 分页结果
  • 使用项索引分页
  • 使用页面索引分页
  • Page Size
• Windows 联合搜索中的扩展元素
  • 最大结果计数
  • 属性映射
• 预览版
• 打开文件位置菜单项
• 其他资源
• 相关主题

OpenSearch 说明文件

Windows 联合搜索的 OpenSearch Description (.osdx) 文件必须遵守以下规则：

• 是有效的 OpenSearch 说明文档，由 OpenSearch 1.1 规范定义。
• 提供具有 RSS 或 Atom 格式类型的 URL 模板。
• 从 Web 下载时，请使用 .osdx 文件扩展名，或与 .osdx 文件扩展名相关联。 例如，服务器不需要使用 .osdx。 服务器可以返回具有任何文件扩展名（例如.xml）的文件，如果服务器对 OpenSearch Description 文档使用正确的 MIME 类型 (.osdx 文件) ，则会将其视为 .osdx 文件。
• (建议) 提供 ShortName 元素值。

Mininum 必需子元素

以下示例 .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 联合搜索中的标准元素

除了最小子元素之外，联合搜索还支持以下标准元素。

Shortname

Windows 使用 ShortName 元素值将 .searchconnector-ms (搜索连接器命名为用户打开 .osdx 文件时创建的) 文件。 Windows 确保生成的文件名仅使用 Windows 文件名中允许的字符。 如果未提供 ShortName 值，.searchconnector-ms 文件将尝试改用 .osdx 文件的文件名。

以下代码演示如何在 .osdx 文件中使用 ShortName 元素。

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

说明

当用户选择 .searchconnector-ms 文件时，Windows 使用 Description 元素值填充 Windows 资源管理器详细信息窗格中显示的文件说明。

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

RSS/Atom 结果的 URL 模板

.osdx 文件必须包含一个 URL 格式 元素和 模板 属性， (返回 RSS 或 Atom 格式结果的 URL 模板) 。 对于 RSS 格式的结果，必须将 format 属性设置为 application/rss+xml ，对于 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>

Web 结果的 URL 模板

如果有可在 Web 浏览器中查看的搜索结果版本，则应提供 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 资源管理器命令栏中会显示一个按钮，如以下屏幕截图所示，该按钮允许用户在用户执行查询时打开 Web 浏览器以查看搜索结果。

在某些情况下，将查询滚动回数据存储的 Web UI 非常重要。 例如，用户可能需要查看超过 100 个结果， (OpenSearch 提供程序请求) 的默认项目数。 如果是这样，用户可能还希望使用仅在数据存储网站上可用的搜索功能，例如使用不同的排序顺序重新查询，或使用相关元数据透视和筛选查询。

URL 模板参数

OpenSearch 提供程序始终执行以下操作：

1. 使用 URL 模板将请求发送到 Web 服务。
2. 在将请求发送到 Web 服务之前，尝试替换在 URL 模板中找到的令牌，如下所示：
   • 替换下表中列出的标准 OpenSearch 令牌。
   • 删除下表中未列出的任何令牌。

支持的令牌	OpenSearch 提供程序的使用方式
{searchTerms}	替换为用户在 Windows 资源管理器搜索输入框中键入的搜索词。
{startIndex}	在“页面”中获取结果时使用。 替换为要返回的第一个结果项的索引。
{startPage}	在“页面”中获取结果时使用。 替换为要返回的搜索结果集的页码。
{count}	在“页面”中获取结果时使用。 替换为 Windows 资源管理器请求的每页搜索结果数。
{language}	已替换为指示所发送查询语言的字符串。
{inputEncoding}	替换为字符串 (“UTF-16”) ，指示正在发送的查询的字符编码。
{outputEncoding}	替换为字符串 (，例如“UTF-16”) ，指示来自 Web 服务的响应所需的字符编码。

 

分页结果

你可能希望限制每个请求返回的结果数。 可以选择一次返回结果的“页”，或者让 OpenSearch 提供程序按项目编号或页码获取其他结果页。 例如，如果每页发送 20 个结果，则发送的第一页从项索引 1 开始，从第 1 页开始;发送的第二页从项目索引 21 开始，从第 2 页开始。 可以使用 URL 模板中的 或 {startPage} 令牌来定义希望 OpenSearch 提供程序请求项{startItem}的方式。

使用项索引分页

项索引标识结果页中的第一个结果项。 如果希望客户端使用项索引发送请求，则可以在 {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 提供程序在结果的第一页中查看 Web 服务返回的项数，并将预期的页面大小设置为该数字。 它使用该数字递增 {startIndex} 后续请求的值。 例如，如果 Web 服务在第一个请求中返回 20 个结果，则提供程序会将预期的页面大小设置为 20。 对于下一个请求，提供程序将 替换为 {startIndex} 值 21 以获取接下来的 20 个项。

注意

如果 Web 服务返回的结果页的项目数少于预期的页面大小，则 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

注意

如果 Web 服务返回的结果页的项目数少于预期的页面大小，则 OpenSearch 提供程序假定它已收到最后一页的结果，并停止发出请求。

 

Page Size

可能需要将 Web 服务配置为允许请求使用 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 v1.1 规范不支持这些扩展子元素，因此必须使用以下命名空间添加它们：

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

最大结果计数

默认情况下，搜索连接器限制为每个用户查询 100 个结果。 可以通过在 OSD 文件中包含 MaximumResultCount 元素来自定义此限制，如以下示例所示：

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

前面的示例在顶级 OpenSearchDescription 元素中声明命名空间前缀ms-ose，然后将其用作元素名称中的前缀。 此声明是必需的，因为 OpenSearch v1.1 规范不支持 MaximumResultCount。

属性映射

当 Web 服务作为 RSS 或 Atom 源返回结果时，OpenSearch 提供程序必须将源中的项元数据映射到 Windows Shell 可以使用的属性。 以下屏幕截图演示了 OpenSearch 提供程序如何映射某些默认 RSS 元素。

默认映射

下表列出了 RSS XML 元素到 Windows Shell 系统属性的默认映射。 XML 路径相对于项元素。 前缀 "media:" 由 Yahoo 搜索命名空间 定义。

RSS XML 路径	Windows Shell 属性 (规范名称)
链接	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 Shell 系统属性。 还可以通过在 .osdx 文件中添加自定义属性映射来映射其他现有 XML 命名空间（如 MediaRSS、iTunes 等）中的元素。

 

自定义属性映射

可以通过在 .osdx 文件中指定映射来自定义从 RSS 输出到 Windows Shell 系统属性的元素映射。

RSS 输出指定：

• XML 命名空间，以及
• 对于项的任何子元素，为要映射的元素名称。

.osdx 文件标识命名空间中每个元素名称的 Windows Shell 属性。 在 .osdx 文件中定义的属性映射会覆盖这些指定属性的默认映射（如果存在）。

下图演示了 RSS 扩展如何映射到 Windows 属性 (规范名称) 。

示例 RSS 结果和 OSD 属性映射

以下示例 RSS 输出标识 https://example.com/schema/2009 为前缀为“example”的 XML 命名空间。 此前缀必须再次显示在 电子邮件 元素之前。

<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 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 值计算的。

缩略图

可以使用 media：thumbnail url=“” 元素为任何项目提供缩略图 URL。 理想的分辨率为 150 x 150 像素。 支持的最大缩略图为 256 x 256 像素。 提供较大的图像需要更多带宽，对用户没有额外好处。

打开文件位置上下文菜单

Windows 为结果项提供名为 “打开文件位置 ”的快捷菜单。 如果用户从该菜单中选择某个项，则会打开所选项的“父”URL。 如果 URL 是 Web URL（如 https://...），则会打开 Web 浏览器并导航到该 URL。 源应为每个项目提供自定义 URL，以确保 Windows 打开有效的 URL。 这可以通过在项的 XML 中的 元素中包含 URL 来实现，如以下示例所示：

<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 资源管理器中可以使用属性列表自定义的 UI 区域：

Windows 资源管理器的每个区域都有一组关联的属性列表，这些属性列表本身被指定为属性。 可以为结果集中的各个项或结果集中的所有项指定自定义属性列表。

要自定义的 UI 区域	实现自定义的 Windows Shell 属性
搜索) 时的内容视图模式 (	System.PropList.ContentViewModeForSearch
浏览) 时 (内容视图模式	System.PropList.ContentViewModeForBrowse
平铺视图模式	System.PropList.TileInfo
细节窗格	System.PropList.PreviewDetails
信息提示 (项的悬停工具提示)	System.PropList.Infotip

 

 

为单个项目指定唯一属性列表：

1. 在 RSS 输出中，添加表示要自定义的属性列表的自定义元素。 例如，以下示例设置详细信息窗格的列表：

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

2. 若要在不修改 RSS 输出的情况下将属性应用于搜索结果中的每个项，请在 .osdx 文件中的 ms-ose：PropertyDefaultValues 元素中指定 proplist，如以下示例所示：

   <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。 这是在列表中指定属性时的默认行为。 例如，属性列表具有 "System.Author" 显示为 "Authors: value"的 。 如果要隐藏属性标签，请将 放在 "~" 属性名称的前面。 例如，如果 proplist 具有 "~System.Size"，则 属性仅显示为一个值，而不显示标签。

预览版

当用户在 Windows 资源管理器中选择结果项并且预览窗格处于打开状态时，将预览该项的内容。

要显示在预览中的内容由 URL 指定，该 URL 确定如下：

1. 如果为项设置了 System.WebPreviewUrl Windows Shell 属性，请使用该 URL。

   注意

   属性需要使用 Windows Shell 命名空间在 RSS 中提供，或在 .osdx 文件中显式映射。

    

2. 如果没有，请改用链接 URL。

以下流程图显示了此逻辑。

可以对预览版使用不同于项本身的 URL。 这意味着，如果你为链接 URL 和机箱或 media:content URL提供不同的 URL，Windows 资源管理器会将链接 URL 用于项目预览，但使用其他 URL 进行文件类型检测、打开、下载等。

Windows 资源管理器如何确定要使用的 URL：

1. 如果提供到 System.ItemFolderPathDisplay 的映射，则 Windows 资源管理器将使用该 URL

2. 如果未提供映射，则 Windows 资源管理器将标识链接和机箱 URL 是否不同。 如果是，则 Windows 资源管理器将使用链接 URL。

3. 如果 URL 相同，或者只有链接 URL，则 Windows 资源管理器会分析链接以从完整 URL 中删除文件名来查找父容器。

   注意

   如果识别到 URL 分析会导致服务出现死链接，则应为 属性提供显式映射。

    

打开文件位置菜单项

右键单击某个项时，将显示 “打开文件位置 ”菜单命令。 此命令将用户带到该项的容器或位置。 例如，在 SharePoint 搜索中，为文档库中的文件选择此选项将在 Web 浏览器中打开文档库根目录。

当用户单击“ 打开文件位置”时，Windows 资源管理器会尝试使用以下流程图中显示的逻辑查找父容器：

其他资源

有关在 Windows 7 及更高版本中使用 OpenSearch 技术实现对远程数据存储的搜索联合的其他信息，请参阅 Windows 联合搜索中的“其他资源”。

相关主题

Windows 中的联合搜索

在 Windows 中使用联合搜索入门

在 Windows 联合搜索中连接 Web 服务

在 Windows 联合搜索中启用数据存储

遵循 Windows 联合搜索中的最佳做法

在 Windows 联合搜索中部署搜索连接器