Definición de comandos de búsqueda de extensión de mensaje

Importante

Los ejemplos de código de esta sección se basan en las versiones 4.6 y posteriores del SDK de Bot Framework. Si busca documentación para versiones anteriores, consulte la sección Extensiones de mensaje - SDK v3 en la carpeta Recursos de la documentación.

Los comandos de búsqueda de extensión de mensaje permiten a los usuarios buscar sistemas externos e insertar los resultados de esa búsqueda en un mensaje en forma de tarjeta. Este documento le guía sobre cómo seleccionar ubicaciones de invocación de comandos de búsqueda y agregar el comando de búsqueda al manifiesto de la aplicación.

Nota:

El límite de tamaño de la tarjeta de resultados es de 28 KB. La tarjeta no se envía si su tamaño supera los 28 KB.

Vea el siguiente vídeo para obtener información sobre cómo definir comandos de búsqueda de extensión de mensaje:


Selección de ubicaciones de invocación de comandos de búsqueda

El comando de búsqueda se invoca desde cualquiera de las siguientes ubicaciones o desde ambas:

  • Área redactar mensaje: los botones de la parte inferior del área de redacción del mensaje.
  • Cuadro de comando: por @mentioning en el cuadro de comando.

Cuando se invoca un comando de búsqueda desde el área del mensaje de redacción, el usuario envía los resultados a la conversación. Cuando se invoca desde el cuadro de comandos, el usuario interactúa con la tarjeta resultante o la copia para usarla en otro lugar.

En la imagen siguiente se muestran las ubicaciones de invocación del comando de búsqueda:

Captura de pantalla que muestra las ubicaciones de invocación de un comando de búsqueda en un canal de Teams.

Agregar el comando de búsqueda al manifiesto de la aplicación

Para agregar el comando de búsqueda al manifiesto de la aplicación, debe agregar un nuevo composeExtension objeto al nivel superior del JSON del manifiesto de la aplicación. Puede agregar el comando de búsqueda con la ayuda del Portal para desarrolladores o manualmente.

Creación de un comando de búsqueda mediante el Portal para desarrolladores

El requisito previo para crear un comando de búsqueda es que ya debe haber creado una extensión de mensaje. Para obtener información sobre cómo crear una extensión de mensaje, vea crear una extensión de mensaje.

Para crear un comando de acción

  1. Abra el Portal para desarrolladores en el cliente Microsoft Teams y seleccione la pestaña Aplicaciones. Si ya ha creado el paquete de la aplicación en el Portal para desarrolladores, seleccione en la lista. Si no ha creado un paquete de aplicación, importe uno existente.

  2. Después de importar un paquete de aplicación, seleccione Extensiones de mensaje en Características de la aplicación.

  3. Para crear una extensión de mensaje, necesita un bot registrado de Microsoft. Puede usar un bot existente o crear uno nuevo. Seleccione la opción Crear nuevo bot , asigne un nombre al nuevo bot y, a continuación, seleccione Crear.

    Captura de pantalla que muestra las opciones para configurar un bot para una aplicación en el Portal para desarrolladores de Teams.

  4. Para usar un bot existente, seleccione Seleccionar un bot existente y elija los bots existentes en la lista desplegable o escriba un identificador de bot si ya tiene un identificador de bot creado.

  5. Seleccione el ámbito de la extensión de mensajería y seleccione Guardar.

  6. Seleccione Agregar un comando en la sección Comando para incluir los comandos, que deciden el comportamiento de la extensión de mensaje. En la imagen siguiente se muestra la adición de comandos para la extensión de mensaje:

    Captura de pantalla que muestra cómo agregar un comando en el Portal para desarrolladores de Teams para definir el comportamiento de la extensión de mensaje.

  7. Seleccione Buscar y escriba Id. de comando, Título de comando y Descripción del comando.

  8. Escriba todos los parámetros y seleccione el tipo de entrada en la lista desplegable.

    Captura de pantalla que muestra cómo agregar un parámetro para definir el comando en el Portal para desarrolladores de Teams para una extensión de mensaje.

  9. Seleccione Agregar un dominio en Vínculos de vista previa.

  10. Escriba dominio válido y, a continuación, seleccione Agregar.

    Captura de pantalla que muestra cómo agregar un dominio válido a la extensión de mensajería para la desplegamiento de vínculos.

  11. Seleccione Guardar.

    Captura de pantalla que muestra cómo guardar toda la configuración y los parámetros de la extensión de mensaje.

