Tworzenie pliku opisu OpenSearch w usłudze Windows Federated Search

Opisuje sposób tworzenia pliku OpenSearch Description (osdx) w celu połączenia zewnętrznych magazynów danych z klientem systemu Windows za pośrednictwem protokołu OpenSearch. Wyszukiwanie federacyjne umożliwia użytkownikom przeszukiwanie zdalnego magazynu danych i wyświetlanie wyników w Eksploratorze Windows.

Ten temat zawiera następujące sekcje:

• Plik opisu OpenSearch
  • Minimalne wymagane elementy podrzędne
• Elementy standardowe w usłudze Windows Federated Search
  • Skrócona_nazwa
  • opis
  • szablon adresu URL dla wyników RSS/Atom
  • szablon adresu URL dla wyników internetowych
  • parametry szablonu adresu URL
  • Wyniki stronicowane
  • stronicowanie z użyciem indeksu elementów
  • Stronicowanie za pomocą indeksu strony
  • rozmiar strony
• Rozszerzone Elementy w usłudze Windows Federated Search
  • maksymalna liczba wyników
  • mapowanie właściwości
• podglądów
• otwórz element menu Lokalizacja pliku
• dodatkowe zasoby
• Tematy pokrewne

Plik opisu OpenSearch

Plik opisu OpenSearch (osdx) dla usługi Windows Federated Search musi przestrzegać następujących reguł:

• Ma być prawidłowym dokumentem Opisu OpenSearch, zgodnie ze specyfikacją OpenSearch 1.1.
• Podaj szablon adresu URL z typem formatu RSS lub Atom.
• Użyj rozszerzenia nazwy pliku osdx lub skojarz je z rozszerzeniem nazwy pliku osdx podczas pobierania z sieci Web. Na przykład nie jest wymagane, aby serwer używał pliku .osdx. Serwer może zwrócić plik z dowolnym rozszerzeniem nazwy pliku, na przykład .xml, i plik ten zostanie potraktowany tak, jak gdyby był plikiem .osdx, pod warunkiem użycia poprawnego typu MIME dla dokumentów opisu OpenSearch (.osdx).
• Podaj wartość elementu ShortName (zalecane).

Minimalne wymagane elementy podrzędne

Poniższy przykładowy plik osdx składa się z ShortName i Url elementów, które są minimalnymi wymaganymi elementami podrzędnymi.

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

Elementy standardowe w usłudze Windows Federated Search

Oprócz minimalnych elementów podrzędnych wyszukiwanie federacyjne obsługuje następujące elementy standardowe.

Krótka nazwa

System Windows używa wartości elementu ShortName, aby nazwać plik .searchconnector-ms (łącznik wyszukiwania), który jest tworzony, gdy użytkownik otworzy plik osdx. System Windows zapewnia, że wygenerowana nazwa pliku używa tylko znaków, które są dozwolone w nazwach plików systemu Windows. Jeśli nie podano wartości ShortName, plik .searchconnector-ms próbuje użyć nazwy pliku osdx.

Poniższy kod ilustruje sposób użycia elementu ShortName w pliku osdx.

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

Opis

System Windows używa wartości elementu Description, aby wypełnić opis pliku wyświetlany w okienku szczegółów Eksploratora Windows, gdy użytkownik wybierze plik .searchconnector-ms.

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

Szablon adresu URL dla wyników rss/atom

Plik .osdx musi zawierać jeden element formatu adresu URL i atrybut szablonu (szablon adresu URL), który zwraca wyniki w formacie RSS lub Atom. Atrybut formatu musi być ustawiony na application/rss+xml dla wyników sformatowanych przez funkcję RSS lub application/atom+xml dla wyników sformatowanych przez program Atom, jak pokazano w poniższym kodzie.

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

Szablon adresu URL dla wyników internetowych

Jeśli istnieje wersja wyników wyszukiwania, którą można wyświetlić w przeglądarce internetowej, należy podać element format adresu URL=text/html oraz atrybut szablonu, jak pokazano w poniższym kodzie.

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

