Fornecedores de pesquisa web do Windows Search

O Windows Search utiliza atualmente a aplicação Web Search from Microsoft Bing para devolver conteúdos web e resultados de pesquisa. No Espaço Económico Europeu (EEE), pode instalar aplicações que implementam um fornecedor de pesquisa web para devolver conteúdos e resultados de pesquisa no Windows Search.

Os provedores de pesquisa integram-se à experiência de pesquisa criando um pacote MSIX com um arquivo de manifesto de pacote que fornece as informações necessárias para que o sistema operacional registre o provedor de pesquisa. Após a instalação, o provedor de pesquisa fica ativado por padrão nas experiências de pesquisa do Windows. Nas Definições do Windows, os utilizadores podem ativar e desativar os fornecedores de pesquisa instalados e gerir a ordem dos fornecedores nos resultados de pesquisa. Os utilizadores podem remover um provedor de pesquisa através da página Definições > Apps > Aplicações Instaladas nas Definições do Windows.

Para desenvolvimento e teste, quando o Modo de Desenvolvedor estiver ativado e a aplicação do fornecedor de pesquisa tiver sido carregada lateralmente no dispositivo, ela aparecerá na lista de fornecedores de pesquisa disponíveis. Para mais informações, consulte Definições para programadores.

Depois que o provedor de pesquisa é registrado no sistema operacional, as consultas do usuário são passadas para o ponto de extremidade HTTP especificado pelo provedor em seu manifesto de pacote usando uma cadeia de caracteres de consulta padronizada. O ponto final retorna resultados sugeridos num documento JSON. Com cada URL sugerida no documento de resposta, o provedor de pesquisa inclui a URL do ponto de extremidade de visualização, que retorna um documento HTML que é exibido no painel de visualização na interface do usuário de resultados da pesquisa.

Este artigo fornece orientações para criar um pacote de aplicação do provedor de pesquisa e detalhes sobre os protocolos para implementar endpoints HTTP do provedor de pesquisa.

Criar um pacote de aplicação para extensibilidade de pesquisa

Os provedores de pesquisa se registram no sistema operacional fornecendo um pacote MSIX que contém as informações necessárias sobre o provedor, como o nome do provedor de pesquisa e os pontos de extremidade HTTP para sugestões e visualizações.

Extensão do aplicativo do provedor de pesquisa

O ficheiro manifesto do pacote da aplicação suporta muitas extensões e funcionalidades diferentes para aplicações do Windows. O formato de manifesto do pacote do aplicativo é definido por um conjunto de esquemas que são documentados na referência do esquema de manifesto do pacote . Os provedores de pesquisa declaram suas informações de registro dentro do uap3:AppExtension. O atributo Name da extensão deve ser definido como "com.microsoft.windows.websearchprovider".

Os provedores de pesquisa devem incluir uap3:Properties como filho de uap3:AppExtension. O esquema de manifesto do pacote não impõe a estrutura do elemento uap3:Properties, exigindo apenas XML bem formado. O restante desta seção descreve o formato XML que o sistema operacional espera para registrar com êxito um provedor de pesquisa.

<uap3:Extension Category="windows.appExtension">
  <uap3:AppExtension Name="com.microsoft.windows.websearchprovider" DisplayName="SearchExampleApp" Id="ContosoSearchApp" PublicFolder="Public">
    <uap3:Properties>
    <!-- Search provider registration content goes here -->
    </uap3:Properties>
  </uap3:AppExtension>
</uap3:Extension>

Hierarquia de elementos

uap3:Propriedades

  Endpoint

  Protocolo

Ponto final

O URL do endpoint HTTPS para o qual o sistema operativo enviará solicitações de consulta de pesquisa.

Protocolo

O esquema de protocolo que será usado ao iniciar os resultados de pesquisa na Web fornecidos. Se o protocolo especificado não for registrado por um aplicativo no sistema operacional, o navegador padrão será iniciado para os resultados da pesquisa. Para obter mais informações sobre como registrar esquemas de protocolo, consulte uap:Protocol.

Exemplo de ficheiro de manifesto do pacote

