Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Descreve como criar um arquivo OpenSearch Description (.osdx) 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 no Windows Explorer.
Este tópico contém as seguintes seções:
- Arquivo de Descrição OpenSearch
- Elementos Padrão na Pesquisa Federada do Windows
- Elementos estendidos na Pesquisa Federada do Windows
- Previews
- Abrir item de menu local do arquivo
- Recursos adicionais
- tópicos relacionados
Arquivo de descrição OpenSearch
Um arquivo de Descrição do OpenSearch (.osdx) para a Pesquisa Federada do Windows deve seguir as seguintes regras:
- Seja um documento de descrição do OpenSearch válido, 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).
Número mínimo de elementos filhos necessários
O exemplo de arquivo .osdx 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}&start={startIndex}&cnt={count}" />
</OpenSearchDescription>
Elementos padrão na Pesquisa Federada do Windows
Além dos elementos filho mínimos, a pesquisa federada dá suporte aos seguintes elementos padrão.
Nome curto
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 em vez disso.
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>
Description
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 de formato deve ser definido para application/rss+xml resultados formatados do RSS ou application/atom+xml para resultados formatados por Atom, conforme mostrado no código a seguir.
Observação
O elemento de formato de 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}&start={startIndex}&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 Url format="text/html" e um atributo template, um botão aparecerá na barra de comandos do Windows Explorer, como mostrado na captura de tela abaixo, permitindo que o usuário abra um navegador da Web para exibir os resultados da pesquisa quando o usuário executa uma consulta.
A reversão da consulta para a interface web do repositório 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 repositório de dados, como consultar novamente com uma ordem de classificação diferente ou pivotar e filtrar a consulta com metadados relacionados.
Parâmetros de modelo de URL
O provedor OpenSearch executa sempre as seguintes ações:
- Usa o modelo de URL para enviar a solicitação para o serviço Web.
- 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 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". Substituir pelo índice do 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. |
| linguagem | 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 caractere desejada para a resposta do serviço Web. |
Resultados paginados
Talvez você queira limitar o número de resultados retornados por solicitação. Você pode optar por retornar uma "página" de resultados de cada 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 que você enviar iniciará 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 modelo de URL com o token {startItem} ou {startPage}.
Paginação usando o índice de item
Um índice de item identifica o primeiro item de resultado em uma página de resultados. Se você 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}&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 analisa 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}&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 uma solicitação para especificar 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}&start={startIndex}&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 de 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 recebidos 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 assumirá que ele 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 no 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 propriedades
Quando um feed RSS ou Atom é retornado como resultado pelo serviço web, o provedor OpenSearch deve mapear os metadados do item nos feeds para propriedades utilizáveis pelo Windows Shell. 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 de item. O "media:" prefixo é definido pelo namespace do Namespace de Pesquisa do Yahoo .
| Caminho XML do RSS | Propriedade do Shell do Windows (nome oficial) |
|---|---|
| Link | System.ItemUrl |
| Title | System.ItemName |
| Autor | Sistema.Autor |
| pubDate | Sistema.DataModificada |
| Description | System.AutoSummary |
| Categoria | Palavras-chave System.Keywords |
| compartimento/@type | System.MIMEType |
| compartimento/@length | System.Size |
| compartimento/@url | System.ContentUrl |
| midia:categoria | Palavras-chave 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 do RSS para as propriedades do sistema do Windows Shell especificando o mapeamento no arquivo .osdx.
A saída do RSS especifica:
- Um namespace XML é
- Para qualquer elemento filho de um item, um nome de elemento para referência de mapeamento.
O arquivo .osdx identifica uma propriedade do Windows Shell para cada nome de elemento em um namespace. Os mapeamentos de propriedade que você define em seu 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 propriedades 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>[email protected]</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 a partir do valor de URL fornecido nos elementos de 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 é de 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 adicional para o usuário.
Abrir o 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 navegado para 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 de propriedades
Alguns layouts de exibição do Windows Explorer são definidos por listas de descrição de propriedade, ou proplists. Uma proplist é uma lista de propriedades delimitada por ponto-e-vírgula, como "prop:System.ItemName; System.Author", que é usada para controlar como seus resultados aparecem no Windows Explorer.
As áreas da 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 listas de propriedades, especificadas como "proplists". Você pode especificar listas de proplists personalizadas para itens individuais em seus conjuntos de resultados ou para todos os itens em um conjunto de resultados.
| Área de interface do usuário para personalizar | Propriedade do Windows Shell 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 mosaico | System.PropList.TileInfo |
| Painel detalhes | System.PropList.PreviewDetails |
| Dica de informações (dica de ferramenta de foco do item) | System.PropList.Infotip |
Para especificar uma lista de propriedades única para um item individual:
Na saída do RSS, adicione um elemento personalizado que representa a lista de adereços 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>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 do modo de exibição de conteúdo das propriedades
A lista de propriedades especificadas em System.PropList.ContentViewModeForSearch e System.PropList.ContentViewModeForBrowse determina o que é mostrado no modo de exibição do conteúdo. Para obter mais informações sobre listas de propriedades, consulte PropList.
As propriedades são estabelecidas 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 flags definidos na documentação de proplistas se aplica à exibição dos itens nos layouts do modo de exibição de conteúdo: "~". Nos exemplos anteriores, a exibição do Windows Explorer rotula algumas das propriedades, como Tags: animals; zoo; lion. Esse é o comportamento padrão quando você especifica uma propriedade na lista. Por exemplo, o proplist contém "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 lista de props tiver "~System.Size", a propriedade será exibida como apenas um valor, sem o rótulo.
Previews
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:
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 explicitamente mapeada no arquivo .osdx.
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 de 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:
Se você fornecer um mapeamento para System.ItemFolderPathDisplay, o Windows Explorer usará essa URL
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 usará a URL do link.
Se as URLs forem as mesmas 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 usuário 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 ao contêiner ou ao 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 fluxograma a seguir:
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" na Pesquisa Federada no Windows.
Tópicos relacionados
-
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