Retourner des données de produit à partir de Microsoft Entra’API protégée

Effectué

Dans cette unité, vous allez apprendre à retourner des données à partir d’une API dans une réponse d’extension de message basée sur la recherche.

Gérer les requêtes de recherche

Lorsqu’un utilisateur entre une requête de recherche, le service bot envoie une requête au point de terminaison d’extension de messagerie. La requête contient la requête de recherche entrée par l’utilisateur. Vous utilisez la requête de recherche pour rechercher des données dans un système externe, qui peut être utilisée dans les résultats de la recherche.

Vous accédez à la requête de recherche entrée par l’utilisateur à l’aide de la propriété Query de l’objet MessagingExtensionQuery dans la méthode OnTeamsMessagingExtensionQueryAsync . La propriété Parameters de l’objet MessagingExtensionQuery contient les paramètres qui ont été passés à l’extension de messagerie lors de son appel. La propriété Parameters est une liste de paires clé-valeur qui contient le nom et la valeur de chaque paramètre.

Modèles de carte adaptative

Une carte adaptative est un format déclaratif permettant de créer des composants d’interface utilisateur indépendants de la plateforme, qui fournissent une expérience utilisateur cohérente sur différentes plateformes et appareils.

Les modèles de carte adaptative sont des fichiers JSON qui définissent la structure d’une carte adaptative. L’utilisation d’un modèle de carte adaptative vous permet de définir la structure du carte dans un fichier distinct et de lier des données au carte au moment de l’exécution.

Vous utilisez des modèles de carte adaptative pour créer le contenu des résultats de recherche incorporés dans la zone de composition de message lorsque l’utilisateur sélectionne un résultat de recherche.

L’extrait de code suivant montre un exemple de base de modèle de carte adaptative :

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

Les modèles de carte adaptative utilisent des liaisons express pour lier les données au carte. Vous utilisez la méthode Expand de l’objet AdaptiveCardTemplate pour lier des données à l’carte. La méthode Expand remplace les liaisons express dans le modèle par les données d’un objet . Les liaisons express sont placées dans ${}. Par exemple, ${name} est une liaison express qui est remplacée par la valeur de la name propriété lorsque le carte est rendu.

L’extrait de code suivant montre comment créer un objet AdaptiveCardTemplate, lier des données au carte et désérialiser le modèle développé à un objet 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);

Vous devez d’abord lire le modèle de carte adaptative à partir d’un fichier et créer un objet AdaptiveCardTemplate . Vous utilisez ensuite la méthode Expand pour lier des données au carte. La méthode Expand remplace les liaisons express dans le modèle par les données de l’objet . Enfin, vous désérialisez le modèle développé en objet JSON, qui peut être utilisé dans la propriété Content d’un objet MessagingExtensionAttachment .

Réponse d’extension de message

Une extension de message doit toujours retourner une réponse à une requête de recherche d’utilisateur. L’objet MessagingExtensionResponse est utilisé pour renvoyer une réponse à l’utilisateur. Lorsque vous retournez des résultats à l’utilisateur, vous incluez un objet composeExtension dans la réponse. L’objet composeExtension contient un objet MessagingExtensionResult qui contient les résultats à afficher à l’utilisateur.

L’extrait de code suivant montre comment retourner une réponse à l’utilisateur :

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

La propriété Attachments de l’objet MessagingExtensionResult contient une liste d’objets MessagingExtensionAttachment .

Chaque objet MessagingExtensionAttachment représente un résultat de recherche affiché pour l’utilisateur. Un objet MessagingExtensionAttachment contient les propriétés suivantes :

• ContentType : type de contenu de la pièce jointe.
• Contenu : contenu de la pièce jointe qui représente le carte incorporé dans la zone de composition de message lorsque l’utilisateur sélectionne le résultat de la recherche.
• Aperçu : aperçu de la pièce jointe qui représente le carte affiché dans les résultats de la recherche.

L’extrait de code suivant montre comment créer une liste d’objets MessagingExtensionAttachment qui contient une carte adaptative et un aperçu carte pour chaque résultat de recherche :

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