Jeśli podasz element Url format="text/html" oraz atrybut szablonu , na pasku poleceń Eksploratora Windows pojawi się przycisk, jak pokazano na poniższym zrzucie ekranu, który umożliwia użytkownikowi otworzenie przeglądarki internetowej w celu wyświetlenia wyników wyszukiwania, gdy użytkownik wykonuje zapytanie.

Przerzucanie zapytania z powrotem do internetowego interfejsu użytkownika magazynu danych jest ważne w niektórych scenariuszach. Na przykład użytkownik może chcieć wyświetlić więcej niż 100 wyników (domyślna liczba elementów, o które prosi dostawca OpenSearch). Jeśli tak, użytkownik może również chcieć użyć funkcji wyszukiwania, które są dostępne tylko w witrynie internetowej magazynu danych, takich jak ponowne wykonywanie zapytań z inną kolejnością sortowania lub przestawiania i filtrowania zapytania za pomocą powiązanych metadanych.

Parametry szablonu adresu URL

Dostawca OpenSearch wykonuje zawsze następujące akcje:

1. Używa szablonu adresu URL do wysyłania żądania do usługi internetowej.
2. Próbuje zastąpić tokeny znalezione w szablonie adresu URL przed wysłaniem żądania do usługi internetowej w następujący sposób:
   • Zastępuje standardowe tokeny OpenSearch wymienione w poniższej tabeli.
   • Usuwa wszystkie tokeny, które nie są wymienione w poniższej tabeli.

Stronicowane wyniki

Możesz ograniczyć liczbę zwracanych wyników na żądanie. Możesz wybrać zwrócenie „strony” wyników na raz lub pozwolić dostawcy OpenSearch uzyskać dodatkowe strony wyników według numeru elementu lub numeru strony. Jeśli na przykład wyślesz dwadzieścia wyników na stronę, pierwsza wysyłana strona rozpoczyna się od indeksu elementu 1 i na stronie 1; Druga wysyłana strona rozpoczyna się od indeksu elementu 21 i strony 2. Możesz zdefiniować sposób żądania elementów przez dostawcę OpenSearch przy użyciu {startItem} lub tokenu {startPage} w szablonie adresu URL.

Stronicowanie przy użyciu indeksu elementów

Indeks elementu identyfikuje pierwszy element wyniku na stronie wyników. Jeśli chcesz, aby klienci wysyłali żądania przy użyciu indeksu elementów, możesz użyć tokenu {startIndex} w url elementu elementu szablonu, jak pokazano w poniższym kodzie.

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

Następnie dostawca OpenSearch zastępuje token w adresie URL wartością indeksu początkowego. Pierwsze żądanie rozpoczyna się od pierwszego elementu, jak pokazano w poniższym przykładzie:

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

Dostawca OpenSearch może uzyskać dodatkowe elementy, zmieniając wartość parametru {startIndex} i wysyłając nowe żądanie. Dostawca powtarza ten proces, dopóki nie uzyska wystarczającej ilości wyników, aby spełnić limit lub osiągnie koniec wyników. Dostawca OpenSearch analizuje liczbę elementów zwracanych przez usługę internetową na pierwszej stronie wyników i ustawia oczekiwany rozmiar strony na ten numer. Używa tej liczby, aby zwiększać wartość {startIndex} dla kolejnych żądań. Jeśli na przykład usługa internetowa zwróci 20 wyników w pierwszym żądaniu, dostawca ustawia oczekiwany rozmiar strony na 20. W przypadku następnego żądania dostawca zastępuje {startIndex} wartością 21, aby uzyskać kolejne 20 elementów.

Stronicowanie przy użyciu indeksu strony

Indeks strony identyfikuje określoną stronę wyników. Jeśli chcesz, aby klienci wysyłali żądania z użyciem numeru strony, możesz użyć tokenu {startPage} w formacie adresu URL elementu szablonu atrybutu, aby to wskazać, co pokazano w poniższym przykładzie.

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

