Creazione di un file di descrizione OpenSearch in Ricerca federata di Windows

Viene descritto come creare un file OpenSearch Description (con estensione osdx) per connettere archivi dati esterni al client Windows tramite il protocollo OpenSearch . La ricerca federata consente agli utenti di eseguire ricerche in un archivio dati remoto e visualizzare i risultati da Esplora risorse.

In questo argomento sono incluse le sezioni seguenti:

• File di descrizione OpenSearch
  • Elementi figlio obbligatori mininum
• Elementi standard in Ricerca federata di Windows
  • Nome breve
  • Descrizione
  • Modello URL per i risultati RSS/Atom
  • Modello URL per i risultati Web
  • Parametri del modello URL
  • Risultati di paging
  • Paging con l'indice dell'elemento
  • Paging con l'indice di pagina
  • Dimensioni pagina
• Elementi estesi in Ricerca federata di Windows
  • Numero massimo risultati
  • Mapping di proprietà
• Anteprime
• Apri voce di menu Percorso file
• Risorse aggiuntive
• Argomenti correlati

File di descrizione OpenSearch

Un file OpenSearch Description (con estensione osdx) per Ricerca federata di Windows deve rispettare le regole seguenti:

• Essere un documento OpenSearch Description valido, come definito dalla specifica OpenSearch 1.1.
• Specificare un modello di URL con un tipo di formato RSS o Atom.
• Usare l'estensione osdx o essere associata all'estensione del nome file osdx durante il download dal Web. Ad esempio, non è necessario che un server usi .osdx. Un server può restituire il file con qualsiasi estensione del nome file, ad esempio .xml e trattato come se fosse un file con estensione osdx se usa il tipo MIME corretto per i documenti di descrizione OpenSearch (file con estensione osdx).
• Specificare un valore dell'elemento ShortName (scelta consigliata).

Elementi figlio obbligatori mininum

Il file con estensione osdx di esempio seguente è costituito da shortName ed Url elementi, ovvero gli elementi figlio minimi necessari.

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

Elementi standard in Ricerca federata di Windows

Oltre agli elementi figlio minimi, la ricerca federata supporta gli elementi standard seguenti.

Nome breve

Windows usa il valore dell'elemento ShortName per denominare il file con estensione searchconnector-ms (connettore di ricerca) creato quando l'utente apre il file con estensione osdx. Windows garantisce che il nome file generato usi solo caratteri consentiti nei nomi di file di Windows. Se non viene specificato alcun valore ShortName , il file con estensione searchconnector-ms tenta di usare invece il nome file con estensione osdx.

Il codice seguente illustra come usare l'elemento ShortName in un file con estensione osdx.

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

Descrizione

Windows usa il valore dell'elemento Description per popolare la descrizione del file visualizzata nel riquadro dei dettagli di Esplora risorse quando un utente seleziona un file con estensione searchconnector-ms.

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

Modello URL per i risultati RSS/Atom

Il file con estensione osdx deve includere un elemento di formato URL e un attributo modello (un modello URL) che restituisce risultati in formato RSS o Atom. L'attributo format deve essere impostato su application/rss+xml per i risultati formattati RSS o application/atom+xml per i risultati formattati atom, come illustrato nel codice seguente.

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

Modello URL per i risultati Web

Se è disponibile una versione dei risultati della ricerca che è possibile visualizzare in un Web browser, è necessario fornire un elemento Url format=text/html e un attributo modello , come illustrato nel codice seguente.

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

Se si specifica un elemento url format="text/html"e un attributo modello, viene visualizzato un pulsante nella barra dei comandi di Esplora risorse, come illustrato nella schermata seguente, che consente all'utente di aprire un Web browser per visualizzare i risultati della ricerca quando l'utente esegue una query.

Il rollover della query nell'interfaccia utente Web dell'archivio dati è importante in alcuni scenari. Ad esempio, un utente può voler visualizzare più di 100 risultati (il numero predefinito di elementi richieste dal provider OpenSearch). In tal caso, l'utente potrebbe anche voler usare le funzionalità di ricerca disponibili solo nel sito Web dell'archivio dati, ad esempio la ripetizione di query con un ordinamento diverso o il pivot e il filtro della query con i metadati correlati.

Parametri del modello URL

Il provider OpenSearch esegue sempre le azioni seguenti:

1. Usa il modello di URL per inviare la richiesta al servizio Web.
2. Tenta di sostituire i token trovati nel modello di URL prima di inviare la richiesta al servizio Web, come indicato di seguito:
   • Sostituisce i token OpenSearch standard elencati nella tabella seguente.
   • Rimuove tutti i token non elencati nella tabella seguente.

