Compartir a través de

Responder a consultas de comandos de búsqueda

  • Artículo

Importante

Los ejemplos de código de esta sección se basan en la versión 4.6 y versiones 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.

Una vez que el usuario envía el comando de búsqueda, el servicio web recibe un composeExtension/query mensaje de invocación que contiene un value objeto con los parámetros de búsqueda. La invocación se desencadena con las condiciones siguientes:

  • A medida que los caracteres se escriben en el cuadro de búsqueda.
  • initialRun se establece en true en el manifiesto de la aplicación y recibe el mensaje de invocación en cuanto se invoca el comando de búsqueda. Para obtener más información, consulte consulta predeterminada.

Este documento le guía sobre cómo responder a las solicitudes de usuario en forma de tarjetas y vistas previas, y las condiciones en las que Microsoft Teams emite una consulta predeterminada.

Los parámetros de solicitud se encuentran en el value objeto de la solicitud, que incluye las siguientes propiedades:

Nombre de propiedad Objetivo
commandId Nombre del comando invocado por el usuario, que coincide con uno de los comandos declarados en el manifiesto de la aplicación.
parameters Matriz de parámetros. Cada objeto de parámetro contiene el nombre del parámetro, junto con el valor de parámetro proporcionado por el usuario.
queryOptions Parámetros de paginación:
skip: omitir el recuento de esta consulta
count: número de elementos que se van a devolver.		 
protected override async Task<MessagingExtensionResponse> OnTeamsMessagingExtensionQueryAsync(ITurnContext<IInvokeActivity> turnContext, MessagingExtensionQuery query, CancellationToken cancellationToken)
{
  // Code to handle the query.
}

Respuesta a las solicitudes de usuario

Cuando el usuario realiza una consulta, Microsoft Teams emite una solicitud HTTP sincrónica al servicio. En ese momento, el código tiene 5 segundos para proporcionar una respuesta HTTP a la solicitud. Durante este tiempo, el servicio puede realizar más búsquedas o cualquier otra lógica de negocios necesaria para atender la solicitud.

El servicio debe responder con los resultados que coincidan con la consulta del usuario. La respuesta debe indicar un código de estado HTTP de 200 OK y una aplicación o un objeto JSON válidos con las siguientes propiedades:

Nombre de propiedad Objetivo
composeExtension Sobre de respuesta de nivel superior.
composeExtension.type Tipo de respuesta. Se admiten los tipos siguientes:
result: muestra una lista de resultados de búsqueda
auth: solicita al usuario que se autentique
config: solicita al usuario que configure la extensión de mensaje.
message: muestra un mensaje de texto sin formato
composeExtension.attachmentLayout Especifica el diseño de los datos adjuntos. Se usa para respuestas de tipo result.
Se admiten los tipos siguientes:
list: lista de objetos de tarjeta que contienen campos de miniatura, título y texto
grid: una cuadrícula de imágenes en miniatura
composeExtension.attachments Matriz de objetos de datos adjuntos válidos. Se usa para respuestas de tipo result.
Se admiten los tipos siguientes:
application/vnd.microsoft.card.thumbnail
application/vnd.microsoft.card.hero
application/vnd.microsoft.teams.card.o365connector
application/vnd.microsoft.card.adaptive
composeExtension.suggestedActions Acciones sugeridas. Se usa para respuestas de tipo auth o config.
composeExtension.text Mensaje que se va a mostrar. Se usa para respuestas de tipo message.

Respuesta de configuración

La respuesta de configuración son los datos devueltos por el servidor o la aplicación para configurar y habilitar la extensión de mensaje dentro de la plataforma de mensajería. El código siguiente es un ejemplo para la configuración de la extensión de mensaje:

