Provedores do Windows Search
Observação
Algumas informações relacionam-se ao produto de pré-lançamento, o qual poderá ser substancialmente modificado antes do lançamento comercial. A Microsoft não oferece nenhuma garantia, explícita ou implícita, quanto às informações fornecidas aqui.
Importante
O recurso descrito neste tópico está disponível em compilações de pré-visualização do Windows a partir de 22631.2787 para Windows 11 e de 19045.3758 para Windows 10, embora compilações mais recentes sejam recomendadas por conterem aprimoramentos de estabilidade. Para saber mais sobre compilações de pré-visualização do Windows, confira Windows 10 Insider Preview.
O Windows Search usa o aplicativo de Pesquisa na Web do Microsoft Bing para trazer conteúdo da Web e resultados da pesquisa. No Espaço Econômico Europeu (EEE), você pode habilitar aplicativos instalados que implementam um provedor de pesquisa na Web para retornar conteúdo da Web e resultados de pesquisa no Windows Search por meio de Configurações.
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 que o sistema operacional registre o provedor de pesquisa. Os usuários podem adicionar um provedor de pesquisa ao Windows instalando o pacote de aplicativo associado e podem remover o provedor de pesquisa por meio da página Adicionar ou remover programas no aplicativo Configurações do 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 Recursos e depuração do modo de desenvolvedor.
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 de extremidade 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 orientação para a criação de um pacote do aplicativo do provedor de pesquisa e detalhes sobre os protocolos para implementar pontos de extremidade 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 do aplicativo do provedor de pesquisa
O arquivo de manifesto do pacote do aplicativo dá suporte a várias extensões e recursos diferentes para aplicativos do 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 as informações de registro no uap3:AppExtension. O atributo Name da extensão precisa 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:Properties
EndPoint
Protocolo
Ponto de extremidade
A URL do ponto de extremidade 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 os resultados da pesquisa. Para obter mais informações sobre como registrar esquemas de protocolo, consulte uap:Protocol.
DynamicContentEndpoint
A URL do ponto de extremidade HTTPS para o qual o sistema operacional enviará uma solicitação para que o ícone de brilho seja exibido na caixa de pesquisa. Para obter mais informações, consulte Implementar um ponto de extremidade de ícone de brilho. Este recurso é suportado a partir do Windows 10 build 19045.4233 e do Windows 11 build 22621.3371.
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>
<DynamicContentEndpoint>https://sub.contoso.com/dynamic</DynamicContentEndpoint>
</uap3:Properties>
</uap3:AppExtension>
</uap3:Extension>
<uap:Extension Category="windows.protocol">
<uap:Protocol Name="customsearch"/>
</uap:Extension>
Implementar um ponto de extremidade de sugestão de 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 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 oferece suporte a conteúdo fornecido por HTTP.
Sugestão de formato de solicitação HTTPS
A solicitação HTTPS para o ponto de extremidade 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 | As localidades associadas à 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, aparecer na cadeia de caracteres de consulta como qry=, 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. OBSERVAÇÃO O sistema operacional não executa limpeza de cadeias de caracteres de consulta. Os provedores de pesquisa podem implementar sua própria higienização quando a consulta é recebida. |
Cabeçalhos de resposta HTTPS de sugestão
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: true
- Access-Control-Allow-Methods: GET
- Content-Type: 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.
| Key | Descrição |
|---|---|
| Sugestões | Contém uma lista de objetos JSON com chave Attributes que representa as sugestões associadas à consulta do 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 do 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. |
| Texto | A descrição do texto da sugestão. |
{"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 ponto de extremidade de visualização do provedor do Windows Search
Os provedores de pesquisa retornam a URL de um ponto de extremidade HTTPS que fornece uma visualização HTML da página associada a cada sugestão nos resultados da pesquisa. 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 ponto de extremidade de 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 tema escuro do sistema Windows de chamada está habilitado. O valor é 1 se o tema escuro estiver habilitado e 0 se estiver desabilitado. |
Visualizar cabeçalhos de resposta HTTPS
- Access-Control-Allow-Origin: https://www.bing.com
- Access-Control-Allow-Credentials: true
- Access-Control-Allow-Methods: GET
- Tipo de conteúdo: text/html; charset=utf-8
- Content-Length: [Deve ser o comprimento exato da visualização html]
Solicitação OPTIONS e CORS (Compartilhamento de Recurso entre Origens)
Os provedores de pesquisa devem oferecer suporte ao método de solicitação OPTIONS e responder a essa solicitação com HTTP OK. Se o ponto de extremidade do provedor de pesquisa estiver usando CORS, o cliente de pesquisa do Windows enviará uma solicitação HTTP OPTIONS antes de cada solicitação GET.
Implementar um ponto de extremidade de ícone de brilho
Os provedores de pesquisa podem, opcionalmente, fornecer ícones de brilho no modo claro e escuro que são exibidos na barra de pesquisa quando o provedor de pesquisa está habilitado no momento. Quando o elemento DynamicContentEndpoint é fornecido no manifesto do aplicativo, uma solicitação será enviada para a URL especificada e o provedor de pesquisa responderá com um arquivo json no formato definido abaixo que inclui as URLs dos arquivos de imagem de ícone e outros metadados. A solicitação de ícone de brilho será enviada periodicamente enquanto o provedor de pesquisa for o provedor mais recente ativo no Windows Search. A cadência para essa solicitação é a cada 6 horas. Uma solicitação também será enviada a cada inicialização da Pesquisa e no desbloqueio do dispositivo.
Formato de solicitação HTTPS do ícone de brilho
A solicitação HTTPS para o ponto de extremidade do ícone de brilho usa o seguinte formato.
https://www.contoso.com/Gleam?cc=FR&setlang=en-us&dateTime=3%2F29%2F2024%2C%208%3A33%3A56%20PM&deviceOs=windows10&schemaversion=1.0.0
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 | As localidades associadas à consulta. |
| cc | O código do país associado à consulta. |
| dateTime | A data e a hora atuais do dispositivo cliente, codificadas por url. |
| deviceOs | O sistema operacional do dispositivo do cliente. O valor desse parâmetro pode ser "Windows10" ou "Windows11". No Windows 10, o tamanho do ícone de brilho é 30x60. No Windows 11, o tamanho do ícone de brilho é 20x36. |
| schemaversion | A versão do esquema de brilho. |
Formato JSON de resposta do ícone de brilho
O ponto de extremidade HTTPS do provedor de pesquisa para ícones de brilho deve retornar um documento JSON com o seguinte formato. Os nomes das chaves devem corresponder exatamente ao formato. A versão atual do esquema é 1.0.0.
| Chave | Descrição |
|---|---|
| schemaVersion | A versão do esquema de brilho. Isso deve corresponder ao parâmetro de cadeia de caracteres de consulta schemaVersion na solicitação. |
| telemetryId | Um identificador exclusivo para o ícone de brilho. Se o valor na resposta for o mesmo que o valor do ícone de brilho atual, o sistema operacional não atualizará o ícone. |
| expirationTime | O tempo de expiração para o ícone de brilho. Deve ser um momento no futuro. |
| content | A seção de conteúdo da resposta. |
| taskbarSearchBox | Contém configurações para a caixa de pesquisa. |
| brilho | Contém configurações para o ícone de brilho. |
| altText | Texto alternativo para o ícone de brilho. |
| dimensionEnum | O valor "30x60" se a solicitação foi enviada de um dispositivo Windows 10. O valor "20x36" se a solicitação foi enviada de um dispositivo Windows 11. |
| iconUrl | Contém as URLs para os arquivos de imagem de ícone de brilho claro e escuro. |
| luz | A URL do arquivo de imagem do ícone de brilho claro. |
| dark | A URL do arquivo de imagem de ícone de brilho escuro. |
{
"schemaVersion":"1.0.0",
"telemetryId":"<unique gleam Id>",
"expirationTime":"2025-12-09T20:37:13Z",
"content": {
"taskbarSearchBox": {
"gleam":{
"altText": "<alt text of the gleam>",
"dimensionEnum": "(30x60 for Windows 10, 20x36 for Windows 11)",
"iconUrl": {
"light":"<3p's light gleam url>",
"dark": "<3p's dark gleam url>"
}
}
}
}
}
Validação de resposta do ícone de brilho
A resposta deve especificar a URL do ativo claro e a URL do ativo escuro. Os domínios para as URLs de imagem de ícone devem usar HTTPS e o subdomínio deve corresponder ao subdomínio especificado no elemento DynamicContentEndpoint no arquivo de manifesto do aplicativo.
Os arquivos de imagem devem estar no formato SVG e o tamanho máximo do arquivo é de 300 kB. O brilho precisa estar dentro de um quadro de 240x120px dentro do SVG.
Se uma carga vazia for recebida, isso limpará o ícone de brilho ativo e nenhum brilho será exibido.
Artigos relacionados
Windows developer