Membuat file deskripsi OpenSearch di Windows Federated Search

Menjelaskan cara membuat file OpenSearch Description (.osdx) untuk menyambungkan penyimpanan data eksternal ke Klien Windows melalui protokol OpenSearch. Pencarian gabungan memungkinkan pengguna untuk mencari penyimpanan data jarak jauh dan melihat hasilnya dari dalam Windows Explorer.

Topik ini berisi bagian berikut:

• File Deskripsi OpenSearch
  • Elemen Anak Minimum yang Diperlukan
• Elemen Standar di Windows Federated Search
  • Nama Pendek
  • Deskripsi
  • Templat URL untuk Hasil RSS/Atom
  • Templat URL Hasil Web
  • Parameter Templat URL
  • Hasil Halaman
  • Penggunaan Halaman Berdasarkan Indeks Item
  • Penomoran Halaman Menggunakan Indeks Halaman
  • Ukuran Halaman
• Elemen yang Diperluas di Windows Federated Search
  • Jumlah Hasil Maksimum
  • Pemetaan Properti
• Pratinjau
• Buka Item Menu Lokasi File
• Sumber Daya Tambahan
• Topik terkait

File deskripsi OpenSearch

File Deskripsi OpenSearch (.osdx) untuk Pencarian Federasi Windows harus mematuhi aturan berikut:

• Jadilah dokumen Deskripsi OpenSearch yang valid, seperti yang didefinisikan oleh spesifikasi OpenSearch 1.1.
• Berikan templat URL dengan jenis format RSS atau Atom.
• Gunakan ekstensi nama file .osdx, atau dikaitkan dengan ekstensi nama file .osdx saat mengunduh dari web. Misalnya, server tidak diperlukan untuk menggunakan .osdx. Server dapat mengembalikan file dengan ekstensi nama file apa pun, seperti .xml misalnya, dan diperlakukan seolah-olah file .osdx jika menggunakan Jenis MIME yang benar untuk dokumen Deskripsi OpenSearch (file.osdx).
• Berikan nilai elemen ShortName (disarankan).

Minimum elemen turunan yang diperlukan

Contoh file .osdx berikut terdiri dari elemen ShortName dan Url, yang merupakan elemen turunan minimum yang diperlukan.

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

Elemen standar dalam Pencarian Federasi Windows

Selain elemen turunan minimum, pencarian terfederasi mendukung elemen standar berikut.

Nama pendek

Windows menggunakan nilai elemen ShortName untuk memberi nama file .searchconnector-ms (konektor pencarian) yang dibuat saat pengguna membuka file .osdx. Windows memastikan bahwa nama file yang dihasilkan hanya menggunakan karakter yang diizinkan dalam nama file Windows. Jika tidak ada nilai ShortName yang disediakan, file .searchconnector-ms mencoba menggunakan nama file file .osdx sebagai gantinya.

Kode berikut mengilustrasikan cara menggunakan elemen ShortName dalam file .osdx.

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

Deskripsi

Windows menggunakan nilai elemen Deskripsi untuk mengisi deskripsi file yang diperlihatkan di panel detail Windows Explorer saat pengguna memilih file .searchconnector-ms.

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

Templat URL untuk hasil rss/atom

File .osdx harus menyertakan satu format Url elemen dan atribut templat (templat URL) yang mengembalikan hasil dalam format RSS atau Atom. Atribut format harus diatur ke application/rss+xml untuk hasil berformat RSS, atau application/atom+xml untuk hasil berformat Atom, seperti yang ditunjukkan dalam kode berikut.

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

Templat URL untuk hasil web

Jika ada versi hasil pencarian yang dapat dilihat di browser web, Anda harus menyediakan elemen format Url =text/html, dan atribut templat , seperti yang ditunjukkan dalam kode berikut.

<OpenSearchDescription xmlns="https://a9.com/-/spec/opensearch/1.1/">
    ...
    <Url format="text/html" template="https://example.com/html.php?query={searchTerms}" />
