Criando um arquivo de descrição do OpenSearch na Pesquisa Federada do Windows

Descreve como criar um arquivo .osdx (OpenSearch Description) para conectar armazenamentos de dados externos ao Cliente Windows por meio do protocolo OpenSearch . A pesquisa federada permite que os usuários pesquisem um armazenamento de dados remoto e exibam os resultados de dentro do Windows Explorer.

Este tópico contém as seguintes seções:

• Arquivo de descrição openSearch
  • Mininumeração de elementos filho necessários
• Elementos Padrão na Pesquisa Federada do Windows
  • Shortname
  • Descrição
  • Modelo de URL para resultados RSS/Atom
  • Modelo de URL para resultados da Web
  • Parâmetros de modelo de URL
  • Resultados paginado
  • Paginação usando o índice de item
  • Paginação usando o índice de página
  • Tamanho da página
• Elementos estendidos na Pesquisa Federada do Windows
  • Contagem máxima de resultados
  • Mapeamento de propriedade
• Visualizações
• Abrir Item de Menu local do arquivo
• Recursos adicionais
• Tópicos relacionados

Arquivo de descrição openSearch

Um arquivo Descrição do OpenSearch (.osdx) para a Pesquisa Federada do Windows deve cumprir as seguintes regras:

• Seja um documento válido de Descrição do OpenSearch, conforme definido pela especificação OpenSearch 1.1.
• Forneça um modelo de URL com um tipo de formato RSS ou Atom.
• Use a extensão de nome de arquivo .osdx ou seja associado à extensão de nome de arquivo .osdx ao baixar da Web. Por exemplo, um servidor não é necessário para usar .osdx. Um servidor pode retornar o arquivo com qualquer extensão de nome de arquivo, como .xml por exemplo, e tratado como se fosse um arquivo .osdx se ele usar o tipo MIME correto para documentos de descrição do OpenSearch (arquivos .osdx).
• Forneça um valor de elemento ShortName (recomendado).

Mininumeração de elementos filho necessários

O arquivo .osdx de exemplo a seguir consiste em ShortName e Url elementos, que são os elementos filho mínimos necessários.

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

Elementos Padrão na Pesquisa Federada do Windows

Além dos elementos filho mínimos, a pesquisa federada dá suporte aos elementos padrão a seguir.

Shortname

O Windows usa o valor do elemento ShortName para nomear o arquivo .searchconnector-ms (conector de pesquisa) criado quando o usuário abre o arquivo .osdx. O Windows garante que o nome do arquivo gerado use apenas caracteres permitidos em nomes de arquivo do Windows. Se nenhum valor ShortName for fornecido, o arquivo .searchconnector-ms tentará usar o nome do arquivo .osdx.

O código a seguir ilustra como usar o elemento ShortName em um arquivo .osdx.

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

Descrição

O Windows usa o valor do elemento Description para preencher a descrição do arquivo mostrada no painel de detalhes do Windows Explorer quando um usuário seleciona um arquivo .searchconnector-ms.

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

Modelo de URL para resultados RSS/Atom

O arquivo .osdx deve incluir um elemento de formato url e um atributo de modelo (um modelo de URL) que retorna resultados no formato RSS ou Atom. O atributo format deve ser definido application/rss+xml como para resultados formatados em RSS ou application/atom+xml para resultados formatados atom, conforme mostrado no código a seguir.

Observação

O elemento de formato url e o atributo de modelo são comumente conhecidos como um modelo de URL.

 

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

Modelo de URL para resultados da Web

Se houver uma versão dos resultados da pesquisa que possa ser exibida em um navegador da Web, você deverá fornecer um elemento url format=text/html e um atributo de modelo , conforme mostrado no código a seguir.

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

Se você fornecer um elemento e um atributo de modelourl format="text/html", um botão aparecerá na barra de comandos do Windows Explorer, conforme mostrado na captura de tela a seguir, que permite que o usuário abra um navegador da Web para exibir os resultados da pesquisa quando o usuário executa uma consulta.

