Een OpenSearch-beschrijvingsbestand maken in Windows Federated Search

Hierin wordt beschreven hoe u een OpenSearch Description-bestand (.osdx) maakt om externe gegevensarchieven te verbinden met de Windows-client via het OpenSearch-protocol. Met federatieve zoekopdrachten kunnen gebruikers zoeken in een extern gegevensarchief en de resultaten bekijken vanuit Windows Verkenner.

Dit onderwerp bevat de volgende secties:

• Beschrijvingsbestand van OpenSearch
  • minimum aantal vereiste onderliggende elementen
• Standaardelementen in Windows Federated Search
  • Shortname
  • Beschrijving
  • URL-sjabloon voor RSS-/Atom-resultaten
  • URL-sjabloon voor webresultaten
  • URL-sjabloonparameters
  • paginagebonden resultaten
  • Pagineren met de itemindex
  • paging met behulp van de pagina-index
  • paginaformaat
• uitgebreide elementen in Windows Federated Search
  • maximumaantal resultaten
  • eigenschapstoewijzing
• voorvertoningen
• Menuoptie Bestandslocatie openen
• Aanvullende middelen
• Verwante onderwerpen

OpenSearch-beschrijvingsbestand

Een OpenSearch Description-bestand (.osdx) voor Windows Federated Search moet voldoen aan de volgende regels:

• Wees een geldig OpenSearch Description-document, zoals gedefinieerd door de specificatie OpenSearch 1.1.
• Geef een URL-sjabloon op met een RSS- of Atom-indelingstype.
• Gebruik de bestandsextensie .osdx of zorg ervoor dat deze geassocieerd is met de bestandsextensie .osdx bij het downloaden van het web. Een server is bijvoorbeeld niet vereist voor het gebruik van .osdx. Een server kan het bestand retourneren met een bestandsnaamextensie, zoals bijvoorbeeld .xml, en behandeld alsof het een .osdx-bestand is als het het juiste MIME-type gebruikt voor OpenSearch Description-documenten (.osdx-bestanden).
• Geef een ShortName elementwaarde op (aanbevolen).

Minimum vereiste kindelementen

Het volgende voorbeeldbestand .osdx bestaat uit ShortName-- en Url-elementen. Dit zijn de minimaal vereiste onderliggende elementen.

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

Standaardelementen in Windows Federated Search

Naast de minimale onderliggende elementen ondersteunt federatieve zoekopdrachten de volgende standaardelementen.

Korte naam

Windows gebruikt de waarde van het ShortName-element om het .searchconnector-ms-bestand (zoekconnector) te noemen dat wordt gemaakt wanneer de gebruiker het .osdx-bestand opent. Windows zorgt ervoor dat de gegenereerde bestandsnaam alleen tekens gebruikt die zijn toegestaan in Windows-bestandsnamen. Als er geen ShortName--waarde wordt opgegeven, probeert het bestand .searchconnector-ms de bestandsnaam van het .osdx-bestand te gebruiken.

De volgende code illustreert hoe u het element ShortName gebruikt in een OSDX-bestand.

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

Beschrijving

Windows gebruikt de Description elementwaarde om de bestandsbeschrijving te vullen die wordt weergegeven in het detailvenster van Windows Verkenner wanneer een gebruiker een .searchconnector-ms-bestand selecteert.

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

URL-sjabloon voor rss-/atomresultaten

Het .osdx-bestand moet één URL-indeling element bevatten en sjabloon kenmerk (een URL-sjabloon) die resultaten retourneert in RSS- of Atom-indeling. Het indelingskenmerk moet worden ingesteld op application/rss+xml voor met RSS opgemaakte resultaten of application/atom+xml voor atom-opgemaakte resultaten, zoals wordt weergegeven in de volgende code.

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

URL-sjabloon voor webresultaten

Als er een versie van de zoekresultaten is die in een webbrowser kan worden weergegeven, moet u een URL-indeling=text/html element opgeven en sjabloon kenmerk, zoals wordt weergegeven in de volgende code.

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

