Esercizio - Estendere e ottimizzare le estensioni dei messaggi da usare con Microsoft 365 Copilot

Completato

In questo esercizio si estende e si ottimizza l'estensione del messaggio per l'uso con Microsoft 365 Copilot. Si aggiunge un nuovo parametro denominato Destinatari e si aggiorna la logica di estensione del messaggio per gestire più parametri. Infine, si esegue ed esegue il debug dell'estensione del messaggio e la si testa in Copilot in Microsoft Teams.

Screenshot di una risposta in Microsoft 365 Copilot che contiene le informazioni restituite dal plug-in dell'estensione del messaggio. Viene visualizzata una scheda adattiva che mostra le informazioni sul prodotto.

Aggiornare la descrizione dell'app

Specificare descrizioni concise e accurate nel manifesto dell'app è fondamentale per garantire che Copilot sappia quando e come richiamare il plug-in. Aggiornare le descrizioni di app, comandi e parametri nel manifesto dell'app.

Aprire Visual Studio e nel progetto TeamsApp:

  1. Nella cartella appPackage aprire manifest.json

  2. Aggiornare l'oggetto descrizione

    {
        "description": {
            "short": "Product look up tool.",
            "full": "Get real-time product information and share them in a conversation. Search by product name or target audience. ${{APP_DISPLAY_NAME}} works with Microsoft 365 Chat. Find products at Contoso. Find Contoso products called mark8. Find Contoso products named mark8. Find Contoso products related to Mark8. Find Contoso products aimed at individuals. Find Contoso products aimed at businesses. Find Contoso products aimed at individuals with the name mark8. Find Contoso products aimed at businesses with the name mark8."
        },
    }
    

Aggiungere un nuovo parametro

Aggiungere un nuovo parametro utilizzabile da Copilot. Questo nuovo parametro consente agli utenti di cercare prodotti con Copilot destinati a destinatari diversi, ad esempio singoli utenti e aziende.

Continuare in Visual Studio e nel progetto TeamsApp:

  1. Nella matrice parameters aggiungere il parametro TargetAudience dopo il parametro ProductName .

    {    
        "parameters": [
            {
                "name": "ProductName",
                "title": "Product name",
                "description": "The name of the product as a keyword",
                "inputType": "text"
            },
            {
                "name": "TargetAudience",
                "title": "Target audience",
                "description": "Audience that the product is aimed at. Consumer products are sold to individuals. Enterprise products are sold to businesses",
                "inputType": "text"
            }
        ]
    }
    
  2. Save your changes

La descrizione del parametro TargetAudience descrive il relativo contenuto e spiega che il parametro deve accettare i valori Consumer o Enterprise consentiti.

Aggiornare quindi la descrizione del comando per includere il nuovo parametro.

  • Nella matrice comandi aggiornare la descrizione del comando

    {
        "commands": [
            {
                "id": "Search",
                "type": "query",
                "title": "Products",
                "description": "Find products by name or by target audience",
                "initialRun": true,
                "fetchTask": false,
                "context": [...],
                "parameters": [...]
            }
        ]
    }
    

Aggiornare la logica dell'estensione del messaggio

Per supportare il nuovo parametro e supportare richieste complesse, aggiornare il metodo OnTeamsMessagingExtensionQueryAsync nel gestore attività bot per gestire più parametri.

Aggiornare prima di tutto la classe ProductService per recuperare i prodotti in base al nome e ai parametri del gruppo di destinatari.

Continuare in Visual Studio nel progetto ProductPlugin:

  1. Nella cartella Servizi aprire ProductsService.cs

  2. Nel file creare nuovi metodi denominati GetProductsByCategoryAsync e GetProductsByNameAndCategoryAsync

    internal async Task<Product[]> GetProductsByCategoryAsync(string category)
    {
        var response = await _httpClient.GetAsync($"{_baseUri}products?category={category}");
        response.EnsureSuccessStatusCode();
        var jsonString = await response.Content.ReadAsStringAsync();
        return System.Text.Json.JsonSerializer.Deserialize<Product[]>(jsonString);
    }
    
    internal async Task<Product[]> GetProductsByNameAndCategoryAsync(string name, string category)
    {
        var response = await _httpClient.GetAsync($"{_baseUri}?name={name}&category={category}");
        response.EnsureSuccessStatusCode();
        var jsonString = await response.Content.ReadAsStringAsync();
        return System.Text.Json.JsonSerializer.Deserialize<Product[]>(jsonString);
    }
    
  3. Save your changes

Aggiungere quindi un nuovo metodo alla classe MessageExtensionHelper per recuperare i prodotti in base ai parametri name e audience.

  1. Nella cartella Helpers aprire MessageExtensionHelper.cs

  2. Nel file creare un nuovo metodo denominato RetrieveProducts che recupera i prodotti in base ai parametri name e audience.

    internal static async Task<IList<Product>> RetrieveProducts(string name, string audience, ProductsService productsService)
    {
        IList<Product> products;
    
        if (string.IsNullOrEmpty(name) && !string.IsNullOrEmpty(audience))
        {
            products = await productsService.GetProductsByCategoryAsync(audience);
        }
        else if (!string.IsNullOrEmpty(name) && string.IsNullOrEmpty(audience))
        {
            products = await productsService.GetProductsByNameAsync(name);
        }
        else if (!string.IsNullOrEmpty(name) && !string.IsNullOrEmpty(audience))
        {
            products = await productsService.GetProductsByNameAndCategoryAsync(name, audience);
        }
        else
        {
            products = [];
        }
    
        return products;
    }
    
  3. Save your changes

