Conectar un bot a Search (versión preliminar)

En este artículo se describe cómo crear un proveedor de búsqueda federado personalizado (potencia por el bot) y conectarlo al canal de búsqueda. Una vez que el administrador de inquilinos habilita el proveedor en su inquilino, las búsquedas del usuario de empresa, desde Office.com, SharePoint.com y Bing.com, pueden incluir resultados de su proveedor de búsqueda personalizado.

La Plataforma de búsqueda federada de Microsoft le permite crear proveedores de búsqueda federados personalizados para permitir que la información participe en las experiencias de respuestas y verticales de Búsqueda de Microsoft sin necesidad de combinar esa información con el índice de Microsoft 365. Para obtener más información, consulte Anuncio de la versión preliminar para desarrolladores de la Plataforma de búsqueda federada de Microsoft y búsqueda federada de Dynamics 365 (versión preliminar).

Nota:

El canal de búsqueda está en versión preliminar privada. Para solicitar acceso, use el formulario de la Versión preliminar privada para desarrolladores de la Búsqueda de Microsoft. En la pregunta 7, seleccione Búsqueda federada.

Los pasos siguientes son necesarios para conectar el bot al canal de búsqueda. Estos pasos se describen con más detalle posteriormente en este artículo.

1. Implemente el bot para que funcione como proveedor de búsquedas.
2. Si el bot requerirá que los usuarios inicien sesión:
   1. En Azure Portal, exponga la API de bot a la plataforma de búsqueda.
   2. En el código del bot, use el URI de ámbito generado para generar un token de usuario.
3. Implementar un bot en Azure.
4. Agregue el canal de búsqueda al bot.
5. Pida al administrador de TI que revise el registro del bot y publique el bot en el inquilino.

Sugerencia

Se recomienda habilitar el proveedor de búsquedas en un inquilino de prueba antes de habilitarlo en producción.

Requisitos previos

• Conocimiento de los Datos básicos de Bot Framework Service y cómo Crear un bot con Bot Framework SDK.
• El bot para conectarse al canal.
• Antes de comenzar, si no tiene una cuenta de Azure, cree una gratuita.

Puede implementar el bot en cualquiera de los idiomas admitidos por Bot Framework SDK. En este artículo se usa el bot de búsqueda federada de C# como ejemplo.

Exposición de la API de bot a la búsqueda

Sugerencia

Este paso solo es necesario si el bot requiere acceso a los recursos de usuario protegidos.

En algunos flujos de trabajo empresariales, un bot podría requerir credenciales de usuario para realizar una acción en nombre del usuario. Para crear una experiencia de inicio de sesión único (SSO) para el bot en el canal de búsqueda, debe permitir que la plataforma de búsqueda proteja un token de acceso de Microsoft Entra ID en nombre del usuario.

Para generar un URI de ámbito y un identificador de aplicación para el bot:

1. Vaya a Azure Portal.
2. Cree un recurso de Bot de Azure si todavía no lo ha hecho.
3. Vaya al servicio Microsoft Entra ID.
4. Vaya al panel Registros de aplicaciones.
5. Seleccione la aplicación asociada al bot.
6. Vaya al panel Exponer una API.
7. Seleccione Agregar un ámbito.
   1. En el panel Agregar un ámbito, se recomienda mantener el URI de identificador de aplicación generado automáticamente. Seleccione Guardar y continuar.
   2. Escriba un valor para Scope name (Nombre de ámbito).
   3. Para ¿Quién puede dar su consentimiento?, se prefieren Administración y usuarios, pero ambas opciones funcionarán.
   4. Escriba un Nombre para mostrar del consentimiento del administrador y una Descripción del consentimiento del administrador.
   5. Opcionalmente, introduzca un Nombre para mostrar de consentimiento del usuario y una Descripción del consentimiento del usuario.
   6. Compruebe que Estado está establecido en Habilitado.
   7. Seleccione Agregar ámbito.
8. Seleccione Agregar una aplicación cliente.
   1. En el panel Agregar una aplicación cliente, establezca Id. de cliente en 81473081-50b9-469a-b9d8-303109583ecb, el Id. de cliente de la plataforma de búsqueda.
   2. En Ámbitos autorizados, seleccione el URI de ámbito que creó en el paso anterior.
   3. Seleccione Agregar aplicación.
9. Vaya al panel Introducción. Copie el URI del id. de la aplicación. Lo necesitará al registrar el bot en el canal de búsqueda.

Implementación del bot