Als u een Url format="text/html" element en sjabloon kenmerk opgeeft, verschijnt er een knop op de opdrachtbalk van Windows Verkenner, zoals te zien in de volgende schermafbeelding. Hiermee kan de gebruiker een webbrowser openen om de zoekresultaten te bekijken wanneer er een query wordt uitgevoerd.

Het doorsturen van de query naar de webgebruikersinterface van de gegevensopslag is in sommige scenario's belangrijk. Een gebruiker kan bijvoorbeeld meer dan 100 resultaten bekijken (het standaardaantal items dat door de OpenSearch-provider wordt aangevraagd). Zo ja, dan wil de gebruiker mogelijk ook zoekfuncties gebruiken die alleen beschikbaar zijn op de website van het gegevensarchief, zoals opnieuw query's uitvoeren met een andere sorteervolgorde, of de query draaien en filteren met gerelateerde metagegevens.

URL-sjabloonparameters

De OpenSearch-provider voert altijd de volgende acties uit:

1. Gebruikt de URL-sjabloon om de aanvraag naar de webservice te verzenden.
2. Pogingen om de tokens in de URL-sjabloon te vervangen voordat de aanvraag naar de webservice wordt verzonden, als volgt:
   • Vervangt de standaard OpenSearch-tokens die worden vermeld in de volgende tabel.
   • Hiermee verwijdert u alle tokens die niet worden vermeld in de volgende tabel.

Gepaginade resultaten

U kunt het aantal geretourneerde resultaten per aanvraag beperken. U kunt ervoor kiezen om een pagina met resultaten tegelijk te retourneren of om de OpenSearch-provider extra pagina's met resultaten te laten ophalen op itemnummer of paginanummer. Als u bijvoorbeeld twintig resultaten per pagina verzendt, begint de eerste pagina die u verzendt bij itemindex 1 en op pagina 1; de tweede pagina die u verzendt, begint bij itemindex 21 en op pagina 2. U kunt definiëren hoe u wilt dat de OpenSearch-provider items aanvraagt met behulp van de {startItem} of het {startPage} token in de URL-sjabloon.

Paging met behulp van de itemindex

Een itemindex identificeert het eerste resultaatitem op een pagina met resultaten. Als u wilt dat clients aanvragen verzenden met behulp van een itemindex, kunt u het {startIndex} token gebruiken in uw URL element sjabloon kenmerk, zoals wordt weergegeven in de volgende code.

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

De OpenSearch provider vervangt vervolgens het token in de URL door een beginindexwaarde. De eerste aanvraag begint met het eerste item, zoals wordt geïllustreerd in het volgende voorbeeld:

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

De OpenSearch-provider kan extra items ophalen door de parameterwaarde {startIndex} te wijzigen en een nieuwe aanvraag uit te geven. De provider herhaalt dit proces totdat het voldoende resultaten krijgt om aan de limiet te voldoen of het einde van de resultaten bereikt. De OpenSearch-provider kijkt naar het aantal items dat door de webservice op de eerste pagina met resultaten wordt geretourneerd en stelt het verwachte paginaformaat in op dat getal. Het gebruikt dat getal om de {startIndex} waarde voor volgende aanvragen te verhogen. Als de webservice bijvoorbeeld 20 resultaten retourneert in de eerste aanvraag, stelt de provider het verwachte paginaformaat in op 20. Voor de volgende aanvraag vervangt de provider {startIndex} door de waarde 21 om de volgende 20 items op te halen.

Paging met behulp van de pagina-index

Een pagina-index identificeert de opgegeven pagina met resultaten. Als u wilt dat klanten aanvragen verzenden met behulp van een paginanummer, kunt u het {startPage} token gebruiken in de URL-indeling element sjabloon kenmerk om dat aan te geven, zoals geïllustreerd in het volgende voorbeeld:

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

De OpenSearch-provider vervangt vervolgens het token in de URL door een parameter voor het paginanummer. De eerste aanvraag begint met de eerste pagina, zoals wordt weergegeven in het volgende voorbeeld:

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

Paginaformaat