A substituição da consulta de volta para a interface do usuário da Web do armazenamento de dados é importante em alguns cenários. Por exemplo, um usuário pode querer exibir mais de 100 resultados (o número padrão de itens que o provedor OpenSearch solicita). Nesse caso, o usuário também pode querer usar recursos de pesquisa que estão disponíveis apenas no site do armazenamento de dados, como consultar novamente com uma ordem de classificação diferente ou dinamizar e filtrar a consulta com metadados relacionados.

Parâmetros de modelo de URL

O provedor OpenSearch executa sempre as seguintes ações:

1. Usa o modelo de URL para enviar a solicitação para o serviço Web.
2. Tenta substituir os tokens encontrados no modelo de URL antes de enviar a solicitação para o serviço Web, da seguinte maneira:
   • Substitui os tokens OpenSearch padrão listados na tabela a seguir.
   • Remove todos os tokens que não estão listados na tabela a seguir.

Token com suporte	Como é usado pelo provedor OpenSearch
{searchTerms}	Substituído pelos termos de pesquisa que o usuário digita na caixa de entrada de pesquisa do Windows Explorer.
{startIndex}	Usado ao obter resultados em "páginas". Substituído pelo índice para o primeiro item de resultado a ser retornado.
{startPage}	Usado ao obter resultados em "páginas". Substituído pelo número de página do conjunto de resultados da pesquisa a ser retornado.
{count}	Usado ao obter resultados em "páginas". Substituído pelo número de resultados da pesquisa por página que o Windows Explorer solicita.
{language}	Substituído por uma cadeia de caracteres que indica o idioma da consulta que está sendo enviada.
{inputEncoding}	Substituído por uma cadeia de caracteres (como "UTF-16") que indica a codificação de caracteres da consulta que está sendo enviada.
{outputEncoding}	Substituído por uma cadeia de caracteres (como "UTF-16") que indica a codificação de caracteres desejada para a resposta do serviço Web.

 

Resultados paginado

Talvez você queira limitar o número de resultados retornados por solicitação. Você pode optar por retornar uma "página" de resultados por vez ou fazer com que o provedor OpenSearch obtenha páginas adicionais de resultados por número de item ou número de página. Por exemplo, se você enviar vinte resultados por página, a primeira página enviada começará no índice de itens 1 e na página 1; a segunda página que você envia começa no índice de itens 21 e na página 2. Você pode definir como deseja que o provedor OpenSearch solicite itens usando o {startItem} ou o {startPage} token no modelo de URL.

Paginação usando o índice de item

Um índice de item identifica o primeiro item de resultado em uma página de resultados. Se quiser que os clientes enviem solicitações usando um índice de item, você pode usar o {startIndex} token no atributo de modelo de elemento url, conforme mostrado no código a seguir.

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

Em seguida, o provedor OpenSearch substitui o token na URL por um valor de índice inicial. A primeira solicitação começa com o primeiro item, conforme ilustrado no exemplo a seguir:

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

O provedor OpenSearch pode obter itens adicionais alterando o valor do {startIndex} parâmetro e emitindo uma nova solicitação. O provedor repete esse processo até obter resultados suficientes para atender ao seu limite ou atingir o final dos resultados. O provedor OpenSearch examina o número de itens retornados pelo serviço Web na primeira página de resultados e define o tamanho de página esperado para esse número. Ele usa esse número para incrementar o {startIndex} valor para solicitações subsequentes. Por exemplo, se o serviço Web retornar 20 resultados na primeira solicitação, o provedor definirá o tamanho de página esperado como 20. Para a próxima solicitação, o provedor substitui {startIndex} pelo valor de 21 para obter os próximos 20 itens.

Observação

Se uma página de resultados retornada pelo serviço Web tiver menos itens do que o tamanho de página esperado, o provedor OpenSearch pressupõe que recebeu a última página de resultados e para de fazer solicitações.

 

Paginação usando o índice de página

Um índice de página identifica a página de resultados especificada. Se você quiser que os clientes enviem solicitações usando um número de página, você pode usar o {startPage} token no atributo de modelo de elemento de formato de URL para indicar isso, conforme ilustrado no exemplo a seguir:

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