Para agregar parámetros adicionales

  1. Seleccione elipse en la sección de comandos y, a continuación, seleccione Editar parámetro.

    Capturas de pantalla que muestran cómo editar parámetros para la extensión de mensaje.

  2. Seleccione Agregar parámetros y escriba todos los parámetros.

    Captura de pantalla que muestra cómo agregar parámetros adicionales para la extensión de mensaje.

Creación manual de un comando de búsqueda

Para agregar manualmente el comando de búsqueda de extensión de mensaje al manifiesto de la aplicación, debe agregar los parámetros siguientes a composeExtension.commands la matriz de objetos:

Nombre de propiedad Objetivo ¿Necesario? Versión mínima del manifiesto
id Esta propiedad es un identificador único que se asigna al comando de búsqueda. La solicitud de usuario incluye este id. 1.0
title Esta propiedad es un nombre de comando. Este valor aparece en la interfaz de usuario (UI). 1.0
description Esta propiedad es un texto de ayuda que indica lo que hace este comando. Este valor aparece en la interfaz de usuario. 1.0
type Esta propiedad debe ser .query No 1.4
initialRun Si esta propiedad se establece en true, indica que este comando debe ejecutarse en cuanto el usuario seleccione este comando en la interfaz de usuario. No 1.0
context Esta propiedad es una matriz opcional de valores que define el contexto en el que está disponible la acción de búsqueda. Los valores posibles sonmessage, compose o commandBox. El valor predeterminado es ["compose", "commandBox"]. No 1,5

Debe agregar los detalles del parámetro de búsqueda que define el texto visible para el usuario en el cliente de Teams.

Nombre de propiedad Objetivo ¿Es obligatoria? Versión mínima del manifiesto
parameters Esta propiedad define una lista estática de parámetros para el comando. No 1.0
parameter.name Esta propiedad describe el nombre del parámetro. parameter.name se envía al servicio en la solicitud del usuario. 1.0
parameter.description Esta propiedad describe los propósitos del parámetro o el ejemplo del valor que se debe proporcionar. Este valor aparece en la interfaz de usuario. 1.0
parameter.title Esta propiedad es un título o etiqueta de parámetro descriptivo corto. 1.0
parameter.inputType Esta propiedad se establece en el tipo de entrada necesaria. Entre los valores posibles se incluyen , , , , , toggletime. datenumbertextareatext El valor predeterminado está establecido en text. No 1.4
parameters.value Valor inicial del parámetro. Actualmente no se admite el valor No 1,5

Ejemplo

En la sección siguiente se muestra un ejemplo del manifiesto de aplicación simple del composeExtensions objeto que define un comando de búsqueda:

{
...
  "composeExtensions": [
    {
      "botId": "57a3c29f-1fc5-4d97-a142-35bb662b7b23",
      "canUpdateConfiguration": true,
      "commands": [{
          "id": "searchCmd",
          "description": "Search Bing for information on the web",
          "title": "Search",
          "initialRun": true,
          "parameters": [{
            "name": "searchKeyword",
            "description": "Enter your search keywords",
            "title": "Keywords"
          }]
        }
      ]
    }
  ],
...
}

Para ver el manifiesto de aplicación completo, consulte Esquema de manifiesto de aplicación.

Ejemplo de código

Ejemplo de nombre Descripción .NET Node.js
Búsqueda de extensión de mensaje de Teams Describe cómo definir comandos de búsqueda y responder a búsquedas. View View

Guía paso a paso

Siga la guía paso a paso para crear una extensión de mensaje basada en búsquedas.

Paso siguiente

Vea también