Zurückgeben von Produktdaten aus Microsoft Entra geschützten API

Abgeschlossen

In dieser Lerneinheit erfahren Sie, wie Sie Daten aus einer API in einer suchbasierten Nachrichtenerweiterungsantwort zurückgeben.

Verarbeiten von Suchabfragen

Wenn ein Benutzer eine Suchabfrage eingibt, sendet der Botdienst eine Anforderung an den Messagingerweiterungsendpunkt. Die Anforderung enthält die vom Benutzer eingegebene Suchabfrage. Sie verwenden die Suchabfrage, um in einem externen System nach Daten zu suchen, die in den Suchergebnissen verwendet werden können.

Sie greifen auf die vom Benutzer eingegebene Suchabfrage mithilfe der Query-Eigenschaft des MessagingExtensionQuery-Objekts in der OnTeamsMessagingExtensionQueryAsync-Methode zu. Die Parameters-Eigenschaft des MessagingExtensionQuery-Objekts enthält die Parameter, die beim Aufruf an die Messagingerweiterung übergeben wurden. Die Parameters-Eigenschaft ist eine Liste von Schlüssel-Wert-Paaren, die den Namen und den Wert der einzelnen Parameter enthält.

Vorlagen für adaptive Karten

Eine adaptive Karte ist ein deklaratives Format zum Erstellen plattformunabhängiger UI-Komponenten, die eine konsistente Benutzererfahrung auf verschiedenen Plattformen und Geräten bieten.

Vorlagen für adaptive Karten sind JSON-Dateien, die die Struktur einer adaptiven Karte definieren. Mithilfe von Vorlagen für adaptive Karten können Sie die Struktur des Karte in einer separaten Datei definieren und Zur Laufzeit Daten an die Karte binden.

Sie verwenden Vorlagen für adaptive Karten, um den Inhalt der Suchergebnisse zu erstellen, die in den Nachrichtenerstellungsbereich eingebettet sind, wenn der Benutzer ein Suchergebnis auswählt.

Der folgende Codeausschnitt zeigt ein einfaches Beispiel für eine Vorlage für adaptive Karten:

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

Vorlagen für adaptive Karten verwenden Expressbindungen, um Daten an die Karte zu binden. Sie verwenden die Expand-Methode des AdaptiveCardTemplate-Objekts, um Daten an die Karte zu binden. Die Expand-Methode ersetzt die express-Bindungen in der Vorlage durch Daten aus einem -Objekt. Die express-Bindungen sind in ${}eingeschlossen. Beispielsweise ist eine express-Bindung, ${name} die durch den Wert der name -Eigenschaft ersetzt wird, wenn die Karte gerendert wird.

Der folgende Codeausschnitt zeigt, wie Sie ein AdaptiveCardTemplate-Objekt erstellen, Daten an die Karte binden und die erweiterte Vorlage an ein JSON-Objekt deserialisieren:

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

Sie lesen zuerst die Vorlage für adaptive Karten aus einer Datei und erstellen ein AdaptiveCardTemplate-Objekt . Anschließend verwenden Sie die Expand-Methode, um Daten an die Karte zu binden. Die Expand-Methode ersetzt die Expressbindungen in der Vorlage durch die Daten aus dem -Objekt. Schließlich deserialisieren Sie die erweiterte Vorlage in ein JSON-Objekt, das in der Content-Eigenschaft eines MessagingExtensionAttachment-Objekts verwendet werden kann.

Antwort der Nachrichtenerweiterung

Eine Nachrichtenerweiterung muss immer eine Antwort auf eine Benutzersuchabfrage zurückgeben. Das MessagingExtensionResponse-Objekt wird verwendet, um eine Antwort an den Benutzer zurückzugeben. Wenn Sie Ergebnisse an den Benutzer zurückgeben, fügen Sie ein composeExtension-Objekt in die Antwort ein. Das composeExtension-Objekt enthält ein MessagingExtensionResult-Objekt , das die Ergebnisse enthält, die dem Benutzer angezeigt werden sollen.

Der folgende Codeausschnitt zeigt, wie eine Antwort an den Benutzer zurückgegeben wird:

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

Die Attachments-Eigenschaft des MessagingExtensionResult-Objekts enthält eine Liste von MessagingExtensionAttachment-Objekten .

Jedes MessagingExtensionAttachment-Objekt stellt ein Suchergebnis dar, das dem Benutzer angezeigt wird. Ein MessagingExtensionAttachment-Objekt enthält die folgenden Eigenschaften:

• ContentType: Der Inhaltstyp der Anlage.
• Inhalt: Der Inhalt der Anlage, die die Karte darstellt, die in den Nachrichtenerstellungsbereich eingebettet ist, wenn der Benutzer das Suchergebnis auswählt.
• Vorschau: Die Vorschau der Anlage, die die in den Suchergebnissen angezeigte Karte darstellt.

Der folgende Codeausschnitt zeigt, wie Sie eine Liste von MessagingExtensionAttachment-Objekten erstellen, die eine adaptive Karte und eine Vorschau Karte für jedes Suchergebnis enthält:

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