Risultati di paging

È possibile limitare il numero di risultati restituiti per richiesta. È possibile scegliere di restituire una "pagina" di risultati alla volta o di ottenere pagine aggiuntive dei risultati dal provider OpenSearch in base al numero di elemento o al numero di pagina. Ad esempio, se si inviano venti risultati per pagina, la prima pagina inviata inizia all'indice dell'elemento 1 e alla pagina 1; la seconda pagina inviata inizia all'indice dell'elemento 21 e alla pagina 2. È possibile definire come si vuole che il provider OpenSearch richieda gli elementi usando o {startItem} il {startPage} token nel modello URL.

Paging con l'indice dell'elemento

Un indice di elemento identifica il primo elemento risultato in una pagina di risultati. Se si vuole che i client inviino richieste usando un indice di elemento, è possibile usare il {startIndex} token nell'attributo del modello di elemento URL, come illustrato nel codice seguente.

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

Il provider OpenSearch sostituisce quindi il token nell'URL con un valore di indice iniziale. La prima richiesta inizia con il primo elemento, come illustrato nell'esempio seguente:

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

Il provider OpenSearch può ottenere elementi aggiuntivi modificando il valore del {startIndex} parametro e inviando una nuova richiesta. Il provider ripete questo processo fino a quando non ottiene risultati sufficienti per soddisfare il limite o raggiunge la fine dei risultati. Il provider OpenSearch esamina il numero di elementi restituiti dal servizio Web nella prima pagina dei risultati e imposta le dimensioni della pagina previste su tale numero. Usa tale numero per incrementare il {startIndex} valore per le richieste successive. Ad esempio, se il servizio Web restituisce 20 risultati nella prima richiesta, il provider imposta le dimensioni della pagina previste su 20. Per la richiesta successiva, il provider sostituisce {startIndex} con il valore di 21 per ottenere i 20 elementi successivi.

Paging con l'indice di pagina

Un indice di pagina identifica la pagina specificata dei risultati. Se si desidera che i client inviino richieste usando un numero di pagina, è possibile usare il token nell'attributo {startPage}modello di elemento formato URL per indicare che, come illustrato nell'esempio seguente:

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

Il provider OpenSearch sostituisce quindi il token nell'URL con un parametro numero di pagina. La prima richiesta inizia con la prima pagina, come illustrato nell'esempio seguente:

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

Dimensioni pagina

È possibile configurare il servizio Web per consentire a una richiesta di specificare le dimensioni delle pagine usando alcuni parametri nell'URL. Una richiesta deve essere specificata nel file con estensione osdx usando il {count} token, come indicato di seguito:

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

Il provider OpenSearch può quindi impostare le dimensioni della pagina desiderate, in numero di risultati per pagina, come illustrato nell'esempio seguente:

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

Per impostazione predefinita, il provider OpenSearch effettua richieste usando una dimensione di pagina pari a 50. Se si desidera una dimensione di pagina diversa, non specificare un {count} token e posizionare il numero desiderato direttamente nell'elemento Modello url .

Il provider OpenSearch determina le dimensioni della pagina in base al numero di risultati restituiti nella prima richiesta. Se la prima pagina dei risultati ricevuti ha meno elementi rispetto al conteggio richiesto, il provider reimposta le dimensioni della pagina per le richieste di pagina successive. Se le richieste di pagina successive restituiscono meno elementi richiesti, il provider OpenSearch presuppone che abbia raggiunto la fine dei risultati.

Elementi estesi nella ricerca federata di Windows

Oltre agli elementi standard, la ricerca federata supporta gli elementi estesi seguenti: MaximumResultCount e ResultsProcessing.

Poiché questi elementi figlio estesi non sono supportati nella specifica OpenSearch v1.1, devono essere aggiunti usando lo spazio dei nomi seguente:

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

Numero massimo di risultati

Per impostazione predefinita, i connettori di ricerca sono limitati a 100 risultati per ogni query utente. Questo limite può essere personalizzato includendo l'elemento MaximumResultCount all'interno del file OSD, come illustrato nell'esempio seguente:

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

Nell'esempio precedente viene dichiarato il prefisso ms-ose dello spazio dei nomi nell'elemento OpenSearchDescription di primo livello e quindi lo usa come prefisso nel nome dell'elemento. Questa dichiarazione è necessaria perché maximumResultCount non è supportato nella specifica OpenSearch v1.1.