</OpenSearchDescription>

Jika Anda menyediakan elemen Url format="text/html" dan templat , tombol muncul di bilah perintah Windows Explorer, seperti yang ditunjukkan pada cuplikan layar berikut, yang memungkinkan pengguna membuka browser web untuk melihat hasil pencarian saat pengguna melakukan kueri.

Pengalihan kueri ke antarmuka web penyimpanan data penting dalam beberapa skenario. Misalnya, pengguna mungkin ingin melihat lebih dari 100 hasil (jumlah default item yang diminta penyedia OpenSearch). Jika demikian, pengguna mungkin juga ingin menggunakan fitur pencarian yang hanya tersedia di situs web penyimpanan data, seperti mengkueri ulang dengan urutan pengurutan yang berbeda, atau mempivot dan memfilter kueri dengan metadata terkait.

Parameter templat URL

Penyedia OpenSearch melakukan selalu tindakan berikut:

1. Menggunakan templat URL untuk mengirim permintaan ke layanan web.
2. Upaya untuk mengganti token yang ditemukan di templat URL sebelum mengirim permintaan ke layanan web, sebagai berikut:
   • Menggantikan token OpenSearch standar yang tercantum dalam tabel berikut.
   • Menghapus token apa pun yang tidak tercantum dalam tabel berikut.

Hasil yang dipaginasi

Anda mungkin ingin membatasi jumlah hasil yang dikembalikan per permintaan. Anda dapat memilih untuk mengembalikan "halaman" hasil pada satu waktu, atau meminta penyedia OpenSearch mendapatkan halaman hasil tambahan baik berdasarkan nomor item atau nomor halaman. Misalnya, jika Anda mengirim dua puluh hasil per halaman, halaman pertama yang Anda kirim dimulai pada indeks item 1 dan di halaman 1; halaman kedua yang Anda kirim dimulai pada indeks item 21 dan di halaman 2. Anda dapat menentukan bagaimana Anda ingin penyedia OpenSearch meminta item dengan menggunakan token {startItem} atau {startPage} di templat URL.

Pemanggilan halaman menggunakan indeks item

Indeks item mengidentifikasi item hasil pertama di halaman hasil. Jika Anda ingin klien mengirim permintaan menggunakan indeks item, Anda dapat menggunakan token {startIndex} di elemen Urlatribut templat, seperti yang ditunjukkan dalam kode berikut.

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

Penyedia OpenSearch kemudian mengganti token di URL dengan nilai indeks awal. Permintaan pertama dimulai dengan item pertama, seperti yang diilustrasikan dalam contoh berikut:

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

Penyedia OpenSearch bisa mendapatkan item tambahan dengan mengubah nilai parameter {startIndex} dan mengeluarkan permintaan baru. Penyedia mengulangi proses ini sampai mendapatkan hasil yang cukup untuk memenuhi batasnya, atau mencapai akhir hasil. Penyedia OpenSearch melihat jumlah item yang dikembalikan oleh layanan web di halaman pertama hasil, dan mengatur ukuran halaman yang diharapkan ke angka tersebut. Ini menggunakan angka tersebut untuk menaikkan nilai {startIndex} untuk permintaan berikutnya. Misalnya, jika layanan web mengembalikan 20 hasil dalam permintaan pertama, maka penyedia menetapkan ukuran halaman yang diharapkan menjadi 20. Untuk permintaan berikutnya, penyedia mengganti {startIndex} dengan nilai 21 untuk mendapatkan 20 item berikutnya.

Penomoran halaman menggunakan indeks halaman

Indeks halaman mengidentifikasi halaman hasil yang ditentukan. Jika Anda ingin klien mengirim permintaan menggunakan nomor halaman, Anda dapat menggunakan token {startPage} dalam format Url elemen atribut templat untuk menunjukkan bahwa, seperti yang diilustrasikan dalam contoh berikut:

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