Em seguida, o provedor OpenSearch substitui o token na URL por um parâmetro de número de página. A primeira solicitação começa com a primeira página, conforme mostrado no exemplo a seguir:

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

Observação

Se uma página de resultados retornada pelo serviço Web tiver menos itens do que o tamanho de página esperado, o provedor OpenSearch pressupõe que recebeu a última página de resultados e para de fazer solicitações.

 

Tamanho da Página

Talvez você queira configurar seu serviço Web para permitir que uma solicitação especifique o tamanho das páginas usando algum parâmetro na URL. Uma solicitação deve ser especificada no arquivo .osdx usando o {count} token , da seguinte maneira:

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

O provedor OpenSearch pode definir o tamanho de página desejado, em número de resultados por página, conforme mostrado no exemplo a seguir:

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

Por padrão, o provedor OpenSearch faz solicitações usando um tamanho de página de 50. Se você quiser um tamanho de página diferente, não forneça um {count} token e coloque o número desejado diretamente no elemento de modelo url .

O provedor OpenSearch determina o tamanho da página com base no número de resultados retornados na primeira solicitação. Se a primeira página de resultados recebida tiver menos itens do que a contagem solicitada, o provedor redefinirá o tamanho da página para quaisquer solicitações de página subsequentes. Se as solicitações de página subsequentes retornarem menos itens do que o solicitado, o provedor OpenSearch pressupõe que chegou ao final dos resultados.

Elementos estendidos na Pesquisa Federada do Windows

Além dos elementos padrão, a pesquisa federada dá suporte aos seguintes elementos estendidos: MaximumResultCount e ResultsProcessing.

Como esses elementos filho estendidos não têm suporte na especificação OpenSearch v1.1, eles devem ser adicionados usando o seguinte namespace:

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

Contagem máxima de resultados

Por padrão, os conectores de pesquisa são limitados a 100 resultados por consulta de usuário. Esse limite pode ser personalizado incluindo o elemento MaximumResultCount dentro do arquivo OSD, conforme mostrado no exemplo a seguir:

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

O exemplo anterior declara o prefixo ms-ose de namespace no elemento OpenSearchDescription de nível superior e o usa como um prefixo no nome do elemento. Essa declaração é necessária porque o MaximumResultCount não tem suporte na especificação OpenSearch v1.1.

Mapeamento de propriedade

Quando os resultados são retornados pelo serviço Web como um RSS ou feed Atom, o provedor OpenSearch deve mapear os metadados do item nos feeds para propriedades que o Shell do Windows pode usar. A captura de tela a seguir ilustra como o provedor OpenSearch mapeia alguns dos elementos RSS padrão.

Mapeamentos padrão

Os mapeamentos padrão de elementos XML RSS para propriedades do sistema Do Windows Shell são listados na tabela a seguir. Os caminhos XML são relativos ao elemento item. O "media:" prefixo é definido pelo namespace Namespace do Yahoo Search .

Caminho XML do RSS	Propriedade do Shell do Windows (nome canônico)
Link	System.ItemUrl
Título	System.ItemName
Autor	System.Author
pubDate	System.DateModified
Descrição	System.AutoSummary
Categoria	System.Keywords
compartimento/@type	System.MIMEType
compartimento/@length	System.Size
compartimento/@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

 

Observação

Além dos mapeamentos padrão de elementos RSS ou Atom padrão, você pode mapear outras propriedades do sistema do Windows Shell incluindo elementos XML adicionais no namespace do Windows para cada uma das propriedades. Você também pode mapear elementos de outros namespaces XML existentes, como MediaRSS, iTunes e assim por diante, adicionando mapeamento de propriedade personalizado no arquivo .osdx.

 

Mapeamentos de propriedade personalizados

Você pode personalizar o mapeamento de elementos da saída RSS para as propriedades do sistema do Windows Shell especificando o mapeamento no arquivo .osdx.

A saída RSS especifica:

• Um namespace XML e
• Para qualquer elemento filho de um item, um nome de elemento para mapear.

