Share via


Windows フェデレーション検索での OpenSearch Description ファイルの作成

OpenSearch Description (.osdx) ファイルを作成して、 OpenSearch プロトコルを介して外部データ ストアを Windows クライアントに接続する方法について説明します。 フェデレーション検索を使用すると、ユーザーはリモート データ ストアを検索し、Windows エクスプローラー内から結果を表示できます。

このトピックは、次のセクションで構成されています。

OpenSearch Description ファイル

Windows フェデレーション検索用の OpenSearch Description (.osdx) ファイルは、次の規則に従う必要があります。

  • OpenSearch 1.1 仕様で定義されている有効な OpenSearch Description ドキュメントである必要があります。
  • RSS または Atom 形式の種類を含む URL テンプレートを指定します。
  • .osdx ファイル名拡張子を使用するか、Web からダウンロードするときに .osdx ファイル名拡張子に関連付けます。 たとえば、サーバーで .osdx を使用する必要はありません。 サーバーは、たとえば、.xmlなどの任意のファイル名拡張子を持つファイルを返し、OpenSearch Description ドキュメント (.osdx ファイル) に正しい MIME の種類を使用する場合は.osdx ファイルのように扱うことができます。
  • ShortName 要素の値を指定します (推奨)。

ミニ数値必須の子要素

次の .osdx ファイルの例は 、ShortNameUrl 要素で構成されています。これは最低限必要な子要素です。

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

フェデレーション検索では、最小の子要素に加えて、次の標準要素がサポートされています。

Shortname

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>

説明

Windows では、Description 要素の値を使用して、ユーザーが .searchconnector-ms ファイルを選択したときに Windows エクスプローラーの詳細ウィンドウに表示されるファイルの説明を設定します。

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

RSS/Atom 結果の URL テンプレート

.osdx ファイルには、結果を RSS または Atom 形式で返す Url 形式 要素と template 属性 (URL テンプレート) を 1 つ含める必要があります。 次のコードに application/rss+xml 示すように、RSS 形式の結果の application/atom+xml 場合は format 属性を、Atom 形式の結果の場合は に設定する必要があります。

Note

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 要素と template 属性を指定する必要があります。

<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" 要素と template 属性を指定すると、次のスクリーン ショットに示すように、Windows エクスプローラー コマンド バーにボタンが表示され、ユーザーがクエリを実行したときに Web ブラウザーを開いて検索結果を表示できるようになります。

Web 検索のロールオーバー ボタンを示すスクリーン ショット。

一部のシナリオでは、クエリをデータ ストアの Web UI にロールバックすることが重要です。 たとえば、ユーザーは 100 件を超える結果 (OpenSearch プロバイダーが要求するアイテムの既定の数) を表示できます。 その場合、ユーザーは、データ ストアの Web サイトでのみ使用できる検索機能 (別の並べ替え順序での再クエリ、関連するメタデータを使用したクエリのピボットとフィルター処理など) を使用することもできます。

URL テンプレート のパラメーター

OpenSearch プロバイダーは常に次のアクションを実行します。

  1. URL テンプレートを使用して Web サービスに要求を送信します。
  2. 次のように、要求を Web サービスに送信する前に、URL テンプレートで見つかったトークンを置き換えようとします。
    • 次の表に示す標準の OpenSearch トークンを置き換えます。
    • 次の表に記載されていないトークンをすべて削除します。
サポートされているトークン OpenSearch プロバイダーによる使用方法
{searchTerms} は、ユーザーが Windows エクスプローラー検索入力ボックスに入力する検索語句に置き換えられました。
{startIndex} "pages" で結果を取得するときに使用されます。
最初に返される結果項目のインデックスに置き換えられました。
{startPage} "pages" で結果を取得するときに使用されます。
を返す検索結果のセットのページ番号に置き換えられます。
{count} "pages" で結果を取得するときに使用されます。
を、Windows エクスプローラーが要求する 1 ページあたりの検索結果の数に置き換えられました。
{language} を、送信されるクエリの言語を示す文字列に置き換えられます。
{inputEncoding} を、送信されるクエリの文字エンコードを示す文字列 ("UTF-16" など) に置き換えられます。
{outputEncoding} Web サービスからの応答に必要な文字エンコードを示す文字列 ("UTF-16" など) に置き換えられます。

 

ページングされた結果

