Restituire i dati del prodotto da Microsoft Entra'API protetta

Completato

In questa unità si apprenderà come restituire i dati da un'API in una risposta di estensione del messaggio basata sulla ricerca.

Gestire le query di ricerca

Quando un utente immette una query di ricerca, il servizio bot invia una richiesta all'endpoint dell'estensione di messaggistica. La richiesta contiene la query di ricerca immessa dall'utente. Usare la query di ricerca per cercare i dati in un sistema esterno, che possono essere usati nei risultati della ricerca.

È possibile accedere alla query di ricerca immessa dall'utente usando la proprietà Query dell'oggetto MessagingExtensionQuery nel metodo OnTeamsMessagingExtensionQueryAsync . La proprietà Parameters dell'oggetto MessagingExtensionQuery contiene i parametri passati all'estensione di messaggistica quando è stato richiamato. La proprietà Parameters è un elenco di coppie chiave-valore che contiene il nome e il valore di ogni parametro.

Modelli di schede adattive

Una scheda adattiva è un formato dichiarativo per la creazione di componenti dell'interfaccia utente indipendenti dalla piattaforma, che offrono un'esperienza utente coerente tra piattaforme e dispositivi diversi.

I modelli di scheda adattiva sono file JSON che definiscono la struttura di una scheda adattiva. L'uso di modelli di scheda adattiva consente di definire la struttura della scheda in un file separato e associare i dati alla scheda in fase di esecuzione.

I modelli di scheda adattiva consentono di creare il contenuto dei risultati della ricerca incorporati nell'area di composizione dei messaggi quando l'utente seleziona un risultato di ricerca.

Il frammento di codice seguente mostra un esempio di base di un modello di scheda adattiva:

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

I modelli di scheda adattiva usano le associazioni rapide per associare i dati alla scheda. Usare il metodo Expand dell'oggetto AdaptiveCardTemplate per associare i dati alla scheda. Il metodo Expand sostituisce le associazioni rapide nel modello con i dati di un oggetto . Le associazioni rapide sono racchiuse in ${}. Ad esempio, ${name} è un'associazione rapida che viene sostituita con il valore della name proprietà quando viene eseguito il rendering della scheda.

Il frammento di codice seguente illustra come creare un oggetto AdaptiveCardTemplate , associare i dati alla scheda e deserializzare il modello espanso a un oggetto 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);

Leggere prima di tutto il modello di scheda adattiva da un file e creare un oggetto AdaptiveCardTemplate . Usare quindi il metodo Expand per associare i dati alla scheda. Il metodo Expand sostituisce le associazioni rapide nel modello con i dati dell'oggetto . Infine, deserializzare il modello espanso in un oggetto JSON, che può essere utilizzato nella proprietà Content di un oggetto MessagingExtensionAttachment .

Risposta dell'estensione del messaggio

Un'estensione del messaggio deve sempre restituire una risposta a una query di ricerca utente. L'oggetto MessagingExtensionResponse viene utilizzato per restituire una risposta all'utente. Quando si restituiscono risultati all'utente, si include un oggetto composeExtension nella risposta. L'oggetto composeExtension contiene un oggetto MessagingExtensionResult che contiene i risultati da visualizzare all'utente.

Il frammento di codice seguente illustra come restituire una risposta all'utente:

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

La proprietà Attachments dell'oggetto MessagingExtensionResult contiene un elenco di oggetti MessagingExtensionAttachment .

Ogni oggetto MessagingExtensionAttachment rappresenta un risultato di ricerca visualizzato all'utente. Un oggetto MessagingExtensionAttachment contiene le proprietà seguenti:

• ContentType: tipo di contenuto dell'allegato.
• Contenuto: contenuto dell'allegato che rappresenta la scheda incorporata nell'area di composizione del messaggio quando l'utente seleziona il risultato della ricerca.
• Anteprima: anteprima dell'allegato che rappresenta la scheda visualizzata nei risultati della ricerca.

Il frammento di codice seguente illustra come creare un elenco di oggetti MessagingExtensionAttachment che contiene una scheda adattiva e una scheda di anteprima per ogni risultato della ricerca:

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