Następnie dostawca OpenSearch zastępuje token w adresie URL parametrem numer strony. Pierwsze żądanie rozpoczyna się od pierwszej strony, jak pokazano w poniższym przykładzie:

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

Rozmiar strony

Możesz skonfigurować usługę internetową, aby zezwolić na żądanie określenia rozmiaru stron przy użyciu parametru w adresie URL. Żądanie musi zostać określone w pliku osdx przy użyciu tokenu {count} w następujący sposób:

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

Dostawca OpenSearch może następnie ustawić żądany rozmiar strony w liczbie wyników na stronę, jak pokazano w poniższym przykładzie:

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

Domyślnie dostawca OpenSearch wysyła żądania przy użyciu domyślnego rozmiaru strony wynoszącego 50. Jeśli chcesz mieć inny rozmiar strony, nie podaj tokenu {count} i zamiast tego umieść żądany numer bezpośrednio w szablonie adresu URL .

Dostawca OpenSearch określa rozmiar strony na podstawie liczby wyników zwróconych w pierwszym żądaniu. Jeśli pierwsza strona odebranych wyników zawiera mniej elementów niż żądana liczba, dostawca resetuje rozmiar strony dla wszystkich kolejnych żądań strony. Jeśli kolejne żądania strony zwracają mniej elementów niż żądane, dostawca OpenSearch zakłada, że osiągnął koniec wyników.

Elementy rozszerzone w usłudze Windows Federated Search

Oprócz elementów standardowych wyszukiwanie federacyjne obsługuje następujące elementy rozszerzone: MaximumResultCount i ResultsProcessing.

Ponieważ te rozszerzone elementy podrzędne nie są obsługiwane w specyfikacji OpenSearch w wersji 1.1, należy je dodać przy użyciu następującej przestrzeni nazw:

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

Maksymalna liczba wyników

Domyślnie łączniki wyszukiwania są ograniczone do 100 wyników na zapytanie użytkownika. Ten limit można dostosować, włączając element MaximumResultCount w pliku OSD, jak pokazano w poniższym przykładzie:

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

Powyższy przykład deklaruje prefiks przestrzeni nazw ms-ose w elementu najwyższego poziomu OpenSearchDescription, a następnie używa go jako prefiksu w nazwie elementu. Ta deklaracja jest wymagana, ponieważ MaximumResultCount nie jest obsługiwany w specyfikacji OpenSearch w wersji 1.1.

Mapowanie właściwości

Gdy wyniki są zwracane przez serwis internetowy jako kanał informacyjny RSS lub Atom, dostawca OpenSearch musi przypisywać metadane elementu w kanałach informacyjnych do właściwości, których może używać powłoka Windows. Poniższy zrzut ekranu przedstawia sposób mapowania niektórych domyślnych elementów RSS przez dostawcę OpenSearch.

Mapowania domyślne

Domyślne mapowania elementów XML RSS na właściwości systemu Windows Shell są wymienione w poniższej tabeli. Ścieżki XML są względne względem elementu item. Prefiks "media:" jest definiowany przez przestrzeń nazw Yahoo Search.

Mapowania właściwości niestandardowych

Mapowanie elementów z danych wyjściowych RSS do właściwości systemu Windows Shell można dostosować, określając mapowanie w pliku osdx.

Dane wyjściowe RSS określają:

• Przestrzeń nazw XML i
• W przypadku dowolnego elementu podrzędnego elementu nazwa elementu, z którym należy dokonać mapowania.

Plik .osdx identyfikuje właściwość powłoki Windows dla każdej nazwy elementu w przestrzeni nazw. Mapowania właściwości zdefiniowane w pliku osdx zastępują domyślne mapowania, jeśli istnieją, dla tych określonych właściwości.

Na poniższym diagramie przedstawiono sposób mapowania rozszerzenia RSS na właściwości systemu Windows (nazwa kanoniczna).

Przykładowe mapowanie wyników RSS i właściwości OSD

Poniższe przykładowe dane wyjściowe RSS identyfikują https://example.com/schema/2009 jako przestrzeń nazw XML z prefiksem "example". Ten prefiks musi pojawić się ponownie przed elementem wiadomości e-mail.

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