{
    "name": "composeExtension/submitAction",
    "type": "invoke",
    "timestamp": "2024-03-08T14:10:47.575Z",
    "localTimestamp": "2024-03-08T19:40:47.575+05:30",
    "id": "f:7dfe18de-94e3-9f38-5d44-adeb31cd8243",
    "channelId": "msteams",
    "serviceUrl": "https://smba.trafficmanager.net/amer/",
    "from": {
        "id": "29:1PBlnIsEROUYzpFjULDVodMHrnpujmfhBdQAf0pcO1EkaDkhI0_Pj_ql-jZUYOGdSc3_KcqaIIjzbleraVJ2Z3g",
        "name": "MOD Administrator",
        "aadObjectId": "ce9def33-d7fc-444c-8728-be1f95e6b6f2"
    },
    "conversation": {
        "isGroup": true,
        "conversationType": "groupChat",
        "tenantId": "4ad59956-0f88-4b88-a9d0-570b6eb4e66b",
        "id": "19:1dd50ba7-e5bd-46ea-b34e-80a415148de7_ce9def33-d7fc-444c-8728-be1f95e6b6f2@unq.gbl.spaces"
    },
    "recipient": {
        "id": "28:9a2b01fc-88c1-40e1-bf87-5079c8e35626",
        "name": "PSDAzureBot"
    },
    "entities": [
        {
            "locale": "en-GB",
            "country": "GB",
            "platform": "Web",
            "timezone": "Asia/Calcutta",
            "type": "clientInfo"
        }
    ],
    "channelData": {
        "tenant": {
            "id": "4ad59956-0f88-4b88-a9d0-570b6eb4e66b"
        },
        "source": {
            "name": "compose"
        }
    },
    "value": {
        "commandId": "razorView",
        "commandContext": "compose",
        "data": {
            "Title": "Welcome to RazorView!",
            "DisplayData": " Today&#x27;s date is 8-3-2024, Friday"
        },
        "context": {
            "theme": "default"
        }
    },
    "locale": "en-GB",
    "localTimezone": "Asia/Calcutta"
}

La siguiente respuesta es la respuesta de configuración que aparece cuando el usuario interactúa con la extensión de redacción:

{
    "composeExtension": {
        "type": "config",
        "suggestedActions": {
            "actions": [
                {
                    "type": "openUrl",
                    "value": "https://7a03-2405-201-a00c-7191-b472-ff64-112d-f806.ngrok-free.app"
                }
            ]
        }
    }
}

En la captura de pantalla se muestra la respuesta de configuración de la extensión de mensaje.

Tipos y vistas previas de tarjetas de respuesta

Nota:

Los resultados de búsqueda de la extensión de mensaje no admiten el relleno.

Teams admite los siguientes tipos de tarjetas:

Para tener una mejor comprensión e información general sobre las tarjetas, vea qué son las tarjetas.

Para obtener información sobre cómo usar los tipos de miniaturas y tarjetas principales, consulte Agregar tarjetas y acciones de tarjeta.

Para obtener más información sobre la tarjeta del conector para grupos de Microsoft 365, consulte Uso de tarjetas de conector para grupos de Microsoft 365.

La lista de resultados se muestra en la interfaz de usuario de Microsoft Teams con una vista previa de cada elemento. La vista previa se genera de una de las dos maneras siguientes:

  • Uso de la preview propiedad dentro del attachment objeto . Los preview datos adjuntos solo pueden ser un héroe o una tarjeta en miniatura.
  • Extracción de las propiedades básicas title, texty image del attachment objeto . Las propiedades básicas solo se usan si no se especifica la preview propiedad .

En el caso de la tarjeta Hero o Thumbnail, excepto la acción de invocación, no se admiten otras acciones, como el botón y la pulsación, en la tarjeta de vista previa.

Para enviar una tarjeta adaptable o una tarjeta de conector para grupos de Microsoft 365, debe incluir una versión preliminar. La preview propiedad debe ser una tarjeta hero o thumbnail. Si no especifica la propiedad preview en el attachment objeto, no se genera una vista previa.

En el caso de las tarjetas hero y thumbnail, no es necesario especificar una propiedad de vista previa; de forma predeterminada, se genera una vista previa.

Ejemplo de respuesta

