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

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

本主题包含以下各节：

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

OpenSearch 说明文件

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

• 作为符合 OpenSearch 1.1 规范定义的有效 OpenSearch 描述文档。
• 提供具有 RSS 或 Atom 格式类型的 URL 模板。
• 使用 .osdx 文件扩展名，或在从 Web 下载时与 .osdx 文件扩展名相关联。 例如，服务器不需要使用 .osdx。 例如，服务器可以返回具有任何文件名扩展名的文件，例如 .xml，并且如果它使用 OpenSearch Description 文件的正确 MIME 类型，则将其视为 .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 元素值命名用户打开 .osdx 文件时创建的 .searchconnector-ms （搜索连接器）文件。 Windows 确保生成的文件名仅使用 Windows 文件名中允许的字符。 如果未提供 ShortName 值，.searchconnector-ms 文件将尝试改用 .osdx 文件的文件名。

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

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

Description

当用户选择 .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 格式 元素和 模板 属性（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>

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 提供程序按项目编号或页码获取其他结果页。 例如，如果每页发送 20 个结果，则发送的第一页从项索引 1 开始，第 1 页开始;发送的第二页从项目索引 21 和第 2 页开始。 您可以使用 URL 模板中的{startItem}或{startPage}令牌来定义 OpenSearch 提供程序请求项目的方式。

使用项索引分页

项索引标识结果页中的第一个结果项。 如果希望客户端使用项索引发送请求，可以使用{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 个项目。

使用页码索引进行分页

页索引标识指定的结果页。 如果希望客户端使用页码发送请求，可以使用 {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 服务配置为允许请求使用 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>

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

属性映射

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

默认映射

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

自定义属性映射

可以在 .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>[email protected]</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 资源管理器视图布局由属性说明列表或属性列表定义。 属性列表是一个以分号分隔的属性列表，例如 "prop:System.ItemName; System.Author"，用于控制结果在 Windows 资源管理器中的显示方式。

以下屏幕截图演示了可以使用 proplist 自定义的 Windows 资源管理器的 UI 区域：

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

若要为单个项指定唯一属性列表，

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

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

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

   <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

然后，我们会看到以下显示：

属性列表标志

在属性列表文档中定义的标志中，只有一个标志适用于在内容视图模式布局中显示项目： "~" 在前面的示例中，Windows 资源管理器视图会标记某些属性，例如 Tags: animals; zoo; lion。 这是在列表中指定属性时的默认行为。 例如，在属性列表中，"System.Author" 显示为 "Authors: value"。 如果要隐藏属性标签，请将 "~" 放在属性名称前面。 例如，如果 proplist 具有 "~System.Size"，则属性仅显示为一个值，而不显示标签。

Previews

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

预览中显示的内容由 URL 指定，如下所示：

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

   注释

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

    

2. 否则，请改用链接 URL。

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

预览版的 URL 可能不同于项目本身。 这意味着，如果你为链接 URL 和附件提供不同的 URL，或者 media:content URL，Windows Explorer 会使用链接 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 联合搜索中部署搜索连接器