W poniższym przykładzie pliku .osdx element XML e-mail jest mapowany na właściwość powłoki 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>

Nie można zamapować niektórych właściwości, ponieważ wartości dla nich są zastępowane później lub nie są edytowalne. Na przykład System.ItemFolderPathDisplay lub System.ItemPathDisplayNarrow nie można zamapować, ponieważ są one obliczane na podstawie wartości adresu URL podanej w linku lub elementach obudowy.

Miniatury

Adresy URL obrazów miniatur można podać dla dowolnego elementu przy użyciu elementu media:thumbnail url="" elementu. Idealna rozdzielczość to 150 x 150 pikseli. Największe obsługiwane miniatury to 256 x 256 pikseli. Zapewnienie większej przepustowości obrazów nie zapewnia dodatkowej korzyści użytkownikowi.

Otwórz menu kontekstowe lokalizacji pliku

System Windows udostępnia menu skrótów o nazwie Otwórz lokalizację pliku dla elementów wyników. Jeśli użytkownik wybierze element z tego menu, zostanie otwarty adres URL "nadrzędny" dla wybranego elementu. Jeśli adres URL jest adresem URL sieci Web, takim jak https://..., przeglądarka internetowa jest otwierana i przechodzi do tego adresu URL. Twoje źródło danych powinno podawać unikalny adres url dla każdego elementu, aby zapewnić, że system Windows otworzy prawidłowy adres. Można to osiągnąć, dołączając adres URL w elemencie wewnątrz kodu XML elementu, jak pokazano w poniższym przykładzie:

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

Jeśli ta właściwość nie jest jawnie ustawiona w kodzie XML elementu, dostawca OpenSearch ustawia go na folder nadrzędny adresu URL elementu. "W powyższym przykładzie dostawca OpenSearch będzie używać wartości łącza, a właściwość System.ItemFolderPathDisplay powłoki systemu Windows zostanie ustawiona na "https://example.com/"."

Dostosowywanie widoków Eksploratora Windows za pomocą list opisu właściwości

Niektóre układy widoku Eksploratora Windows są definiowane przez listy opisów właściwości lub listy proplist. Proplista to rozdzielana średnikami lista właściwości, takich jak "prop:System.ItemName; System.Author", która służy do kontrolowania sposobu wyświetlania wyników w Eksploratorze Windows.

Obszary interfejsu użytkownika Eksploratora Windows, które można dostosować za pomocą list proplist, są ilustrowane w poniższym zrzucie ekranu:

Każdy obszar Eksploratora Windows ma skojarzony zestaw proplist, które same są określane jako właściwości. Możesz określić niestandardowe listy właściwości dla pojedynczych elementów w zestawach wyników lub dla wszystkich elementów w zestawie wyników.

Aby określić unikatową listę proplist dla pojedynczego elementu:

1. W danych wyjściowych RSS dodaj element niestandardowy reprezentujący listę właściwości, które chcesz dostosować. Na przykład poniższy przykład ustawia listę okienka szczegółów:

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

2. Aby zastosować właściwość do każdego elementu w wynikach wyszukiwania bez modyfikowania danych wyjściowych RSS, określ proplist w elemencie ms-ose:PropertyDefaultValues w pliku .osdx, jak pokazano w następującym przykładzie.

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

Układ właściwości w trybie widoku zawartości

Lista właściwości określonych w System.PropList.ContentViewModeForSearch i System.PropList.ContentViewModeForBrowse listach właściwości określają, co jest wyświetlane w trybie widoku zawartości. Aby uzyskać więcej informacji na temat list właściwości, zobacz PropList.

Właściwości są ułożone zgodnie z liczbami pokazanymi w następującym wzorcu układu:

Jeśli użyjemy następującej listy właściwości,

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

Następnie zostanie wyświetlony następujący ekran:

Flagi listy właściwości