Penyedia OpenSearch kemudian mengganti token di URL dengan parameter nomor halaman. Permintaan pertama dimulai dengan halaman pertama, seperti yang ditunjukkan dalam contoh berikut:

https://example.com/rss.php?query=frogs&page=1

Ukuran halaman

Anda mungkin ingin mengonfigurasi layanan web Anda untuk mengizinkan permintaan untuk menentukan ukuran halaman dengan menggunakan beberapa parameter di URL. Permintaan harus ditentukan dalam file .osdx dengan menggunakan token {count}, sebagai berikut:

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

Penyedia OpenSearch kemudian dapat mengatur ukuran halaman yang diinginkan, dalam jumlah hasil per halaman, seperti yang ditunjukkan dalam contoh berikut:

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

Secara default penyedia OpenSearch membuat permintaan menggunakan ukuran halaman 50. Jika Anda menginginkan ukuran halaman yang berbeda, maka jangan berikan token {count}, dan sebagai gantinya letakkan angka yang diinginkan langsung di templat Url elemen.

Penyedia OpenSearch menentukan ukuran halaman berdasarkan jumlah hasil yang dikembalikan pada permintaan pertama. Jika halaman pertama hasil yang diterima memiliki lebih sedikit item daripada jumlah yang diminta, penyedia mengatur ulang ukuran halaman untuk permintaan halaman berikutnya. Jika permintaan halaman berikutnya mengembalikan lebih sedikit item daripada yang diminta, penyedia OpenSearch mengasumsikan bahwa itu telah mencapai akhir hasil.

Elemen yang diperluas di Windows Federated Search

Selain elemen standar, pencarian federasi mendukung elemen yang diperluas berikut: MaximumResultCount dan ResultsProcessing.

Karena elemen turunan yang diperluas ini tidak didukung dalam spesifikasi OpenSearch v1.1, elemen tersebut harus ditambahkan dengan menggunakan namespace layanan berikut:

http://schemas.microsoft.com/opensearchext/2009/

Jumlah hasil maksimum

Secara default, konektor pencarian dibatasi hingga 100 hasil per kueri pengguna. Batas ini dapat disesuaikan dengan menyertakan elemen MaximumResultCount dalam file OSD seperti yang ditunjukkan dalam contoh berikut:

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

Contoh sebelumnya mendeklarasikan awalan namespace ms-ose di elemen OpenSearchDescription tingkat atas, lalu menggunakannya sebagai awalan dalam nama elemen. Deklarasi ini diperlukan karena MaximumResultCount tidak didukung dalam spesifikasi OpenSearch v1.1.

Pemetaan properti

Ketika hasil dikembalikan oleh layanan web sebagai umpan RSS atau Atom, penyedia OpenSearch harus memetakan metadata item dalam umpan ke properti yang dapat digunakan Windows Shell. Cuplikan layar berikut menggambarkan bagaimana penyedia OpenSearch memetakan beberapa elemen RSS default.

Pemetaan default

Pemetaan default elemen XML RSS ke properti sistem Windows Shell, tercantum dalam tabel berikut. Jalur XML relatif terhadap elemen item. Awalan "media:" ditentukan oleh namespace Yahoo Search Namespace.

Pemetaan properti kustom

Anda dapat menyesuaikan pemetaan elemen dari output RSS Anda ke properti sistem Windows Shell dengan menentukan pemetaan dalam file .osdx.

Output RSS menyatakan:

• Namespace XML, dan
• Untuk elemen turunan item apa pun, nama elemen yang akan dipetakan.

File .osdx mengidentifikasi properti Windows Shell untuk setiap nama elemen dalam namespace. Pemetaan properti yang Anda tentukan dalam file .osdx menggantikan pemetaan default, jika ada, untuk properti yang ditentukan tersebut.

Diagram berikut ini mengilustrasikan bagaimana sebuah ekstensi RSS dipetakan ke dalam properti Windows (nama kanonis).

diagram