Mapping di proprietà

Quando i risultati vengono restituiti dal servizio Web come feed RSS o Atom, il provider OpenSearch deve eseguire il mapping dei metadati dell'elemento nei feed alle proprietà che windows Shell può usare. La schermata seguente illustra come il provider OpenSearch esegue il mapping di alcuni degli elementi RSS predefiniti.

Mapping predefiniti

I mapping predefiniti degli elementi XML RSS alle proprietà di sistema di Windows Shell sono elencati nella tabella seguente. I percorsi XML sono relativi all'elemento item. Il "media:" prefisso è definito dallo spazio dei nomi Dello spazio dei nomi Yahoo Search .

Mapping delle proprietà personalizzate

È possibile personalizzare il mapping degli elementi dall'output RSS alle proprietà del sistema di Windows Shell specificando il mapping nel file con estensione osdx.

L'output RSS specifica:

• Spazio dei nomi XML e
• Per qualsiasi elemento figlio di un elemento, un nome di elemento da eseguire con il mapping.

Il file con estensione osdx identifica una proprietà di Windows Shell per ogni nome di elemento in uno spazio dei nomi. I mapping delle proprietà definiti nel file con estensione osdx eseguono l'override dei mapping predefiniti, se presenti, per tali proprietà specificate.

Il diagramma seguente illustra come un'estensione RSS esegue il mapping alle proprietà di Windows (nome canonico).

Esempio di risultati RSS e mapping delle proprietà OSD

L'output RSS di esempio seguente identifica https://example.com/schema/2009 come spazio dei nomi XML con il prefisso "example". Questo prefisso deve essere visualizzato di nuovo prima dell'elemento di posta elettronica .

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

Nel file osdx di esempio seguente l'elemento di posta elettronica XML esegue il mapping alla proprietà 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>

Non è possibile eseguire il mapping di alcune proprietà perché i valori vengono sottoposti a override in un secondo momento o non sono modificabili. Ad esempio, System.ItemFolderPathDisplay o System.ItemPathDisplayNarrow non possono essere mappati perché vengono calcolati dal valore URL fornito negli elementi link o enclosure.

Anteprime

Gli URL dell'immagine di anteprima possono essere forniti per qualsiasi elemento usando l'elemento media:thumbnail url="". La risoluzione ideale è 150 x 150 pixel. Le anteprime più grandi supportate sono 256 x 256 pixel. L'offerta di immagini più grandi richiede una larghezza di banda maggiore senza alcun vantaggio aggiuntivo per l'utente.

Aprire il menu di scelta rapida percorso file

Windows fornisce un menu di scelta rapida denominato Apri percorso file per gli elementi dei risultati. Se l'utente seleziona un elemento dal menu, viene aperto l'URL "padre" per l'elemento selezionato. Se l'URL è un URL Web, ad esempio https://..., il Web browser viene aperto e spostato su tale URL. Il feed deve fornire un URL personalizzato per ogni elemento per assicurarsi che Windows apre un URL valido. Questa operazione può essere eseguita includendo l'URL all'interno di un elemento all'interno del codice XML dell'elemento, come illustrato nell'esempio seguente:

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

Se questa proprietà non è impostata in modo esplicito nel codice XML dell'elemento, il provider OpenSearch lo imposta sulla cartella padre dell'URL dell'elemento. Nell'esempio precedente, il provider OpenSearch userà il valore del collegamento e imposta il valore della proprietà System.ItemFolderPathDisplay di Windows Shell su "https://example.com/".

Personalizzare le visualizzazioni di Esplora risorse con elenchi di descrizioni delle proprietà

Alcuni layout di visualizzazione di Esplora risorse sono definiti dagli elenchi di descrizioni delle proprietà o dagli elenchi proplist. Un elenco di proprietà è un elenco delimitato da punto e virgola di proprietà, ad esempio "prop:System.ItemName; System.Author", usato per controllare la modalità di visualizzazione dei risultati in Esplora risorse.

Le aree dell'interfaccia utente di Esplora risorse che possono essere personalizzate tramite proplist sono illustrate nella schermata seguente:

Ogni area di Esplora risorse dispone di un set associato di proplist, che vengono specificati come proprietà. È possibile specificare proplist personalizzati per singoli elementi nei set di risultati o per tutti gli elementi di un set di risultati.

Per specificare un elenco di proprietà univoco per un singolo elemento:

1. Nell'output RSS aggiungere un elemento personalizzato che rappresenta l'elenco proplist da personalizzare. L'esempio seguente, ad esempio, imposta l'elenco per il riquadro dei dettagli:

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