O arquivo .osdx identifica uma propriedade do Shell do Windows para cada nome de elemento em um namespace. Os mapeamentos de propriedade definidos no arquivo .osdx substituem os mapeamentos padrão, se existirem, para essas propriedades especificadas.

O diagrama a seguir ilustra como uma extensão RSS é mapeada para propriedades do Windows (nome canônico).

Exemplo de resultados do RSS e mapeamento de propriedade OSD

O exemplo de saída RSS a seguir identifica https://example.com/schema/2009 como o namespace XML com o prefixo "example". Esse prefixo deve aparecer novamente antes do elemento de email .

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

No arquivo .osdx de exemplo a seguir, o elemento de email XML é mapeado para a propriedade System.Contact.EmailAddress do 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>

Há algumas propriedades que não podem ser mapeadas porque os valores para elas são substituídos posteriormente ou não são editáveis. Por exemplo, System.ItemFolderPathDisplay ou System.ItemPathDisplayNarrow não pode ser mapeado porque eles são calculados com base no valor de URL fornecido nos elementos link ou compartimento.

Miniaturas

As URLs de imagem em miniatura podem ser fornecidas para qualquer item usando o elemento media:thumbnail url=" "" . A resolução ideal é 150 x 150 pixels. As maiores miniaturas com suporte são 256 x 256 pixels. Fornecer imagens maiores requer mais largura de banda sem nenhum benefício extra para o usuário.

Abrir Menu de Contexto do Local do Arquivo

O Windows fornece um menu de atalho chamado Abrir local do arquivo para itens de resultado. Se o usuário selecionar um item nesse menu, a URL "pai" do item selecionado será aberta. Se a URL for uma URL da Web, como https://..., o navegador da Web será aberto e navegue até essa URL. O feed deve fornecer uma URL personalizada para cada item para garantir que o Windows abra uma URL válida. Isso pode ser feito incluindo a URL dentro de um elemento dentro do XML do item, conforme ilustrado no exemplo a seguir:

<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 essa propriedade não estiver definida explicitamente no XML do item, o provedor OpenSearch a definirá como a pasta pai da URL do item. No exemplo acima, o provedor OpenSearch usaria o valor do link e definiria o valor da propriedade System.ItemFolderPathDisplay do Windows Shell como "https://example.com/".

Personalizar exibições do Windows Explorer com listas de descrição da propriedade

Alguns layouts de exibição do Windows Explorer são definidos por listas de descrição de propriedade ou listas de proplists. Uma proplist é uma lista delimitada por ponto e vírgula de propriedades, como "prop:System.ItemName; System.Author", que é usada para controlar como os resultados aparecem no Windows Explorer.

As áreas de interface do usuário do Windows Explorer que podem ser personalizadas usando proplists são ilustradas na seguinte captura de tela:

Cada área do Windows Explorer tem um conjunto associado de proplists, que são especificados como propriedades. Você pode especificar listas de props personalizadas para itens individuais em seus conjuntos de resultados ou para todos os itens em um conjunto de resultados.

Área da interface do usuário para personalizar	Propriedade do Shell do Windows que implementa a personalização
Modo de exibição de conteúdo (ao pesquisar)	System.PropList.ContentViewModeForSearch
Modo de exibição de conteúdo (ao navegar)	System.PropList.ContentViewModeForBrowse
Modo de exibição de bloco	System.PropList.TileInfo
Painel de detalhes	System.PropList.PreviewDetails
Dica de informações (dica de ferramenta de foco do item)	System.PropList.Infotip

 

 

Para especificar uma proplist exclusiva para um item individual:

1. Na saída do RSS, adicione um elemento personalizado que representa a lista de propriedades que você deseja personalizar. Por exemplo, o exemplo a seguir define a lista do painel de detalhes:

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

2. Para aplicar uma propriedade a cada item nos resultados da pesquisa sem modificar a saída RSS, especifique uma proplist dentro de um elemento ms-ose:PropertyDefaultValues no arquivo .osdx, conforme mostrado no exemplo a seguir:

   <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 de propriedades do modo de exibição de conteúdo

