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

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

本主題包含下列幾節：

• OpenSearch 描述檔案
  • Mininum 必要子項目
• Windows 同盟搜尋中的標準元素
  • Shortname
  • 說明
  • RSS/Atom 結果的 URL 範本
  • Web 結果的 URL 範本
  • URL 範本參數
  • 分頁結果
  • 使用專案索引分頁
  • 使用頁面索引分頁
  • 頁面大小
• Windows 同盟搜尋中的擴充元素
  • 結果計數上限
  • 屬性對應
• 預覽
• 開啟檔案位置功能表項目
• 其他資源
• 相關主題

OpenSearch 描述檔案

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

• 為有效的 OpenSearch 描述檔，如 OpenSearch 1.1 規格所定義。
• 提供具有 RSS 或 Atom 格式類型的 URL 範本。
• 使用 .osdx 副檔名，或在從 Web 下載時與 .osdx 副檔名相關聯。 例如，不需要伺服器才能使用 .osdx。 伺服器可以傳回副檔名為任何的檔案，例如.xml，如果它使用正確的 MIME 類型作為 OpenSearch Description 檔 (.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>

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 格式的結果。 格式屬性必須針對 RSS 格式化的結果或 application/atom+xml Atom 格式化的結果設定為 application/rss+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 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 格式=「text/html」 元素和 範本 屬性，按鈕會出現在 Windows 檔案總管命令列中，如下列螢幕擷取畫面所示，讓使用者能夠在使用者執行查詢時開啟網頁瀏覽器來檢視搜尋結果。

在某些情況下，查詢的變換回資料存放區的 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} 的方式。

使用專案索引分頁

專案索引會識別結果頁面中的第一個結果專案。 如果您想要用戶端使用專案索引傳送要求，您可以在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。 針對下一個要求，提供者會 {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 提供者會假設它已收到最後一頁的結果，並停止提出要求。

 

頁面大小

您可能想要設定 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 提供者會假設它已到達結果的結尾。

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
Description	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 是網頁 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 區域會在下列螢幕擷取畫面中說明：

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

要自訂的 UI 區域	實作自訂的 Windows Shell 屬性
搜尋) 時的內容檢視模式 (	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 輸出的情況下，將屬性套用至搜尋結果中的每個專案，請在 .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 proplist 中指定的屬性清單會決定內容檢視模式中顯示的內容。 如需屬性清單的詳細資訊，請參閱 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。

   注意

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

    

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 搜尋中，針對文件庫中的檔案選取此選項，會在網頁瀏覽器中開啟文件庫根目錄。

當使用者按一下 [開啟檔案位置] 時，Windows 檔案總管會嘗試使用下列流程圖中顯示的邏輯來尋找父容器：

其他資源

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

相關主題

Windows 中的同盟搜尋

在 Windows 中使用同盟搜尋消費者入門

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

在 Windows 同盟搜尋中啟用您的資料存放區

遵循 Windows 同盟搜尋中的最佳做法

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