要求ごとに返される結果の数を制限することができます。 一度に結果の "ページ" を返すか、OpenSearch プロバイダーにアイテム番号またはページ番号で結果の追加ページを取得させることができます。 たとえば、1 ページあたり 20 件の結果を送信した場合、最初に送信するページはアイテム インデックス 1 とページ 1 から始まります。送信する 2 番目のページは、アイテム インデックス 21 と 2 ページ目から始まります。 URL テンプレートの または {startPage} トークンを使用{startItem}して、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 個の項目を取得します。

Note

Web サービスによって返される結果のページの数が予想されるページ サイズよりも少ない場合、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

Note

Web サービスによって返される結果のページの数が予想されるページ サイズよりも少ない場合、OpenSearch プロバイダーは結果の最後のページを受信したと見なし、要求を停止します。

 

Page Size

URL のパラメーターを使用してページのサイズを指定するように要求を許可するように Web サービスを構成できます。 次のように、トークンを使用して.osdx ファイルに要求を {count} 指定する必要があります。

<Url format="application/rss+xml" 
    template="https://example.com/rss.php?query={searchTerms}&amp;start={startIndex}&amp;cnt={count}" />

OpenSearch プロバイダーは、次の例に示すように、目的のページ サイズを 1 ページあたりの結果数で設定できます。

https://example.com/rss.php?query=frogs&start=1&cnt=50

既定では、OpenSearch プロバイダーはページ サイズ 50 を使用して要求を行います。 別のページ サイズが必要な場合は、トークンを {count} 指定せず、代わりに Url テンプレート 要素に目的の番号を直接配置します。

OpenSearch プロバイダーは、最初の要求で返された結果の数に基づいてページ サイズを決定します。 受信した結果の最初のページのアイテム数が要求された数より少ない場合、プロバイダーは後続のページ要求のページ サイズをリセットします。 後続のページ要求で返されるアイテムの数が要求よりも少ない場合、OpenSearch プロバイダーは結果の最後に達したと見なします。

フェデレーション検索では、標準要素に加えて、 MaximumResultCountResultsProcessing という拡張要素がサポートされています。

これらの拡張子要素は 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を宣言し、それを要素名のプレフィックスとして使用します。 この宣言は、 MaximumResultCountOpenSearch v1.1 仕様でサポートされていないために必要です。

プロパティ マッピング

Web サービスから RSS または Atom フィードとして結果が返される場合、OpenSearch プロバイダーはフィード内のアイテム メタデータを Windows シェルで使用できるプロパティにマップする必要があります。 次のスクリーン ショットは、OpenSearch プロバイダーが既定の RSS 要素の一部をマップする方法を示しています。

組み込みの rss-to-windows-shell プロパティ マッピングを示すスクリーン ショット

既定のマップ

RSS XML 要素と Windows シェル システム プロパティの既定のマッピングを次の表に示します。 XML パスは、item 要素に対する相対パスです。 プレフィックスは"media:"、Yahoo Search 名前空間名前空間によって定義されます。

RSS XML パス Windows Shell プロパティ (正規名)
Link System.ItemUrl
Title System.ItemName
Author System.Author
Pubdate System.DateModified
説明 System.AutoSummary
カテゴリ System.Keywords
enclosure/@type System.MIMEType
enclosure/@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

 

Note

標準の RSS 要素または Atom 要素の既定のマッピングに加えて、各プロパティの Windows 名前空間に追加の XML 要素を含めることで、他の Windows シェル システム プロパティをマップできます。 .osdx ファイルにカスタム プロパティ マッピングを追加することで、MediaRSS、iTunes などの他の既存の XML 名前空間の要素をマップすることもできます。

 

カスタム プロパティ マッピング

.osdx ファイルでマッピングを指定することで、RSS 出力から Windows シェル システム プロパティへの要素のマッピングをカスタマイズできます。

RSS 出力では、次のことが指定されます。

  • XML 名前空間と
  • 項目の子要素の場合、マップ対象の要素名。

.osdx ファイルは、名前空間内の各要素名の Windows シェル プロパティを識別します。 .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 シェル プロパティ 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 が などの https://...Web URL の場合、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 は、Windows エクスプローラーでの結果の表示方法を制御するために使用される、 などの"prop:System.ItemName; System.Author"プロパティのセミコロンで区切られたリストです。

次のスクリーン ショットでは、プロップリストを使用してカスタマイズできる Windows エクスプローラーの UI 領域を示します。