2. Per applicare una proprietà a ogni elemento nei risultati della ricerca senza modificare l'output RSS, specificare un proplist all'interno di un elemento ms-ose:PropertyDefaultValues nel file con estensione osdx, come illustrato nell'esempio seguente:

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

Layout della modalità visualizzazione contenuto delle proprietà

L'elenco delle proprietà specificate negli elenchi proplist System.PropList.ContentViewModeForSearch e System.PropList.ContentViewModeForBrowse determina cosa viene visualizzato in modalità visualizzazione contenuto. Per altre informazioni sugli elenchi di proprietà, vedere PropList.

Le proprietà sono disposte in base ai numeri mostrati nel modello di layout seguente:

Se si usa l'elenco seguente di proprietà,

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

Viene quindi visualizzata la visualizzazione seguente:

Flag elenco delle proprietà

Solo uno dei flag definiti nella documentazione di proplist si applica alla visualizzazione di elementi nei layout in modalità Visualizzazione contenuto: "~". Negli esempi precedenti la visualizzazione Esplora risorse etichetta alcune delle proprietà, ad esempio Tags: animals; zoo; lion. Questo è il comportamento predefinito quando si specifica una proprietà nell'elenco. Ad esempio, l'elenco proplist è "System.Author" visualizzato come "Authors: value". Quando si vuole nascondere l'etichetta della proprietà, posizionare un "~" oggetto davanti al nome della proprietà. Ad esempio, se l'oggetto proplist ha "~System.Size", la proprietà viene visualizzata come un valore, senza l'etichetta.

Anteprime

Quando l'utente seleziona un elemento di risultato in Esplora risorse e il riquadro di anteprima è aperto, il contenuto dell'elemento viene visualizzato in anteprima.

Il contenuto da visualizzare nell'anteprima viene specificato da un URL, determinato come segue:

1. Se la proprietà System.WebPreviewUrl di Windows Shell è impostata per l'elemento, usare tale URL.

   Nota

   La proprietà deve essere specificata nel formato RSS usando lo spazio dei nomi della shell di Windows o mappata in modo esplicito nel file con estensione osdx.

    

2. In caso contrario, usare invece l'URL del collegamento.

Il diagramma di flusso seguente mostra questa logica.

È possibile usare un URL diverso per l'anteprima rispetto all'elemento stesso. Ciò significa che se fornisci URL diversi per l'URL del collegamento e l'enclosure o media:content URL, Esplora risorse usa l'URL di collegamento per le anteprime dell'elemento, ma usa l'altro URL per il rilevamento del tipo di file, l'apertura, il download e così via.

In che modo Esplora risorse determina l'URL da usare:

1. Se si specifica un mapping a System.ItemFolderPathDisplay, Esplora risorse usa tale URL

2. Se non si specifica un mapping, Esplora risorse identifica se gli URL del collegamento e dell'enclosure sono diversi. In tal caso, Esplora risorse usa l'URL del collegamento.

3. Se gli URL sono uguali o se è presente solo un URL di collegamento, Esplora risorse analizza il collegamento per trovare il contenitore padre rimuovendo il nome del file dall'URL completo.

   Nota

   Se si riconosce che l'analisi degli URL genera collegamenti non recapitabili per il servizio, è necessario fornire un mapping esplicito per la proprietà .

    

Apri voce di menu Percorso file

Quando un elemento fa clic con il pulsante destro del mouse, viene visualizzato il comando di menu Apri percorso file . Questo comando porta l'utente al contenitore per o alla posizione dell'elemento. Ad esempio, in una ricerca di SharePoint, la selezione di questa opzione per un file in una raccolta documenti aprirà la radice della raccolta documenti nel Web browser.

Quando un utente fa clic su Apri percorso file, Esplora risorse tenta di trovare un contenitore padre usando la logica illustrata nel diagramma di flusso seguente:

Risorse aggiuntive

Per altre informazioni sull'implementazione della federazione di ricerca in archivi dati remoti tramite tecnologie OpenSearch in Windows 7 e versioni successive, vedere "Risorse aggiuntive" in Ricerca federata in Windows.

Argomenti correlati

Ricerca federata in Windows

Introduzione con Ricerca federata in Windows

Connessione del servizio Web in Ricerca federata di Windows

Abilitazione dell'archivio dati in Ricerca federata di Windows

Procedure consigliate seguenti in Ricerca federata di Windows

Distribuzione di connettori di ricerca in Ricerca federata di Windows