Il metodo RetrieveProduct recupera i prodotti in base ai parametri name e audience. Se il parametro name è vuoto e il parametro audience non è vuoto, il metodo recupera i prodotti in base al parametro audience. Se il parametro name non è vuoto e il parametro audience è vuoto, il metodo recupera i prodotti in base al parametro name. Se i parametri name e audience non sono vuoti, il metodo recupera i prodotti in base a entrambi i parametri. Se entrambi i parametri sono vuoti, il metodo restituisce un elenco vuoto.

Aggiornare quindi la classe SearchApp per gestire il nuovo parametro.

  1. Nella cartella Cerca aprire SearchApp.cs

  2. Nel metodo OnTeamsMessagingExtensionQueryAsync sostituire il codice seguente:

    var name = MessageExtensionHelpers.GetQueryParameterValueByName(query.Parameters, "ProductName");
    
    var productService = new ProductsService(tokenResponse.Token);
    var products = await productService.GetProductsByNameAsync(name);
    

    Con:

    var name = MessageExtensionHelpers.GetQueryParameterValueByName(query.Parameters, "ProductName");
    var audience = MessageExtensionHelpers.GetQueryParameterValueByName(query.Parameters, "TargetAudience");
    
    var productService = new ProductsService(tokenResponse.Token);
    var products = await MessageExtensionHelpers.RetrieveProducts(name, audience, productService);
    
  3. Save your changes

Il metodo OnTeamsMessagingExtensionQueryAsync recupera ora i parametri nome e gruppo di destinatari dai parametri di query. Recupera quindi i prodotti in base ai parametri name e audience usando il metodo RetrieveProducts .

Creare e aggiornare le risorse

Con tutto ciò che è ora disponibile, eseguire il processo Preparare le dipendenze delle app di Teams per creare nuove risorse e aggiornarne di quelle esistenti.

Continuare in Visual Studio:

  1. In Esplora soluzioni fare clic con il pulsante destro del mouse sul progetto TeamsApp
  2. Espandere il menu Teams Toolkit, selezionare Prepare Teams App Dependencies (Preparare le dipendenze delle app di Teams)
  3. Nella finestra di dialogo Account Microsoft 365 selezionare Continua
  4. Nella finestra di dialogo Provision (Provision ) selezionare Provisioning (Provisioning)
  5. Nella finestra di dialogo di avviso di Teams Toolkit selezionare Provisioning
  6. Nella finestra di dialogo Informazioni di Teams Toolkit selezionare l'icona a croce per chiudere la finestra di dialogo

Eseguire ed eseguire il debug

Con il provisioning delle risorse, avviare una sessione di debug per testare l'estensione del messaggio.

Avviare innanzitutto Dev Proxy per simulare l'API personalizzata.

  1. Aprire una finestra del terminale

  2. Eseguire il comando seguente per avviare Dev Proxy:

    devproxy --config-file "~appFolder/presets/learn-copilot-me-plugin/products-api-config.json"
    
  3. Se richiesto, accettare l'avviso del certificato

Nota

Quando Dev Proxy è in esecuzione, funge da proxy a livello di sistema.

Avviare quindi una sessione di debug in Visual Studio:

  1. Per avviare una nuova sessione di debug, premere F5 o selezionare Avvia dalla barra degli strumenti

  2. Attendere l'apertura di una finestra del browser e la finestra di dialogo di installazione dell'app viene visualizzata nel client Web di Microsoft Teams. Se richiesto, immettere le credenziali dell'account Microsoft 365.

  3. Nella finestra di dialogo di installazione dell'app selezionare Aggiungi

  4. Aprire l'app Copilot in Microsoft Teams

  5. Nell'area compose message (Componi messaggi) aprire il riquadro a comparsa Plugins (Plug-in )

  6. Nell'elenco dei plug-in attivare o disattivare il plug-in prodotti Contoso per abilitarlo

    Screenshot di Microsoft 365 Copilot in Microsoft Teams con il plug-in Prodotti Contoso abilitato.

  7. Immettere Find Contoso products aimed at individuals (Trova prodotti Contoso destinati a singoli utenti ) come messaggio e inviarlo

  8. Attendere la risposta di Copilot

    Screenshot di Microsoft 365 Copilot in Microsoft Teams che mostra il messaggio copilot visualizzato durante l'elaborazione della richiesta dell'utente.

  9. Nella risposta copilot vengono visualizzati i dati restituiti nella risposta del plug-in e viene fatto riferimento al plug-in nella risposta

    Screenshot di una risposta in Microsoft 365 Copilot che contiene le informazioni restituite dal plug-in dell'estensione del messaggio. Viene visualizzata una scheda adattiva che mostra le informazioni sul prodotto.

  10. Per visualizzare la scheda adattiva pertinente al risultato, passare il puntatore del mouse sui riferimenti nella risposta copilot

    Screenshot di Microsoft 365 Copilot in Microsoft Teams che mostra una scheda adattiva con le informazioni sul prodotto visualizzate. La scheda viene visualizzata quando l'utente passa il puntatore su un riferimento nella risposta copilot.

Tornare a Visual Studio e selezionare Arresta dalla barra degli strumenti oppure premere MAIUSC + F5 per arrestare la sessione di debug. Inoltre, arrestare Dev Proxy usando CTRL + C.