Devolver dados de produtos de Microsoft Entra API protegida

Concluído

Nesta unidade, vai aprender a devolver dados de uma API numa resposta de extensão de mensagem baseada em pesquisa.

Processar consultas de pesquisa

Quando um utilizador introduz uma consulta de pesquisa, o serviço de bot envia um pedido para o ponto final da extensão de mensagens. O pedido contém a consulta de pesquisa introduzida pelo utilizador. Utilize a consulta de pesquisa para procurar dados num sistema externo, que podem ser utilizados nos resultados da pesquisa.

Pode aceder à consulta de pesquisa introduzida pelo utilizador através da propriedade Consulta do objeto MessagingExtensionQuery no método OnTeamsMessagingExtensionQueryAsync . A propriedade Parameters do objeto MessagingExtensionQuery contém os parâmetros que foram transmitidos à extensão de mensagens quando foi invocada. A propriedade Parâmetros é uma lista de pares chave-valor que contém o nome e o valor de cada parâmetro.

Modelos de Cartão Ajustável

Um Cartão Ajustável é um formato declarativo para criar componentes de IU agnósticos de plataforma, que proporcionam uma experiência de utilizador consistente em diferentes plataformas e dispositivos.

Os modelos de Cartão Adaptável são ficheiros JSON que definem a estrutura de um Cartão Ajustável. A utilização de modelos de Cartão Ajustável permite-lhe definir a estrutura do card num ficheiro separado e vincular dados ao card no runtime.

Utilize modelos de Cartão Ajustável para criar o conteúdo dos resultados da pesquisa incorporados na área de composição de mensagens quando o utilizador seleciona um resultado de pesquisa.

O fragmento de código seguinte mostra um exemplo básico de um modelo de Cartão Ajustável:

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

Os modelos de Cartão Ajustável utilizam enlaces expressos para vincular dados à card. Utilize o método Expandir do objeto AdaptiveCardTemplate para vincular dados ao card. O método Expand substitui os enlaces expressos no modelo por dados de um objeto. Os enlaces expresso estão incluídos em ${}. Por exemplo, ${name} é um enlace expresso que é substituído pelo valor da name propriedade quando o card é composto.

O fragmento de código seguinte mostra como criar um objeto AdaptiveCardTemplate, vincular dados ao card e anular a serialização do modelo expandido para um 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);

Primeiro, leu o modelo cartão ajustável a partir de um ficheiro e cria um objeto AdaptiveCardTemplate . Em seguida, utilize o método Expandir para vincular dados ao card. O método Expand substitui os enlaces expressos no modelo pelos dados do objeto. Por fim, anula a serialização do modelo expandido para um objeto JSON, que pode ser utilizado na propriedade Content de um objeto MessagingExtensionAttachment .

Resposta da extensão de mensagem

Uma extensão de mensagem tem sempre de devolver uma resposta a uma consulta de pesquisa de utilizador. O objeto MessagingExtensionResponse é utilizado para devolver uma resposta ao utilizador. Ao devolver resultados ao utilizador, inclui um objeto composeExtension na resposta. O objeto composeExtension contém um objeto MessagingExtensionResult que contém os resultados a apresentar ao utilizador.

O fragmento de código seguinte mostra como devolver uma resposta ao utilizador:

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

A propriedade Anexos do objeto MessagingExtensionResult contém uma lista de objetos MessagingExtensionAttachment .

Cada objeto MessagingExtensionAttachment representa um resultado de pesquisa que é apresentado ao utilizador. Um objeto MessagingExtensionAttachment contém as seguintes propriedades:

• ContentType: o tipo de conteúdo do anexo.
• Conteúdo: o conteúdo do anexo que representa o card incorporado na área de composição de mensagens quando o utilizador seleciona o resultado da pesquisa.
• Pré-visualização: a pré-visualização do anexo que representa o card que é apresentado nos resultados da pesquisa.

O fragmento de código seguinte mostra como criar uma lista de objetos MessagingExtensionAttachment que contém um Cartão Ajustável e card de pré-visualização para cada resultado de pesquisa:

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