Responder a consultas de comandos de búsqueda

Artículo
03/26/2024

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.
}

Referencia de código de ejemplo

class TeamsMessagingExtensionsSearch extends TeamsActivityHandler {
    async handleTeamsMessagingExtensionQuery(context, query) {
  // Code to handle the query.
    }
}

El siguiente JSON se abrevia para resaltar las secciones más relevantes.

{
  "type": "invoke",
  "name": "composeExtension/query",
  "value": {
    "commandId": "searchCmd",
    "parameters": [
      {
        "name": "searchKeywords",
        "value": "Toronto"
      }
    ],
    "queryOptions": {
      "skip": 0,
      "count": 25
    }
  },
...
}

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 búsquedas adicionales 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`. Actualmente, se admiten los siguientes tipos: `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`. Actualmente, se admiten los siguientes tipos: `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

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
      }
  };
}

Referencia de código de ejemplo

class TeamsMessagingExtensionsSearchBot extends TeamsActivityHandler {
    async handleTeamsMessagingExtensionQuery(context, query) {
        const searchQuery = query.parameters[0].value;
        const response = await axios.get(`http://registry.npmjs.com/-/v1/search?${ querystring.stringify({ text: searchQuery, size: 8 }) }`);

        const attachments = [];
        response.data.objects.forEach(obj => {
            const heroCard = CardFactory.heroCard(obj.package.name);
            const preview = CardFactory.heroCard(obj.package.name);
            const attachment = { ...heroCard, preview };
            attachments.push(attachment);
        });

        return {
            composeExtension: {
                type: 'result',
                attachmentLayout: 'list',
                attachments: attachments
            }
        };
    }
}

{
  "composeExtension": {
    "type": "result",
    "attachmentLayout": "list",
    "attachments": [
      {
        "contentType": "application/vnd.microsoft.teams.card.o365connector",
        "content": {
          "sections": [
            {
              "activityTitle": "[85069]: Create a cool app",
              "activityImage": "https://placekitten.com/200/200"
            },
            {
              "title": "Details",
              "facts": [
                {
                  "name": "Assigned to:",
                  "value": "[Larry Brown](mailto:larryb@example.com)"
                },
                {
                  "name": "State:",
                  "value": "Active"
                }
              ]
            }
          ]
        },
        "preview": {
          "contentType": "application/vnd.microsoft.card.thumbnail",
          "content": {
            "title": "85069: Create a cool app",
            "images": [
              {
                "url": "https://placekitten.com/200/200"
              }
            ]
          }
        }
      },
      {
        "contentType": "application/vnd.microsoft.card.adaptive",
        "content": {
          "type": "AdaptiveCard",
          "body": [
            {
              "type": "Container",
              "items": [
                {
                  "type": "TextBlock",
                  "text": "Microsoft Corp (NASDAQ: MSFT)",
                  "size": "medium",
                  "isSubtle": true
                },
                {
                  "type": "TextBlock",
                  "text": "September 19, 4:00 PM EST",
                  "isSubtle": true
                }
              ]
            },
            {
              "type": "Container",
              "spacing": "none",
              "items": [
                {
                  "type": "ColumnSet",
                  "columns": [
                    {
                      "type": "Column",
                      "width": "stretch",
                      "items": [
                        {
                          "type": "TextBlock",
                          "text": "75.30",
                          "size": "extraLarge"
                        },
                        {
                          "type": "TextBlock",
                          "text": "▼ 0.20 (0.32%)",
                          "size": "small",
                          "color": "attention",
                          "spacing": "none"
                        }
                      ]
                    },
                    {
                      "type": "Column",
                      "width": "auto",
                      "items": [
                        {
                          "type": "FactSet",
                          "facts": [
                            {
                              "title": "Open",
                              "value": "62.24"
                            },
                            {
                              "title": "High",
                              "value": "62.98"
                            },
                            {
                              "title": "Low",
                              "value": "62.20"
                            }
                          ]
                        }
                      ]
                    }
                  ]
                }
              ]
            }
          ],
          "version": "1.0"
        },
        "preview": {
          "contentType": "application/vnd.microsoft.card.thumbnail",
          "content": {
            "title": "Microsoft Corp (NASDAQ: MSFT)",
            "text": "75.30 ▼ 0.20 (0.32%)"
          }
        }
      }
    ]
  }
}

Habilitación y control de acciones de pulsación

Referencia de código de ejemplo

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 }
        }
    });
}

Referencia de código de ejemplo

async handleTeamsMessagingExtensionSelectItem(context, obj) {
        return {
            composeExtension: {
                  type: 'result',
                  attachmentLayout: 'list',
                  attachments: [CardFactory.thumbnailCard(obj.Item3)]
            }
        };
    }

{
    "name": "composeExtension/selectItem",
    "type": "invoke",
    "value": {
        "Item1": "Package_Name",
        "Item2": "Version",
        "Item3": "Package Description"
    },
    .
    .
    .
}

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 los resultados después de que el usuario haya iniciado 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