A lista de propriedades especificadas nas listas de proplists System.PropList.ContentViewModeForSearch e System.PropList.ContentViewModeForBrowse determina o que é mostrado no modo de exibição conteúdo. Para obter mais informações sobre listas de propriedades, consulte PropList.

As propriedades são dispostas de acordo com os números mostrados no seguinte padrão de layout:

Se usarmos a lista de propriedades a seguir,

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

Em seguida, vemos a seguinte exibição:

Observação

Para obter a melhor legibilidade, as propriedades mostradas na coluna mais à direita devem ser rotuladas.

 

Sinalizadores de lista de propriedades

Apenas um dos sinalizadores definidos na documentação de proplists se aplica à exibição de itens em layouts de modo de Exibição de Conteúdo: "~". Nos exemplos anteriores, o windows Explorer exibir rótulos de algumas das propriedades, como Tags: animals; zoo; lion. Esse é o comportamento padrão quando você especifica uma propriedade na lista. Por exemplo, a proplist tem "System.Author" que é exibido como "Authors: value". Quando você quiser ocultar o rótulo da propriedade, coloque um "~" na frente do nome da propriedade. Por exemplo, se a proplist tiver "~System.Size", a propriedade será exibida como apenas um valor, sem o rótulo .

Visualizações

Quando o usuário seleciona um item de resultado no Windows Explorer e o painel de visualização está aberto, o conteúdo do item é visualizado.

O conteúdo a ser mostrado na visualização é especificado por uma URL, que é determinada da seguinte maneira:

1. Se a propriedade System.WebPreviewUrl do Windows Shell estiver definida para o item, use essa URL.

   Observação

   A propriedade precisa ser fornecida no RSS usando o namespace do Shell do Windows ou mapeada explicitamente no arquivo .osdx.

    

2. Caso contrário, use a URL do link.

O fluxograma a seguir mostra essa lógica.

É possível usar uma URL diferente para a visualização do que para o item em si. Isso significa que, se você fornecer URLs diferentes para a URL do link e o compartimento ou media:content URL, o Windows Explorer usará a URL do link para visualizações do item, mas usará a outra URL para detecção de tipo de arquivo, abertura, download e assim por diante.

Como o Windows Explorer determina qual URL usar:

1. Se você fornecer um mapeamento para System.ItemFolderPathDisplay, o Windows Explorer usará essa URL

2. Se você não fornecer um mapeamento, o Windows Explorer identificará se as URLs do link e do compartimento são diferentes. Nesse caso, o Windows Explorer usa a URL do link.

3. Se as URLs forem iguais ou se houver apenas uma URL de link, o Windows Explorer analisará o link para localizar o contêiner pai removendo o nome do arquivo da URL completa.

   Observação

   Se você reconhecer que a análise de URL resultaria em links inativos para seu serviço, você deverá fornecer um mapeamento explícito para a propriedade.

    

Abrir Item de Menu local do arquivo

Quando um clica com o botão direito do mouse em um item, o comando de menu Abrir local do arquivo é exibido. Esse comando leva o usuário para o contêiner para ou o local desse item. Por exemplo, em uma pesquisa do SharePoint, selecionar essa opção para um arquivo em uma biblioteca de documentos abriria a raiz da biblioteca de documentos no navegador da Web.

Quando um usuário clica em Abrir local do arquivo, o Windows Explorer tenta localizar um contêiner pai usando a lógica mostrada no seguinte fluxograma:

Recursos adicionais

Para obter informações adicionais sobre como implementar a federação de pesquisa em armazenamentos de dados remotos usando tecnologias OpenSearch no Windows 7 e posteriores, consulte "Recursos adicionais" em Pesquisa Federada no Windows.

Tópicos relacionados

Pesquisa federada no Windows

Introdução com Pesquisa Federada no Windows

Conectando seu serviço Web na Pesquisa Federada do Windows

Habilitando seu armazenamento de dados na Pesquisa Federada do Windows

Seguindo as práticas recomendadas na Pesquisa Federada do Windows

Implantando conectores de pesquisa na Pesquisa Federada do Windows