共用方式為

在 Windows 同盟搜尋中建立 OpenSearch 描述檔案

  • 發行項

描述如何建立 OpenSearch Description （.osdx） 檔案，以透過 OpenSearch 通訊協定將外部數據存放區連線到 Windows 用戶端。 同盟搜尋可讓使用者搜尋遠端數據存放區，並從 Windows 檔案總管中檢視結果。

本主題包含下列各節：

OpenSearch 描述檔

Windows 同盟搜尋的 OpenSearch Description （.osdx） 檔案必須遵守下列規則：

  • 為有效的 OpenSearch 描述檔，如 OpenSearch 1.1 規格所定義。
  • 提供具有 RSS 或 Atom 格式類型的 URL 範本。
  • 從 Web 下載時，請使用 .osdx 擴展名，或與 .osdx 擴展名相關聯。 例如，伺服器不需要使用 .osdx。 例如，伺服器可以傳回擴展名為任何擴展名的檔案，例如 .xml，如果檔案使用正確的MIME類型作為OpenSearch描述檔 （.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 元素值來命名用戶開啟 .osdx 檔案時所建立的 .searchconnector-ms （search connector） 檔案。 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 元素，以及一個 範本 屬性（URL 範本），其傳回結果為 RSS 或 Atom 格式。 format 屬性必須設定為 RSS 格式化結果的 application/rss+xml，或針對 Atom 格式化結果 application/atom+xml，如下列程式代碼所示。

注意

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

如果有可在網頁瀏覽器中檢視的搜尋結果版本，您應該提供 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 format=“text/html” 元素和 範本 屬性，按鈕會出現在 Windows 檔案總管命令行中，如下列螢幕快照所示，讓使用者開啟網頁瀏覽器，以在使用者執行查詢時檢視搜尋結果。

顯示 Web 搜尋變換按鈕的螢幕快照。

在某些情況下，查詢的變換回到數據存放區的 Web UI 非常重要。 例如，使用者可能想要檢視超過 100 個結果（OpenSearch 提供者要求的預設項目數目）。 若是如此，使用者可能也想要使用只能在數據存放區網站上找到的搜尋功能，例如使用不同的排序順序重新查詢，或透過相關的元數據來旋轉和篩選查詢。

URL 樣本參數

OpenSearch 提供者一律會執行下列動作：

  1. 使用 URL 範本將要求傳送至 Web 服務。
  2. 嘗試先取代 URL 範本中找到的令牌，再將要求傳送至 Web 服務，如下所示：
    • 取代下表所列的標準 OpenSearch 令牌。
    • 拿掉下表中未列出的任何令牌。
支援的令牌 OpenSearch 提供者的使用方式
{searchTerms} 使用者在 Windows 檔案總管的搜尋輸入方塊中輸入的字詞將被取代。
{startIndex} 使用於取得「頁面」的結果時。
更換成要返回的第一個結果項目的索引。
{startPage} 用於取得「頁面」結果時。
取代為要傳回之搜尋結果集的頁碼。
{count} 在取得「頁面」的結果時使用。
以 Windows 檔案總管要求的每個頁面搜尋結果數目取代。
語言 以表示所傳送查詢語言的字串取代 。
{inputEncoding} 取代為字串 （例如 “UTF-16”），表示所傳送查詢的字元編碼。
{outputEncoding} 取代為字串（例如 “UTF-16”），表示 Web 服務回應所需的字元編碼。

 

分頁結果

您可能想要限制每個要求傳回的結果數目。 您可以選擇一次傳回結果的「頁面」，或讓OpenSearch提供者依專案編號或頁碼取得其他結果頁面。 例如，如果您每頁傳送 20 個結果，您傳送的第一頁會從專案索引 1 開始，而頁面 1 則為 ;您傳送的第二個頁面會從專案索引 21 和第 2 頁開始。 您可以使用 URL 範本中的 {startItem} 或 {startPage} 令牌，定義您希望 OpenSearch 供應者請求項目的方式。

使用項目索引分頁

專案索引會識別結果頁面中的第一個結果專案。 如果您想要用戶端使用專案索引傳送要求，您可以在 Url 元素中使用 {startIndex} 令牌，範本 屬性，如下列程式代碼所示。

<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。 針對下一個要求，提供者會以 21 的值取代 {startIndex}，以獲得接下來的 20 個項目。

注意

如果網路服務傳回的結果頁面項目少於預期的頁面大小，則 OpenSearch 提供者會假設已收到最後一頁結果，並停止發送請求。

 

使用頁面索引進行分頁