El canal de búsqueda envía cada consulta de usuario al bot como una actividad de invocación con el nombre "application/search". El bot devuelve los resultados de la consulta en la respuesta de invocación. Use el formato de tarjeta adaptable para los resultados de la consulta enviados de vuelta al canal de búsqueda.

1. Actualice los paquetes de Bot Framework y Tarjetas adaptables del proyecto a la versión más reciente.
2. Opcionalmente, agregue código de autenticación para generar un token de usuario.
3. Implemente un método de búsqueda de datos para cada origen de datos que se va a incluir.
4. Genere la tarjeta adaptable para mostrar los resultados.

Obtención del identificador de seguimiento de la plataforma de búsqueda

La plataforma de búsqueda asigna un identificador de seguimiento único a cada consulta que envía al bot. La plataforma lo agrega a los datos del canal de la actividad de invocación. Puede decidir registrar el identificador de seguimiento de la solicitud. Use la propiedad traceId de los datos del canal para obtener el identificador de seguimiento.

En el ejemplo de búsqueda federada, el método SearchHelper.GetSearchTraceId muestra cómo obtener el identificador de seguimiento de la actividad de invocación.

Agregar autenticación

Si expone la API de bot a Search y solicitó la autenticación al conectar el bot a Search, puede obtener el token de autenticación de usuario de los datos del canal de la actividad.

La propiedad authorizations de los datos del canal puede contener una lista de tokens de autenticación. Si expone la API de bot a Search, la lista contendrá el token delegado. El token de la lista tendrá la siguiente estructura:

Nombre de propiedad	Type	Descripción
authType	integer	El tipo de token de autenticación: 0 para desconocido o predeterminado, o 2 para el token delegado.
token	string	El propio token de autenticación.

En el ejemplo de búsqueda federada:

• La clase SearchBotAuthenticationToken y la enumeración AuthenticationTypes representan esta información.
• El método SearchHelper.GetSearchOboToken muestra cómo obtener el token de la actividad de invocación.

Una vez que tenga el token, puede usarlo cuando solicite recursos protegidos para el usuario. Para más información acerca del uso de tokens delegados, consulte Plataforma de identidad de Microsoft y flujo con derechos delegados de OAuth 2.0.

Consulta de cada almacén de datos

El canal de búsqueda envía una consulta al bot como una actividad invoke, con los detalles de la consulta en la propiedad value de la actividad, que representa un objeto JSON con la siguiente estructura:

Nombre de propiedad	Type	Descripción
queryText	string	El texto de la consulta.
kind	string	El tipo de consulta: "buscar" cuando los resultados se muestren en una pestaña vertical personalizada o "searchAnswer" cuando se muestre un resultado como respuesta en la pestaña Todos.
queryOptions	object	Opciones de consulta adicionales usadas para la paginación.
queryOptions.skip	integer	El índice del primer resultado a enviar.
queryOptions.top	integer	El número máximo de resultados a enviar.

Devuelve los resultados de búsqueda en la respuesta de invocación:

• Establezca siempre la propiedad Status del objeto de respuesta de invocación en 200, lo que indica que la conexión de red está bien. La propiedad Body del objeto tiene un código de estado independiente.

• La propiedad Body representa un objeto JSON con la estructura siguiente:

  Nombre de propiedad	Type	Descripción
  statusCode	integer	Código de estado HTTP que se usa para indicar si el bot pudo ejecutar correctamente la consulta.
  type	cadena	El tipo de la respuesta de invocación, que define el formato del campo de valor. Use "application/vnd.microsoft.search.searchResponse" para los resultados de búsqueda o "application/vnd.microsoft.error" para ver un mensaje de error.
  value	object	Un valor que corresponde al valor type.

  Para los mensajes de error, el objeto value contiene:

  Nombre de propiedad	Type	Descripción
  código	string	Un código de error definido por el bot o null si no se especifica.
  message	string	Un mensaje de error o null si no se especifica.

  Para los resultados de la búsqueda, el objeto value contiene:

  Nombre de propiedad	Type	Descripción
  results	matriz de objetos de resultados de búsqueda	Los resultados, o null si no hay ninguno.
  displayLayouts	matriz de objetos de diseño de pantalla	Los diseños de presentación o null si no los hay.
  totalResultCount	integer	Resultados totales disponibles, si se admite la paginación; de lo contrario, null.
  moreResultsAvailable	Booleano	Indica si hay más resultados disponibles.

  Los objetos de resultado de búsqueda contienen:

  Nombre de propiedad	Type	Descripción
  value	string	Un identificador o valor único para este resultado de búsqueda.
  layoutId	string	El Id. del diseño de presentación que se va a usar para este resultado.
  data.searchResultText	string	El texto de este resultado.

  Los objetos de diseño para mostrar contienen:

  Nombre de propiedad	Type	Descripción
  layoutId	string	El Id. de diseño.
  layoutBody	string	El cuerpo del diseño como un objeto JSON de tarjetas adaptables.

