Crear un archivo de descripción de OpenSearch en la búsqueda federada de Windows
Describe cómo crear un archivo de descripción de OpenSearch (.osdx) para conectar almacenes de datos externos al cliente de Windows a través del protocolo OpenSearch . La búsqueda federada permite a los usuarios buscar en un almacén de datos remoto y ver los resultados desde el Explorador de Windows.
Este tema contiene las siguientes secciones:
- Archivo de descripción de OpenSearch
- Elementos estándar en la búsqueda federada de Windows
- Elementos extendidos en la búsqueda federada de Windows
- Versiones Preliminares
- Abrir elemento de menú Ubicación de archivo
- Recursos adicionales
- Temas relacionados
Archivo de descripción de OpenSearch
Un archivo de descripción de OpenSearch (.osdx) para la búsqueda federada de Windows debe cumplir las reglas siguientes:
- Ser un documento de descripción de OpenSearch válido, tal como se define en la especificación de OpenSearch 1.1.
- Proporcione una plantilla de dirección URL con un tipo de formato RSS o Atom.
- Use la extensión de nombre de archivo .osdx o asocie con la extensión de nombre de archivo .osdx al descargar desde la web. Por ejemplo, no se requiere un servidor para usar .osdx. Un servidor puede devolver el archivo con cualquier extensión de nombre de archivo, como .xml por ejemplo, y tratado como si fuera un archivo .osdx si usa el tipo MIME correcto para documentos de descripción de OpenSearch (archivos .osdx).
- Proporcione un valor de elemento ShortName (recomendado).
Elementos secundarios obligatorios de mininumeración
El siguiente archivo .osdx de ejemplo consta de elementos y Url
ShortName, que son los elementos secundarios mínimos necesarios.
<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}&start={startIndex}&cnt={count}" />
</OpenSearchDescription>
Elementos estándar en la búsqueda federada de Windows
Además de los elementos secundarios mínimos, la búsqueda federada admite los siguientes elementos estándar.
Shortname
Windows usa el valor del elemento ShortName para asignar un nombre al archivo .searchconnector-ms (conector de búsqueda) que se crea cuando el usuario abre el archivo .osdx. Windows garantiza que el nombre de archivo generado use solo los caracteres permitidos en los nombres de archivo de Windows. Si no se proporciona ningún valor shortName , el archivo .searchconnector-ms intenta usar el nombre de archivo del archivo .osdx en su lugar.
En el código siguiente se muestra cómo usar el elemento ShortName en un archivo .osdx.
<OpenSearchDescription xmlns="https://a9.com/-/spec/opensearch/1.1/">
<ShortName>My web Service</ShortName>
...
</OpenSearchDescription>
Descripción
Windows usa el valor del elemento Description para rellenar la descripción del archivo que se muestra en el panel de detalles del Explorador de Windows cuando un usuario selecciona un archivo .searchconnector-ms.
<OpenSearchDescription xmlns="https://a9.com/-/spec/opensearch/1.1/">
...
<Description>Searches the example company book catalog</Description>
</OpenSearchDescription>
Plantilla de dirección URL para resultados RSS/Atom
El archivo .osdx debe incluir un elemento de formato URL y un atributo de plantilla (una plantilla de dirección URL) que devuelva los resultados en formato RSS o Atom. El atributo format debe establecerse application/rss+xml
en para los resultados con formato RSS o application/atom+xml
para los resultados con formato Atom, como se muestra en el código siguiente.
Nota
El elemento de formato url y el atributo de plantilla se conocen normalmente como plantilla de dirección URL.
<OpenSearchDescription xmlns="https://a9.com/-/spec/opensearch/1.1/">
...
<Url format="application/rss+xml" template="https://example.com/rss.php?query=
{searchTerms}&start={startIndex}&cnt={count}" />
</OpenSearchDescription>
Plantilla de dirección URL para resultados web
Si hay una versión de los resultados de búsqueda que se pueden ver en un explorador web, debe proporcionar un elemento Url format=text/html
y un atributo de plantilla , como se muestra en el código siguiente.
<OpenSearchDescription xmlns="https://a9.com/-/spec/opensearch/1.1/">
...
<Url format="text/html" template="https://example.com/html.php?query={searchTerms}" />
</OpenSearchDescription>
Si proporcionas un elemento url format="text/html" y un atributo de plantilla , aparece un botón en la barra de comandos del Explorador de Windows, como se muestra en la siguiente captura de pantalla, que permite al usuario abrir un explorador web para ver los resultados de la búsqueda cuando el usuario realiza una consulta.
La sustitución de la consulta de vuelta a la interfaz de usuario web del almacén de datos es importante en algunos escenarios. Por ejemplo, un usuario puede querer ver más de 100 resultados (el número predeterminado de elementos que solicita el proveedor de OpenSearch). Si es así, es posible que el usuario también quiera usar características de búsqueda que solo están disponibles en el sitio web del almacén de datos, como volver a consultar con un criterio de ordenación diferente, o dinamizar y filtrar la consulta con metadatos relacionados.
Parámetros de plantilla de dirección URL
El proveedor de OpenSearch realiza siempre las siguientes acciones:
- Usa la plantilla de dirección URL para enviar la solicitud al servicio web.
- Intenta reemplazar los tokens que se encuentran en la plantilla de dirección URL antes de enviar la solicitud al servicio web, como se indica a continuación:
- Reemplaza los tokens de OpenSearch estándar que se enumeran en la tabla siguiente.
- Quita los tokens que no aparecen en la tabla siguiente.
Token admitido | Uso del proveedor OpenSearch |
---|---|
{searchTerms} | Se reemplaza por los términos de búsqueda que escribe el usuario en el cuadro de entrada de búsqueda del Explorador de Windows. |
{startIndex} | Se usa al obtener resultados en "páginas". Reemplazado por el índice del primer elemento de resultado que se va a devolver. |
{startPage} | Se usa al obtener resultados en "páginas". Se reemplaza por el número de página del conjunto de resultados de búsqueda que se va a devolver. |
{count} | Se usa al obtener resultados en "páginas". Reemplazado por el número de resultados de búsqueda por página que solicita el Explorador de Windows. |
{language} | Se reemplaza por una cadena que indica el idioma de la consulta que se envía. |
{inputEncoding} | Se reemplaza por una cadena (como "UTF-16") que indica la codificación de caracteres de la consulta que se envía. |
{outputEncoding} | Se reemplaza por una cadena (como "UTF-16") que indica la codificación de caracteres deseada para la respuesta del servicio web. |
Resultados paginados
Es posible que desee limitar el número de resultados devueltos por solicitud. Puede optar por devolver una "página" de resultados a la vez o para que el proveedor de OpenSearch obtenga páginas adicionales de resultados por número de elemento o número de página. Por ejemplo, si envía veinte resultados por página, la primera página que envía comienza en el índice de elemento 1 y en la página 1; la segunda página que envía comienza en el índice de elemento 21 y en la página 2. Puede definir cómo desea que el proveedor de OpenSearch solicite elementos mediante el {startItem}
token o en {startPage}
la plantilla de dirección URL.
Paginación mediante el índice de elementos
Un índice de elemento identifica el primer elemento de resultado en una página de resultados. Si desea que los clientes envíen solicitudes mediante un índice de elementos, puede usar el token en el {startIndex}
atributo de plantilla de elemento Url, como se muestra en el código siguiente.
<Url format="application/rss+xml"
template="https://example.com/rss.php?query={searchTerms}&start={startIndex}" />
A continuación, el proveedor de OpenSearch reemplaza el token de la dirección URL por un valor de índice inicial. La primera solicitud comienza con el primer elemento, como se muestra en el ejemplo siguiente:
https://example.com/rss.php?query=frogs&start=1
El proveedor de OpenSearch puede obtener elementos adicionales cambiando el valor del {startIndex}
parámetro y emitiendo una nueva solicitud. El proveedor repite este proceso hasta que obtiene suficientes resultados para satisfacer su límite o alcanza el final de los resultados. El proveedor de OpenSearch examina el número de elementos devueltos por el servicio web en la primera página de resultados y establece el tamaño de página esperado en ese número. Usa ese número para incrementar el {startIndex}
valor de las solicitudes posteriores. Por ejemplo, si el servicio web devuelve 20 resultados en la primera solicitud, el proveedor establece el tamaño de página esperado en 20. Para la siguiente solicitud, el proveedor reemplaza {startIndex}
por el valor de 21 para obtener los siguientes 20 elementos.
Nota
Si una página de resultados devuelta por el servicio web tiene menos elementos que el tamaño de página esperado, el proveedor de OpenSearch supone que ha recibido la última página de resultados y deja de realizar solicitudes.
Paginación mediante el índice de página
Un índice de página identifica la página especificada de resultados. Si desea que los clientes envíen solicitudes mediante un número de página, puede usar el token en el {startPage}
atributo de plantilla de elemento de formato URL para indicarlo, como se muestra en el ejemplo siguiente:
<Url format="application/rss+xml"
template="https://example.com/rss.php?query={searchTerms}&page={startPage}" />
A continuación, el proveedor de OpenSearch reemplaza el token de la dirección URL por un parámetro de número de página. La primera solicitud comienza con la primera página, como se muestra en el ejemplo siguiente:
https://example.com/rss.php?query=frogs&page=1
Nota
Si una página de resultados devuelta por el servicio web tiene menos elementos que el tamaño de página esperado, el proveedor de OpenSearch supone que ha recibido la última página de resultados y deja de realizar solicitudes.
Tamaño de página
Es posible que desee configurar el servicio web para permitir que una solicitud especifique el tamaño de las páginas mediante algún parámetro en la dirección URL. Se debe especificar una solicitud en el archivo .osdx mediante el {count}
token, como se indica a continuación:
<Url format="application/rss+xml"
template="https://example.com/rss.php?query={searchTerms}&start={startIndex}&cnt={count}" />
Después, el proveedor de OpenSearch puede establecer el tamaño de página deseado, en el número de resultados por página, como se muestra en el ejemplo siguiente:
https://example.com/rss.php?query=frogs&start=1&cnt=50
De forma predeterminada, el proveedor de OpenSearch realiza solicitudes con un tamaño de página de 50. Si desea un tamaño de página diferente, no proporcione un {count}
token y, en su lugar, coloque el número deseado directamente en el elemento de plantilla url.
El proveedor de OpenSearch determina el tamaño de página en función del número de resultados devueltos en la primera solicitud. Si la primera página de los resultados recibidos tiene menos elementos que el recuento solicitado, el proveedor restablece el tamaño de página para las solicitudes de página posteriores. Si las solicitudes de página posteriores devuelven menos elementos de los solicitados, el proveedor de OpenSearch asume que ha llegado al final de los resultados.
Elementos extendidos en la búsqueda federada de Windows
Además de los elementos estándar, la búsqueda federada admite los siguientes elementos extendidos: MaximumResultCount y ResultsProcessing.
Dado que estos elementos secundarios extendidos no se admiten en la especificación OpenSearch v1.1, se deben agregar mediante el siguiente espacio de nombres:
http://schemas.microsoft.com/opensearchext/2009/
Recuento máximo de resultados
De forma predeterminada, los conectores de búsqueda están limitados a 100 resultados por consulta de usuario. Este límite se puede personalizar incluyendo el elemento MaximumResultCount dentro del archivo OSD, como se muestra en el ejemplo siguiente:
<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>
En el ejemplo anterior se declara el prefijo ms-ose
de espacio de nombres en el elemento OpenSearchDescription de nivel superior y, a continuación, se usa como prefijo en el nombre del elemento. Esta declaración es necesaria porque MaximumResultCount no se admite en la especificación OpenSearch v1.1.
Asignación de propiedades
Cuando el servicio web devuelve los resultados como fuente RSS o Atom, el proveedor de OpenSearch debe asignar los metadatos de elemento de las fuentes a las propiedades que puede usar el Shell de Windows. En la captura de pantalla siguiente se muestra cómo el proveedor de OpenSearch asigna algunos de los elementos RSS predeterminados.
Asignaciones predeterminadas
Las asignaciones predeterminadas de elementos XML RSS a las propiedades del sistema de Windows Shell se enumeran en la tabla siguiente. Las rutas de acceso XML son relativas al elemento item. El "media:"
prefijo se define mediante el espacio de nombres de Yahoo Search .
Ruta de acceso XML RSS | Propiedad de Shell de Windows (nombre canónico) |
---|---|
Vínculo | System.ItemUrl |
Título | System.ItemName |
Autor | System.Author |
pubDate | System.DateModified |
Descripción | System.AutoSummary |
Category | System.Keywords |
gabinete/@type | System.MIMEType |
gabinete/@length | System.Size |
gabinete/@url | System.ContentUrl |
media:category | System.Keywords |
media:content/@fileSize | System.Size |
media:content/@type | System.MIMEType |
media:content/@url | System.ContentUrl |
media:group/content/@fileSize | System.Size |
media:group/content/@type | System.MIMEType |
media:group/content/@url | System.ContentUrl |
media:thumbnail/@url | System.ItemThumbnailUrl |
Nota
Además de las asignaciones predeterminadas de elementos RSS o Atom estándar, puede asignar otras propiedades del sistema de Windows Shell incluyendo elementos XML adicionales en el espacio de nombres de Windows para cada una de las propiedades. También puede asignar elementos de otros espacios de nombres XML existentes, como MediaRSS, iTunes, etc., agregando la asignación de propiedades personalizadas en el archivo .osdx.
Asignaciones de propiedades personalizadas
Puede personalizar la asignación de elementos de la salida RSS a las propiedades del sistema de Windows Shell especificando la asignación en el archivo .osdx.
La salida RSS especifica:
- Un espacio de nombres XML y
- Para cualquier elemento secundario de un elemento, un nombre de elemento con el que se va a asignar.
El archivo .osdx identifica una propiedad de Windows Shell para cada nombre de elemento de un espacio de nombres. Las asignaciones de propiedades que defina en el archivo .osdx invalidan las asignaciones predeterminadas, si existen, para esas propiedades especificadas.
En el diagrama siguiente se muestra cómo se asigna una extensión RSS a las propiedades de Windows (nombre canónico).
Ejemplo de resultados RSS y asignación de propiedades de OSD
La siguiente salida RSS de ejemplo identifica https://example.com/schema/2009
como el espacio de nombres XML con el prefijo "example". Este prefijo debe aparecer de nuevo antes del elemento email .
<rss version="2.0" xmlns:example="https://example.com/schema/2009">
...
<item>
<title>Someone</title>
<example:email>Someone@example.com</example:email>
</item>
En el siguiente archivo .osdx de ejemplo, el elemento de correo electrónico XML se asigna a la propiedad System.Contact.EmailAddress de Windows Shell.
<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>
Hay algunas propiedades que no se pueden asignar porque los valores de estos se invalidan más adelante o no se pueden editar. Por ejemplo, System.ItemFolderPathDisplay o System.ItemPathDisplayNarrow no se pueden asignar porque se calculan a partir del valor de dirección URL proporcionado en los elementos de vínculo o contenedor.
Miniaturas
Se pueden proporcionar direcciones URL de imagen en miniatura para cualquier elemento mediante el elemento media:thumbnail url="". La resolución ideal es de 150 x 150 píxeles. Las miniaturas más grandes admitidas son de 256 x 256 píxeles. Proporcionar imágenes más grandes toma más ancho de banda sin ventaja adicional al usuario.
Menú contextual Abrir ubicación de archivo
Windows proporciona un menú contextual denominado Abrir ubicación de archivo para los elementos de resultado. Si el usuario selecciona un elemento en ese menú, se abre la dirección URL "primaria" del elemento seleccionado. Si la dirección URL es una dirección URL web, como https://...
, se abre el explorador web y se navega a esa dirección URL. La fuente debe proporcionar una dirección URL personalizada para cada elemento para asegurarse de que Windows abre una dirección URL válida. Esto se puede lograr mediante la inclusión de la dirección URL dentro de un elemento dentro del XML del elemento, como se muestra en el ejemplo siguiente:
<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>
...
Si esta propiedad no se establece explícitamente en el XML del elemento, el proveedor de OpenSearch lo establece en la carpeta primaria de la dirección URL del elemento. En el ejemplo anterior, el proveedor de OpenSearch usaría el valor del vínculo y establecería el valor de la propiedad System.ItemFolderPathDisplay del Shell de Windows en "https://example.com/"
.
Personalizar vistas del Explorador de Windows con listas de descripción de propiedades
Algunos diseños de vista del Explorador de Windows se definen mediante listas de descripción de propiedades o listas de propiedades. Una lista proplist es una lista delimitada por punto y coma de propiedades, como "prop:System.ItemName; System.Author"
, que se usa para controlar cómo aparecen los resultados en el Explorador de Windows.
Las áreas de interfaz de usuario del Explorador de Windows que se pueden personalizar mediante listas de propiedades se muestran en la siguiente captura de pantalla:
Cada área del Explorador de Windows tiene un conjunto asociado de listas de propiedades, que se especifican como propiedades. Puede especificar listas de propiedades personalizadas para elementos individuales en los conjuntos de resultados o para todos los elementos de un conjunto de resultados.
Área de interfaz de usuario para personalizar | Propiedad de Windows Shell que implementa la personalización |
---|---|
Modo de vista de contenido (al buscar) | System.PropList.ContentViewModeForSearch |
Modo de vista de contenido (al examinar) | System.PropList.ContentViewModeForBrowse |
Modo de vista de mosaico | System.PropList.TileInfo |
Panel de detalles | System.PropList.PreviewDetails |
Información sobre información (información sobre herramientas sobre el puntero del elemento) | System.PropList.Infotip |
Para especificar una lista de propiedades única para un elemento individual:
En la salida RSS, agregue un elemento personalizado que represente la lista de propiedades que desea personalizar. Por ejemplo, en el ejemplo siguiente se establece la lista del panel de detalles:
<win:System.PropList.PreviewDetails> prop:System.ItemName;System.Author</win:System.PropList.PreviewDetails>
Para aplicar una propiedad a todos los elementos de los resultados de búsqueda sin modificar la salida RSS, especifique una lista de propiedades dentro de un elemento ms-ose:PropertyDefaultValues en el archivo .osdx, como se muestra en el ejemplo siguiente:
<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>
Diseño del modo de vista de contenido de propiedades
La lista de propiedades especificadas en system.PropList.ContentViewModeForSearch y System.PropList.ContentViewModeForBrowse proplists determina lo que se muestra en el modo de vista contenido. Para obtener más información sobre las listas de propiedades, vea PropList.
Las propiedades se diseñan según los números que se muestran en el siguiente patrón de diseño:
Si usamos la siguiente lista de propiedades,
prop:~System.ItemNameDisplay;System.Author;System.ItemPathDisplay;~System.Search.AutoSummary;
System.Size;System.Photo.DateTaken;System.Keywords
A continuación, vemos la siguiente pantalla:
Nota
Para obtener la mejor legibilidad, las propiedades que se muestran en la columna más adecuada deben etiquetarse.
Marcas de lista de propiedades
Solo se aplica una de las marcas definidas en la documentación de proplists a la presentación de elementos en diseños de modo vista de contenido: "~"
. En los ejemplos anteriores, la vista Explorador de Windows etiqueta algunas de las propiedades, como Tags: animals; zoo; lion
. Ese es el comportamiento predeterminado cuando se especifica una propiedad en la lista. Por ejemplo, la lista de propiedades tiene "System.Author"
que se muestra como "Authors: value"
. Cuando desee ocultar la etiqueta de propiedad, coloque un "~"
delante del nombre de la propiedad. Por ejemplo, si la lista de propiedades tiene "~System.Size"
, la propiedad se muestra como un valor, sin la etiqueta .
Versiones Preliminares
Cuando el usuario selecciona un elemento de resultado en el Explorador de Windows y el panel de vista previa está abierto, se muestra una vista previa del contenido del elemento.
El contenido que se va a mostrar en la versión preliminar se especifica mediante una dirección URL, que se determina de la siguiente manera:
Si la propiedad System.WebPreviewUrl de Windows Shell está establecida para el elemento, use esa dirección URL.
Nota
La propiedad debe proporcionarse en RSS mediante el espacio de nombres de Windows Shell o asignar explícitamente en el archivo .osdx.
Si no es así, use la dirección URL del vínculo en su lugar.
En el diagrama de flujo siguiente se muestra esta lógica.
Es posible usar una dirección URL diferente para la versión preliminar que para el propio elemento. Esto significa que si proporciona direcciones URL diferentes para la dirección URL del vínculo y el contenedor o media:content URL
, el Explorador de Windows usa la dirección URL de vínculo para las vistas previas del elemento, pero usa la otra dirección URL para la detección de tipos de archivo, la apertura, la descarga, etc.
Cómo determina el Explorador de Windows qué dirección URL se va a usar:
Si proporciona una asignación a System.ItemFolderPathDisplay, el Explorador de Windows usa esa dirección URL.
Si no proporciona una asignación, el Explorador de Windows identifica si las direcciones URL del vínculo y del contenedor son diferentes. Si es así, el Explorador de Windows usa la dirección URL del vínculo.
Si las direcciones URL son las mismas o si solo hay una dirección URL de vínculo, el Explorador de Windows analiza el vínculo para buscar el contenedor primario quitando el nombre de archivo de la dirección URL completa.
Nota
Si reconoce que el análisis de direcciones URL daría lugar a vínculos inactivos para el servicio, debe proporcionar una asignación explícita para la propiedad .
Abrir elemento de menú Ubicación de archivo
Cuando un elemento hace clic con el botón derecho, aparece el comando de menú Abrir ubicación de archivo . Este comando lleva al usuario al contenedor para o la ubicación de ese elemento. Por ejemplo, en una búsqueda de SharePoint, al seleccionar esta opción para un archivo de una biblioteca de documentos se abriría la raíz de la biblioteca de documentos en el explorador web.
Cuando un usuario hace clic en Abrir ubicación de archivo, el Explorador de Windows intenta buscar un contenedor primario mediante la lógica que se muestra en el diagrama de flujo siguiente:
Recursos adicionales
Para obtener más información sobre cómo implementar la federación de búsqueda en almacenes de datos remotos mediante tecnologías openSearch en Windows 7 y versiones posteriores, consulta "Recursos adicionales" en Búsqueda federada en Windows.
Temas relacionados
-
Conexión del servicio web en la búsqueda federada de Windows
-
Habilitar el almacén de datos en la búsqueda federada de Windows
-
Procedimientos recomendados siguientes en la búsqueda federada de Windows
-
Implementación de conectores de búsqueda en la búsqueda federada de Windows