U kunt uw webservice zo configureren dat een aanvraag de grootte van de pagina's kan opgeven met behulp van een parameter in de URL. Een aanvraag moet als volgt worden opgegeven in het .osdx-bestand met behulp van het {count} token:

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

De OpenSearch provider kan vervolgens het gewenste paginaformaat instellen, in het aantal resultaten per pagina, zoals wordt weergegeven in het volgende voorbeeld:

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

De OpenSearch-provider doet standaard aanvragen met een paginagrootte van 50. Als u een ander paginaformaat wilt, geeft u geen {count} token op en plaatst u in plaats daarvan het gewenste nummer rechtstreeks in het URL-sjabloon element.

De OpenSearch-provider bepaalt het paginaformaat op basis van het aantal resultaten dat wordt geretourneerd op de eerste aanvraag. Als de eerste pagina met ontvangen resultaten minder items bevat dan het aantal dat is aangevraagd, stelt de provider de paginagrootte opnieuw in voor eventuele volgende paginaaanvragen. Als volgende paginaaanvragen minder items retourneren dan aangevraagd, gaat de OpenSearch-provider ervan uit dat deze het einde van de resultaten heeft bereikt.

Uitgebreide elementen in Windows Federated Search

Naast de standaardelementen ondersteunt federatieve zoekopdrachten de volgende uitgebreide elementen: MaximumResultCount en ResultsProcessing.

Omdat deze uitgebreide onderliggende elementen niet worden ondersteund in de specificatie OpenSearch v1.1, moeten ze worden toegevoegd met behulp van de volgende naamruimte:

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

Maximumaantal resultaten

Standaard zijn zoekconnectors beperkt tot 100 resultaten per gebruikersquery. Deze limiet kan worden aangepast door het element MaximumResultCount in het OSD-bestand op te tellen, zoals wordt weergegeven in het volgende voorbeeld:

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

In het voorgaande voorbeeld wordt het voorvoegsel van de naamruimte ms-ose gedeclareerd in het topelement OpenSearchDescription en vervolgens wordt het gebruikt als voorvoegsel in de elementnaam. Deze declaratie is vereist omdat de MaximumResultCount- niet wordt ondersteund in de specificatie OpenSearch v1.1.

Eigenschapstoewijzing

Wanneer resultaten worden geretourneerd door de webservice als RSS- of Atom-feed, moet de OpenSearch-provider de metagegevens van het item in de feeds toewijzen aan eigenschappen die de Windows Shell kan gebruiken. In de volgende schermafbeelding ziet u hoe de OpenSearch-provider enkele van de standaard RSS-elementen toewijst.

Standaardtoewijzingen

De standaardtoewijzingen van RSS XML-elementen aan systeemeigenschappen van Windows Shell worden vermeld in de volgende tabel. XML-paden zijn relatief ten opzichte van het itemelement. Het "media:" voorvoegsel wordt gedefinieerd door de Yahoo Search-naamruimte.

Aangepaste eigenschapstoewijzingen

U kunt de toewijzing van elementen van uw RSS-uitvoer aanpassen aan de systeemeigenschappen van Windows Shell door de toewijzing op te geven in het OSDX-bestand.

De RSS-uitvoer geeft het volgende op:

• Een XML-naamruimte en
• Voor elk onderliggend element van een item, een elementnaam om mee te vergelijken.

Het .osdx-bestand identificeert een Windows Shell-eigenschap voor elke elementnaam in een naamruimte. De eigenschapstoewijzingen die u in uw .osdx-bestand definieert, overschrijven de standaardtoewijzingen, indien aanwezig, voor deze opgegeven eigenschappen.

In het volgende diagram ziet u hoe een RSS-extensie wordt toegewezen aan Windows-eigenschappen (canonieke naam).

oplevert

Voorbeeld van RSS-resultaten en toewijzing van OSD-eigenschappen

De volgende voorbeeld-RSS-uitvoer identificeert https://example.com/schema/2009 als de XML-naamruimte met het voorvoegsel 'voorbeeld'. Dit voorvoegsel moet opnieuw verschijnen vóór het e-mailelement.

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