En el ejemplo de búsqueda federada, el método SearchHelper.RunFederatedSearch muestra cómo obtener la información de consulta de la actividad de invocación y cómo dar formato a la respuesta de invocación.

Visualización de los resultados de la búsqueda

Puede crear verticales de búsqueda y tipos de resultados para personalizar los resultados de búsqueda que ven los usuarios cuando buscan en SharePoint, Office y Bing. Las verticales facilitan a los usuarios encontrar la información que tienen permiso para ver. Para obtener más información, consulte la sección Elementos de tarjeta adaptable compatibles.

Si el bot recibe una consulta para la que no tiene respuesta, su respuesta debe contener una respuesta vacía.

Registre el bot en Azure

Para conectar el bot al canal de búsqueda, debe tener un recurso de bot aprovisionado en Azure. Para más información, consulte cómo Registrar un bot con Azure o cómo Implementar el bot en Azure.

Conectar el bot a Search

Las instrucciones siguientes muestran cómo conectar un bot a Search.

Sugerencia

Se recomienda habilitar el proveedor de búsquedas en un inquilino de prueba antes de habilitarlo en producción.

1. Vaya a Azure Portal.

2. Abra el recurso del bot.

3. Abra el panel Canales (Vista previa).

4. Seleccione Buscar.

5. En la pestaña Buscar Configuración, escriba información para el bot.

   

   1. En Metadatos del proveedor de búsquedas, introduzca el nombre que se va a mostrar en la UI de búsqueda.

   2. En Frases desencadenadoras, defina las frases que representan las consultas que el bot puede responder.

      Nota:

      En el caso de las versiones iniciales, solo está disponible inglés (en-US).

      • Cargue un archivo .csv que contenga las frases. El archivo debe contener una columna de datos, sin encabezados.
      • En la lista Preferencia de idioma, seleccione el idioma en el que se escriben las frases desencadenadoras.

   3. En Autenticación, indique si el proveedor de búsquedas requiere autenticación de usuario.

      • Si se requiere autenticación, escriba la dirección URL de autenticación. Utilice el URI del id. de aplicación que copió al exponer la API para el bot.

   4. Seleccione Siguiente.

6. En las pestañas Verticales, si desea que los resultados del proveedor de búsquedas aparezcan en su propia vertical personalizada en la página de resultados de la búsqueda, escriba el nombre del segmento vertical en el campo; de lo contrario, deje este campo vacío. Después, seleccione Siguiente.
   La página de resultados de la búsqueda es para Office.com, SharePoint.com y Bing.com.

7. En la pestaña Publicación de inquilinos, revise la configuración y agregue información de publicación.

   1. Revise el nombre del proveedor de búsquedas y las consultas de ejemplo. Vuelva a las pestañas anteriores para cambiar esta información, si es necesario.
   2. Escriba una descripción del proveedor de búsquedas.
   3. Introduzca un correo electrónico de contacto de soporte técnico. Use el correo electrónico de un desarrollador o grupo de desarrolladores que tenga acceso al proveedor de búsquedas.

8. Seleccione Agregar para solicitar la aprobación del administrador de TI.

Aprobación de un proveedor de búsquedas en un inquilino

El administrador de TI realiza la aprobación del proveedor de búsqueda en el inquilino en la página Search & Intelligence del Centro de administración de Microsoft 365.

Comprobación de la conexión

Se recomienda habilitar el proveedor de búsquedas en un inquilino de prueba antes de habilitarlo en producción.

Modificación de un proveedor de búsquedas

Puede editar el proveedor de búsquedas antes de enviarlo para su revisión por parte del administrador de TI. Es posible que tenga que hacerlo si se rechaza la solicitud inicial o se desactiva el servicio.

1. En Azure Portal, vaya al recurso de bot que contiene el proveedor de búsquedas que desea editar.
2. Vaya al panel Canales (Vista previa).
3. Seleccione el canal de Búsqueda y seleccione Editar.
   1. Azure muestra el panel Canal de búsqueda. En este panel, puede editar la configuración.
   2. Para modificar las frases desencadenadoras, descargue el archivo, edítelo localmente y cárguelo.
   3. Una vez finalizadas las modificaciones, seleccione Agregar de nuevo para enviar el proveedor de búsquedas para su revisión por parte del administrador de TI.

