Compartir a través de

Proveedores de búsqueda web de Windows Search

Windows Search usa actualmente la búsqueda web de la aplicación Microsoft Bing para devolver contenido web y resultados de búsqueda. En el Espacio Económico Europeo (EEE), puedes instalar aplicaciones que implementen un proveedor de búsqueda web para devolver contenido web y resultados de búsqueda en Windows Search.

Captura de pantalla de la interfaz de usuario de Windows Search con la integración del proveedor de búsqueda de terceros.

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. Después de la instalación, el proveedor de búsqueda está habilitado de forma predeterminada en las experiencias de Windows Search. En la aplicación Configuración de Windows, los usuarios pueden habilitar y deshabilitar proveedores de búsqueda instalados y administrar el orden de los proveedores en los resultados de la búsqueda. Los usuarios pueden quitar un proveedor de búsqueda a través de la página Aplicaciones > instaladas de configuración > en la aplicación Configuración de Windows.

En el caso del 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 Características y depuración 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 dentro de uap3:AppExtension. El atributo Name de la extensión debe establecerse en "com.microsoft.windows.websearchprovider".

Los proveedores de búsqueda deben incluir uap3:Properties como elemento secundario de uap3:AppExtension. El esquema de manifiesto del paquete no impone la estructura del elemento uap3:Properties, aparte de exigir que sea un XML bien formado. 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:Propiedades

  Punto Final

  Protocolo

Punto final

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 el registro de esquemas de protocolo, consulte uap:Protocol.

PuntoFinalDeContenidoDinámico

Esta característica ya no se admite. Para obtener más información, consulte Implementar un endpoint de icono 'gleam'. Dirección URL del punto de conexión HTTPS al que el sistema operativo enviará una solicitud para que se muestre el icono de brillo en el cuadro de búsqueda.

Ejemplo de archivo de manifiesto de paquete

A continuación se muestra un ejemplo de archivo de manifiesto de 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 sugerida

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 final de sugerencia son los siguientes.

Parámetro Descripción
setlang Localización 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.

Propuestas de encabezados de respuesta HTTPS

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.
consulta 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.
Mensaje de 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 endpoint de vista previa debe devolver el código HTML para una página en funcionamiento.

Vista previa del formato de solicitud HTTPS

La solicitud HTTPS al punto de conexión de versión preliminar usa el siguiente formato.

https://contoso.com?Darkschemeovr=1

Los parámetros de cadena de consulta pasados al punto final 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.

Implementar un punto de conexión de icono de destello

Nota:

Esta característica gleam ya no está habilitada. Los iconos gleam ya no se muestran para todos los proveedores web del EEE. El contenido de esta sección de la documentación está obsoleto.

Los proveedores de búsqueda pueden proporcionar opcionalmente iconos de brillo de 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 del icono de brillo se enviará periódicamente mientras el proveedor de búsqueda más reciente esté activo en Windows Search. La cadencia de esta solicitud es cada 6 horas. También se enviará una solicitud en cada inicio de búsqueda y en el desbloqueo del dispositivo.

Formato de solicitud HTTPS de icono de Gleam

La solicitud HTTPS al punto de conexión del icono gleam 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 final de sugerencia son los siguientes.

Parámetro Descripción
setlang Localización asociada a la consulta.
Cc Código de país asociado a la consulta.
fechaHora Fecha y hora actuales del dispositivo cliente, con codificación URL.
dispositivoSO 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 brillo es de 30x60. En Windows 11, el tamaño del icono de brillo es de 20 x 36
schemaversion Versión del esquema Gleam.

Formato de JSON de respuesta del icono Gleam

El punto de conexión HTTPS del proveedor de búsqueda para iconos gleam debe devolver un documento JSON con el siguiente formato. Los nombres de clave deben coincidir exactamente con el formato. La versión actual del esquema es 1.0.0.

Clave Descripción
schemaVersion Versión del esquema Gleam. Esto debe coincidir con el parámetro de cadena de consulta schemaVersion de la solicitud.
telemetryId Identificador único del icono de brillo. Si el valor de la respuesta es el mismo que el valor del icono de brillo actual, el sistema operativo no actualizará el icono.
tiempo de expiración Hora de expiración del icono de brillo. Debe ser un momento en el futuro.
contenido Sección de contenido de la respuesta.
cuadro de búsqueda de la barra de tareas Contiene la configuración del cuadro de búsqueda.
brillo Contiene la configuración del icono de brillo.
texto alternativo Texto alternativo para el icono de brillo.
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.
URL del icono Contiene las direcciones URL de los archivos de imagen de icono de brillo claro y oscuro.
luz Dirección URL del archivo de imagen del icono de destello.
oscuro Dirección URL del archivo de imagen de icono de brillo 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 Gleam

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 estar en formato SVG y el tamaño máximo del archivo es de 300 kB. El brillo debe estar dentro de un marco 240x120px dentro del SVG.

Si se recibe una carga vacía, se borrará el icono de brillo activo y no se mostrará ningún brillo.