Tylko jedna flaga zdefiniowana w dokumentacji proplists ma zastosowanie do wyświetlania elementów w układach trybu widoku zawartości: "~". W poprzednich przykładach w Eksploratorze Windows są wyświetlane etykiety niektórych właściwości, takich jak Tags: animals; zoo; lion. Jest to zachowanie domyślne podczas określania właściwości na liście. Na przykład lista właściwości zawiera "System.Author", które jest wyświetlane jako "Authors: value". Jeśli chcesz ukryć etykietę właściwości, umieść "~" przed nazwą właściwości. Jeśli na przykład proplista ma "~System.Size", właściwość jest wyświetlana tylko jako wartość, bez etykiety.

Podglądy

Gdy użytkownik wybierze element wyniku w Eksploratorze Windows i okienko podglądu jest otwarte, zawartość elementu jest wyświetlana w podglądzie.

Zawartość wyświetlana w wersji zapoznawczej jest określana przez adres URL, który jest określany w następujący sposób:

1. Jeśli dla elementu ustawiona jest właściwość powłoki systemu Windows System.WebPreviewUrl, użyj tego adresu URL.

   Notatka

   Właściwość musi być podana w funkcji RSS przy użyciu przestrzeni nazw powłoki systemu Windows lub jawnie zamapowana w pliku osdx.

    

2. Jeśli nie, zamiast tego użyj adresu URL łącza.

Poniższy schemat blokowy przedstawia tę logikę.

W wersji zapoznawczej można użyć innego adresu URL niż dla samego elementu. Oznacza to, że w przypadku podania różnych adresów URL linku i obudowy lub media:content URLEksplorator Windows używa adresu URL linku do podglądu elementu, ale używa innego adresu URL do wykrywania typów plików, otwierania, pobierania i tak dalej.

Jak Eksplorator Windows określa adres URL, który ma być używany:

1. Jeśli podasz mapowanie System.ItemFolderPathDisplay, Eksplorator Windows używa tego adresu URL

2. Jeśli nie podasz mapowania, Eksplorator Windows określi, czy linki i adresy URL załączników są inne. Jeśli tak, Eksplorator Windows używa adresu URL linku.

3. Jeśli adresy URL są takie same lub jeśli istnieje tylko adres URL łącza, Eksplorator Windows analizuje link w celu znalezienia kontenera nadrzędnego, usuwając nazwę pliku z pełnego adresu URL.

   Notatka

   Jeśli rozpoznasz, że parsowanie adresów URL spowodowałoby nieaktywne linki dla twojej usługi, powinieneś podać jawne mapowanie dla właściwości.

    

Otwórz element menu Lokalizacja pliku

Po kliknięciu prawym przyciskiem myszy na elemencie pojawia się polecenie menu Otwórz lokalizację pliku. To polecenie powoduje przejście użytkownika do kontenera dla tego elementu lub jego lokalizacji. Na przykład w wyszukiwaniu programu SharePoint wybranie tej opcji dla pliku w bibliotece dokumentów spowoduje otwarcie katalogu głównego biblioteki dokumentów w przeglądarce internetowej.

Gdy użytkownik kliknie Otwórz lokalizację pliku, Eksplorator Windows próbuje znaleźć kontener nadrzędny przy użyciu logiki pokazanej w następującym schemacie blokowym:

kontenera nadrzędnego w Eksploratorze Windows

Dodatkowe zasoby

Aby uzyskać dodatkowe informacje na temat implementacji federacyjnego wyszukiwania w zdalnych magazynach danych za pomocą technologii OpenSearch w systemie Windows 7 i nowszych, zobacz "Dodatkowe zasoby" w Federacyjne wyszukiwanie w systemie Windows.

Tematy pokrewne

wyszukiwanie federacyjne w systemie Windows

Wprowadzenie do wyszukiwania federacyjnego w systemie Windows

Łączenie Twojej usługi sieciowej w Usłudze Windows Federated Search

Włączanie Twojego Magazynu Danych w Usłudze Windows Federated Search

Zgodnie z najlepszymi praktykami w usłudze Windows Federated Search

Wdrażanie łączników wyszukiwania w Windows Federated Search