Provedores de pesquisa na Web do Windows Search

Pesquisa do Windows atualmente usa o aplicativo Microsoft Bing para retornar conteúdo da Web e resultados de pesquisa. Na Área Econômica Europeia (EEE), você pode instalar aplicativos que implementam um provedor de pesquisa na Web para retornar o conteúdo da Web e os resultados da pesquisa em Windows Pesquisa.

Os provedores de pesquisa se integram à experiência de pesquisa criando um pacote MSIX com um arquivo de manifesto de pacote que fornece as informações necessárias para o sistema operacional registrar o provedor de pesquisa. Após a instalação, o provedor de pesquisa é habilitado por padrão nas experiências de pesquisa Windows. No Windows Configurações, os usuários podem habilitar e desabilitar provedores de pesquisa instalados e gerenciar a ordem dos provedores nos resultados da pesquisa. Os usuários podem remover um provedor de pesquisa por meio da página Settings > Apps > Aplicativos Instalados em Configurações de Windows.

Para desenvolvimento e teste, quando o Modo de Desenvolvedor estiver habilitado e o aplicativo do provedor de pesquisa tiver sido sideloaded no dispositivo, ele aparecerá na lista de provedores de pesquisa disponíveis. Para obter mais informações, consulte Configurações para desenvolvedores.

Depois que o provedor de pesquisa é registrado com o sistema operacional, as consultas de usuário são passadas para o ponto de extremidade HTTP especificado pelo provedor no manifesto do pacote usando uma cadeia de caracteres de consulta padronizada. O endpoint retorna resultados sugeridos em um 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 dos resultados da pesquisa.

Este artigo fornece diretrizes para a criação de um pacote de aplicativos do provedor de pesquisa e detalhes dos protocolos para implementação de endpoints HTTP do provedor de pesquisa.

Criar um pacote do aplicativo de 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 de aplicativo do provedor de pesquisa

O arquivo de manifesto do pacote de aplicativos dá suporte a várias extensões e recursos diferentes para aplicativos Windows. O formato do manifesto do pacote do aplicativo é definido por um conjunto de esquemas documentados na Referência de esquemas de manifesto do pacote. Os provedores de pesquisa declaram suas informações de registro no 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 o filho de uap3:AppExtension. O esquema de manifesto do pacote não impõe a estrutura do elemento uap3:Properties, a não ser a exigência de um 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 endereço HTTPS para o qual o sistema operacional enviará solicitações de consulta de pesquisa.

Protocolo

O esquema de protocolo que será usado ao iniciar os resultados da 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 obter os resultados da pesquisa. Para obter mais informações sobre como registrar esquemas de protocolo, consulte uap:Protocol.

Exemplo de arquivo de manifesto do pacote

Veja a seguir um arquivo de manifesto do pacote de exemplo appmanifest.xml para registrar um provedor 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 do provedor do Windows Search

Os provedores de pesquisa devem expor e registrar um ponto de extremidade HTTPS chamado pelo sistema operacional quando um usuário digita na caixa do Windows Search. Esse ponto de extremidade deve retornar uma cadeia de caracteres formatada em JSON que contém as sugestões de pesquisa para a consulta de usuário fornecida. O conteúdo deve ser entregue via HTTPS. A integração de pesquisa não dá suporte ao conteúdo entregue 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 de cadeia de caracteres de consulta passados para o ponto de extremidade de sugestão são os seguintes.

Parâmetro	Descrição
setlang	A localidade associada à consulta.
cc	O código do país associado à consulta.
consulta	A consulta fornecida pelo usuário. Se o parâmetro não tiver valor, ou seja, será exibido na cadeia de caracteres de consulta como qry=, então a consulta do usuário estará vazia. Os provedores de pesquisa ainda podem fornecer sugestões e visualizar páginas em resposta a uma consulta vazia. NOTA O sistema operacional não executa nenhuma sanitização de cadeias de caracteres de consulta. Os provedores de pesquisa podem implementar sua própria sanitização quando a consulta é recebida.

Sugestão de cabeçalhos de resposta HTTPS

O provedor de pesquisa deve incluir os seguintes cabeçalhos na resposta do ponto de extremidade HTTPS de sugestão.

• Access-Control-Allow-Origin: https://www.bing.com
• Access-Control-Allow-Credentials: verdadeiro
• Access-Control-Allow-Methods: GET
• Tipo de conteúdo: application/json; charset=utf-8
• Comprimento do conteúdo: [Deve ser o comprimento exato da resposta]

Formato JSON de resposta à 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 de chave devem corresponder exatamente ao formato.

Chave	Descrição
Sugestões	Contém uma lista de objetos JSON com chave Attributes que representa as sugestões associadas à consulta de usuário.
Atributos	Contém os atributos de uma sugestão.
url	A URL da sugestão de pesquisa no site do provedor.
consulta	A consulta de usuário associada à sugestão de pesquisa.
previewPaneUrl	A URL do ponto de extremidade de visualização a partir do qual uma visualização HTML da sugestão pode ser recuperada.
secondaryIconUrl	Optional. A URL de uma imagem que é exibida no lugar do ícone de lupa padrão da sugestão. Se essa chave não estiver presente, o ícone de spyglass padrão será exibido. Para obter a melhor qualidade de exibição, a imagem deve ser quadrada. O corte de imagens que não são quadradas não é garantido.
Texto	A descrição do texto da sugestão.

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

Implementar um ponto de extremidade de visualização do provedor do Windows Search

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

Visualizar formato de solicitação HTTPS

A solicitação HTTPS para o endereço de pré-visualização usa o seguinte formato.

https://contoso.com?Darkschemeovr=1

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

Parâmetro	Descrição
Darkschemeovr	Especifica se o sistema de Windows de chamada tem o tema escuro habilitado. O valor será 1 se o tema escuro estiver habilitado e 0 se o tema escuro estiver desabilitado.

Visualizar cabeçalhos de resposta HTTPS

• Access-Control-Allow-Origin: https://www.bing.com
• Access-Control-Allow-Credentials: verdadeiro
• Access-Control-Allow-Methods: GET
• Tipo de Conteúdo: texto/html; charset=utf-8
• Tamanho do Conteúdo: [Deve ser o tamanho exato da pré-visualização HTML]

Solicitação OPTIONS e CORS (Compartilhamento de Recurso entre Origens)

O cliente Windows Search envia uma solicitação HTTP OPTIONS (simulação CORS) antes de cada solicitação GET. Os provedores de pesquisa devem dar suporte ao método de solicitação OPTIONS e responder com HTTP 200 OK.

Artigos relacionados