Segue-se um exemplo de ficheiro de manifesto de pacote appmanifest.xml para registar um fornecedor de pesquisa do Windows Search.

<!-- appxmanifest.xml -->

  <uap3:Extension Category="windows.appExtension">
	  <uap3:AppExtension Name="com.microsoft.windows.websearchprovider" DisplayName="CustomSearch" Id="CustomSearchApp" PublicFolder="Public">
		  <uap3:Properties>
			  <Endpoint>https://customsearchendpoint</Endpoint>
			  <Protocol>customsearch</Protocol>
		  </uap3:Properties>
	  </uap3:AppExtension>
  </uap3:Extension>
  <uap:Extension Category="windows.protocol">
	  <uap:Protocol Name="customsearch"/>
  </uap:Extension>

Implementar um endpoint de sugestão para o fornecedor do Windows Search

Os fornecedores de pesquisa devem expor e registar um endpoint HTTPS que é chamado pelo sistema operativo quando um utilizador escreve na caixa de Pesquisa do Windows. Esse ponto de extremidade deve retornar uma cadeia de caracteres formatada em JSON contendo as sugestões de pesquisa para a consulta de usuário fornecida. O conteúdo deve ser entregue por HTTPS. A integração de pesquisa não suporta conteúdo fornecido por HTTP.

Sugestão de formato de solicitação HTTPS

A solicitação HTTPS para o endpoint de sugestão usa o seguinte formato.

https://contoso.com?setlang=en-US&cc=US&qry=

Os parâmetros da cadeia de consulta passados para o ponto de extremidade de sugestão são os seguintes.

Cabeçalhos de resposta HTTPS sugeridos

O fornecedor de pesquisa deve incluir os seguintes cabeçalhos na resposta do endpoint HTTPS de sugestão.

• Acesso-Controle-Allow-Origin: https://www.bing.com
• Access-Control-Allow-Credentials: verdadeiro
• Controlador de Acesso-Permitir-Métodos: GET
• Tipo de conteúdo: application/json; charset=utf-8
• Content-Length: [Deve ser o comprimento exato da resposta]

Formato JSON de resposta de sugestão

O ponto de extremidade HTTPS do provedor de pesquisa para sugestões deve retornar um documento JSON com o seguinte formato. Os nomes das chaves devem corresponder exatamente ao formato.

{"Suggestions": 
   [{"Attributes": 
     {"url":"https://www.contoso.com/search?q=projection+matrix","query":"projection matrix","previewPaneUrl":"http://www.contoso.com/preview"} ,"Text":"projection matrix"}, 
    {"Attributes": 
     {"url":"https://www.contoso.com/search?q=rotation+matrix","query":"rotation matrix","previewPaneUrl":"http://www.contoso.com/preview"} ,"Text":"rotation matrix"}
    ] 
} 

Implementar um endpoint de pré-visualização do fornecedor de Pesquisa do Windows

Os provedores de pesquisa retornam o URL de um endpoint HTTPS que oferece uma pré-visualização HTML da página associada a cada sugestão nos resultados de pesquisa. A resposta do endpoint de pré-visualização deve retornar o código HTML para uma página funcional.

Visualizar formato de solicitação HTTPS

A solicitação HTTPS para o ponto final de visualização usa o seguinte formato.

https://contoso.com?Darkschemeovr=1

Os parâmetros da cadeia de consulta passados para o ponto de extremidade de sugestão são os seguintes.

Visualizar cabeçalhos de resposta HTTPS

• Acesso-Controle-Allow-Origin: https://www.bing.com
• Access-Control-Allow-Credentials: verdadeiro
• Controlador de Acesso-Permitir-Métodos: GET
• Content-Type: texto/html; charset=utf-8
• Content-Length: [Deve ser o comprimento exato da pré-visualização HTML]

Solicitação OPTIONS e compartilhamento de recursos entre origens (CORS)

O cliente Windows Search envia um pedido HTTP OPTIONS (CORS preflight) antes de cada pedido GET. Os fornecedores de pesquisa devem suportar o método de pedido OPTIONS e responder com HTTP 200 OK.

Artigos relacionados