プロップリストを使用してカスタマイズできるエクスプローラーの 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 プロップリストで指定されたプロパティの一覧によって、コンテンツ ビュー モードで表示される内容が決まります。 プロパティ リストの詳細については、「 PropList」を参照してください。

プロパティは、次のレイアウト パターンに示されている数値に従ってレイアウトされます。

コンテンツ ビューの既定のレイアウト パターンを示すスクリーン ショット

次のプロパティの一覧を使用する場合は、

prop:~System.ItemNameDisplay;System.Author;System.ItemPathDisplay;~System.Search.AutoSummary;
    System.Size;System.Photo.DateTaken;System.Keywords

次に、次の表示が表示されます。

サンプル のプロパティ レイアウトを示すスクリーン ショット。

Note

読みやすくするために、右端の列に表示されるプロパティにラベルを付ける必要があります。

 

プロパティ リスト フラグ

proplists ドキュメントで定義されているフラグの 1 つだけが、コンテンツ ビュー モード レイアウト "~"のアイテムの表示に適用されます。 前の例では、Windows エクスプローラー ビューでは、 などのプロパティの一部にラベルが付きますTags: animals; zoo; lion。 これは、リストでプロパティを指定するときの既定の動作です。 たとえば、proplist には "System.Author" として表示される "Authors: value"が含まれているとします。 プロパティ ラベルを非表示にする場合は、プロパティ名の前に を配置 "~" します。 たとえば、proplist に が含 "~System.Size"まれている場合、プロパティはラベルなしで値として表示されます。

プレビュー

ユーザーが Windows エクスプローラーで結果アイテムを選択し、プレビュー ウィンドウが開いていると、アイテムの内容がプレビューされます。

プレビューで表示するコンテンツは、次のように決定される URL で指定されます。

  1. アイテムに System.WebPreviewUrl Windows Shell プロパティが設定されている場合は、その URL を使用します。

    Note

    プロパティは、Windows シェル名前空間を使用して RSS で指定するか、.osdx ファイルに明示的にマップする必要があります。

     

  2. そうでない場合は、代わりにリンク URL を使用します。

次のフローチャートは、このロジックを示しています。

プレビューに使用する URL を Windows エクスプローラーで選択する方法を示すフローチャート

プレビューには、アイテム自体とは異なる URL を使用できます。 つまり、リンク URL とエンクロージャ または media:content URLに異なる URL を指定した場合、Windows エクスプローラーはアイテムのプレビューにリンク URL を使用しますが、ファイルの種類の検出、開き、ダウンロードなどに他の URL を使用します。

Windows エクスプローラーで使用する URL を決定する方法:

  1. System.ItemFolderPathDisplay へのマッピングを指定すると、Windows エクスプローラーはその URL を使用します

  2. マッピングを指定しない場合、Windows エクスプローラーはリンク URL とエンクロージャ URL が異なるかどうかを識別します。 その場合、Windows エクスプローラーはリンク URL を使用します。

  3. URL が同じ場合、またはリンク URL しかない場合、Windows エクスプローラーはリンクを解析し、完全な URL からファイル名を削除して親コンテナーを検索します。

    Note

    URL 解析によってサービスのリンクが停止する場合は、 プロパティの明示的なマッピングを指定する必要があります。

     

[ファイルの場所] メニュー項目を開く

項目を右クリックすると、[ファイルの場所を 開く ] メニュー コマンドが表示されます。 このコマンドを実行すると、その項目の または の場所のコンテナーにユーザーが移動します。 たとえば、SharePoint 検索では、ドキュメント ライブラリ内のファイルに対してこのオプションを選択すると、Web ブラウザーでドキュメント ライブラリ ルートが開きます。

ユーザーが [ファイルの場所を開く] をクリックすると、Windows エクスプローラーは、次のフローチャートに示すロジックを使用して、親コンテナーの検索を試みます。

エクスプローラーが親コンテナーを識別する方法を示すフローチャート

その他のリソース

Windows 7 以降で OpenSearch テクノロジを使用してリモート データ ストアに検索フェデレーションを実装する方法の詳細については、「 Windows でのフェデレーション検索」の「追加リソース」を参照してください。

Windows でのフェデレーション検索

Windows でのフェデレーション検索を使用したはじめに

Windows フェデレーション検索での Web サービスの接続

Windows フェデレーション検索でのデータ ストアの有効化

Windows フェデレーション検索のベスト プラクティスに従う

Windows フェデレーション検索での検索コネクタの展開