Proveedores de Windows Search
Nota:
Parte de la información hace referencia al producto de versión preliminar, el cual puede sufrir importantes modificaciones antes de que se publique la versión comercial. Microsoft no proporciona ninguna garantía, expresa o implícita, con respecto a la información proporcionada aquí.
Importante
La función descrita en este tema está disponible en las versiones preliminares de Windows a partir de la versión 22631.2787 para Windows 11 y la versión 19045.3758 para Windows 10, aunque se recomiendan las versiones más recientes porque contienen mejoras de estabilidad. Para más información sobre las compilaciones preliminares de Windows, consulte Windows 10 Insider Preview.
Windows Search utiliza actualmente la aplicación Web Search de Microsoft Bing para devolver contenido web y resultados de búsqueda. En el Espacio Económico Europeo (EEE), puede habilitar las aplicaciones instaladas que implementan un proveedor de búsqueda web para devolver contenido web y resultados de búsqueda en Windows Search a través de Configuración.
Los proveedores de búsqueda se integran con la experiencia de búsqueda mediante la creación de un paquete MSIX con un archivo de manifiesto de paquete que proporciona la información necesaria para que el sistema operativo registre el proveedor de búsqueda. Los usuarios pueden agregar un proveedor de búsqueda a Windows instalando el paquete de aplicación asociado y pueden quitar el proveedor de búsqueda a través de la página Agregar o quitar programas de la aplicación de Configuración de Windows.
Para el desarrollo y las pruebas, cuando el modo de desarrollador está habilitado y la aplicación del proveedor de búsqueda se ha descargado localmente en el dispositivo, aparecerá en la lista de proveedores de búsqueda disponibles. Para obtener más información, consulte Depuración y características del modo de desarrollador.
Una vez registrado el proveedor de búsqueda con el sistema operativo, las consultas de usuario se pasan al punto de conexión HTTP especificado por el proveedor en su manifiesto de paquete mediante una cadena de consulta estandarizada. El punto de conexión devuelve resultados sugeridos en un documento JSON. Con cada dirección URL sugerida en el documento de respuesta, el proveedor de búsqueda incluye la dirección URL del punto de conexión de vista previa, que devuelve un documento HTML que se muestra en el panel de vista previa en la interfaz de usuario de los resultados de búsqueda.
En este artículo se proporcionan instrucciones para crear un paquete de aplicación del proveedor de búsqueda y detalles sobre los protocolos para implementar puntos de conexión HTTP del proveedor de búsqueda.
Creación de un paquete de aplicación de extensibilidad de búsqueda
Los proveedores de búsqueda se registran en el sistema operativo proporcionando un paquete MSIX que contiene información necesaria sobre el proveedor, como el nombre del proveedor de búsqueda y los puntos de conexión HTTP para sugerencias y vistas previas.
Extensión de aplicación del proveedor de búsqueda
El archivo de manifiesto del paquete de aplicación admite muchas extensiones y características diferentes para las aplicaciones de Windows. El formato del manifiesto de paquete de la aplicación se define mediante un conjunto de esquemas que se documentan en la referencia del esquema del manifiesto del paquete. Los proveedores de búsqueda declaran su información de registro en uap3:AppExtension. El atributo Name de la extensión debe establecerse en "com.microsoft.windows.websearchprovider".
Los proveedores de búsqueda deberían incluir uap3:Properties como elemento secundario de uap3:AppExtension. El esquema del manifiesto de paquete no aplica la estructura del elemento uap3:Properties que no requiera XML con formato correcto. En el resto de esta sección se describe el formato XML que espera el sistema operativo para registrar correctamente un proveedor de búsqueda.
<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>
Jerarquía de elementos
uap3:Properties
EndPoint
Protocolo
Punto de conexión
Dirección URL del punto de conexión HTTPS al que el sistema operativo enviará solicitudes de consulta de búsqueda.
Protocolo
Esquema de protocolo que se usará al iniciar los resultados de búsqueda web proporcionados. Si una aplicación no registra el protocolo especificado en el sistema operativo, se iniciará el explorador predeterminado para los resultados de búsqueda. Para obtener más información sobre cómo registrar esquemas de protocolo, consulte uap:Protocol.
DynamicContentEndpoint
Dirección URL del punto de conexión HTTPS al que el sistema operativo enviará una solicitud para que se muestre el icono de destello en el cuadro de búsqueda. Para obtener más información, consulte Implementación de un punto de conexión de icono de destello. Esta característica es compatible a partir de la compilación 19045.4233 de Windows 10 y la compilación 22621.3371 de Windows 11.
Archivo de manifiesto de paquete de ejemplo
A continuación se muestra un ejemplo archivo de manifiesto del paquete appmanifest.xml para registrar un proveedor de 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>
Implementación de un punto de conexión de sugerencia del proveedor de Windows Search
Los proveedores de búsqueda deben exponer y registrar un punto de conexión HTTPS al que llama el sistema operativo cuando un usuario escribe en el cuadro Búsqueda de Windows. Este punto de conexión debe devolver una cadena con formato JSON que contenga las sugerencias de búsqueda para la consulta de usuario proporcionada. El contenido debe entregarse a través de HTTPS. La integración de búsqueda no admite contenido entregado a través de HTTP.
Formato de solicitud HTTPS de sugerencia
La solicitud HTTPS al punto de conexión de sugerencia usa el siguiente formato.
https://contoso.com?setlang=en-US&cc=US&qry=
Los parámetros de cadena de consulta pasados al punto de conexión de sugerencia son los siguientes.
| Parámetro | Descripción |
|---|---|
| setlang | Configuración regional asociada a la consulta. |
| cc | Código de país asociado a la consulta. |
| qry | Consulta proporcionada por el usuario. Si el parámetro no tiene ningún valor, es decir, aparece en la cadena de consulta como qry=, la consulta de usuario está vacía. Los proveedores de búsqueda todavía pueden proporcionar sugerencias y páginas de vista previa en respuesta a una consulta vacía. NOTA El sistema operativo no realiza ninguna sanación de las cadenas de consulta. Los proveedores de búsqueda pueden implementar su propia limpieza cuando se recibe la consulta. |
Encabezados de respuesta HTTPS de sugerencia
El proveedor de búsqueda debe incluir los siguientes encabezados en la respuesta del punto de conexión HTTPS de sugerencia.
- 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: [Debe ser la longitud exacta de la respuesta]
Formato JSON de respuesta de sugerencia
El punto de conexión HTTPS del proveedor de búsqueda para sugerencias debe devolver un documento JSON con el siguiente formato. Los nombres de clave deben coincidir exactamente con el formato.
| Clave | Descripción |
|---|---|
| Sugerencias | Contiene una lista de objetos JSON con clave Attributes que representa las sugerencias asociadas a la consulta de usuario. |
| Atributos | Contiene los atributos de una sugerencia. |
| url | Dirección URL de la sugerencia de búsqueda en el sitio web del proveedor. |
| Query | Consulta de usuario asociada a la sugerencia de búsqueda. |
| previewPaneUrl | Dirección URL del punto de conexión de vista previa desde el que se puede recuperar una vista previa HTML de la sugerencia. |
| Texto | Descripción del texto de la sugerencia. |
{"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"}
]
}
Implementación de un punto de conexión de versión preliminar del proveedor de Windows Search
Los proveedores de búsqueda devuelven la dirección URL de un punto de conexión HTTPS que proporciona una vista previa HTML de la página asociada a cada sugerencia en los resultados de búsqueda. La respuesta del punto de conexión de vista previa debe devolver el código HTML para una página en funcionamiento.
Vista previa del formato de solicitud HTTPS
La vista previa HTTPS al punto de conexión de sugerencia usa el siguiente formato.
https://contoso.com?Darkschemeovr=1
Los parámetros de cadena de consulta pasados al punto de conexión de sugerencia son los siguientes.
| Parámetro | Descripción |
|---|---|
| Darkschemeovr | Especifica si el sistema de Windows que llama tiene habilitado el tema oscuro. El valor es 1 si el tema oscuro está habilitado y 0 si el tema oscuro está deshabilitado. |
Vista previa de encabezados de respuesta HTTPS
- Access-Control-Allow-Origin: https://www.bing.com
- Access-Control-Allow-Credentials: true
- Access-Control-Allow-Methods: GET
- Content-Type: text/html; charset=utf-8
- Content-Length: [Debe ser la longitud exacta del html de vista previa]
Solicitud OPTIONS y uso compartido de recursos entre orígenes (CORS)
Los proveedores de búsqueda deben admitir el método de solicitud OPTIONS y responder a esta solicitud con HTTP OK. Si el punto de conexión del proveedor de búsqueda usa CORS, el cliente de búsqueda de Windows enviará una solicitud HTTP OPTIONS antes de cada solicitud GET.
Implementación de un punto de conexión de icono de destello
Los proveedores de búsqueda pueden proporcionar iconos de destello en modo claro y oscuro que se muestran en la barra de búsqueda cuando el proveedor de búsqueda está habilitado actualmente. Cuando se proporciona el elemento DynamicContentEndpoint en el manifiesto de la aplicación, se enviará una solicitud a la dirección URL especificada y el proveedor de búsqueda responderá con un archivo JSON en el formato definido a continuación, que incluye las direcciones URL de los archivos de imagen de icono y otros metadatos. La solicitud de icono de destello se enviará periódicamente mientras el proveedor de búsqueda sea el proveedor de búsqueda más reciente activo en Windows Search. La cadencia de esta solicitud es cada 6 horas. También se enviará una solicitud en cada inicio de Search y en el desbloqueo del dispositivo.
Formato de solicitud HTTPS de icono de destello
La solicitud HTTPS al punto de conexión de icono de destello usa el siguiente 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
Los parámetros de cadena de consulta pasados al punto de conexión de sugerencia son los siguientes.
| Parámetro | Descripción |
|---|---|
| setlang | Configuración regional asociada a la consulta. |
| cc | Código de país asociado a la consulta. |
| dateTime | Fecha y hora actuales del dispositivo cliente, con codificación URL. |
| deviceOs | Sistema operativo del dispositivo cliente. El valor de este parámetro puede ser "Windows10" o "Windows11". En Windows 10, el tamaño del icono de destello es de 30x60. En Windows 11, el tamaño del icono de destello es de 20x36. |
| schemaversion | Versión del esquema de destello. |
Formato JSON de respuesta de icono de destello
El punto de conexión HTTPS del proveedor de búsqueda para iconos de destello debe devolver un documento JSON con el siguiente formato. Los nombres de clave deben coincidir exactamente con el formato. La versión del esquema actual es 1.0.0.
| Clave | Descripción |
|---|---|
| schemaVersion | Versión del esquema de destello. Esto debe coincidir con el parámetro de cadena de consulta schemaVersion de la solicitud. |
| telemetryId | Un identificador único del icono de destello. Si el valor de la respuesta es el mismo que el valor del icono de destello actual, el sistema operativo no actualizará el icono. |
| expirationTime | Hora de caducidad del icono de destello. Debe ser una hora futura. |
| content | La sección de contenido de la respuesta. |
| taskbarSearchBox | Contiene la configuración del cuadro de búsqueda. |
| destello | Contiene la configuración del icono de destello. |
| altText | Texto alternativo para el icono de destello. |
| dimensionEnum | Valor "30x60" si la solicitud se envió desde un dispositivo Windows 10. Valor "20x36" si la solicitud se envió desde un dispositivo Windows 11. |
| iconUrl | Contiene las direcciones URL de los archivos de imagen de icono de destello claro y oscuro. |
| luz | Dirección URL del archivo de imagen de icono de destello claro. |
| dark | Dirección URL del archivo de imagen de icono de destello oscuro. |
{
"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>"
}
}
}
}
}
Validación de respuesta del icono de destello
La respuesta debe especificar la dirección URL del recurso claro y la dirección URL del recurso oscuro. Los dominios de las direcciones URL de la imagen de icono deben usar HTTPS y el subdominio debe coincidir con el subdominio especificado en el elemento DynamicContentEndpoint del archivo de manifiesto de la aplicación.
Los archivos de imagen deben tener el formato SVG y el tamaño máximo del archivo es de 300 kB. El destello debe estar dentro de un marco de 240x120 px dentro del SVG.
Si se recibe una carga vacía, se borrará el icono de destello activo y no se mostrará ningún destello.