In het volgende voorbeeld .osdx-bestand wordt het XML--e-mailelement toegewezen aan de eigenschap 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>

Er zijn enkele eigenschappen die niet kunnen worden toegewezen omdat de waarden voor deze eigenschappen later worden overschreven of niet kunnen worden gewijzigd. System.ItemFolderPathDisplay of System.ItemPathDisplayNarrow kan niet worden toegewezen bijvoorbeeld omdat zij worden berekend op basis van de URL-waarde die is opgegeven in de link- of enclosure-elementen.

Miniatuurweergaven

Url's voor miniatuurafbeeldingen kunnen worden opgegeven voor elk item met behulp van het media:thumbnail url="" element. De ideale resolutie is 150 x 150 pixels. De grootste miniaturen die worden ondersteund, zijn 256 x 256 pixels. Het leveren van grotere afbeeldingen vergt meer bandbreedte zonder extra voordeel voor de gebruiker.

Bestandslocatie openen via het contextmenu

Windows biedt een snelmenu met de naam Bestandslocatie openen voor resultaatitems. Als de gebruiker een item in dat menu selecteert, wordt de 'bovenliggende' URL voor het geselecteerde item geopend. Als de URL een web-URL is, zoals https://..., wordt de webbrowser geopend en naar die URL genavigeerd. Uw feed moet een aangepaste URL voor elk item opgeven om ervoor te zorgen dat Windows een geldige URL opent. Dit kan worden bereikt door de URL op te geven binnen een element in de XML van het item, zoals wordt geïllustreerd in het volgende voorbeeld:

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

Als deze eigenschap niet expliciet is ingesteld in de XML van het item, stelt de OpenSearch-provider deze in op de bovenliggende map van de URL van het item. In het bovenstaande voorbeeld zou de OpenSearch-provider de koppelingswaarde gebruiken en de eigenschapswaarde System.ItemFolderPathDisplay Windows Shell instellen op "https://example.com/".

Weergaven van Windows Verkenner aanpassen met lijsten met eigenschappenbeschrijvingen

Sommige weergave-indelingen van Windows Verkenner worden gedefinieerd door lijsten met eigenschappenbeschrijvingen of proplists. Een proplist is een door puntkomma's gescheiden lijst met eigenschappen, zoals "prop:System.ItemName; System.Author", die wordt gebruikt om te bepalen hoe uw resultaten worden weergegeven in Windows Verkenner.

De ui-gebieden van Windows Verkenner die kunnen worden aangepast met behulp van proplists, worden geïllustreerd in de volgende schermafbeelding:

Elk gebied van Windows Verkenner heeft een gekoppelde set proplists, die zelf worden opgegeven als eigenschappen. U kunt aangepaste proplists opgeven voor afzonderlijke items in uw resultatensets of voor alle items in een set resultaten.

Een unieke proplist voor een afzonderlijk item opgeven:

1. Voeg in de RSS-uitvoer een aangepast element toe dat de proplist vertegenwoordigt die u wilt aanpassen. In het volgende voorbeeld wordt bijvoorbeeld de lijst voor het detailvenster ingesteld:

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

2. Als u een eigenschap wilt toepassen op elk item in de zoekresultaten zonder de RSS-uitvoer te wijzigen, geeft u een proplist op binnen een ms-ose:PropertyDefaultValues element in het .osdx-bestand, zoals wordt weergegeven in het volgende voorbeeld:

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

Indeling van eigenschappen in de inhoudsweergavemodus

De lijst met eigenschappen die zijn opgegeven in de System.PropList.ContentViewModeForSearch en System.PropList.ContentViewModeForBrowse proplists bepaalt wat wordt weergegeven in de modus Inhoudsweergave. Voor meer informatie over eigenschappenlijsten, zie PropList.

De eigenschappen worden ingedeeld volgens de getallen die worden weergegeven in het volgende indelingspatroon:

Als we de volgende lijst met eigenschappen gebruiken,

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

Vervolgens zien we de volgende weergave:

Markeringen voor eigenschappenlijst

Slechts één van de vlaggen, zoals gedefinieerd in de proplists-documentatie, is van toepassing op de weergave van items in de lay-outs van de inhoudsweergavemodus: "~". In de vorige voorbeelden worden sommige eigenschappen in de weergave van Windows Verkenner gelabeld, zoals Tags: animals; zoo; lion. Dit is het standaardgedrag wanneer u een eigenschap in de lijst opgeeft. De proplist heeft bijvoorbeeld "System.Author" die wordt weergegeven als "Authors: value". Wanneer u het label van de eigenschap wilt verbergen, plaatst u '"~"' vóór de eigenschapsnaam. Als de proplist bijvoorbeeld "~System.Size"heeft, wordt de eigenschap weergegeven als slechts een waarde, zonder het label.

Voorbeelden

Wanneer de gebruiker een resultaatitem selecteert in Windows Verkenner en het voorbeeldvenster is geopend, wordt de inhoud van het item als voorbeeld weergegeven.

De inhoud die in de preview moet worden weergegeven, wordt opgegeven door een URL, die als volgt wordt bepaald:

1. Als de eigenschap System.WebPreviewUrl Windows Shell is ingesteld voor het item, gebruikt u die URL.

   Notitie

   De eigenschap moet worden opgegeven in de RSS met behulp van de Windows Shell-naamruimte of expliciet toegewezen in het .osdx-bestand.

    

2. Als dat niet het is, gebruikt u in plaats daarvan de URL van de koppeling.

In het volgende stroomdiagram ziet u deze logica.

Het is mogelijk om een andere URL te gebruiken voor de preview dan voor het item zelf. Dit betekent dat als u verschillende URL's opgeeft voor de koppelings-URL en het bijgevoegd bestand of media:content URL, Windows Verkenner de koppelings-URL gebruikt voor voorbeeldweergaven van het item, maar de andere URL gebruikt voor bestandsdetectie, openen, downloaden en dergelijke.

Hoe Windows Verkenner bepaalt welke URL moet worden gebruikt:

1. Als u een toewijzing opgeeft voor System.ItemFolderPathDisplay, dan gebruikt Windows Explorer die URL.

2. Als u geen toewijzing opgeeft, geeft Windows Verkenner aan of de koppelings- en bijlage-URL's verschillen. Als dat het geval is, gebruikt Windows Verkenner de koppeling-URL.

3. Als de URL's hetzelfde zijn of als er slechts een koppelings-URL is, parseert Windows Verkenner de koppeling om de bovenliggende container te vinden door de bestandsnaam uit de volledige URL te verwijderen.

   Notitie

   Als u herkent dat de URL-parsering tot dode koppelingen voor uw service zou leiden, moet u een expliciete toewijzing voor de eigenschap opgeven.

    

Menuoptie Bestandslocatie openen

Wanneer je met de rechtermuisknop op een item klikt, wordt de menuopdracht Bestandslocatie openen weergegeven. Met deze opdracht wordt de gebruiker naar de container of locatie van dat item gestuurd. Als u bijvoorbeeld in een SharePoint-zoekopdracht deze optie selecteert voor een bestand in een documentbibliotheek, wordt de hoofdmap van de documentbibliotheek in de webbrowser geopend.

Wanneer een gebruiker op Bestandslocatie openen klikt, probeert Windows Explorer een ouder container te vinden met behulp van de logica zoals getoond in het volgende stroomdiagram.

Aanvullende bronnen

Zie 'Aanvullende bronnen' op Federatieve zoekfunctie in Windowsvoor meer informatie over het implementeren van zoekfederatie naar externe gegevensarchieven met behulp van OpenSearch-technologieën in Windows 7 en hoger.

Verwante onderwerpen

Federatieve zoekfunctie in Windows

Aan de slag met Federated Search in Windows

Uw Webservice koppelen in Windows Federated Search

uw gegevensarchief inschakelen in Windows Federated Search

Het volgen van beste praktijken in Windows Federated Search

Zoekconnectors implementeren in Windows Federated Search