頁面索引會識別指定的結果頁面。 如果您想讓用戶端使用頁碼來傳送要求，您可以在 URL 格式的 元素 範本 屬性中使用 {startPage} 令牌以指示這一點，如下示例所示：

<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 提供者會假設它已收到最後一頁結果，並停止發出請求。

 

頁面大小

您可能想要設定 Web 服務，以允許要求使用 URL 中的某些參數來指定頁面的大小。 必須使用 {count} 令牌在 .osdx 檔案中指定要求，如下所示：

<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 提供者會假設它已到達結果的結尾。

除了標準元素之外，同盟搜尋還支援下列擴充元素：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-to-windows-shell 屬性對應

預設映射

下表列出 RSS XML 元素與 Windows Shell 系統屬性的預設對應。 XML 路徑是相對於項目元素的。 "media:" 前綴是由雅虎搜尋命名空間 命名空間 定義。

RSS XML 路徑 Windows Shell 屬性 （正式名稱）
連結 System.ItemUrl
標題 System.ItemName
作者 系統.作者
發布日期 系統.日期修改
描述 系統.自動摘要
類別 System.Keywords
外殼/@type 系統.MIME類型
外殼/@length System.Size
封裝/@url System.ContentUrl
媒體：類別 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.MIME類型
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 屬性（標準名稱）。

圖表顯示 xml 命名空間和 xml 路徑的組合會產生標準名稱

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://...，則會開啟網頁瀏覽器並流覽至該 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 檔案總管中的顯示方式。

下列螢幕快照說明可使用 proplist 自定義的 Windows 檔案總管 UI 區域：

螢幕快照，其中顯示可使用 proplists 自定義的 Windows 檔案總管 ui 區域

Windows 檔案總管的每個區域都有一組相關聯的 proplists，而這些 proplists 本身被指定為屬性。 您可以針對結果集中的個別專案或一組結果集中的所有專案指定自訂屬性清單。

要自定義的UI區域 實作自定義的 Windows Shell 屬性
內容檢視模式 （搜尋時） System.PropList.ContentViewModeForSearch
內容檢視模式 （瀏覽時） System.PropList.ContentViewModeForBrowse
方塊檢視模式 System.PropList.TileInfo
詳細資訊窗格 System.PropList.預覽詳細資料
資訊提示（項目懸停時的工具提示） System.PropList.Infotip

 

 

若要為個別項目指定唯一的 proplist：

  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。 這是當您在清單中指定屬性時的預設行為。 例如，proplist 具有 "System.Author"，會顯示為 "Authors: value"。 當您想要隱藏屬性標籤時，請將 "~" 放在屬性名稱前面。 例如，如果 proplist 有 "~System.Size"，則屬性只會顯示為值，而不顯示標籤。

預覽

當使用者在 Windows 檔案總管中選取結果項目並開啟預覽窗格時，會預覽項目的內容。

預覽中顯示的內容是由 URL 指定，其決定如下：

  1. 如果已為項目設定 System.WebPreviewUrl Windows Shell 屬性，請使用該 URL。

    注意

    必須在 RSS 中使用 Windows Shell 命名空間來提供該屬性，或在 .osdx 文件中明確對應。

     

  2. 如果沒有，請改用連結 URL。

下列流程圖顯示此邏輯。

流程圖，顯示 Windows 檔案總管如何選取要用於預覽的 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 剖析會導致服務的失效連結，您應該為該 URL 屬性提供明確的對應。

     

開啟檔案位置選單項目

當以滑鼠右鍵按一下項目時，[開啟檔案位置] 選單命令即會出現。 此命令會將使用者帶到該專案的容器或位置。 例如，在 SharePoint 搜尋中，針對文檔庫中的檔案選取此選項，將會在網頁瀏覽器中開啟文檔庫根目錄。

當使用者按一下 [開啟檔案位置]時，Windows 檔案管理器會嘗試按照下列流程圖所顯示的邏輯來尋找上層容器。

流程圖，顯示 Windows 檔案總管如何識別父容器

其他資源

如需在 Windows 7 和更新版本中使用 OpenSearch 技術實作遠端數據存放區搜尋同盟的詳細資訊，請參閱 Windows 中同盟搜尋的「其他資源」。

在 Windows 中 同盟搜尋

Windows 中開始使用同盟搜尋

在 Windows 同盟搜尋中連線您的 Web 服務

在 Windows 聯邦搜尋中啟用您的資料存放區

在 Windows 聯邦搜尋中遵循最佳實務

在 Windows 同盟搜尋 中部署搜尋連接器