Contoh hasil RSS dan pemetaan properti OSD

Contoh output RSS berikut mengidentifikasi https://example.com/schema/2009 sebagai namespace XML dengan awalan "contoh". Awalan ini harus muncul lagi sebelum elemen email .

<rss version="2.0" xmlns:example="https://example.com/schema/2009">
   ...
    <item>
      <title>Someone</title>
      <example:email>[email protected]</example:email>
    </item>

Dalam contoh file .osdx berikut, elemen email XML dipetakan ke properti 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>

Ada beberapa properti yang tidak dapat dipetakan karena nilainya akan ditimpa di kemudian hari atau tidak dapat diedit. Misalnya, System.ItemFolderPathDisplay atau System.ItemPathDisplayNarrow tidak dapat dipetakan karena dihitung dari nilai URL yang disediakan di elemen tautan atau penutup.

Gambar mini

URL gambar mini dapat disediakan untuk item apa pun dengan menggunakan elemen media:thumbnail url="". Resolusi idealnya adalah 150 x 150 piksel. Gambar mini terbesar yang didukung adalah 256 x 256 piksel. Menyediakan gambar yang lebih besar membutuhkan lebih banyak bandwidth tanpa manfaat tambahan bagi pengguna.

Buka menu konteks di lokasi file

Windows menyediakan menu pintasan bernama Buka lokasi file untuk item hasil. Jika pengguna memilih item dari menu tersebut, URL "induk" untuk item yang dipilih akan dibuka. Jika URL adalah URL web, seperti https://..., browser web dibuka dan dinavigasi ke URL tersebut. Umpan Anda harus menyediakan URL kustom untuk setiap item untuk memastikan bahwa Windows membuka URL yang valid. Ini dapat dicapai dengan menyertakan URL dalam elemen di dalam XML item, seperti yang diilustrasikan dalam contoh berikut:

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

Jika properti ini tidak secara eksplisit diatur dalam XML item, penyedia OpenSearch mengaturnya ke folder induk URL item. Dalam contoh di atas, penyedia OpenSearch akan menggunakan nilai tautan, dan mengatur nilai properti System.ItemFolderPathDisplay Windows Shell ke "https://example.com/".

Mengkustomisasi tampilan Windows Explorer dengan daftar deskripsi properti

Beberapa tata letak tampilan Windows Explorer ditentukan berdasarkan daftar deskripsi properti, atau proplists. Proplis adalah daftar properti yang dibatasi titik koma, seperti "prop:System.ItemName; System.Author", yang digunakan untuk mengontrol bagaimana hasil Anda muncul di Windows Explorer.

Area UI Windows Explorer yang dapat disesuaikan dengan menggunakan daftar properti ditunjukkan dalam tangkapan layar berikut:

Setiap area di Windows Explorer memiliki sekumpulan daftar properti terkait, yang juga ditentukan sebagai properti. Anda dapat menentukan daftar properti kustom untuk item individual dalam kumpulan hasil Anda atau untuk semua item dalam kumpulan hasil.

Untuk menentukan proplist unik untuk item tertentu:

1. Dalam output RSS Anda, tambahkan elemen kustom yang mewakili proplis yang ingin Anda sesuaikan. Misalnya, contoh berikut mengatur daftar untuk panel detail:

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

2. Untuk menerapkan properti ke setiap item dalam hasil pencarian tanpa memodifikasi output RSS, tentukan proplis dalam elemen ms-ose:PropertyDefaultValues dalam file .osdx, seperti yang ditunjukkan dalam contoh berikut:

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

Tata letak mode tampilan properti konten

Daftar properti yang ditentukan dalam System.PropList.ContentViewModeForSearch dan System.PropList.ContentViewModeForBrowse proplists menentukan apa yang ditampilkan dalam mode tampilan Konten. Untuk informasi selengkapnya tentang daftar properti, lihat PropList.

Properti ditata sesuai dengan angka yang ditunjukkan dalam pola tata letak berikut:

cuplikan layar

Jika kita menggunakan daftar properti berikut,

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

Kemudian kita melihat tampilan berikut:

Bendera daftar properti

Hanya satu penanda yang ditentukan dalam dokumentasi proplists yang berlaku untuk penampilan item dalam tata letak mode Tampilan Konten: "~". Dalam contoh sebelumnya, tampilan Windows Explorer melabeli beberapa properti, seperti Tags: animals; zoo; lion. Itu adalah perilaku default saat Anda menentukan properti dalam daftar. Misalnya, daftar properti memiliki "System.Author" yang ditampilkan sebagai "Authors: value". Saat Anda ingin menyembunyikan label properti, letakkan "~" di depan nama properti. Misalnya, jika proplis memiliki "~System.Size", properti ditampilkan hanya sebagai nilai, tanpa label.

Pratinjau-pratinjau

Saat pengguna memilih item hasil di Windows Explorer dan panel pratinjau terbuka, konten item dipratinjau.

Konten yang akan ditampilkan dalam pratinjau ditentukan oleh URL, yang ditentukan sebagai berikut:

1. Jika properti System.WebPreviewUrl Windows Shell diatur untuk item tersebut, maka gunakan URL tersebut.

   Nota

   Properti perlu disediakan di RSS dengan menggunakan namespace Windows Shell, atau dipetakan secara eksplisit dalam file .osdx.

    

2. Jika tidak, gunakan URL tautan sebagai gantinya.

Diagram alur berikut menunjukkan logika ini.

Dimungkinkan untuk menggunakan URL yang berbeda untuk pratinjau daripada untuk item itu sendiri. Ini berarti bahwa jika Anda menyediakan URL yang berbeda untuk URL tautan dan penutup atau media:content URL, Windows Explorer menggunakan URL tautan untuk pratinjau item tetapi menggunakan URL lain untuk deteksi jenis file, membuka, mengunduh, dan sebagainya.

Cara Windows Explorer menentukan URL apa yang akan digunakan:

1. Jika Anda menyediakan pemetaan untuk System.ItemFolderPathDisplay, maka Windows Explorer menggunakan URL tersebut

2. Jika Anda tidak menyediakan pemetaan, maka Windows Explorer mengidentifikasi apakah tautan dan URL penutup berbeda. Jika demikian, maka Windows Explorer menggunakan URL tautan.

3. Jika URL sama atau hanya ada URL tautan, Maka Windows Explorer mengurai tautan untuk menemukan kontainer induk dengan menghapus nama file dari URL lengkap.

   Nota

   Jika Anda mengenali bahwa penguraian URL akan mengakibatkan tautan mati untuk layanan Anda, Anda harus memberikan pemetaan eksplisit untuk properti tersebut.

    

Buka item menu lokasi file

Saat mengklik kanan item, perintah Buka lokasi file menu muncul. Perintah ini membawa pengguna ke kontainer untuk atau lokasi item tersebut. Misalnya, dalam pencarian SharePoint, memilih opsi ini untuk file di pustaka dokumen akan membuka akar pustaka dokumen di browser web.

Saat pengguna mengklik Buka lokasi file, Windows Explorer mencoba menemukan kontainer induk, dengan menggunakan logika yang diperlihatkan dalam diagram alur berikut:

Sumber daya tambahan

Untuk informasi tambahan tentang menerapkan federasi pencarian ke penyimpanan data jarak jauh menggunakan teknologi OpenSearch di Windows 7 dan yang lebih baru, lihat "Sumber Daya Tambahan" di Federated Search di Windows.

Topik terkait

Pencarian Federasi di Windows

Memulai Pencarian Terpadu di Windows

Menyambungkan Layanan web Anda di Pencarian Federasi Windows

Mengaktifkan Penyimpanan Data Anda di Windows Federated Search

Mengikuti Praktik Terbaik di Windows Federated Search

Menyebarkan Konektor Pencarian di Windows Federated Search