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 Description ドキュメントである必要があります。
• RSS 形式または Atom 形式の URL テンプレートを指定します。
• .osdx ファイル名拡張子を使用するか、Web からダウンロードするときに .osdx ファイル名拡張子に関連付けます。 たとえば、サーバーで .osdx を使用する必要はありません。 サーバーは、.xml などの任意のファイル名拡張子を持つファイルを返し、OpenSearch Description ドキュメント (.osdx ファイル) に適切な 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

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

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

rss/atom 結果の URL テンプレート

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

<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 プロバイダーが要求する既定のアイテム数) を表示できます。 その場合、ユーザーは、データ ストアの Web サイトでのみ使用できる検索機能 (別の並べ替え順序での再クエリ、関連するメタデータを使用したクエリのピボットとフィルター処理など) を使用することもできます。

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

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

1. URL テンプレートを使用して Web サービスに要求を送信します。
2. 次のように、要求を Web サービスに送信する前に、URL テンプレートで見つかったトークンを置き換えようとします。
   • 次の表に示す標準の OpenSearch トークンを置き換えます。
   • 次の表に示されていないトークンを削除します。

ページングされた結果

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

項目インデックスを使用したページング

項目インデックスは、結果のページ内の最初の結果項目を識別します。 クライアントが項目インデックスを使用して要求を送信する場合は、次のコードに示すように、{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 個の項目を取得します。

ページ インデックスを使用したページング

ページ インデックスは、指定した結果ページを識別します。 クライアントがページ番号を使用して要求を送信する場合は、{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

ページ サイズ

URL 内のパラメーターを使用してページのサイズを指定する要求を許可するように Web サービスを構成できます。 次のように、 {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>

前の例では、最上位レベルの ms-ose 要素で名前空間プレフィックスを宣言し、それを要素名のプレフィックスとして使用します。 この宣言は、OpenSearch v1.1 仕様で MaximumResultCount がサポートされていないために必要です。

プロパティ マッピング

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

既定のマッピング

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

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

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

RSS 出力は次を指定します。

• XML名前空間とそして
• 任意の項目の子要素について、マップする要素名を指定してください。

.osdx ファイルは、名前空間内の各要素名の Windows シェル プロパティを識別します。 .osdx ファイルで定義するプロパティ マッピングは、指定されたプロパティの既定のマッピング (存在する場合) をオーバーライドします。

次の図は、RSS 拡張機能が Windows プロパティ (正規名) にどのようにマップされるかを示しています。

RSS 結果と OSD プロパティマッピングの例

次の RSS 出力例では、プレフィックス "example" を持つ XML 名前空間として https://example.com/schema/2009 を識別します。 このプレフィックスは 、電子メール 要素の前にもう一度表示する必要があります。

<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 シェル プロパティ 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"などのプロパティのセミコロン区切りのリストです。

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

Previews

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

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

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

   注

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

    

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

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

プレビューには、アイテム自体とは異なる 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 からファイル名を削除することで、リンクを解析して親コンテナーを検索します。

   注

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

    

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

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

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

その他のリソース

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

関連トピック

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

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

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

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

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

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