protected override async Task<MessagingExtensionResponse> OnTeamsMessagingExtensionQueryAsync(ITurnContext<IInvokeActivity> turnContext, MessagingExtensionQuery query, CancellationToken cancellationToken) 
{
  var text = query?.Parameters?[0]?.Value as string ?? string.Empty;

  // Searches NuGet for a package.
  var obj = JObject.Parse(await (new HttpClient()).GetStringAsync($"https://azuresearch-usnc.nuget.org/query?q=id:{text}&prerelease=true"));
  var packages = obj["data"].Select(item => (item["id"].ToString(), item["version"].ToString(), item["description"].ToString()));

  // We take every row of the results and wrap them in cards wrapped in in MessagingExtensionAttachment objects.
  // The Preview is optional, if it includes a Tap, that will trigger the OnTeamsMessagingExtensionSelectItemAsync event back on this bot.
  var attachments = packages.Select(package => new MessagingExtensionAttachment
      {
          ContentType = HeroCard.ContentType,
          Content = new HeroCard { Title = package.Item1 },
          Preview = new HeroCard { Title = package.Item1, Tap = new CardAction { Type = "invoke", Value = package } }.ToAttachment()
      })
      .ToList();

  // The list of MessagingExtensionAttachments must we wrapped in a MessagingExtensionResult wrapped in a MessagingExtensionResponse.
  return new MessagingExtensionResponse
  {
      ComposeExtension = new MessagingExtensionResult
      {
          Type = "result",
          AttachmentLayout = "list",
          Attachments = attachments
      }
  };
}

Habilitación y control de acciones de pulsación

protected override Task<MessagingExtensionResponse> OnTeamsMessagingExtensionSelectItemAsync(ITurnContext<IInvokeActivity> turnContext, JObject query, CancellationToken cancellationToken)
{
    // The Preview card's Tap should have a Value property assigned, this will be returned to the bot in this event.
    var (packageId, version, description, projectUrl, iconUrl) = query.ToObject<(string, string, string, string, string)>();

    var card = new ThumbnailCard
    {
        Title = "Card Select Item",
        Subtitle = description
    };

    var attachment = new MessagingExtensionAttachment
    {
        ContentType = ThumbnailCard.ContentType,
        Content = card,
    };

    return Task.FromResult(new MessagingExtensionResponse
    {
        ComposeExtension = new MessagingExtensionResult
        {
            Type = "result",
            AttachmentLayout = "list",
            Attachments = new List<MessagingExtensionAttachment> { attachment }
        }
    });
}

Consulta predeterminada

Si establece initialRuntrue en en el manifiesto, Microsoft Teams emite una consulta predeterminada cuando el usuario abre por primera vez la extensión de mensaje. El servicio puede responder a esta consulta con un conjunto de resultados rellenados previamente. Esto resulta útil cuando el comando de búsqueda requiere autenticación o configuración, y muestra elementos, favoritos o cualquier otra información que no dependa de la entrada del usuario.

La consulta predeterminada tiene la misma estructura que cualquier consulta de usuario normal, con el name campo establecido initialRun en y value establecido true en como se muestra en el objeto siguiente:

{
  "type": "invoke",
  "name": "composeExtension/query",
  "value": {
    "commandId": "searchCmd",
    "parameters": [
      {
        "name": "initialRun",
        "value": "true"
      }
    ],
    "queryOptions": {
      "skip": 0,
      "count": 25
    }
  },
  ⋮
}

Ejemplo de código

Ejemplo de nombre Descripción .NET Node.js Manifiesto
Búsqueda de extensión de mensaje de Teams En este ejemplo se muestra cómo crear una extensión de mensaje basada en búsqueda. Busca paquetes nudget y muestra los resultados en la extensión de mensajería basada en búsquedas. View View View
Autenticación y configuración de la extensión de mensaje de Teams En este ejemplo se muestra una extensión de mensaje que tiene una página de configuración, acepta solicitudes de búsqueda y devuelve resultados después de que el usuario inicie sesión. También muestra cero vínculo de instalación de aplicaciones desplegada junto con la desplegamiento normal de vínculos View View View

Paso siguiente

Adición de autenticación de terceros a la extensión de mensaje

Vea también