Conectar un bot para buscar (versión preliminar)

En este artículo se describe cómo crear un proveedor de búsqueda federado personalizado (power by el bot) y conectarlo al canal de búsqueda. Una vez que el Administrador de inquilinos habilita el proveedor en su inquilino, el usuario empresarial busca, desde Office.com, SharePoint.com y Bing.com, puede incluir resultados de su proveedor de búsqueda personalizado.

La Plataforma de búsqueda federada de Microsoft permite crear proveedores de búsqueda federados personalizados para permitir que la información participe en las experiencias verticales de respuestas & 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 de federación de Dynamics 365 (versión preliminar).

Nota

El canal de búsqueda está en versión preliminar privada. Para solicitar acceso, use el formulario Búsqueda de Microsoft Developer Private Preview. 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 más adelante en este artículo.

  1. Implemente el bot para que funcione como proveedor de búsqueda.
  2. Si el bot requerirá que los usuarios inicien sesión:
    1. En el 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úsqueda en un inquilino de prueba antes de habilitarlo en producción.

Requisitos previos

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.

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 puede 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 Azure AD 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. Si aún no tiene un recurso de bot, cree un recurso de Azure Bot.
  3. Vaya al servicio Azure Active Directory.
  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 nombre de ámbito.
    3. Por Quién puede dar su consentimiento, se prefieren administradores 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, escriba un nombre para mostrar de consentimiento del usuario y una descripción del consentimiento del usuario.
    6. Compruebe que State está establecido en Habilitado.
    7. Seleccione la opción Agregar un ámbito.
  8. Seleccione Agregar una aplicación cliente.
    1. En el panel Agregar una aplicación cliente , establezca Id.81473081-50b9-469a-b9d8-303109583ecbde cliente en , el identificador 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 una aplicación.
  9. Vaya al panel Información general . Copie el URI del identificador de 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 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 de los datos del traceId canal para obtener el identificador de seguimiento.

En el ejemplo de búsqueda federada, el SearchHelper.GetSearchTraceId método 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 de los datos del authorizations canal puede contener una lista de tokens de autenticación. Si expone la API de bot a La búsqueda, la lista contendrá el token en nombre de . El token de la lista tendrá la estructura siguiente:

Nombre de propiedad Tipo Descripción
authType integer El tipo de token de autenticación: 0 para desconocido o predeterminado, o 2 para el token en nombre de .
token string Token de autenticación en sí.

En el ejemplo de búsqueda federada:

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

Una vez que tenga el token, puede usarlo al solicitar cualquier recurso protegido para el usuario. Para obtener información sobre el uso de tokens en nombre de , consulte flujo en nombre de Plataforma de identidad de Microsoft y OAuth 2.0 on-Behalf-Of.

Consulta de cada almacén de datos

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

Nombre de propiedad Tipo 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 Índice del primer resultado que se va a enviar.
queryOptions.top integer Número máximo de resultados que se van a enviar.

Los resultados de búsqueda se devuelven en la respuesta de invocación:

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

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

    Nombre de propiedad Tipo Descripción
    statusCode integer Código de estado HTTP usado para indicar si el bot pudo ejecutar correctamente la consulta.
    type string 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 obtener un mensaje de error.
    value object Valor que corresponde al valor type.

    Para los mensajes de error, el value objeto contiene:

    Nombre de propiedad Tipo Descripción
    código string Código de error definido por el bot o null si no se especifica.
    message string Mensaje de error o null si no se especifica.

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

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

    Los objetos de resultado de búsqueda contienen:

    Nombre de propiedad Tipo Descripción
    value string Identificador o valor único para este resultado de búsqueda.
    layoutId string Identificador del diseño de presentación que se va a usar para este resultado.
    data.searchResultText string Texto de este resultado.

    Los objetos de diseño de pantalla contienen:

    Nombre de propiedad Tipo Descripción
    layoutId string Identificador de diseño.
    layoutBody string Cuerpo del diseño como un objeto JSON de tarjetas adaptables.

En el ejemplo de búsqueda federada, el SearchHelper.RunFederatedSearch método 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.

Registro del 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.

Las instrucciones siguientes muestran cómo conectar un bot a La búsqueda.

Sugerencia

Se recomienda habilitar el proveedor de búsqueda 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 (versión preliminar).

  4. Seleccione Search.

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

    Sample of the Search Settings tab

    1. En Metadatos del proveedor de búsqueda, escriba el nombre que se va a mostrar en la interfaz de usuario de búsqueda.

    2. En Frases de desencadenador, 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).

      • Upload un .csv archivo que contiene las frases. El archivo debe contener una columna de datos, sin encabezados.
      • En la lista Preferencias de idioma , seleccione el idioma en el que se escriben las frases del desencadenador.
    3. En Autenticación, indique si el proveedor de búsqueda requiere autenticación de usuario.

      • Si se requiere autenticación, escriba la dirección URL de autenticación. Use el URI del identificador de aplicación que copió al exponer la API del bot.
    4. Seleccione Next (Siguiente).

  6. En la pestaña Verticales , si desea que los resultados del proveedor de búsqueda aparezcan en su propio vertical personalizado en la página de resultados de búsqueda, escriba el nombre 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úsqueda y las consultas de ejemplo. Volver a las pestañas anteriores para cambiar esta información, si es necesario.
    2. Escriba una descripción del proveedor de búsqueda.
    3. Escriba 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úsqueda.
  8. Seleccione Agregar para solicitar la aprobación del administrador de TI.

Aprobación de un proveedor de búsqueda 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úsqueda en un inquilino de prueba antes de habilitarlo en producción.

Modificación de un proveedor de búsqueda

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

  1. En el Azure Portal, vaya al recurso del bot que contiene el proveedor de búsqueda que desea editar.
  2. Vaya al panel Canales (versión preliminar).
  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 desencadenadores, descargue el archivo, edítelo localmente y cargue el archivo.
    3. Una vez finalizadas las ediciones, seleccione Agregar de nuevo para enviar el proveedor de búsqueda para que lo revise el administrador de TI.

Eliminación de un proveedor de búsqueda

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

Para quitar el canal de búsqueda del bot:

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

Para eliminar el recurso del bot:

  1. En el Azure Portal, vaya al recurso del bot.
  2. Si aún no lo ha hecho, quite el canal de búsqueda del bot.
  3. En la parte superior del panel Información general, seleccione Eliminar.
  4. Haga clic en 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 desarrolladores de bots.

Acerca de las frases de desencadenador

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

Sugerencia

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

Por ejemplo, piense en un bot que administra las programaciones de vuelos y el estado.

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

    En lugar de un término genérico, como "calendario" que se puede aplicar a escuelas y programas de TELEVISIÓN, use frases más específicas, como "tabla de tiempo de vuelo" y "programación de vuelos".

  2. Incluya frases diversas 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 de desencadenador para este tipo de programación de vuelos y bot de estado pueden incluir:

  • Calendario de vuelos
  • Estado del vuelo
  • 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 de desencadenador 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 de 10 días
  • Hoy es alto
  • Probabilidad de lluvia de hoy
  • ¿Va a nieve mañana?
  • Velocidad del viento mañana
  • Es 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 dar 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, vea Administrar diseños de resultados de búsqueda de Búsqueda de Microsoft y el Explorador de esquemas de tarjetas adaptables.

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

La búsqueda federada no admite HTML

Importante

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

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

  1. Quitar <span> elementos y <u> .
  2. Reemplace <div> los elementos y <br> por los elementos de párrafo (<p>).
  3. Convierta el html restante en Markdown.

Pasos siguientes