Eliminación de un proveedor de búsquedas

El proveedor de búsquedas se eliminará si quita el canal de búsqueda del recurso del bot.

Para quitar el canal de búsqueda del bot:

1. En Azure Portal, vaya al recurso de bot.
2. Vaya al panel Canales (Vista previa).
3. Seleccione el canal Buscar.
4. En la parte superior del panel Canal de búsqueda, seleccione Eliminar canal.
5. Para confirmar la operación, seleccione Sí.

Para eliminar el recurso de bot:

1. En Azure Portal, vaya al recurso de bot.
2. Si aún no lo ha hecho, elimine el canal de búsqueda del bot.
3. En la parte superior del panel Información general, seleccione Eliminar.
4. Seleccione Aceptar para confirmar la operación.

Información adicional

El canal de búsqueda usa la búsqueda federada y el esquema de tarjetas adaptables:

Para obtener más información sobre el esquema de tarjeta adaptable, consulte Tarjetas adaptables para desarrollo de bots.

Acerca de las frases desencadenadoras

Una frase desencadenadora es una frase que la plataforma de búsqueda usa para enrutar una consulta al proveedor de búsquedas personalizado con tecnología del bot. La búsqueda federada reenvía la expresión de un usuario al proveedor de búsquedas cuando la expresión es una coincidencia cercana a una de las frases desencadenadoras.

Sugerencia

Si hay más de un proveedor de búsquedas disponible, la búsqueda federada elige solo una, en función de las frases desencadenadoras proporcionadas y la consulta del usuario.

Por ejemplo, piense en un bot que administra los horarios y estado de los vuelos.

1. Piense en algunas formas comunes que un usuario haría referencia al bot o lo usaría. Asegúrese de distinguir el bot de otros usuarios.

   En lugar de un término genérico, como "horario" que se puede aplicar a escuelas y programas de TV, use frases más específicas, como "tabla de horarios de vuelos" y "programación de vuelos".

2. Incluya diversas frases que cubran el ámbito de las características del bot, como la hora de salida y el estado actual.

   Por ejemplo, incluya consultas sobre: horas de llegada o salida y aeropuertos.

Las frases desencadenadoras para este tipo de bot de programación y estado de vuelos pueden incluir:

• Horarios de vuelos
• Estado de vuelos
• Hora de salida del vuelo 675
• ¿Cuándo sale mi vuelo?
• Hora de llegada del vuelo 468
• Estado del vuelo de Seattle Tacoma
• Estado del vuelo de Heathrow

Como otro ejemplo, las frases desencadenadoras de un bot de previsión meteorológica pueden incluir:

• Previsión meteorológica local
• Información meteorológica
• El tiempo de mañana
• Previsión meteorológica para 10 días
• Máxima de hoy
• La probabilidad de lluvia de hoy
• ¿Nevará mañana?
• Velocidad del viento mañana
• ¿Hace viento afuera?
• Tiempo en Londres

Elementos de tarjeta adaptable admitidos

Se admite un subconjunto del esquema de tarjeta adaptable en la búsqueda federada. Para obtener información sobre cómo aplicar formato a los resultados de búsqueda, consulte Personalización de la página de resultados de búsqueda.

La compatibilidad incluye los siguientes elementos de tarjeta adaptable: TextBlock, RichTextBlock, Image, ColumnSet, ImageSet y FactSet. Para obtener más información, consulte administración de diseños de resultados de búsqueda de la Búsqueda de Microsoft y el Explorador de esquemas de tarjetas adaptables.

Puede crear cada tarjeta directamente como JSON o puede usar el paquete NuGet de AdaptiveCards.

La búsqueda federada no admite HTML

Importante

La búsqueda federada no representará texto de tarjeta adaptable que contenga HTML.

La plataforma de búsqueda no incluye un analizador HTML. Sin embargo, puede eliminar algunas de las etiquetas y utilizar el paquete NuGet Html2Markdown para convertir HTML a Markdown:

1. Quite los elementos <span> y <u>.
2. Reemplace los elementos <div> y <br> por los elementos de párrafo (<p>).
3. Convierta el código HTML restante en Markdown.

Pasos siguientes

• Para obtener información sobre la compatibilidad de canales en el servicio de conector del bot, consulta Conectar un bot a canales.
• Para obtener información sobre cómo compilar bots, consulte Cómo funcionan los bots y el inicio rápido Creación de un bot con Bot Framework SDK.
• Para obtener información sobre la implementación de bots, consulte Implementación del bot y Configuración de la implementación continua.