Devolver datos del producto de Microsoft Entra API protegida

Completado

En esta unidad, aprenderá a devolver datos de una API en una respuesta de extensión de mensaje basada en búsqueda.

Control de consultas de búsqueda

Cuando un usuario escribe una consulta de búsqueda, el servicio bot envía una solicitud al punto de conexión de la extensión de mensajería. La solicitud contiene la consulta de búsqueda especificada por el usuario. Use la consulta de búsqueda para buscar datos en un sistema externo, que se puede usar en los resultados de la búsqueda.

Tiene acceso a la consulta de búsqueda especificada por el usuario mediante la propiedad Query del objeto MessagingExtensionQuery en el método OnTeamsMessagingExtensionQueryAsync . La propiedad Parameters del objeto MessagingExtensionQuery contiene los parámetros que se pasaron a la extensión de mensajería cuando se invocó. La propiedad Parameters es una lista de pares clave-valor que contiene el nombre y el valor de cada parámetro.

Plantillas de tarjeta adaptable

Una tarjeta adaptable es un formato declarativo para crear componentes de interfaz de usuario independientes de la plataforma, que proporcionan una experiencia de usuario coherente en diferentes plataformas y dispositivos.

Las plantillas de tarjeta adaptable son archivos JSON que definen la estructura de una tarjeta adaptable. El uso de plantillas de tarjeta adaptable permite definir la estructura de la tarjeta en un archivo independiente y enlazar datos a la tarjeta en tiempo de ejecución.

Las plantillas de tarjeta adaptable se usan para crear el contenido de los resultados de búsqueda insertados en el área de redacción de mensajes cuando el usuario selecciona un resultado de búsqueda.

El siguiente fragmento de código muestra un ejemplo básico de una plantilla de tarjeta adaptable:

{
  "type": "AdaptiveCard",
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "version": "1.5",
  "body": [
    {
      "type": "TextBlock",
      "text": "${name}",
      "wrap": true,
      "style": "heading"
    }
  ]
}

Las plantillas de tarjeta adaptable usan enlaces rápidos para enlazar datos a la tarjeta. El método Expand del objeto AdaptiveCardTemplate se usa para enlazar datos a la tarjeta. El método Expand reemplaza los enlaces express de la plantilla por datos de un objeto . Los enlaces express se incluyen en ${}. Por ejemplo, ${name} es un enlace rápido que se reemplaza por el valor de la name propiedad cuando se representa la tarjeta.

El siguiente fragmento de código muestra cómo crear un objeto AdaptiveCardTemplate , enlazar datos a la tarjeta y deserializar la plantilla expandida en un objeto JSON:

var cardJson = await File.ReadAllTextAsync(Path.Combine(".", "Resources", "card.json"), cancellationToken);
var template = new AdaptiveCardTemplate(cardJson);
var expandedTemplate = template.Expand({ name: "Product" });
var content = JsonConvert.DeserializeObject(expandedTemplate);

Primero lee la plantilla tarjeta adaptable de un archivo y crea un objeto AdaptiveCardTemplate . A continuación, use el método Expand para enlazar datos a la tarjeta. El método Expand reemplaza los enlaces express de la plantilla por los datos del objeto . Por último, se deserializa la plantilla expandida en un objeto JSON, que se puede usar en la propiedad Content de un objeto MessagingExtensionAttachment .

Respuesta de la extensión de mensaje

Una extensión de mensaje siempre debe devolver una respuesta a una consulta de búsqueda de usuario. El objeto MessagingExtensionResponse se usa para devolver una respuesta al usuario. Al devolver resultados al usuario, se incluye un objeto composeExtension en la respuesta. El objeto composeExtension contiene un objeto MessagingExtensionResult que contiene los resultados que se mostrarán al usuario.

El siguiente fragmento de código muestra cómo devolver una respuesta al usuario:

return new MessagingExtensionResponse
{
    ComposeExtension = new MessagingExtensionResult
    {
        Type = "result",
        AttachmentLayout = "list",
        Attachments = attachments
    }
};

La propiedad Attachments del objeto MessagingExtensionResult contiene una lista de objetos MessagingExtensionAttachment .

Cada objeto MessagingExtensionAttachment representa un resultado de búsqueda que se muestra al usuario. Un objeto MessagingExtensionAttachment contiene las siguientes propiedades:

• ContentType: el tipo de contenido de los datos adjuntos.
• Contenido: el contenido de los datos adjuntos que representa la tarjeta insertada en el área de redacción del mensaje cuando el usuario selecciona el resultado de la búsqueda.
• Vista previa: vista previa de los datos adjuntos que representa la tarjeta que se muestra en los resultados de la búsqueda.

El siguiente fragmento de código muestra cómo crear una lista de objetos MessagingExtensionAttachment que contiene una tarjeta adaptable y una tarjeta de vista previa para cada resultado de búsqueda:

var attachments = products.Select(product =>
{
    var expandedTemplate = template.Expand(product);

    return new MessagingExtensionAttachment
    {
        ContentType = AdaptiveCard.ContentType,
        Content = JsonConvert.DeserializeObject(content),
        Preview = new ThumbnailCard
        {
            Title = product.Name,
            Subtitle = product.Category,
            Images = [new() { Url = product.ImageUrl }]
        }.ToAttachment()
    };
}).ToList();