Esercitazioni

Questo articolo illustra altre informazioni sulla creazione di funzionalità per le app di Teams. Ecco un elenco delle guide dettagliate disponibili per le funzionalità della piattaforma Teams.

# Funzionalità Guida passo passo
1. Bot - Esegui il debug del tuo chat bot basato sull'intelligenza artificiale utilizzando Microsoft 365 Agents Playground
- Inviare messaggi proattivi
2. Estensione messaggio - Creare un'estensione messaggio basata su API
- Crea un'estensione messaggio basata sull'azione
- Creare la prima app di estensione messaggio con JavaScript
3. TAB Crea l'app per la prima scheda usando C diesis
4. SSO - Creare un bot con autenticazione SSO
- Aggiungere SSO all'app di estensione schede e messaggi

Creare la prima app bot

Inizia a sviluppare app per Microsoft Teams con la tua prima app Teams. È possibile creare un'app bot con Teams usando Javascript.


Crea il tuo primo bot

L'app dispone di una funzionalità che viene fornita con una propria interfaccia utente e esperienza utente:

Il diagramma mostra che questa app ha tre caratteristiche.

In questo tutorial imparerai quanto segue:

  • Come configurare un nuovo progetto con Microsoft 365 Agents Toolkit (noto in precedenza come Teams Toolkit).
  • Come creare un'app bot.
  • Come distribuire l'app.

Prerequisiti

Assicurarsi di installare gli strumenti seguenti per la creazione e la distribuzione delle app.

  Installare Per l'utilizzo...
Obbligatorio    
  Toolkit per agenti di Microsoft 365 Un'estensione di Microsoft Visual Studio Code che crea un'impalcatura di progetto per l'app. Usa la versione più recente.
  Microsoft Teams Microsoft Teams per collaborare con tutti i tuoi collaboratori tramite app per chat, riunioni e chiamate, in un unico posto.
  Node.js Ambiente di runtime JavaScript back-end. Per altre informazioni, vedere Node.js tabella di compatibilità delle versioni per il tipo di progetto.
  Microsoft Edge (scelta consigliata) o Google Chrome Un browser con strumenti di sviluppo.
  Visual Studio Code Ambienti di compilazione JavaScript, TypeScript o SharePoint Framework (SPFx). Usa la versione più recente.
Dati facoltativi    
  Strumenti di Azure per Visual Studio Code e l'interfaccia della riga di comando di Azure Strumenti di Azure per accedere ai dati archiviati o distribuire un back-end basato sul cloud per l'app Teams in Azure.
  Strumenti di sviluppo React per Chrome OPPURE Strumenti di sviluppo React per Microsoft Edge Un'estensione DevTools del browser per la libreria JavaScript open source React.
  Microsoft Graph Explorer Microsoft Graph Explorer, uno strumento basato su browser che consente di eseguire una query dai dati di Microsoft Graph.
  Portale per sviluppatori per Teams Portale basato sul Web per configurare, gestire e pubblicare l'app Teams, anche nell'organizzazione o nello Store di Microsoft Teams.

Suggerimento

Se si usano i dati di Microsoft Graph, si dovrebbero ottenere informazioni e aggiungere segnalibri a Microsoft Graph Explorer. Questo strumento basato su browser consente di eseguire query su Microsoft Graph all'esterno di un'app.

Configurare i prerequisiti

Dopo aver installato gli strumenti necessari, configura l'ambiente di sviluppo.

Installare Microsoft 365 Agents Toolkit

Microsoft 365 Agents Toolkit (in precedenza noto come Teams Toolkit) aiuta a semplificare il processo di sviluppo con strumenti per il provisioning e la distribuzione di risorse cloud per l'app e la pubblicazione su Teams Store.

Puoi utilizzare Agents Toolkit con Visual Studio Code o un'interfaccia a riga di comando denominata Microsoft 365 Agents Toolkit CLI (in precedenza nota come CLI di TeamsFx).

  1. Apri Visual Studio Code e seleziona Estensioni (CTRL+MAIUSC+X o Visualizza>estensioni).

  2. Nella casella di ricerca, inserisci Microsoft 365 Agents Toolkit.

  3. Selezionare Installa.

    Screenshot che mostra l'installazione dell'estensione Agents Toolkit.

    L'icona di Microsoft 365 Agents Toolkit viene visualizzata nella barra delle attività di Visual Studio Code.

Puoi anche installare Agents Toolkit da Visual Studio Code Marketplace.

Configurare il tenant di sviluppo di Teams

Un tenant è uno spazio o un contenitore per l'organizzazione in Teams in cui si chatta, si condividono file ed si eseguono riunioni. Questo spazio è anche il luogo in cui carichi e testi la tua app. Verificare se si è pronti per lo sviluppo con il tenant.

Controlla l'opzione Carica un'app

Dopo aver creato l'app personalizzata, è necessario caricarla in Teams con l'opzione Carica un'app personalizzata . Accedere al proprio account Microsoft 365 per verificare se questa opzione è abilitata.

La procedura seguente consente di verificare se è possibile caricare app in Teams:

  1. Nel client Teams selezionare l'icona App .

  2. Seleziona Gestisci le tue app.

  3. Selezionare Carica un'app.

  4. Cerca l'opzione per caricare un'app personalizzata. Se l'opzione è visibile, è possibile caricare app personalizzate.

    Screenshot che mostra l'opzione per caricare un'app personalizzata in Teams.

Nota

Se non trovi l'opzione per caricare un'app personalizzata, contatta l'amministratore di Teams.

Creare un tenant di sviluppo di Teams gratuito

Se non hai un account sviluppatore di Teams, partecipa al programma per sviluppatori di Microsoft 365. Questo passaggio è facoltativo.

  1. Passare al programma per sviluppatori di Microsoft 365.

  2. Seleziona Partecipa ora e segui le istruzioni sullo schermo.

  3. Nella schermata iniziale, seleziona Configura abbonamento E5.

  4. Configura il tuo account amministratore. Al termine, viene visualizzata la schermata seguente:

    Lo screenshot mostra il Programma per sviluppatori di Microsoft 365.

  5. Accedere a Teams con l'account amministratore appena configurato. Verificare di avere l'opzione Carica un'app personalizzata in Teams.

Ottenere un account di Azure gratuito

Se si vuole ospitare l'app o accedere alle risorse in Azure, è necessario avere una sottoscrizione di Azure. Crea un account gratuito prima di iniziare.

Ora hai tutti gli strumenti per configurare il tuo account. Quindi, configuriamo il tuo ambiente di sviluppo e iniziamo a costruire! Selezionare l'app che si vuole creare per prima.

Creare un'area di lavoro di progetto per l'app bot

Creiamo la tua prima app bot.

La funzionalità bot di un'app Teams crea un chatbot o un bot conversazionale. Lo si usa per eseguire attività semplici e automatizzate, come fornire assistenza ai clienti. Un bot dialoga con un servizio Web e aiuta a usarne le offerte. Puoi ottenere previsioni del tempo, effettuare prenotazioni o qualsiasi altro servizio offerto utilizzando un bot conversazionale.

Il diagramma che mostra questa app ha tre caratteristiche. Bot è evidenziato.

Come già preparato per la creazione di queste app, è possibile configurare un nuovo progetto Teams per la creazione dell'app bot.

In questa esercitazione si apprenderà:

  1. Come configurare un nuovo progetto bot con Agents Toolkit.
  2. Informazioni sulla struttura di directory del progetto di app.

Importante

I bot sono disponibili in Government Community Cloud (GCC), GCC High, Department of Defense (DoD) e Teams gestiti da ambienti 21Vianet .

Creare l'area di lavoro del progetto bot

Se i prerequisiti ci sono, iniziamo!

Nota

L'interfaccia utente di Visual Studio Code mostrata è da Mac. Può variare a seconda del sistema operativo, della versione di Agents Toolkit e dell'ambiente.

  1. Apri Visual Studio Code.

  2. Seleziona l'icona di Microsoft 365 Agents Toolkit nella barra delle attività di Visual Studio Code.

  3. Selezionare Crea un nuovo agente/app>App di Teams.

    Questa schermata mostra la posizione del collegamento Crea nuovo progetto nella barra laterale di Agents Toolkit.

  4. Selezionare Bot per creare un nuovo progetto bot.

    Screenshot che mostra la procedura guidata per Crea nuovo progetto.

  5. Assicurarsi che Bot di base sia selezionato come funzionalità dell'app da creare nell'app.

    Lo screenshot mostra la funzionalità dell'app da aggiungere alla nuova app.

  6. Selezionare JavaScript come linguaggio di programmazione.

    Lo screenshot mostra l'opzione per selezionare il linguaggio di programmazione.

  7. Selezionare Cartella predefinita per archiviare la cartella principale del progetto nella posizione predefinita.

    Lo screenshot mostra la selezione della posizione predefinita.

    Puoi anche modificare la posizione predefinita seguendo questa procedura:

    1. Selezionare Sfoglia.

      Screenshot che mostra la selezione dell'opzione Sfoglia percorso.

    2. Selezionare la posizione dell'area di lavoro del progetto.

    3. Selezionare la cartella Seleziona.

      Screenshot che mostra la cartella da selezionare.

  8. Immettere un nome appropriato per l'app e quindi selezionare INVIO.

    Screenshot che mostra dove immettere il nome dell'app.

Viene visualizzata una finestra di dialogo in cui è necessario scegliere sì o no per considerare attendibili gli autori dei file in questa cartella.

Screenshot che mostra la finestra di dialogo per considerare attendibili o meno gli autori dei file in questa cartella.

L'app di Teams con funzionalità bot viene creata in pochi secondi.

Screenshot che mostra l'app creata.

Dopo la creazione dell'app, Agents Toolkit visualizza il seguente messaggio:

Lo screenshot mostra un messaggio che indica che la funzionalità è stata creata correttamente.

Seleziona Debug locale per visualizzare in anteprima il progetto.

Riepilogo rapido della creazione di un'app Teams. Guardare questo breve riepilogo sulla creazione di un'app Teams.

Creare un'app Teams

Panoramica del codice sorgente dell'app bot

Al termine dell'impalcatura, visualizzare le directory e i file del progetto in Esplora risorse in Visual Studio Code.

Screenshot che mostra la struttura della cartella.

Cartella/File Sommario
m365agents.yml File di progetto principale
m365agents.local.yml Questa operazione sostituisce m365agents.yml le azioni che abilitano l'esecuzione e il debug locali.
.vscode/ File VSCode per il debug locale.
appPackage/ Modelli per il manifesto dell'applicazione Teams.
adaptiveCards/ Schede adattive inviate dal bot.
infra/ Modelli per il provisioning delle risorse di Azure.
index.js Punto di ingresso e express gestore dell'applicazione.
teamsBot.js Gestore attività di Teams.

Suggerimento

Acquisire familiarità con i bot esterni a Teams prima di integrare il primo bot in Teams.

Creare ed eseguire la prima app bot

Dopo aver configurato l'area di lavoro del progetto con Agents Toolkit, crea il progetto bot. Devi accedere al tuo account Microsoft 365.

Accedi al tuo account Microsoft 365

Usare questo account per accedere a Teams. Se usi un tenant del programma per sviluppatori di Microsoft 365, l'account amministratore configurato durante la registrazione è il tuo account Microsoft 365.

  1. Apri Visual Studio Code.

  2. Seleziona l'icona di Microsoft 365 Agents Toolkit nella barra laterale.

  3. Seleziona Accedi a M365 usando le tue credenziali.

    Il Web browser predefinito si apre per consentire l'accesso all'account.

  4. Chiudi il browser quando richiesto e torna a Visual Studio Code.

  5. Torna a Agents Toolkit all'interno di Visual Studio Code.

    Usare questo account per accedere a Teams. Se usi un tenant del programma per sviluppatori di Microsoft 365, l'account amministratore configurato durante la registrazione è il tuo account Microsoft 365.

    Screenshot che mostra dove accedere a Microsoft 365 e Azure.

Ora sei pronto per creare l'app ed eseguirla in locale!

Creare ed eseguire la prima app bot in locale

Per compilare ed eseguire l'app nell'ambiente locale:

  1. Seleziona F5 in Visual Studio Code per eseguire l'app in modalità di debug.

    Nota

    Se Agents Toolkit non è in grado di verificare un particolare prerequisito, ti chiede di verificare.

    Informazioni su cosa accade quando esegui l'app in locale nel debugger.

    Nel caso te lo stia chiedendo, quando premi il tasto F5 , Agents Toolkit:

    1. Verifica tutti i prerequisiti seguenti:
    • Hai eseguito l'accesso con un account Microsoft 365.
    • Il caricamento di app personalizzate è abilitato per l'account Microsoft 365.
    • Supportata Node.js versione è installata.
    • La porta richiesta dall'app bot è disponibile.
    1. Installa pacchetti npm.
    2. Avvia Dev Tunnel per creare un tunnel HTTP.
    3. Registra l'app in Microsoft Entra ID e configura l'app.
    4. Registra l'applicazione bot in Bot Framework e configura l'applicazione bot.
    5. Registra l'app nel portale per sviluppatori di Teams e configura l'app.
    6. Avvia l'app bot.
    7. Avvia Teams in un Web browser e carica l'app bot personalizzata.

    Screenshot che mostra quando viene premuto il tasto F5 per il debug.

    Nota

    Quando esegui l'app per la prima volta, tutte le dipendenze vengono scaricate e l'app viene compilata. Al termine della compilazione, viene aperta automaticamente una finestra del browser. Il completamento di questo processo può richiedere da tre a cinque minuti.

    Teams esegue l'app in un Web browser.

  2. Accedere con il proprio account Microsoft 365, se richiesto.

  3. Selezionare Aggiungi per caricare l'app bot personalizzata in Teams.

    Screenshot della finestra di dialogo dei dettagli dell'app per aggiungere l'app bot a Teams.

  4. Selezionare Apri per aprire l'app nell'ambito personale.

    In alternativa, puoi cercare e selezionare l'ambito richiesto oppure selezionare un canale, una chat o una riunione dall'elenco e spostarti nella finestra di dialogo per selezionare Vai.

    Screenshot della finestra di dialogo di selezione dell'ambito con un elenco di ambiti condivisi.

    Ora il bot funziona correttamente in Teams! Dopo aver caricato l'app, si apre una sessione di chat con il bot.

    Lo screenshot mostra che il bot è in esecuzione nel client di Teams.

    Puoi digitare welcome per visualizzare una scheda introduttiva e digitare learn per accedere alla documentazione della scheda adattiva e dei comandi bot.

    Screenshot che mostra la scheda di informazioni nel bot nel client di Teams.

    Puoi eseguire le normali attività di debug, come l'impostazione di punti di interruzione, come con qualsiasi altra applicazione web. Aprire il bot/teamsBot.js file e individuare il onMessage() metodo. Imposta un punto di interruzione in ogni caso. Quindi, digitare del testo.

    Informazioni su come risolvere i problemi se l'app non viene eseguita in locale.

    Per eseguire correttamente l'app in Teams, assicurarsi di aver abilitato il caricamento dell'app personalizzata nell'account di Teams. Per altre informazioni sul caricamento di app personalizzate, vedere la sezione dei prerequisiti.

    Importante

    Il caricamento di app personalizzate è disponibile in Government Community Cloud (GCC) e non è supportato in GCC High, DoD e Teams gestiti da 21Vianet.

    Suggerimento

    Verifica la presenza di problemi prima di caricare un'app personalizzata, usando lo strumento di convalida delle app. Questo strumento è incluso nel toolkit. Correggere gli errori di caricamento dell'app.

Distribuire la prima app di Teams

Si è imparato a creare, creare ed eseguire l'app di Teams con la funzionalità Bot. Il passaggio finale consiste nel distribuire l'app in Azure.

Distribuiamo la prima app con funzionalità Bot in Azure usando Agents Toolkit.

Accedere all'account di Azure

Usare questo account per accedere al portale di Azure Microsoft ed eseguire il provisioning di nuove risorse cloud per supportare l'app.

  1. Apri Visual Studio Code.

  2. Aprire la cartella del progetto in cui è stata creata l'app bot.

  3. Seleziona l'icona di Microsoft 365 Agents Toolkit nella barra laterale.

  4. Seleziona Accedi ad Azure usando le tue credenziali.

    Suggerimento

    Se è installata l'estensione ACCOUNT AZURE e si usa lo stesso account, è possibile ignorare questo passaggio. Utilizzare lo stesso account usato per le altre estensioni.

    Il Web browser predefinito si apre per consentire l'accesso all'account.

  5. Chiudi il browser quando richiesto e torna a Visual Studio Code.

    La sezione ACCOUNT della barra laterale mostra i due account separatamente. Elenca anche il numero di sottoscrizioni di Azure utilizzabili disponibili. Assicurarsi di avere almeno una sottoscrizione di Azure utilizzabile disponibile. In caso contrario, disconnettersi e usare un altro account.

Congratulazioni, hai creato un'app Teams! Ora andiamo avanti e impariamo come distribuire una delle app in Azure utilizzando Agents Toolkit.

Effettuare il provisioning e distribuire l'app in Azure

La distribuzione consiste in due passaggi. Innanzitutto, Azure crea le risorse cloud necessarie (operazione nota anche come provisioning). Quindi, Azure copia il codice dell'app nelle risorse cloud create. Per questa esercitazione si distribuirà l'app bot.

Qual è la differenza tra provisioning e distribuzione?
Il passaggio Provisioning crea risorse in Azure e Microsoft 365 per l'app, ma non copia il codice (HTML, CSS o JavaScript) nelle risorse. La fase Deploy copia il codice per l'app nelle risorse create durante la fase di provisioning. È comune eseguire la distribuzione più volte senza eseguire il provisioning di nuove risorse. Poiché il passaggio di provisioning può richiedere del tempo per essere completato, è separato dal passaggio di distribuzione.

Seleziona l'icona di Microsoft 365 Agents Toolkit nella barra laterale di Visual Studio Code.

  1. Selezionare Provisioning.

    Screenshot che mostra la selezione del provisioning nel cloud in Toolkit agenti.

  2. Selezionare una sottoscrizione da usare per le risorse di Azure.

    Screenshot che mostra la sottoscrizione da usare per le risorse di Azure.

    L'app è ospitata usando le risorse di Azure.

    Una finestra di dialogo avvisa che potrebbero essere addebitati costi per l'esecuzione di risorse in Azure.

  3. Selezionare Provisioning.

    Screenshot che mostra una finestra di dialogo che indica la possibilità di incorrere in costi durante l'esecuzione di risorse in Azure.

    Il processo di provisioning crea risorse nel cloud di Azure. Potrebbe essere necessario un po' di tempo. Puoi monitorare l'avanzamento guardando le finestre di dialogo nell'angolo in basso a destra. Dopo alcuni minuti, viene visualizzato l'avviso seguente:

    Lo screenshot mostra un avviso che mostra hellomsg che è stato eseguito correttamente il provisioning nel cloud.

    Se lo desideri, puoi visualizzare le risorse fornite. Per questa esercitazione non è necessario visualizzare le risorse.

    La risorsa di cui è stato eseguito il provisioning viene visualizzata nella sezione AMBIENTE .

    Screenshot che mostra la risorsa di cui viene eseguito il provisioning nella sezione ambiente.

  4. Seleziona Distribuisci dal pannello LIFECYCLE al termine del provisioning.

    Lo screenshot mostra la distribuzione nel cloud evidenziata in rosso.

    Come per il provisioning, la distribuzione richiede del tempo. Puoi monitorare il processo guardando le finestre di dialogo nell'angolo in basso a destra. Dopo alcuni minuti, viene visualizzato un avviso di completamento.

Ora è possibile usare lo stesso processo per distribuire le app Bot ed Estensione messaggio in Azure.

Eseguire l'app distribuita

Una volta completati i passaggi di provisioning e distribuzione:

  1. Apri il pannello di debug (Ctrl+MAIUSC+D / ⌘⇧-D o Visualizza > esecuzione) da Visual Studio Code.

  2. Selezionare Avvia remoto (Edge) dal menu a discesa della configurazione di avvio.

  3. Selezionare Avvia debug (F5). Viene chiesto di caricare l'app bot personalizzata in Teams.

    Screenshot che mostra il debug e l'avvio dell'app in remoto.

  4. Selezionare Aggiungi.

    Screenshot della finestra di dialogo dei dettagli dell'app per aggiungere l'app a Teams.

  5. Selezionare Apri per aprire l'app nell'ambito personale.

    In alternativa, puoi cercare e selezionare l'ambito richiesto oppure selezionare un canale, una chat o una riunione dall'elenco e spostarti nella finestra di dialogo per selezionare Vai.

    Screenshot della finestra di dialogo di selezione dell'ambito con l'elenco degli ambiti condivisi.

    L'app bot è stata aggiunta correttamente al client Teams.

    Screenshot che mostra la scheda di informazioni nel bot nel client di Teams.

Informazioni su cosa accade quando si distribuisce l'app in Azure

Prima della distribuzione, l'applicazione è stata eseguita in locale:

  • Il back-end viene eseguito usando le Funzioni di Azure Core Tools.
  • L'endpoint HTTP dell'applicazione, in cui Microsoft Teams carica l'applicazione, viene eseguito in locale.

Il processo di distribuzione è previsto in due passaggi. È possibile effettuare il provisioning delle risorse in una sottoscrizione di Azure attiva e quindi distribuire o caricare il codice back-end e front-end per l'applicazione in Azure.

  • Il back-end, se configurato, usa vari servizi di Azure, tra cui il Servizio app di Azure e Archiviazione di Azure.
  • L'applicazione front-end viene distribuita in un account di archiviazione di Azure configurato per l'hosting Web statico.

Congratulazioni!

Ce l'hai fatta!

Hai creato un'app bot.

Una volta che hai imparato a creare un'app di base, puoi passare alla creazione di app più complesse. Hai completato l'esercitazione per creare un bot con JavaScript.

Esercitazioni

Esegui il debug del tuo chat bot basato sull'intelligenza artificiale utilizzando Microsoft 365 Agents Playground

Avvia lo sviluppo di app Microsoft Teams con l'app chat bot IA di Teams ed esegui il debug con Microsoft 365 Agents Playground (in precedenza noto come Strumento di test app di Teams). Agents Playground semplifica il debug delle app basate su bot. Per utilizzare Agents Playground non è necessario un account sviluppatore di Microsoft 365, il tunneling o la registrazione di app e bot di Teams.


Esercitazione: Esegui il debug del chat bot basato su IA

Prerequisiti

È possibile chattare con il bot e visualizzare i messaggi e le schede adattive così come vengono visualizzate in Teams. Puoi anche simulare un'attività in Agents Playground usando i trigger di attività.

Nota

  • Agents Playground è disponibile solo nella versione 5.4.0 di Microsoft 365 Agents Toolkit (precedentemente noto come Teams Toolkit).
  • Agents Playground è supportato solo per client desktop e web.

Questa guida dettagliata ti aiuta a creare un chatbot IA utilizzando Agents Toolkit ed eseguirne il debug con lo strumento di test. Dopo aver completato questa guida, verrà visualizzato l'output seguente, in cui l'utente può accedere e usare il chat bot IA:

Screenshot che mostra il bot aperto nello strumento di test.

Installare Per l'utilizzo...
Visual Studio Code o Visual Studio Ambienti di compilazione JavaScript, TypeScript o C#. Usa la versione più recente.
Toolkit per agenti di Microsoft 365 Estensione di Microsoft Visual Studio Code che crea un'impalcatura di progetto per l'app. Usa Agents Toolkit v5.4.0. Per ulteriori informazioni, vedi Agents Toolkit.
Node.js Ambiente di runtime JavaScript back-end. Per altre informazioni, vedere Node.js tabella di compatibilità delle versioni per il tipo di progetto.
OpenAI o Azure OpenAI Per prima cosa, crea la tua chiave API OpenAI per utilizzare il GPT di OpenAI. Se si vuole ospitare l'app o accedere alle risorse in Azure, è necessario creare un servizio OpenAI di Azure.
Microsoft Edge (scelta consigliata) o Google Chrome Un browser con strumenti di sviluppo.

Creare un'area di lavoro di progetto per l'app chat bot IA

La funzionalità bot di un'app Teams crea un chatbot o un bot conversazionale. Comunica con un servizio web, facilitando l'utilizzo dei suoi servizi. Il bot può eseguire attività semplici e automatizzate come fornire assistenza ai clienti. Puoi ottenere previsioni del tempo, effettuare prenotazioni o qualsiasi altro servizio offerto utilizzando un bot conversazionale.

Lo screenshot mostra l'app con tre funzionalità. Bot è evidenziato.

Poiché ci si è già preparati per la creazione di queste app, è possibile configurare un nuovo progetto di Teams per la creazione dell'app chat bot IA.

Creare l'area di lavoro del progetto bot

Se i prerequisiti ci sono, iniziamo!

  1. Apri Visual Studio Code.

  2. Seleziona l'icona di Microsoft 365 Agents Toolkit nella barra delle attività di Visual Studio Code.

  3. Seleziona Crea un nuovo agente/app.

    Lo screenshot mostra la posizione del collegamento Crea nuovo progetto nella barra laterale di Agents Toolkit.

  4. Seleziona Agenti per Teams>:Azure OpenAI> Immetti subito un input in Input Chiave del servizio API di Azure

    Screenshot che mostra i modelli di app Agents Toolkit.

  5. Selezionare Agenti di base per Teams. Se è necessaria una funzionalità diversa per il bot, selezionare l'opzione richiesta.

    Screenshot che mostra la funzionalità dell'app da aggiungere alla nuova app.

  6. Seleziona il linguaggio di programmazione come JavaScript.

    Screenshot mostra l'opzione per selezionare il linguaggio di programmazione.

  7. Selezionare Cartella predefinita.

    Screenshot mostra la selezione della posizione predefinita.

    Per modificare la posizione predefinita, segui questi passaggi:

    1. Selezionare Sfoglia.

      Screenshot che mostra la selezione dell'opzione Sfoglia percorso.

    2. Selezionare la posizione dell'area di lavoro del progetto.

    3. Selezionare Seleziona cartella.

      Screenshot che mostra la cartella da selezionare.

  8. Immettere un nome appropriato per l'app e quindi premere INVIO .

    Screenshot che mostra dove immettere il nome dell'app.

    Viene visualizzata una finestra di dialogo in cui è necessario scegliere Sì o No per considerare attendibili gli autori dei file in questa cartella.

    Screenshot che mostra la finestra di dialogo per considerare attendibili o meno gli autori dei file in questa cartella.

Ora hai creato correttamente l'area di lavoro del tuo progetto di chat bot IA.

Panoramica del codice sorgente dell'app bot

Dopo aver completato lo scaffolding, esplora le directory e i file di progetto nella sezione EXPLORER di Visual Studio Code.

Screenshot che mostra la struttura della cartella bot di esempio del toolkit Teams.

Nome cartella o file Sommario
env/.env.playground Il file di configurazione con le variabili di ambiente che possono essere confermate in Git.
env/.env.playground.user Il file di configurazione con le variabili di ambiente, incluse le credenziali, che non sono commit in Git per impostazione predefinita.
appPackage File del modello manifesto dell'app e icone delle app (color.png e outline.png).
appPackage/manifest.json Manifesto dell'app per l'esecuzione dell'app in ambiente locale e remoto.
src/app.js Gestisce le logiche di business per il chat bot IA.
m365agents.yml Questo è il file di progetto principale di Agents Toolkit. Il file di progetto definisce due elementi principali: proprietà e definizione delle configurazioni e delle fasi.
m365agents.local.yml Questa operazione sostituisce m365agents.yml le azioni che abilitano l'esecuzione e il debug locali.
m365agents.playground.yml Questa operazione sostituisce m365agents.yml le azioni che abilitano l'esecuzione e il debug locali nello strumento di test.

Crea ed esegui la tua app chat bot IA

Creare una chiave e un endpoint OpenAI per il chat bot IA

  1. Passare al portale di Azure.

  2. Selezionare Crea una risorsa e cercare Azure OpenAI.

  3. Selezionare Azure OpenAI e scegliere Crea.

    Screenshot che mostra OpenAI di Azure nel portale di Azure.

  4. Compilare i dettagli necessari e selezionare Avanti.

    Lo screenshot mostra la sottoscrizione di Azure OpenAI e il gruppo di risorse.

  5. Seleziona Tutte le reti, incluso Internet, che possono accedere a questa risorsa e quindi seleziona Avanti.

    Screenshot che mostra i dettagli della rete OpenAI di Azure.

  6. Compilare i dettagli necessari e selezionare Avanti.

    Screenshot che mostra i dettagli dei tag OpenAI di Azure.

  7. Selezionare Crea.

    Screenshot che mostra l'anteprima e la creazione di Azure OpenAI.

La chiave e l'endpoint per il chat bot IA sono stati creati correttamente.

Screenshot che mostra la distribuzione di Azure OpenAI.

Nota

Puoi anche ottenere la chiave API OpenAI per eseguire il debug del tuo chat bot AI.

Ottenere le chiavi e l'endpoint di Azure OpenAI

  1. Selezionare Vai alle risorse.

    Screenshot che mostra la distribuzione di Azure OpenAI.

  2. Selezionare Chiavi ed endpoint nel riquadro sinistro e copiare la chiave e l'endpoint. È possibile copiare la CHIAVE 1 o la CHIAVE 2.

    Screenshot che mostra le chiavi e gli endpoint.

    Salvare la chiave e l'endpoint per un ulteriore utilizzo.

  3. Selezionare Distribuzioni di modelli nel riquadro sinistro e selezionare Gestisci distribuzioni.

    Screenshot che mostra la distribuzione del modello per Azure OpenAI.

    Viene visualizzata la finestra di Azure OpenAI Studio.

  4. Selezionare Distribuzioni nel riquadro sinistro e selezionare + Crea nuova distribuzione.

    Screenshot che mostra le distribuzioni di modelli per Azure OpenAI.

  5. Selezionare i dettagli seguenti:

    1. Selezionare gpt-35-turbo dall'elenco a discesa Seleziona un modello .

      Nota

      Solo il modello gpt-35-turbo è supportato per il chat bot AI.

    2. Selezionare 0301 (impostazione predefinita) dall'elenco a discesa Versione modello .

    3. Immettere il nome della distribuzione e selezionare Crea.

      Screenshot che mostra il modello e la versione per la distribuzione di Azure OpenAI.

    4. Copiare e salvare il nome della distribuzione per un ulteriore utilizzo.

      Screenshot che mostra il nome della distribuzione di Azure OpenAI.

Aggiornare la chiave e gli endpoint di Azure OpenAI

  1. Apri il progetto in Visual Studio Code.

  2. In EXPLORER, vai al file env.env.playground.user>.

  3. Immettere il SECRET_AZURE_OPENAI_API_KEY e il SECRET_AZURE_OPENAI_ENDPOINT.

    ...
SECRET_AZURE_OPENAI_API_KEY=<azure-openai-api-key>
SECRET_AZURE_OPENAI_ENDPOINT=<azure-openai-endpoint>

  4. Vai al file app.jssrc>.

  5. Commentare il OpenAI codice e decommentarlo Azure OpenAI .

  6. Immettere il nome della distribuzione di Azure OpenAI in azureDefaultDeployment.

    
// Use OpenAI
// apiKey: config.openAIKey,
// defaultModel: "gpt-3.5-turbo",

azureApiKey: config.azureOpenAIKey,
azureDefaultDeployment: "gpt-35-turbo",
azureEndpoint: config.azureOpenAIEndpoint,

Esegui il debug e l'esecuzione dell'app chat bot IA

  1. Nel riquadro sinistro seleziona ESEGUI ed ESEGUI debug (CTRL+MAIUSC+D), quindi seleziona Esegui debug in Agents Playground dall'elenco a discesa.

    Screenshot che mostra l'opzione per selezionare il debug nel playground degli agenti.

  2. Agents Playground apre il tuo chat bot IA in una pagina web.

    Screenshot che mostra il bot aperto nello strumento di test.

Trigger di attività

Esistono due tipi di trigger di attività:

Trigger di attività predefiniti

Agents Playground fornisce trigger di attività predefiniti per testare le funzionalità del tuo bot.

Categoria Attività Gestore
Attivare l'attività di aggiornamento dell'installazione Bot di installazione


Bot di disinstallazione		 onInstallationUpdate
onInstallationUpdateAdded

onInstallationUpdate
onInstallationUpdateRemove
Attivare l'attività di aggiornamento della conversazione Aggiungere un utente


Aggiungi bot


Aggiungere un canale		 onMembersAdded
onTeamsMembersAddedEvent

onMembersAdded
onTeamsMembersAddedEvent

onTeamsChannelCreatedEvent
Rimuovi utente


Rimuovi bot


Rimuovi canale

Rimuovi team		 onMembersRemoved
onTeamsMembersRemovedEvent

onMembersRemoved
onTeamsMembersRemovedEvent

onTeamsChannelDeletedEvent

onTeamsTeamDeletedEvent
Rinomina canale

Rinomina il team		 onTeamsChannelRenamedEvent

onTeamsTeamRenamedEvent

Nota

Tutti i tipi di attività non sono disponibili in tutti gli ambiti. Ad esempio, non è possibile aggiungere o rimuovere un canale in una chat personale o in una chat di gruppo.

I trigger di attività predefiniti sono disponibili nel menu Simula un'attività in Agents Playground.

Per simulare un'attività di Add User , seguire questa procedura:

  1. In Agents Playground, vai a Simulare un'attività>Aggiungi utente.

    Screenshot che mostra l'opzione Aggiungi utente sotto Simula un'attività.

    Verrà visualizzata una finestra di dialogo che visualizza in anteprima il gestore attività.

  2. Seleziona Invia attività.

    Screenshot che mostra l'opzione per inviare attività per l'utente di aggiunta di attività fittizie predefinita.

    Il bot invia la risposta seguente:

    Screenshot che mostra la risposta dell'utente di aggiunta di attività fittizie predefinita.

Trigger di attività personalizzati

È possibile usare l'attività personalizzata per personalizzare i trigger di attività, ad esempio reactionsAdded per soddisfare i requisiti dell'app bot. Agents Playground compila automaticamente le proprietà richieste dell'attività. È inoltre possibile modificare il tipo di attività e aggiungere altre proprietà.

  1. Selezionare Simula un'attività>Attività personalizzata.

    Screenshot che mostra l'elenco delle opzioni in Simula un'attività.

  2. Aggiungi messageReaction per personalizzare l'attività nella type proprietà:

    {
    "type": "messageReaction",
    "reactionsAdded": [
    {
        "type": "like"
    }
    ],
    "replyToId": "d60fd1cb-3e8f-44ef-849c-404806ba1b47"
}

  3. Seleziona Invia attività.

    Screenshot che mostra l'opzione per inviare attività dopo la personalizzazione su attività fittizie.

    Il bot invia un onReactionsAdded gestore in risposta.

    Screenshot che mostra la risposta di un'attività fittizia personalizzata.

Sfida completa

Ti è venuto in mente un risultato come questo?

Screenshot che mostra il bot aperto nello strumento di test.

Congratulazioni! Hai creato correttamente un'app chat bot IA. Ora hai imparato a eseguire il debug della tua app di chat bot IA in Agents Playground.

Area giochi agenti di Microsoft 365

Inizio pagina

Inviare messaggi proattivi

Un messaggio proattivo è un messaggio inviato da un bot in risposta a semplici comandi inviati nella chat da un utente.


Esercitazione: Inviare messaggi proattivi

La risposta al messaggio può essere in uno dei formati seguenti:

  • Messaggi di benvenuto
  • Messaggi pianificati
  • Notifiche

Questa guida dettagliata consente di inviare un messaggio proattivo da un bot. Verrà visualizzato l'output seguente:

Screenshot che mostra il messaggio di benvenuto proattivo nella chat di Teams.

Prerequisiti

Assicurarsi di installare gli strumenti seguenti per la creazione e la distribuzione delle app.

  Installare Per l'uso
  Microsoft Visual Studio Code JavaScript o TypeScript, ambienti di compilazione. Usa la versione più recente.
  Microsoft 365 Agents Toolkit (in precedenza noto come Teams Toolkit) Estensione di Visual Studio Code che crea un'impalcatura di progetto per l'app. Usa la versione più recente.
  Node.js Ambiente di runtime JavaScript back-end. Per altre informazioni, vedere Node.js tabella di compatibilità delle versioni per il tipo di progetto.
  Microsoft Teams Teams per collaborare con tutti i tuoi collaboratori tramite app per chat, riunioni, chiamate e in un unico posto.
  Microsoft Edge (scelta consigliata) o Google Chrome Un browser con strumenti di sviluppo.
  Account sviluppatore di Microsoft 365 Accesso all'account di Teams con le autorizzazioni appropriate per installare un'app.

Preparare l'ambiente di sviluppo

Dopo aver installato gli strumenti necessari, configura l'ambiente di sviluppo.

Installare Microsoft 365 Agents Toolkit

Microsoft 365 Agents Toolkit (in precedenza noto come Teams Toolkit) aiuta a semplificare il processo di sviluppo con strumenti per il provisioning e la distribuzione di risorse cloud per l'app e la pubblicazione su Teams Store.

Puoi utilizzare Agents Toolkit con Visual Studio Code o un'interfaccia a riga di comando denominata Microsoft 365 Agents Toolkit CLI (in precedenza nota come CLI di TeamsFx).

  1. Apri Visual Studio Code e seleziona Estensioni (CTRL+MAIUSC+X o Visualizza>estensioni).

  2. Nella casella di ricerca, inserisci Microsoft 365 Agents Toolkit.

  3. Selezionare Installa.

    Screenshot che mostra l'installazione dell'estensione Agents Toolkit.

    L'icona di Microsoft 365 Agents Toolkit viene visualizzata nella barra delle attività di Visual Studio Code.

Puoi anche installare Agents Toolkit da Visual Studio Code Marketplace.

Configurare il tenant di sviluppo di Teams

Un tenant è uno spazio o un contenitore per l'organizzazione in Teams in cui si chatta, si condividono file ed si eseguono riunioni. Questo spazio è anche il luogo in cui carichi e testi la tua app. Verificare se si è pronti per lo sviluppo con il tenant.

Controlla l'opzione Carica un'app

Dopo aver creato l'app personalizzata, è necessario caricarla in Teams con l'opzione Carica un'app personalizzata . Accedere al proprio account Microsoft 365 per verificare se questa opzione è abilitata.

La procedura seguente consente di verificare se è possibile caricare app in Teams:

  1. Nel client Teams selezionare l'icona App .

  2. Seleziona Gestisci le tue app.

  3. Selezionare Carica un'app.

  4. Cerca l'opzione per caricare un'app personalizzata. Se l'opzione è visibile, è possibile caricare app personalizzate.

    Screenshot che mostra l'opzione per caricare un'app personalizzata in Teams.

    Nota

    Se non trovi l'opzione per caricare un'app personalizzata, contatta l'amministratore di Teams.

Creare un tenant di sviluppo di Teams gratuito (facoltativo)

Se non hai un account sviluppatore di Teams, partecipa al programma per sviluppatori di Microsoft 365.

  1. Passare al programma per sviluppatori di Microsoft 365.

  2. Seleziona Partecipa ora e segui le istruzioni sullo schermo.

  3. Nella schermata iniziale, seleziona Configura abbonamento E5.

  4. Configura il tuo account amministratore. Al termine, viene visualizzata la schermata seguente:

    Questo screenshot mostra il Programma per sviluppatori di Microsoft 365.

  5. Accedere a Teams con l'account amministratore appena configurato. Verificare di avere l'opzione Carica un'app personalizzata in Teams.

Bot di messaggistica proattiva

Per creare un bot di messaggi proattivo usando Visual Studio Code, segui questa procedura:

  1. Apri Visual Studio Code.

  2. Seleziona l'icona di Microsoft 365 Agents Toolkit nella barra delle attività di Visual Studio Code.

  3. Nel riquadro sinistro selezionare Visualizza esempi.

    Screenshot che mostra l'opzione Visualizza esempi nella barra delle attività di Visual Studio.

  4. Nell'elenco degli esempi, selezionare Messaggistica proattiva. Si apre un esempio predefinito, pronto per il debug.

    Screenshot che mostra l'esempio di bot di messaggistica proattiva predefinito nell'elenco di esempi.

  5. Selezionare Crea.

    Screenshot che mostra l'opzione Crea per creare un bot di messaggistica proattivo.

  6. Selezionare Cartella predefinita per archiviare la cartella principale del progetto nella posizione predefinita.

    Screenshot che mostra l'opzione per selezionare la posizione predefinita.

    Se si desidera modificare la posizione predefinita, eseguire i passaggi seguenti:

    1. Selezionare Sfoglia.

      Screenshot che mostra l'opzione per esplorare la posizione.

    2. Selezionare la posizione dell'area di lavoro del progetto.

    3. Selezionare Seleziona cartella.

      Screenshot che mostra l'opzione per selezionare la cartella.

    Il bot di messaggi proattivo viene creato in pochi secondi e visualizza la finestra di dialogo di conferma dell'esito positivo del messaggio proattivo nell'angolo in basso a destra con l'opzione per eseguire il debug:

    Screenshot che mostra il bot di messaggi proattivo creato. :::

  7. Seleziona l'icona Esegui ed esegui debug nell'angolo in alto a sinistra.

  8. Selezionare Debug (Edge) o Debug (Chrome) dall'elenco a discesa.

    Screenshot che mostra le opzioni di debug tra cui scegliere.

    Quando il debug ha esito positivo, viene richiesto di caricare il bot di messaggistica proattivo in Teams nel computer locale.

  9. Selezionare Aggiungi.

    Screenshot della finestra di dialogo dettagli estensione messaggio con l'opzione Aggiungi evidenziata.

  10. Cercare e selezionare l'ambito necessario oppure selezionare un canale, una chat o una riunione dall'elenco e spostarsi nella finestra di dialogo per selezionare Vai.

    Screenshot della finestra di dialogo per la selezione dell'ambito che mostra l'elenco degli ambiti condivisi.

    L'app bot di messaggi proattivi viene caricata nel client di Teams e in risposta al messaggio inviato viene visualizzato il messaggio seguente.

    Screenshot che mostra la risposta proattiva del bot dei messaggi nella chat.

  11. Copiare e incollare l'URL o passare all'URL nel browser. Un messaggio di benvenuto proattivo viene attivato e condiviso nella chat.

    Lo screenshot mostra il browser che attiva il bot per rispondere con un messaggio proattivo in Teams.

  12. Passare a Teams. Si riceverà un messaggio di benvenuto proattivo dal bot.

    Screenshot che mostra la risposta del bot nella chat.

Panoramica del codice sorgente

Agents Toolkit fornisce componenti per la creazione di un'app. Dopo aver creato il progetto, è possibile visualizzare le cartelle e i file del progetto nell'area EXPLORER di Visual Studio Code.

Screenshot che mostra la scheda Struttura.

La nuova cartella del progetto contiene il contenuto seguente:

Cartella/File Sommario
.vscode/ File di Visual Studio Code per il debug.
appManifest/ Modelli per il manifesto dell'app (in precedenza chiamato manifesto dell'app Teams).
env/ Le coppie nome/valore vengono archiviate nei file di ambiente e usate da m365agents.yml per personalizzare le regole di provisioning e distribuzione.
manifest.json Il manifesto dell'app per la pubblicazione tramite il portale per sviluppatori di Teams è archiviato in Properties/manifest.json.
m365agents.yml Il file di progetto principale descrive la configurazione dell'app e definisce il set di azioni da eseguire in ogni fase del ciclo di vita.
m365agents.local.yml Questa operazione sostituisce m365agents.yml le azioni che abilitano l'esecuzione e il debug locali.

Distribuire il bot di messaggi proattivo

Hai imparato a creare ed eseguire l'app di Teams con la funzionalità di messaggistica proattiva. Distribuiamo la prima app con funzionalità di bot di messaggi proattivi su Azure utilizzando Agents Toolkit.

Accedere all'account di Azure

Usare il proprio account per accedere al portale di Azure Microsoft ed effettuare il provisioning di nuove risorse cloud per supportare l'applicazione.

  1. Apri Visual Studio Code.

  2. Aprire la cartella del progetto in cui è stata creata l'app bot di messaggistica proattiva.

  3. Seleziona l'icona di Microsoft 365 Agents Toolkit nella barra delle attività di Visual Studio Code.

  4. Seleziona Accedi ad Azure usando le tue credenziali.

    Suggerimento

    Se è installata l'estensione ACCOUNT AZURE e si usa lo stesso account, è possibile ignorare questo passaggio.

    Il Web browser predefinito si apre per consentire l'accesso all'account.

  5. Chiudi il browser quando richiesto e torna a Visual Studio Code.

La sezione ACCOUNT della barra laterale mostra i due account separatamente. Elenca anche il numero di sottoscrizioni di Azure utilizzabili disponibili. Assicurarsi di avere almeno una sottoscrizione di Azure utilizzabile. In caso contrario, disconnettersi e usare un altro account.

Distribuire l'app in Azure

La distribuzione consiste in due passaggi. Innanzitutto, vengono create le risorse cloud necessarie (noto anche come provisioning). Quindi, il codice dell'app viene copiato nelle risorse cloud create. Per questa esercitazione si distribuirà l'app bot.

Qual è la differenza tra provisioning e distribuzione?
Il provisioning crea risorse in Azure e Microsoft 365 per l'app, ma non viene copiato alcun codice (HTML, CSS e JavaScript) nelle risorse.
Deploy copia il codice per l'app nelle risorse create durante il provisioning. È comune eseguire la distribuzione più volte senza eseguire il provisioning di nuove risorse. Poiché il provisioning può richiedere del tempo, il completamento è separato dalla distribuzione.

  1. Seleziona l'icona di Microsoft 365 Agents Toolkit nella barra delle attività di Visual Studio Code.

  2. Selezionare Provisioning in LIFECYCLE.

    Screenshot che mostra i comandi di provisioning.

  3. Seleziona uno degli abbonamenti esistenti.

    Screenshot che mostra l'opzione di sottoscrizione per il provisioning.

  4. Selezionare un gruppo di risorse esistente o crearne uno nuovo. Per altre informazioni, vedere Creare un gruppo di risorse.

    Screenshot che mostra l'opzione del gruppo di risorse per il provisioning.

    Nota

    Viene visualizzata una finestra di dialogo in cui viene indicato che potrebbero essere addebitati costi per l'esecuzione di risorse in Azure.

  5. Selezionare Provisioning.

    Screenshot della finestra di dialogo del provisioning.

    Il processo di provisioning crea risorse nel cloud di Azure. È possibile monitorare lo stato nelle finestre di dialogo visualizzate nell'angolo in basso a destra. Dopo alcuni minuti, viene visualizzata la seguente finestra di dialogo:

    Screenshot che mostra la finestra di dialogo di completamento del provisioning.

  6. Selezionare Distribuisci in LIFECYCLE.

    Screenshot che mostra l'opzione Deploy in LIFECYCLE.

  7. Seleziona Distribuisci.

    Screenshot che mostra la finestra di dialogo di conferma per la distribuzione.

    La distribuzione richiede del tempo. È possibile monitorare lo stato nelle finestre di dialogo visualizzate nell'angolo in basso a destra. Dopo alcuni minuti, viene visualizzata la finestra di dialogo seguente.

    Screenshot che mostra la finestra di dialogo di conferma della distribuzione.

  8. Apri il pannello di debug (Ctrl+MAIUSC+D / ⌘⇧-D o Visualizza>esecuzione) da Visual Studio Code.

  9. Selezionare Avvia remoto (Edge) dall'elenco a discesa configurazione avvio.

    Screenshot che mostra l'opzione debug remoto evidenziata.

    Quando il debug ha esito positivo, viene richiesto di caricare l'app bot di messaggi proattivi in Teams.

  10. Selezionare Aggiungi.

    Screenshot della finestra di dialogo dell'app Estensione messaggio con l'opzione Aggiungi evidenziata.

  11. Cercare e selezionare l'ambito necessario oppure selezionare un canale, una chat o una riunione dall'elenco e spostarsi nella finestra di dialogo per selezionare Vai.

    Screenshot che mostra la finestra di dialogo di selezione dell'ambito con l'elenco degli ambiti condivisi.

    L'app bot di messaggi proattivi viene caricata nel client di Teams e in risposta al messaggio inviato viene visualizzato il messaggio seguente.

    Screenshot che mostra la risposta proattiva del bot dei messaggi nella chat.

  12. Copiare e incollare l'URL o passare all'URL nel browser. Un messaggio di benvenuto proattivo viene attivato e condiviso nella chat.

    Lo screenshot mostra il browser che attiva il bot per rispondere con un messaggio proattivo in Teams.

  13. Passare a Teams. Si riceverà un messaggio di benvenuto proattivo dal bot.

    Screenshot che mostra la risposta del bot nella chat.

Sfida completa

Ti è venuta in mente una cosa del genere?

Lo screenshot mostra il messaggio di benvenuto proattivo.

Lo scenario è stato completato.

  • È possibile inviare notifiche su base giornaliera o richiedere feedback agli utenti su base periodica.
  • È possibile gestire i limiti di limitazione per evitare più notifiche.

Inviare messaggi proattivi

Inizio pagina

Creare un'estensione messaggio basata su API

Le estensioni dei messaggi create con l'API (basate su API) migliorano notevolmente la funzionalità delle app di Teams, consentendo loro di interagire con i servizi esterni. Le estensioni dei messaggi basate su API consentono di semplificare i flussi di lavoro riducendo la necessità di passare da un'applicazione all'altra.


Esercitazione: Creare un'estensione messaggio basata su API

Nota

Le estensioni dei messaggi basate su API supportano solo i comandi di ricerca.

È possibile utilizzare le estensioni dei messaggi basate su API per integrare servizi esterni comunemente utilizzati nel flusso di lavoro aziendale. Ad esempio, un'azienda che usa spesso un sistema CRM per la gestione dei clienti potrebbe utilizzare un'estensione messaggio per recuperare e visualizzare i dati dei clienti direttamente da Teams. Questa app consente di risparmiare tempo e migliorare l'efficienza riducendo la necessità di passare da un'applicazione all'altra. Questa funzionalità è supportata in tutte le piattaforme in cui Teams è disponibile, tra cui desktop, Web e dispositivi mobili.

Prerequisiti per la creazione di un'estensione messaggio

Ecco un elenco degli strumenti necessari per la creazione e la distribuzione delle app.

Installare Per l'utilizzo...
Microsoft Teams Microsoft Teams per collaborare con tutti i tuoi collaboratori tramite app per chat, riunioni o chiamate, in un unico posto.
Microsoft Edge (scelta consigliata) o Google Chrome Un browser con strumenti di sviluppo.
Visual Studio Code Ambienti di compilazione JavaScript, TypeScript o SharePoint Framework (SPFx). Usare la versione 1.55 o successiva.
Account sviluppatore di Microsoft 365 Accesso all'account di Teams con le autorizzazioni appropriate per installare un'app.
Account di Azure Accesso alle risorse di Azure.
Documento OpenAPI Description (OAD) Un documento che descrive le funzionalità della tua API. Per ulteriori informazioni, vedere Descrizione di OpenAPI.

Configurare il tenant di sviluppo di Teams

Un tenant è come uno spazio o un contenitore per l'organizzazione in Teams, in cui si chatta, si condividono file ed si eseguono riunioni. Questo spazio è anche il luogo in cui carichi e testi la tua app personalizzata. Verificare se si è pronti per lo sviluppo con il tenant.

Controllare l'opzione di caricamento dell'app personalizzata

Dopo aver creato l'app, è necessario caricarla in Teams senza distribuirla. Questo processo è noto come caricamento di app personalizzate. Accedi al tuo account Microsoft 365 per visualizzare questa opzione.

Nota

Il caricamento delle app personalizzate è necessario per visualizzare in anteprima e testare le app nell'ambiente locale di Teams. Se non è abilitato, non è possibile visualizzare in anteprima e testare l'app nell'ambiente locale di Teams.

Si ha già un tenant e si dispone dell'accesso come amministratore? Controlliamo se lo sai davvero!

Verificare se è possibile caricare un'app personalizzata in Teams:

  1. Nel client Teams selezionare l'icona App .

  2. Seleziona Gestisci le tue app.

  3. Selezionare Carica un'app.

  4. Cerca l'opzione per caricare un'app personalizzata. Se viene visualizzata l'opzione, il caricamento di app personalizzate è abilitato.

    Screenshot che mostra la home page del bot.

Nota

Se non trovi l'opzione per caricare un'app personalizzata, contatta l'amministratore di Teams.

Creare un tenant di sviluppo di Teams gratuito (facoltativo)

Se non hai un account sviluppatore di Teams, puoi ottenerlo gratuitamente. Partecipa al programma per sviluppatori di Microsoft 365!

  1. Passare al programma per sviluppatori di Microsoft 365.

  2. Seleziona Partecipa ora e segui le istruzioni sullo schermo.

  3. Nella schermata iniziale, seleziona Configura abbonamento E5.

  4. Configura il tuo account amministratore. Al termine, viene visualizzata la schermata seguente.

    Lo screenshot mostra il Programma per sviluppatori di Microsoft 365.

  5. Accedere a Teams con l'account amministratore appena configurato. Verificare di avere l'opzione Carica un'app personalizzata in Teams.

Ottenere un account di Azure gratuito

Se si vuole ospitare l'app o accedere alle risorse in Azure, è necessario avere una sottoscrizione di Azure. Crea un account gratuito prima di iniziare.

Hai tutti gli strumenti per configurare il tuo account. Quindi, configuriamo il tuo ambiente di sviluppo e iniziamo a costruire! Selezionare l'app che si desidera creare per prima.

Creare un documento di descrizione OpenAPI

OpenAPI Description (OAD) è la specifica standard del settore che delinea come sono strutturati e delineati i file OpenAPI. Si tratta di un formato leggibile e indipendente dal linguaggio per descrivere le API. Leggere e scrivere è facile sia per gli esseri umani che per le macchine. Lo schema è leggibile dal computer e rappresentato in YAML o JSON.

Per interagire con le API è necessario un documento di descrizione OpenAPI. Il documento Descrizione OpenAPI deve soddisfare i seguenti criteri:

  • La auth proprietà non deve essere specificata.

  • JSON e YAML sono i formati supportati.

  • Sono supportate le versioni 2.0 e 3.0.x di OpenAPI.

  • Teams non supporta i costrutti oneOf, anyOf, allOf e not (swagger.io).

  • La creazione di array per la richiesta non è supportata, tuttavia sono supportati gli oggetti annidati all'interno di un corpo della richiesta JSON.

  • Il corpo della richiesta, se presente, deve essere application/JSON per garantire la compatibilità con un'ampia gamma di API.

  • Definire un URL del server del protocollo HTTPS per la servers.url proprietà.

  • È supportata solo la ricerca con un singolo parametro.

  • È consentito un solo parametro obbligatorio senza un valore predefinito.

  • Sono supportati solo i metodi POST e GET HTTP.

  • Il documento OpenAPI Description deve avere un file .operationId

  • L'operazione non deve richiedere parametri Header o Cookie senza valori predefiniti.

  • Un comando deve avere esattamente un parametro.

  • Assicurarsi che non siano presenti riferimenti remoti nel documento Descrizione OpenAPI.

  • Un parametro obbligatorio con un valore predefinito è considerato facoltativo.

    Abbiamo usato la seguente descrizione OpenAPI come esempio per questa esercitazione:

    Descrizione OpenAPI 
        openapi: 3.0.1
    info:
    title: OpenTools Plugin
    description: A plugin that allows the user to find the most appropriate AI tools for their use cases, with their pricing information.
    version: 'v1'
    servers:
        - url: https://gptplugin.opentools.ai
    paths:
    /tools:
    get:
    operationId: searchTools
    summary: Search for AI Tools
        parameters:
        - in: query
          name: search
          required: true
          schema:
          type: string
          description: Used to search for AI tools by their category based on the keywords. For example, a search for "tool to create music" provides a list of tools that can create music.
        responses:
        "200":
          description: OK
          content:
          application/json:
            schema:
            $ref: '#/components/schemas/searchToolsResponse'
        "400":
          description: Search Error
          content:
          application/json:
            schema:
            ref: '#/components/schemas/searchToolsError'
        components:
        schemas:
        searchToolsResponse:
        required:
        - search
        type: object
        properties:
        tools:
        type: array
        items:
        type: object
        properties:
        name:
        type: string
        description: The name of the tool.
        opentools_url:
        type: string
        description: The URL to access the tool.
        main_summary:
        type: string
        description: A summary of what the tool is.
        pricing_summary:
        type: string
        description: A summary of the pricing of the tool.
        categories:
        type: array
        items:
        type: string
        description: The categories assigned to the tool.
        platforms:
        type: array
        items:
        type: string
        description: The platforms that this tool is available on.
        description: The list of AI tools.
        searchToolsError:
        type: object
        properties:
        message:
        type: string
        description: Message of the error.

    Nota

    Assicurarsi che la required: true proprietà sia disponibile per un solo parametro. Se sono presenti più parametri obbligatori, è possibile aggiornare la proprietà required per required: false gli altri parametri.

È possibile verificare se il documento Descrizione OpenAPI è valido. Per verificare, attenersi alla seguente procedura:

  1. Vai a Swagger o OpenAPI validator e convalida il documento OpenAPI Description.

  2. Salvare il documento di descrizione di OpenAPI.

  3. Vai a Editor Swagger.

  4. Nel riquadro sinistro incollare la Descrizione OpenAPI nell'editor.

  5. Nel riquadro di destra selezionare GET.

  6. Seleziona Prova.

  7. Inserisci i valori per il parametro di ricerca come Strumento per creare musica.

  8. Seleziona Esegui. L'editor di Swagger visualizza una risposta con un elenco di prodotti.

    Screenshot che mostrano i parametri, i relativi valori e l'opzione **EXECUTE** nell'editor di swagger.

  9. Passare alcorpo della rispostadella risposta> del server.

  10. In , productscopiare il primo prodotto dall'elenco e salvarlo per riferimento futuro.

    Screenshot mostra il prodotto evidenziato selezionato dal corpo della risposta.

Crea modello di rendering della risposta

Un documento di descrizione OpenAPI richiede un modello di rendering delle risposte affinché l'app risponda alle richieste GET o POST. Il modello di rendering della risposta è costituito da un modello di scheda adattiva, un modello di scheda di anteprima e metadati.

Modello di scheda adattiva

Per creare un modello di scheda adattiva, effettuate le seguenti operazioni:

  1. Vai a ChatGPT e poni la seguente query nell'area di composizione del messaggio:

    
Create an Adaptive Card Template that binds to the following response:
    "categories": [
        "Music Generation",
        "AI Detection"
    ],
    "chatbot_short_url": "https://goto.opentools.ai/c/ai-music-generator",
    "main_summary": "AI Music Generator is an AI-powered music composing tool that allows users to create original and personalized music for various purposes. It can generate melodies, harmonies, and rhythms tailored to specific needs and preferences, with customization options such as genre, mood, length, and instrumentation. The tool is designed for creative individuals, from beginners to professionals, and can produce high-quality music in seconds. Every generated piece of music is royalty-free and can be used instantly, with no limitations on beat creation. With advanced AI technology, AI Music Generator makes music production accessible to everyone.",
    "name": "AI Music Generator",
    "opentools_url": "https://goto.opentools.ai/ai-music-generator",
    "platforms": [
        "Web",
        "App",
        "API"
    ]

  2. Seleziona Invia messaggio.

  3. ChatGPT genera una risposta con un modello di scheda adattiva che si associa ai dati di esempio. Salva il modello di scheda adattiva per riferimento futuro.

    Di seguito è riportato un esempio del modello Scheda adattiva:

    Modello di scheda adattiva 
    
{
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
"type": "AdaptiveCard",
"version": "1.4",
"body": [
    {
    "type": "TextBlock",
    "text": "AI Music Generator",
    "weight": "Bolder",
    "size": "Large"
    },
    {
    "type": "TextBlock",
    "text": "Categories",
    "size": "Medium"
    },
    {
    "type": "TextBlock",
     "text": "Music Generation, AI Detection",
     "wrap": true
    },
    {
    "type": "TextBlock",
    "text": "Description",
    "size": "Medium"
    },
    {
    "type": "TextBlock",
    "text": "AI Music Generator is an AI-powered music composing tool that allows users to create original and personalized music for various purposes. It can generate melodies, harmonies, and rhythms tailored to specific needs and preferences, with customization options such as genre, mood, length, and instrumentation. The tool is designed for creative individuals, from beginners to professionals, and can produce high-quality music in seconds. Every generated piece of music is royalty-free and can be used instantly, with no limitations on beat creation. AI Music Generator is powered by advanced AI technology, and it makes music production accessible to everyone.",
    "wrap": true
    },
    {
    "type": "TextBlock",
    "text": "Platform",
    "size": "Medium"
    },
    {
    "type": "TextBlock",
    "text": "Web, App, API",
    "wrap": true
    }
],
"actions": [
    {
    "type": "Action.OpenUrl",
    "title": "Learn More",
    "url": "https://goto.opentools.ai/ai-music-generator"
    },
    {
    "type": "Action.OpenUrl",
    "title": "Try It",
    "url": "https://goto.opentools.ai/c/ai-music-generator"
    }
]
}

  4. Per verificare se la scheda adattiva generata si associa ai dati di esempio, effettuate le seguenti operazioni:

    1. Vai ad Adaptive Card Designer.

    2. Passare a Seleziona app host e quindi selezionare Microsoft Teams nell'elenco a discesa.

    3. Vai a CARD PAYLOAD EDITOR e incolla il codice del modello di Adaptive Card.

    4. Vai a EDITOR DATI DI ESEMPIO e incolla la risposta GET API salvata in precedenza.

      Screenshot che mostrano la finestra di progettazione della scheda adattiva con il modello Scheda adattiva e i dati di esempio.

    5. Seleziona la modalità Anteprima. La finestra di progettazione della scheda adattiva visualizza una scheda adattiva con i dati che associano la risposta al modello.

      Screenshot che mostra la finestra di progettazione della scheda adattiva con il modello Scheda adattiva e i dati di esempio.

Crea un modello di biglietto di anteprima

Il modello di scheda di anteprima può contenere a titlesubtitle, e proprietàimage. Se la risposta dell'API non ha un'immagine, puoi rimuovere la proprietà dell'immagine.

Di seguito è riportato un esempio di modello di biglietto in anteprima:

Modello di biglietto in anteprima 
   "previewCardTemplate": {
        "title": "${if(name, name, 'N/A')}",
        "subtitle": "$${if(price, price, 'N/A')}"
    }

Creare una condizione SE per e titlesubtitle, dove:

  • Se il nome esiste, il bot usa il nome.
  • Se il nome non esiste, il bot usa NA.

Ad esempio, "title": "Name: ${if(name, name, 'N/A')}". Salva il modello di scheda di anteprima per riferimento futuro.

Modello di rendering delle risposte

Il modello di rendering della risposta deve essere conforme allo schema ospitato in https://developer.microsoft.com/json-schemas/teams/v1.20/MicrosoftTeams.ResponseRenderingTemplate.schema.json.

Per creare un modello di rendering di risposta, segui questi passaggi:

  1. Crea un file JSON e aggiungi il seguente codice al file:

    { 
  "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.20/MicrosoftTeams.ResponseRenderingTemplate.schema.json", 
  "version": "1.0", 
  "jsonPath": "", 
  "responseLayout": "", 
  "responseCardTemplate": { 
 },
 "previewCardTemplate": {
     }
 }

  2. Aggiorna le proprietà nel modello di rendering della risposta come indicato di seguito:

    # Nome della proprietà Value
    1. "$schema" "https://developer.microsoft.com/json-schemas/teams/v1.20/MicrosoftTeams.ResponseRenderingTemplate.schema.json"
    2. "version" "1.0"
    version è la versione del modello di rendering da usare.
    3. "jsonPath" "tools"
    jsonPath è il percorso di uno o più risultati nella risposta JSON della risposta. Aggiungi il jsonPath ai dati/array pertinenti dall'elenco dei prodotti nella risposta dell'API. In questo caso, gli jsonPath strumenti is. Per altre informazioni su come determinare il percorso JSON, vedere Esecuzione di query su JSON con percorso JSON.
    4. "responseLayout" "list"
    responseLayout Specifica il layout degli allegati. Usato per le risposte di tipo risultato. I tipi supportati sono elenco e griglia. Se il corpo della risposta contiene un oggetto con più elementi come testo, titolo e immagine, il layout della risposta deve essere impostato su list. Se la risposta dell'API contiene solo immagini o miniature, il layout della risposta deve essere impostato su grid.
    5. "responseCardTemplate" Incolla il codice del modello di scheda adattiva salvato in precedenza.
    responseCardTemplate è un modello di scheda adattiva per eseguire il mapping della risposta JSON a una scheda adattiva.
    6. "previewCardTemplate" Incolla il codice del modello di biglietto di anteprima salvato in precedenza.
    previewCardTemplate è un modello di scheda di anteprima che viene usato per visualizzare un'anteprima dei risultati nel riquadro a comparsa dell'estensione messaggio.

  3. Salva il modello di rendering della risposta nella stessa cartella in cui hai salvato il documento OpenAPI Description.

Il codice seguente è un esempio di modello di rendering delle risposte:

Modello di rendering delle risposte 

{
    "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.20/MicrosoftTeams.ResponseRenderingTemplate.schema.json",
    "version": "1.0",
    "jsonPath": "tools",
    "responseLayout": "list",
    "responseCardTemplate": {
        "type": "AdaptiveCard",
        "version": "1.4",
        "body": [
            {
            "type": "TextBlock",
            "text": "AI Music Generator",
            "weight": "Bolder",
            "size": "Large"
            },
            {
            "type": "TextBlock",
            "text": "Categories",
            "size": "Medium"
            },
            {
            "type": "TextBlock",
            "text": "Music Generation, AI Detection",
            "wrap": true
            },
            {
            "type": "TextBlock",
            "text": "Description",
            "size": "Medium"
            },
            {
            "type": "TextBlock",
            "text": "AI Music Generator is an AI-powered music composing tool that allows users to create original and personalized music for various purposes. It can generate melodies, harmonies, and rhythms tailored to specific needs and preferences, with customization options such as genre, mood, length, and instrumentation. The tool is designed for creative individuals, from beginners to professionals, and can produce high-quality music in seconds. Every generated piece of music is royalty-free and can be used instantly, with no limitations on beat creation. With advanced AI technology, AI Music Generator makes music production accessible to everyone.",
            "wrap": true
            },
            {
            "type": "TextBlock",
            "text": "Platform",
            "size": "Medium"
            },
            {
            "type": "TextBlock",
            "text": "Web, App, API",
            "wrap": true
            }
        ],
        "actions": [
            {
            "type": "Action.OpenUrl",
            "title": "Learn More",
            "url": "https://goto.opentools.ai/ai-music-generator"
            },
            {
            "type": "Action.OpenUrl",
            "title": "Try It",
            "url": "https://goto.opentools.ai/c/ai-music-generator"
            }
        ]
    },
    "previewCardTemplate": {
        "title": "${if(name, name, 'N/A')}",
        "subtitle": "$${if(price, price, 'N/A')}"
    } 
}

Creare il manifesto dell'app

Ora è necessario creare un manifesto dell'app (in precedenza chiamato manifesto dell'app Teams). Il manifesto dell'app descrive come si integra l'app nel prodotto Microsoft Teams.

Creare un manifesto dell'app Teams

Per creare il manifesto, seguire questa procedura:

  1. Crea un nuovo file JSON. Il manifesto dell'app deve essere conforme alla versione 1.20 dello schema definito nello schema del manifesto dell'app.

  2. Aggiungi il seguente codice al file JSON:

    Manifesto dell'app 
    {
 "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.20/MicrosoftTeams.schema.json",
 "manifestVersion": "1.20",
 "version": "1.0.3",
 "id": "<<YOUR-MICROSOFT-APP-ID>>",
 "packageName": "com.microsoft.teams.extension",
 "developer": {
     "name": "Teams App, Inc.",
     "websiteUrl": "https://www.example.com",
     "privacyUrl": "https://www.example.com/termofuse",
     "termsOfUseUrl": "https://www.example.com/privacy"
 },
 "icons": {
     "color": "color.png",
     "outline": "outline.png"
 },
 "name": {
     "short": "Search ME API",
     "full": "Search ME API full"
 },
 "description": {
     "short": "product app for testing API Message Extensions",
     "full": "product app for testing API Message Extensions"
 },
 "accentColor": "#FFFFFF",
 "composeExtensions": [
     {
         "composeExtensionType": "",
         "apiSpecificationFile": "",
         "commands": [
             {
                 "context": [
                     "compose"
                 ],
                 "type": "query",
                 "title": "API for fetching Klarna.",
                 "id": "",
                 "parameters": [
                     {
                         "name": "",
                         "title": "",
                         "description": ""
                     }
                 ],
                 "description": "",
                 "apiResponseRenderingTemplateFile": ""
             }
         ]
     }
 ],
 "permissions": [
     "identity",
     "messageTeamMembers"
 ],
 "validDomains": []
}

  3. Aggiorna le proprietà del manifesto dell'app come indicato di seguito:

    • Sostituire <<YOUR-MICROSOFT-APP-ID>> con l'ID dell'app Microsoft del bot.
    • Aggiornare il valore di composeExtensionType per .apiBased
    • Aggiornare il valore per apiSpecificationFile il percorso del file di descrizione di OpenAPI.
    • Aggiornare il valore di commands.id per .searchTools
    • Aggiornare il valore di commands.title per .Search for AI Tools
    • Aggiornare il valore di commands.description per .Search for AI Tools
    • Aggiornare il valore di parameters.name per .search Se non sono presenti parametri, i valori devono essere parametri di query o properties.name se si fa riferimento a una proprietà nello schema del corpo della richiesta.
    • Aggiorna il apiResponseRenderingTemplateFile percorso del file del modello di rendering della risposta.
    • Aggiornare il valore per validDomains l'endpoint service URL definito nel file di descrizione di OpenAPI.

  4. Salvare il manifesto dell'app di Teams nella stessa cartella in cui sono stati salvati, il documento di descrizione OpenAPI e il modello di rendering della risposta.

    • Hai bisogno di un'immagine a colori e di un'immagine di contorno. Queste immagini devono essere incluse nella cartella e referenziate nel manifesto dell'app Teams.

    • Comprimere il contenuto della cartella. Il file ZIP deve includere i file seguenti:

      • Documento di descrizione di OpenAPI
      • Modello di rendering delle risposte
      • Manifesto dell'app
      • Icona a colori
      • Icona Struttura

Caricare un'app personalizzata in Teams

Accedere all'ambiente di test di Teams per testare l'app in Teams. Per caricare un'app personalizzata in Teams, seguire questa procedura:

  1. Passare a Microsoft Teams e accedere con le credenziali del tenant di test.

  2. Vai a : Gestisci>la tua app>: Carica un'app.

  3. Selezionare Carica un'app personalizzata.

  4. Seleziona il file zip creato e seleziona Apri.

  5. Selezionare Aggiungi.

    Screenshot dell'app di estensione del messaggio con l'opzione Aggiungi evidenziata.

  6. Scegliere Apri.

    Screenshot dell'app di estensione del messaggio con l'opzione Apri evidenziata.

  7. Passare a una chat, quindi selezionare + dall'area di composizione dei messaggi e cercare l'app.

  8. Selezionare l'app ed eseguire una query di ricerca.

    Lo screenshot mostra che dall'icona più nel menu chat gli utenti possono richiamare l'app di estensione del messaggio visualizzata nel menu a comparsa.

  9. L'app risponde con un Adaptive Card nella finestra della chat.

  10. Selezionare Invia.

    Screenshot che mostra la scheda adattiva con i risultati della ricerca nel messaggio di chat in Teams.

Congratulazioni! Ce l'hai fatta! Hai imparato a creare un'estensione del messaggio basata su API utilizzando il documento di descrizione di OpenAPI.

Creare un'estensione messaggio basata su API

Inizio pagina

Crea un'estensione messaggio basata sull'azione

L'estensione del messaggio basata sull'azione di Teams consente agli utenti di interagire con i servizi Web nel client Microsoft Teams. Le estensioni dei messaggi consentono di avviare azioni in un sistema esterno dall'area di composizione dei messaggi, dalla casella di comando o direttamente da un messaggio.


Esercitazione: Creare un'estensione messaggio basata sulle azioni

Caratteristiche principali dell'estensione del messaggio basata sull'azione:

  • Presenta all'utente un pop-up modale per raccogliere o visualizzare informazioni.
  • Attiva i comandi di azione dall'area di composizione del messaggio, dalla casella dei comandi o da un messaggio.

Questa guida dettagliata consente di creare un'estensione messaggio basata sull'azione di Teams per avviare azioni dalla composizione del messaggio e dall'area dei messaggi. Alla fine di questo tutorial, puoi ottenere l'output seguente:

Screenshot dell'output dell'estensione messaggio dopo aver completato la guida dettagliata.

Prerequisiti

Assicurati di installare gli strumenti seguenti e di configurare l'ambiente di sviluppo:

  Installare Per l'utilizzo...
  Microsoft Teams Microsoft Teams per collaborare con tutti i tuoi collaboratori tramite app per chat, riunioni e chiamate, in un unico posto.
  Visual Studio 2022 È possibile installare la versione enterprise in Visual Studio 2022 e installare i carichi di lavoro di sviluppo ASP.NET e Web. Usa la versione più recente.
  .NET Core SDK Associazioni personalizzate per il debug locale e le distribuzioni di app Funzioni di Azure. Se non è installata la versione più recente, installare la versione portatile.
  Tunnel di sviluppo Le funzionalità dell'app Teams (bot conversazionali, estensioni dei messaggi e webhook in ingresso) richiedono connessioni in ingresso. Un tunnel connette il sistema di sviluppo a Teams. Dev tunnel è un potente strumento per aprire in modo sicuro il tuo localhost a Internet e controllare chi ha accesso. Il tunnel di sviluppo è disponibile in Visual Studio 2022 versione 17.7.0 o successiva.
oppure
È possibile usare ngrok anche come tunnel per connettere il sistema di sviluppo a Teams. Non è necessario per le app che includono solo schede. Questo pacchetto è installato all'interno della directory del progetto (usando npm devDependencies).

Nota

Dopo aver scaricato ngrok, registrati e installa authtoken.

Configurare l'ambiente locale

  1. Apri Microsoft-Teams-samples.

  2. Selezionare il codice.

  3. Nel menu a discesa selezionare Apri con GitHub Desktop.

    Screenshot che mostra l'opzione per clonare il repository in locale.

  4. Seleziona Clona.

Registra l'app Microsoft Entra

La procedura seguente consente di creare e registrare il bot nel portale di Azure:

  • Creare e registrare l'app di Azure.
  • Creare un segreto client per abilitare l'autenticazione SSO del bot.
  • Aggiungere il canale Teams per distribuire il bot.
  • Crea un tunnel per gli endpoint del server Web usando Dev Tunnel (consigliato) o NGREK.
  • Aggiungere l'endpoint di messaggistica al tunnel di sviluppo creato.

Aggiungere la registrazione dell'app

  1. Passare al portale di Azure.

  2. Selezionare Registrazioni app.

    Screenshot che mostra i servizi di Azure per selezionare Registrazioni app.

  3. Selezionare + Nuova registrazione.

    Screenshot che mostra la pagina Nuova registrazione in Interfaccia di amministrazione di Microsoft Entra.

  4. Immettere il nome dell'app.

  5. Selezionare gli account in qualsiasi directory organizzativa (qualsiasi tenant Microsoft Entra ID - multitenant).

  6. Seleziona Registrati.

    Screenshot che mostra l'opzione per registrare il bot nell'interfaccia di amministrazione di Microsoft Entra.

    L'app è registrata in Microsoft Entra ID. Viene visualizzata la pagina Panoramica app.

    Screenshot che mostra la pagina di panoramica della registrazione dell'app.

    Nota

    Salvare l'ID app dall'ID applicazione (client) e dall'ID directory (tenant) per un ulteriore utilizzo.

Creare un tunnel

Seguire uno dei due metodi seguenti per creare un tunnel.

  1. Aprire Visual Studio.

  2. Seleziona Crea un nuovo progetto.

    Screenshot che mostra la selezione per creare un nuovo progetto.

  3. Nella casella di ricerca immettere ASP.NET. Nei risultati della ricerca selezionare App Web ASP.NET Core.

  4. Selezionare Avanti.

    Screenshot che mostra la ricerca e la selezione del modello.

  5. Immettere il nome del progetto e selezionare Avanti.

    Screenshot che mostra il nome del progetto da inserire.

  6. Selezionare Crea.

    Screenshot che mostra le informazioni aggiuntive del progetto.

    Viene visualizzata una finestra di panoramica.

    Screenshot che mostra la finestra panoramica.

  7. Nell'elenco a discesa debug, selezionare Tunnel di sviluppo (nessun tunnel attivo)>Crea un tunnel....

    Screenshot che mostra l'elenco a discesa per selezionare i tunnel dev.

    Viene visualizzata una finestra popup.

  8. Aggiorna i seguenti dettagli nella finestra popup:

    1. Account: immetti un account Microsoft o GitHub.
    2. Nome: immettere un nome per il tunnel.
    3. Tipo di tunnel: dall'elenco a discesa, selezionare Temporaneo.
    4. Accesso: dall'elenco a discesa, selezionare Pubblico.

  9. Selezionare OK.

    Screenshot che mostra i dettagli da aggiornare per la creazione del tunnel.

    Viene visualizzata una finestra popup che mostra che il tunnel di sviluppo è stato creato correttamente.

  10. Selezionare OK.

    Lo screenshot mostra il messaggio popup che indica che il tunnel è stato creato.

    È possibile trovare il tunnel creato nell'elenco a discesa di debug come segue:

    Lo screenshot mostra che il tunnel è attivo e selezionato.

  11. Selezionare F5 per eseguire l'applicazione in modalità di debug.

  12. Se viene visualizzata una finestra di dialogo Avviso di sicurezza , selezionare Sì.

    Screenshot che mostra la finestra di dialogo per accettare l'avviso di sicurezza.

    Viene visualizzata una finestra popup.

  13. Selezionare Continua.

    Screenshot che mostra l'URL del tunnel.

    La home page di Dev Tunnel si apre in una nuova finestra del browser e Dev Tunnel è ora attivo.

    Screenshot che mostra la pagina di benvenuto di Dev Tunnel nel browser.

  14. Passare a Visual Studio, selezionare Visualizza > output.

  15. Dal menu a discesa della console di output , seleziona Dev Tunnel.

    La console di output mostra l'URL del tunnel di sviluppo.

    Screenshot che mostra l'URL nella console di output di Visual Studio.

Aggiungere l'autenticazione Web

  1. Nel riquadro sinistro, in Gestisci, selezionare Autenticazione.

  2. Selezionare Aggiungi una piattaforma>Web.

    Screenshot che mostra la selezione dell'autenticazione Web.

  3. Immettere l'URI di reindirizzamento per l'app aggiungendolo auth-end al nome di dominio completo. Ad esempio, https://your-devtunnel-domain/auth-end o https://your-ngrok-domain/auth-end.

  4. In Concessione implicita e flussi ibridi selezionare le caselle di controllo Token di accesso e Token ID .

  5. Selezionare Configura.

    Screenshot che mostra l'opzione per aggiungere l'URI di reindirizzamento e selezionare la concessione implicita e i flussi ibridi.

  6. In Web selezionare Aggiungi URI.

  7. Immettere https://token.botframework.com/.auth/web/redirect.

  8. Selezionare Salva.

    Screenshot che mostra l'opzione per aggiungere l'URI di reindirizzamento e selezionare la concessione implicita e i flussi ibridi.

Creare un segreto client

Nota

Se viene visualizzato l'errore, i segreti client vengono bloccati dai criteri a livello di tenant. Per altre informazioni, contattare l'amministratore del tenant, è possibile creare un certificato. Per istruzioni dettagliate, fare riferimento a Creare un certificato per la registrazione dell'app.

  1. Nel riquadro sinistro, in Gestisci, seleziona Certificati & segreti.

  2. In Segreti client selezionare + Nuovo segreto client.

    Screenshot che mostra la selezione del nuovo segreto client.

    Viene visualizzata la finestra Aggiungi un segreto client .

  3. Immettere la descrizione.

  4. Selezionare Aggiungi.

    Screenshot che mostra l'opzione di descrizione del segreto client per aggiungerla.

  5. In Valore, selezionare Copia negli Appunti per salvare il valore del segreto client per un ulteriore utilizzo.

    Screenshot che mostra l'opzione per copiare il valore dell'ID segreto client per copiare il valore negli Appunti.

Aggiungere autorizzazioni API

  1. Nel riquadro sinistro selezionare Autorizzazioni API.

  2. Selezionare + Aggiungi un'autorizzazione.

    Screenshot che mostra l'opzione per selezionare Aggiungi autorizzazione.

  3. Selezionare Microsoft Graph.

  4. Selezionare Autorizzazioni delegate.

  5. Selezionare Utente>User.Read.

  6. Selezionare Aggiungi autorizzazioni.

    Screenshot che mostra l'opzione per selezionare le autorizzazioni.

    Nota

    • Se a un'app non viene concesso il consenso dell'amministratore IT, gli utenti devono fornire il consenso la prima volta che usano un'app.
    • Gli utenti devono acconsentire alle autorizzazioni API solo se l'app Microsoft Entra è registrata in un tenant diverso.

Aggiungere l'URI ID applicazione

  1. Nel riquadro sinistro, in Gestisci, selezionare Esponi un'API.

  2. Accanto a URI ID applicazione selezionare Aggiungi.

    Screenshot che mostra l'opzione per aggiungere l'ID applicazione URI per l'app.

  3. Aggiornare l'URI dell'ID applicazione nel api://botid-{AppID} formato e selezionare Salva.

    Screenshot che mostra l'opzione per aggiungere l'ID dell'app URI e salvare.

Aggiungere un ambito

  1. Nel riquadro sinistro, in Gestisci, selezionare Esponi un'API.

  2. Selezionare + Aggiungere un ambito.

    Screenshot che mostra la selezione per aggiungere un ambito.

  3. Immetti access_as_user come nome dell'ambito.

  4. In Chi può fornire il consenso?, selezionare Amministratori e utenti.

  5. Aggiornare i valori per il resto dei campi come indicato di seguito:

    • Invio Teams può accedere al profilo dell'utente come nome visualizzato con il consenso dell'Amministratore.

    • INVIO Consente a Teams di chiamare le API Web dell'app come utente corrente come descrizione del consenso dell'Amministratore.

    • Invio Teams può accedere al profilo utente ed effettuare richieste per conto dell'utente come nome visualizzato per il consenso dell'utente.

    • Invio Consenti a Teams di chiamare le API di questa app con gli stessi diritti dell'utente della descrizione delconsenso dell'utente.

  6. Assicurati che lo stato sia impostato su Abilitato.

  7. Selezionare Aggiungi ambito.

    La figura seguente mostra i campi e i valori:

    Screenshot che mostra i valori compilati nel campo per Aggiungere un ambito.

    Nota

    Il nome dell'ambito deve corrispondere all'ID applicazione URI, con /access_as_user l'aggiunta alla fine.

    Screenshot che mostra i dettagli negli ambiti.

Aggiungere un'applicazione client

  1. Nel riquadro sinistro, in Gestisci, selezionare Esponi un'API.

    In Applicazioni client autorizzate identificare le applicazioni che si desidera autorizzare per l'applicazione Web dell'app.

  2. Selezionare + Aggiungi un'applicazione client.

    Screenshot che mostra l'opzione Seleziona applicazione client.

  3. Aggiungere Teams per dispositivi mobili o desktop e l'applicazione Web di Teams.

    1. Per Teams per dispositivi mobili o desktop: immettere l'ID client come 1fec8e78-bce4-4aaf-ab1b-5451cc387264.

      Screenshot che mostra l'applicazione ID client per dispositivi mobili o desktop.

    2. Per Teams Web: immettere l'ID client come 5e3ce6c0-2b1f-4285-8d4b-75ee78787346.

      Screenshot che mostra l'applicazione ID client Web.

  4. Selezionare la casella di controllo Ambiti autorizzati .

  5. Selezionare Aggiungi applicazione.

    Screenshot che mostra l'opzione per selezionare gli ambiti autorizzati e aggiungere l'applicazione.

    L'immagine seguente mostra l'ID client:

    Screenshot che mostra l'output delle applicazioni client.

Crea il tuo bot

Creare una risorsa Bot di Azure

Nota

Se si sta già testando il bot in Teams, disconnettersi dall'app e da Teams. Per visualizzare questa modifica, accedere di nuovo.

  1. Vai alla Home.

  2. Selezionare + Crea una risorsa.

  3. Nella casella di ricerca immettere Azure Bot.

  4. Seleziona INVIO.

  5. Selezionare Bot di Azure.

  6. Selezionare Crea.

    Screenshot che mostra la creazione del bot di Azure.

  7. Immettere il nome del bot in Bot handle.

  8. Seleziona il tuo abbonamento dall'elenco a discesa.

  9. Seleziona il tuo gruppo di risorse dall'elenco a discesa.

    Screenshot che mostra l'opzione gruppo di risorse e sottoscrizione nel portale di Azure.

    Se non si ha un gruppo di risorse esistente, è possibile creare un nuovo gruppo di risorse. Per creare un nuovo gruppo di risorse, seguire questa procedura:

    1. Selezionare Crea nuovo.
    2. Immettere il nome della risorsa e selezionare OK.
    3. Selezionare una posizione nell'elenco a discesa Nuova posizione gruppo di risorse .

    Screenshot che mostra l'opzione Nuovo gruppo di risorse nel portale di Azure.

  10. In Prezzi, seleziona Cambia piano.

    Screenshot che mostra l'opzione di prezzo nel portale di Azure.

  11. Selezionare Selezione libera> FO.

    Screenshot che mostra l'opzione per selezionare gratuito.

  12. In ID app Microsoft, selezionare il tipo di app come multi-tenant.

  13. In Tipo di creazione selezionare Usa registrazione app esistente.

  14. Immettere l'ID dell'app.

    Nota

    Non è possibile creare più di un bot con lo stesso ID app Microsoft.

  15. Seleziona Rivedi + Crea.

    Screenshot che mostra la creazione di un nuovo bot.

  16. Al termine della convalida, seleziona Crea.

    Il bot richiede alcuni minuti per il provisioning.

  17. Seleziona Vai alla risorsa.

    Screenshot che mostra l'opzione Vai alla risorsa nel portale di Azure.

    Il bot di Azure è stato creato correttamente.

    Screenshot che mostra l'output di un bot.

Aggiungere un canale di Teams

  1. Nel riquadro sinistro selezionare Canali.

  2. In Canali disponibili selezionare Microsoft Teams.

    Screenshot che mostra la selezione di Teams nei canali.

  3. Seleziona la casella di controllo per accettare le condizioni d'uso.

  4. Seleziona Accetto.

    Screenshot che mostra l'accettazione delle condizioni d'uso.

  5. Selezionare Applica.

    Screenshot che mostra Microsoft Teams come messaggio da applicare.

Aggiungere un endpoint di messaggistica

Usare uno dei modi seguenti per aggiungere un endpoint di messaggistica:

  1. Utilizza l'URL del tunnel di sviluppo nella console di output come endpoint di messaggistica.

    Screenshot che mostra l'URL nella console di output di Visual Studio.

  2. Nel riquadro sinistro, in Impostazioni, selezionare Configurazione.

  3. Aggiornare l'endpoint di messaggistica nel formato https://your-devtunnel-domain/api/messages.

    Lo screenshot mostra l'endpoint di messaggistica che aggiunge l'api.

  4. Selezionare Applica.

    È stato configurato correttamente un bot nel servizio Azure Bot.

    Nota

    Se la chiave di strumentazione di Application Insights mostra un errore, eseguire l'aggiornamento con l'ID app.

Configurare le impostazioni dell'app e i file manifesto

  1. Passare al file appsettings.json nel repository clonato.

    Screenshot che mostra il percorso del file json appsettings.

  2. Apri il file di appsettings.json e aggiorna le seguenti informazioni:

    • Impostato "MicrosoftAppId"sull'ID app Microsoft del bot.
    • Impostato "MicrosoftAppPassword" sul valore dell'ID segreto client del bot.
    • Impostato ConnectionName come nome della connessione OAuth.
    • Impostato "MicrosoftAppType" su MultiTenant.
    • Impostato "MicrosoftAppTenantId" su common.

    Screenshot che mostra il json appsettings.

  3. Passare al file manifest.json nel repository clonato.

    Screenshot che mostra la selezione del file json del manifesto.

  4. Aprire il file manifest.json e aggiornare le modifiche seguenti:

    • Sostituire tutte le occorrenze di "{TODO: MicrosoftAppId}" con l'ID dell'app Microsoft.
    • Impostato "<<domain-name>>" sul dominio ngrok o dev tunnel.

    Screenshot che mostra i dettagli compilati nel file manifesto in Visual Studio.

Creare ed eseguire il servizio

Per compilare ed eseguire il servizio, utilizzare Visual Studio o la riga di comando.

  1. Aprire Visual Studio.

  2. Vai a File>Apri>Progetto/Soluzione.....

    Screenshot di Visual Studio con il progetto/la soluzione evidenziato in rosso.

  3. Nella cartella csharp selezionare il file TeamsMessagingExtensionsAction.csproj .

    Screenshot del repository clonato con TeamsMessagingExtensionsAction.csproj evidenziato in rosso.

  4. Premere F5 per avviare il progetto.

  5. Selezionare Sì se viene visualizzata la finestra di dialogo seguente:

    Screenshot che mostra un avviso di sicurezza con l'opzione Sì evidenziata in rosso.

    Viene visualizzata una pagina Web con un messaggio Il bot è pronto!.

    Screenshot della pagina Web che mostra che il bot è pronto!.

Aggiungere l'app Estensione messaggio azione a Teams

  1. Nel repository clonato, vai a samples>msgext-action>csharp>TeamsAppManifest.

  2. Creare un .zip con i file seguenti presenti nella cartella Manifesto :

    • manifest.json
    • icon-outline.png
    • icon-color.png

    Screenshot del repository clonato con il file ZIP dell'estensione Messaging evidenziato in rosso.

  3. Nel client Teams selezionare l'icona App .

  4. Seleziona Gestisci le tue app.

  5. Selezionare Carica un'app.

  6. Cerca l'opzione per caricare un'app personalizzata. Se viene visualizzata l'opzione, il caricamento di app personalizzate è abilitato.

    Screenshot che mostra il caricamento di un'app personalizzata.

    Nota

    Se non trovi l'opzione per caricare un'app personalizzata, contatta l'amministratore di Teams.

  7. Selezionare Apri per caricare il file messaging.zip creato nella cartella TeamsAppManifest.

    Screenshot del repository clonato che visualizza il file ZIP di messaggistica.

  8. Selezionare Aggiungi.

    Screenshot della finestra di dialogo dei dettagli dell'app per aggiungere l'app dell'estensione messaggio.

  9. Selezionare Apri per aprire l'app nell'ambito personale.

    In alternativa, puoi cercare e selezionare l'ambito richiesto oppure selezionare un canale, una chat o una riunione dall'elenco e spostarti nella finestra di dialogo per selezionare Vai.

    Screenshot della finestra di dialogo di selezione dell'ambito per selezionare l'ambito richiesto.

Interagire con l'app in Teams

  1. Selezionare il comando Crea scheda dall'elenco dei comandi della casella di composizione.

    Screenshot del menu di composizione del messaggio con Crea scheda evidenziato in rosso.

  2. Inserisci le tue informazioni nella finestra pop-up modale.

    Lo screenshot mostra il popup Crea modello scheda dell'estensione per la messaggistica delle azioni.

  3. Selezionare Invia.

    Screenshot del popup Crea modello di scheda con l'opzione Invia evidenziata in rosso.

  4. Selezionare Altre opzioni (...) dal menu di riversamento.

  5. Selezionare Altre azioni>Condividi messaggio.

    Screenshot che mostra il menu di riversamento dei messaggi. Le azioni Condividi messaggio e Altre azioni sono evidenziate in rosso.

  6. Se vuoi includere un'immagine, seleziona la casella di controllo Includi immagine nella scheda Hero e quindi seleziona Invia.

    Screenshot dell'estensione di messaggistica di azione con la casella di controllo Includi immagine nella scheda Hero e l'opzione Invia evidenziata in rosso.

Sfida completa

Ti è venuta in mente una cosa del genere?

Screenshot dell'output dell'estensione del messaggio dopo aver completato la guida dettagliata.

È stata completata l'esercitazione per iniziare a usare un'app Action Message Extension .

Comandi Azione

Inizio pagina

Creare un bot con autenticazione SSO

I bot conversazionali in Microsoft Teams eseguono attività automatizzate ripetitive avviate dagli utenti, ad esempio il servizio clienti. L'utente deve eseguire l'accesso più volte senza l'autenticazione Single Sign-on (SSO). Con i metodi di autenticazione SSO, gli utenti non devono accedere al bot più volte.


Esercitazione: Creare un bot con l'autenticazione SSO

Un bot si comporta in modo diverso a seconda della conversazione in cui è coinvolto:

  • I bot nelle conversazioni nei canali e nelle chat di gruppo richiedono che gli utenti utilizzino @mention il bot.
  • I bot in una conversazione uno-a-uno non richiedono un @mention. Tutti i messaggi inviati dall'utente vengono instradati al bot.

Questa guida dettagliata ti aiuta a creare un bot con l'autenticazione SSO. Verrà visualizzato l'output seguente:

Screenshot del bot con l'output dell'autenticazione SSO dopo aver completato la guida dettagliata.

Prerequisiti per la creazione di un bot

Assicurati di installare gli strumenti seguenti e di configurare l'ambiente di sviluppo:

Installare Per l'utilizzo...
Microsoft Teams Microsoft Teams per collaborare con tutti gli utenti tramite app per chat, riunioni e chiamate in un'unica posizione.
Visual Studio 2022 È possibile installare la versione enterprise in Visual Studio 2022 e installare i carichi di lavoro di sviluppo ASP.NET e Web. Usa la versione più recente.
Account sviluppatore di Microsoft 365 Accesso all'account di Teams con le autorizzazioni appropriate per installare un'app.
Tunnel di sviluppo Le funzionalità dell'app Teams (bot conversazionali, estensioni dei messaggi e webhook in ingresso) richiedono connessioni in ingresso. Un tunnel connette il sistema di sviluppo a Teams. Dev tunnel è un potente strumento per aprire in modo sicuro il tuo localhost a Internet e controllare chi ha accesso. Il tunnel di sviluppo è disponibile in Visual Studio 2022 versione 17.7.0 o successiva.
oppure
È possibile usare ngrok anche come tunnel per connettere il sistema di sviluppo a Teams. Non è necessario per le app che includono solo schede. Questo pacchetto è installato all'interno della directory del progetto (usando npm devDependencies).

Nota

Dopo aver scaricato ngrok, registrati e installa authtoken.

Configurare il tenant di sviluppo di Teams

Un tenant è come uno spazio o un contenitore in cui si chatta, si condividono file ed si eseguono riunioni per l'organizzazione in Teams. È anche possibile caricare e testare l'app personalizzata.

Verificare la presenza di un'opzione di caricamento app personalizzata

Dopo aver creato l'app, è necessario caricarla in Teams senza distribuirla. Questo processo è noto come caricamento di app personalizzate. Accedi al tuo account Microsoft 365 per visualizzare questa opzione.

Nota

Il caricamento delle app personalizzate è necessario per visualizzare in anteprima e testare le app nell'ambiente locale di Teams. Abilitare il caricamento dell'app per visualizzare l'anteprima e testare l'app in Teams in locale.

Si ha già un tenant e si dispone dell'accesso come amministratore? Controlliamo se lo sai davvero!

Per verificare le app di caricamento personalizzate in Teams:

  1. Nel client Teams selezionare l'icona App .

  2. Seleziona Gestisci le tue app.

  3. Selezionare Carica un'app

  4. Cerca l'opzione Carica un'app personalizzata. Se viene visualizzata l'opzione, il caricamento di app personalizzate è abilitato.

    Screenshot che mostra le app di Teams, Gestisci le tue app, Carica un'app e Carica un'app personalizzata evidenziate in rosso.

Nota

Se non è possibile caricare un'app personalizzata, contattare l'amministratore di Teams.

Creare un tenant di sviluppo di Teams gratuito

Se non hai un account sviluppatore di Teams, puoi ottenerlo gratuitamente. Partecipa al programma per sviluppatori di Microsoft 365!

  1. Passare al programma per sviluppatori di Microsoft 365.

  2. Seleziona Partecipa ora e segui le istruzioni sullo schermo.

  3. Nella schermata iniziale, seleziona Configura abbonamento E5.

  4. Configurare un account amministratore. Al termine, viene visualizzata la schermata seguente.

    Screenshot dell'abbonamento al programma per sviluppatori di Microsoft 365.

  5. Accedere a Teams con il nuovo account amministratore appena configurato. Verificare di avere l'opzione Carica un'app personalizzata in Teams.

Configurare l'ambiente locale

Segui questi passaggi per clonare il repository:

  1. Apri Microsoft-Teams-samples.

  2. Selezionare il codice.

  3. Nel menu a discesa selezionare Apri con GitHub Desktop.

    Screenshot che mostra l'opzione per clonare il repository in locale.

  4. Seleziona Clona.

Registra l'app Microsoft Entra

La procedura seguente consente di creare e registrare il bot nel portale di Azure:

  • Creare e registrare l'app di Azure.
  • Creare un segreto client per abilitare l'autenticazione SSO del bot.
  • Aggiungere il canale Teams per distribuire il bot.
  • Crea un tunnel per gli endpoint del server Web usando Dev Tunnel (consigliato) o NGREK.
  • Aggiungere l'endpoint di messaggistica al tunnel di sviluppo creato.

Aggiungere la registrazione dell'app

  1. Passare al portale di Azure.

  2. Selezionare Registrazioni app.

    Screenshot che mostra i servizi di Azure per selezionare Registrazioni app.

  3. Selezionare + Nuova registrazione.

    Screenshot che mostra la pagina Nuova registrazione in Interfaccia di amministrazione di Microsoft Entra.

  4. Immettere il nome dell'app.

  5. Selezionare l'opzione tenant in base alle esigenze.

  6. Seleziona Registrati.

    Screenshot che mostra l'opzione per registrare il bot nell'interfaccia di amministrazione di Microsoft Entra.

    L'app è registrata in Microsoft Entra ID. Viene visualizzata la pagina Panoramica app.

    Screenshot che mostra la pagina di panoramica della registrazione dell'app.

    Nota

    Salvare l'ID app dall'ID applicazione (client) e dall'ID directory (tenant) per un ulteriore utilizzo.

Creare un tunnel

Seguire uno dei due metodi seguenti per creare un tunnel.

  1. Aprire Visual Studio.

  2. Seleziona Crea un nuovo progetto.

    Screenshot che mostra la selezione per creare un nuovo progetto.

  3. Nella casella di ricerca immettere ASP.NET. Nei risultati della ricerca selezionare App Web ASP.NET Core.

  4. Selezionare Avanti.

    Screenshot che mostra la ricerca e la selezione del modello.

  5. Immettere il nome del progetto e selezionare Avanti.

    Screenshot che mostra il nome del progetto da inserire.

  6. Selezionare Crea.

    Screenshot che mostra le informazioni aggiuntive del progetto.

    Viene visualizzata una finestra di panoramica.

    Screenshot che mostra la finestra panoramica.

  7. Nell'elenco a discesa debug, selezionare Tunnel di sviluppo (nessun tunnel attivo)>Crea un tunnel....

    Screenshot che mostra l'elenco a discesa per selezionare i tunnel dev.

    Viene visualizzata una finestra popup.

  8. Aggiorna i seguenti dettagli nella finestra popup:

    1. Account: immetti un account Microsoft o GitHub.
    2. Nome: immettere un nome per il tunnel.
    3. Tipo di tunnel: dall'elenco a discesa, selezionare Temporaneo.
    4. Accesso: dall'elenco a discesa, selezionare Pubblico.

  9. Selezionare OK.

    Screenshot che mostra i dettagli da aggiornare per la creazione del tunnel.

    Viene visualizzata una finestra popup che mostra che il tunnel di sviluppo è stato creato correttamente.

  10. Selezionare OK.

    Lo screenshot mostra il messaggio popup che indica che il tunnel è stato creato.

    Puoi trovare il tunnel che hai creato nell'elenco a discesa di debug come segue:

    Lo screenshot mostra che il tunnel è attivo e selezionato.

  11. Selezionare F5 per eseguire l'applicazione in modalità di debug.

  12. Se viene visualizzata una finestra di dialogo Avviso di sicurezza , selezionare Sì.

    Screenshot che mostra la finestra di dialogo per accettare l'avviso di sicurezza.

    Viene visualizzata una finestra popup.

  13. Selezionare Continua.

    Screenshot che mostra l'URL del tunnel.

    La home page di Dev Tunnel si apre in una nuova finestra del browser e Dev Tunnel è ora attivo.

    Screenshot che mostra la pagina di benvenuto di Dev Tunnel nel browser.

  14. Passare a Visual Studio, selezionare Visualizza > output.

  15. Dal menu a discesa della console di output , seleziona Dev Tunnel.

    La console di output mostra l'URL del tunnel di sviluppo.

    Screenshot che mostra l'URL nella console di output di Visual Studio.

Aggiungere l'autenticazione Web

  1. Nel riquadro sinistro, in Gestisci, selezionare Autenticazione.

  2. Selezionare Aggiungi una piattaforma>Web.

    Screenshot che mostra la selezione dell'autenticazione Web.

  3. Immettere l'URI di reindirizzamento per l'app aggiungendolo auth-end al nome di dominio completo. Ad esempio, https://your-devtunnel-domain/auth-end o https://your-ngrok-domain/auth-end.

  4. In Concessione implicita e flussi ibridi selezionare le caselle di controllo Token di accesso e Token ID .

  5. Selezionare Configura.

    Screenshot che mostra l'opzione per aggiungere l'URI di reindirizzamento e selezionare la concessione implicita e i flussi ibridi.

  6. In Web selezionare Aggiungi URI.

  7. Immettere https://token.botframework.com/.auth/web/redirect.

  8. Selezionare Salva.

    Screenshot che mostra l'opzione per aggiungere l'URI di reindirizzamento e selezionare la concessione implicita e i flussi ibridi.

Creare un segreto client

Nota

Se viene visualizzato l'errore, i segreti client vengono bloccati dai criteri a livello di tenant. Per altre informazioni, contattare l'amministratore del tenant, è possibile creare un certificato. Per istruzioni dettagliate, fare riferimento a Creare un certificato per la registrazione dell'app.

  1. Nel riquadro sinistro, in Gestisci, seleziona Certificati & segreti.

  2. In Segreti client selezionare + Nuovo segreto client.

    Screenshot che mostra la selezione del nuovo segreto client.

    Viene visualizzata la finestra Aggiungi un segreto client .

  3. Immettere la descrizione.

  4. Selezionare Aggiungi.

    Screenshot che mostra l'opzione di descrizione del segreto client per aggiungerla.

  5. In Valore, selezionare Copia negli Appunti per salvare il valore del segreto client per un ulteriore utilizzo.

    Screenshot che mostra l'opzione per copiare il valore dell'ID segreto client per copiare il valore negli Appunti.

Aggiungere autorizzazioni API

  1. Nel riquadro sinistro selezionare Autorizzazioni API.

  2. Selezionare + Aggiungi un'autorizzazione.

    Screenshot che mostra l'opzione per selezionare Aggiungi autorizzazione.

  3. Selezionare Microsoft Graph.

  4. Selezionare Autorizzazioni delegate.

  5. Selezionare Utente>User.Read.

  6. Selezionare Aggiungi autorizzazioni.

    Screenshot che mostra l'opzione per selezionare le autorizzazioni.

    Nota

    • Se a un'app non viene concesso il consenso dell'amministratore IT, gli utenti devono fornire il consenso la prima volta che usano un'app.
    • Gli utenti devono acconsentire alle autorizzazioni API solo se l'app Microsoft Entra è registrata in un tenant diverso.

Aggiungere l'URI ID applicazione

  1. Nel riquadro sinistro, in Gestisci, selezionare Esponi un'API.

  2. Accanto a URI ID applicazione selezionare Aggiungi.

    Screenshot che mostra l'opzione per aggiungere l'ID applicazione URI per l'app.

  3. Aggiornare l'URI dell'ID applicazione nel api://botid-{AppID} formato e selezionare Salva.

    Screenshot che mostra l'opzione per aggiungere l'ID dell'app URI e salvare.

Aggiungere un ambito

  1. Nel riquadro sinistro, in Gestisci, selezionare Esponi un'API.

  2. Selezionare + Aggiungere un ambito.

    Screenshot che mostra la selezione per aggiungere un ambito.

  3. Immetti access_as_user come nome dell'ambito.

  4. In Chi può fornire il consenso?, selezionare Amministratori e utenti.

  5. Aggiornare i valori per il resto dei campi come indicato di seguito:

    1. Invio Teams può accedere al profilo dell'utente come nome visualizzato con il consenso dell'Amministratore.

    2. INVIO Consente a Teams di chiamare le API Web dell'app come utente corrente come descrizione del consenso dell'Amministratore.

    3. Invio Teams può accedere al profilo utente ed effettuare richieste per conto dell'utente come nome visualizzato per il consenso dell'utente.

    4. Invio Consenti a Teams di chiamare le API di questa app con gli stessi diritti dell'utente della descrizione delconsenso dell'utente.

  6. Assicurati che lo stato sia impostato su Abilitato.

  7. Selezionare Aggiungi ambito.

    La figura seguente mostra i campi e i valori:

    Screenshot che mostra i valori compilati nel campo per Aggiungere un ambito.

    Nota

    Il nome dell'ambito deve corrispondere all'ID applicazione URI, con /access_as_user l'aggiunta alla fine.

    Screenshot che mostra i dettagli negli ambiti.

Aggiungere un'applicazione client

  1. Nel riquadro sinistro, in Gestisci, selezionare Esponi un'API.

    In Applicazioni client autorizzate identificare le applicazioni che si desidera autorizzare per l'applicazione Web dell'app.

  2. Selezionare + Aggiungi un'applicazione client.

    Screenshot che mostra l'opzione Seleziona applicazione client.

  3. Aggiungere Teams per dispositivi mobili o desktop e l'applicazione Web di Teams.

    1. Per Teams per dispositivi mobili o desktop: immettere l'ID client come 1fec8e78-bce4-4aaf-ab1b-5451cc387264.

      Screenshot che mostra l'applicazione ID client per dispositivi mobili o desktop.

    2. Per Teams Web: immettere l'ID client come 5e3ce6c0-2b1f-4285-8d4b-75ee78787346.

      Screenshot che mostra l'applicazione ID client Web.

  4. Selezionare la casella di controllo Ambiti autorizzati .

  5. Selezionare Aggiungi applicazione.

    Screenshot che mostra l'opzione per selezionare gli ambiti autorizzati e aggiungere l'applicazione.

    L'immagine seguente mostra l'ID client:

    Screenshot che mostra l'output delle applicazioni client.

Aggiornare il manifesto

  1. Nel riquadro sinistro selezionare Manifesto.

  2. Imposta il valore per su requestedAccessTokenVersion2 e seleziona Salva.

    Screenshot che mostra l'opzione manifesto e i dettagli del token di accesso nel portale di Azure.

Crea il tuo bot

Creare una risorsa Bot di Azure

Nota

Se si sta già testando il bot in Teams, disconnettersi dall'app e da Teams. Per visualizzare questa modifica, accedere di nuovo.

  1. Vai alla Home.

  2. Selezionare + Crea una risorsa.

  3. Nella casella di ricerca immettere Azure Bot.

  4. Seleziona INVIO.

  5. Selezionare Bot di Azure.

  6. Selezionare Crea.

    Screenshot che mostra la creazione del bot di Azure.

  7. Immettere il nome del bot in Bot handle.

  8. Seleziona il tuo abbonamento dall'elenco a discesa.

  9. Seleziona il tuo gruppo di risorse dall'elenco a discesa.

    Screenshot che mostra l'opzione gruppo di risorse e sottoscrizione nel portale di Azure.

    Se non si ha un gruppo di risorse esistente, è possibile creare un nuovo gruppo di risorse. Per creare un nuovo gruppo di risorse, seguire questa procedura:

    1. Selezionare Crea nuovo.
    2. Immettere il nome della risorsa e selezionare OK.
    3. Selezionare una posizione nell'elenco a discesa Nuova posizione gruppo di risorse .

    Screenshot che mostra l'opzione Nuovo gruppo di risorse nel portale di Azure.

  10. In Prezzi, seleziona Cambia piano.

    Screenshot che mostra l'opzione di prezzo nel portale di Azure.

  11. Selezionare Selezione libera> FO.

    Screenshot che mostra l'opzione per selezionare gratuito.

  12. In ID app Microsoft, selezionare il tipo di app come multi-tenant.

  13. In Tipo di creazione selezionare Usa registrazione app esistente.

  14. Immettere l'ID dell'app.

    Nota

    Non è possibile creare più di un bot con lo stesso ID app Microsoft.

  15. Seleziona Rivedi + Crea.

    Screenshot che mostra la creazione di un nuovo bot.

  16. Al termine della convalida, seleziona Crea.

    Il bot richiede alcuni minuti per il provisioning.

  17. Seleziona Vai alla risorsa.

    Screenshot che mostra l'opzione Vai alla risorsa nel portale di Azure.

    Il bot di Azure è stato creato correttamente.

    Screenshot che mostra l'output di un bot.

Aggiungere un canale di Teams

  1. Nel riquadro sinistro selezionare Canali.

  2. In Canali disponibili selezionare Microsoft Teams.

    Screenshot che mostra la selezione di Teams nei canali.

  3. Seleziona la casella di controllo per accettare le condizioni d'uso.

  4. Seleziona Accetto.

    Screenshot che mostra l'accettazione delle condizioni d'uso.

  5. Selezionare Applica.

    Screenshot che mostra Microsoft Teams come messaggio da applicare.

Aggiungere un endpoint di messaggistica

Usare uno dei modi seguenti per aggiungere un endpoint di messaggistica:

  1. Utilizza l'URL del tunnel di sviluppo nella console di output come endpoint di messaggistica.

    Screenshot che mostra l'URL nella console di output di Visual Studio.

  2. Nel riquadro sinistro, in Impostazioni, selezionare Configurazione.

  3. Aggiornare l'endpoint di messaggistica nel formato https://your-devtunnel-domain/api/messages.

    Lo screenshot mostra l'endpoint di messaggistica che aggiunge l'API.

  4. Selezionare Applica.

    È stato configurato correttamente un bot nel servizio Azure Bot.

    Nota

    Se la chiave di strumentazione di Application Insights mostra un errore, eseguire l'aggiornamento con l'ID app.

Aggiungere impostazioni di connessione OAuth

  1. Nel riquadro sinistro selezionare Configurazione.

  2. Selezionare Aggiungi impostazioni di connessione OAuth.

  3. In Nuova impostazione di connessione, aggiornare i dettagli seguenti:

    • Nome: immettere un nome per la nuova impostazione di connessione. È possibile usare il nome nelle impostazioni del codice del servizio bot.
    • Provider di servizi: nell'elenco a discesa selezionare Azure Active Directory v2.
    • ID client: aggiornare l'ID dell'app Microsoft.
    • Segreto client: aggiornare il valore dei segreti client.
    • URL di scambio token: aggiornare l'URI dell'ID applicazione.
    • ID tenant: immettere common.
    • Ambiti: Immettere User.Read.

  4. Selezionare Salva.

    Screenshot che mostra i valori aggiunti per impostare la connessione OAuth.

Configurare le impostazioni dell'app e i file manifesto

  1. Passare al file appsettings.json nel repository clonato.

    Screenshot che mostra il percorso del file json appsettings.

  2. Apri il file di appsettings.json e aggiorna le seguenti informazioni:

    • Impostato "MicrosoftAppId"sull'ID app Microsoft del bot.
    • Impostato "MicrosoftAppPassword" sul valore dell'ID segreto client del bot.
    • Impostato ConnectionName come nome della connessione OAuth.
    • Impostato "MicrosoftAppType" su MultiTenant.
    • Impostato "MicrosoftAppTenantId" su common.

    Screenshot che mostra il json appsettings.

  3. Passare al file manifest.json nel repository clonato.

    Screenshot che mostra la selezione del file json del manifesto.

  4. Aprire il file manifest.json e aggiornare le modifiche seguenti:

    • Sostituire tutte le occorrenze di "{TODO: MicrosoftAppId}" con l'ID dell'app Microsoft.
    • Impostato "<<domain-name>>" sul dominio ngrok o dev tunnel.

    Screenshot che mostra i dettagli compilati nel file manifesto in Visual Studio.

Creare ed eseguire il servizio

  1. Aprire Visual Studio.

  2. Vai a File,>Apri>progetto/soluzione....

    Screenshot del menu file di Visual Studio. Le voci di menu Intitolate Apri nel menu File e Progetto/Soluzione in Apri sono evidenziate in rosso.

  3. Da bot-conversazione-sso-quickstart>csharp_dotnetcore cartella e selezionare BotConversationSsoQuickstart.sln file.

    Screenshot del file di Project con il percorso del file e il file BotSSOCSharp.csproj evidenziati in rosso.

  4. Selezionare F5 per eseguire il progetto.

  5. Se viene visualizzata una finestra di dialogo Avviso di sicurezza , selezionare Sì.

    Screenshot dell'avviso di sicurezza con l'opzione Sì evidenziata in rosso.

    Si apre una pagina Web con un messaggio Il bot è pronto!.

    Nota

    Questa pagina viene visualizzata solo quando si passa all'URL localhost.

    Lo screenshot della pagina Web che visualizza il bot è pronto.

    Risoluzione dei problemi

    Se viene visualizzato l'errore Impossibile trovare il pacchetto , eseguire le operazioni seguenti:

    1. Passare a Strumenti> Gestionepacchetti> NuGetImpostazioni di Gestione pacchetti.
    2. Nella finestra Opzioni visualizzata selezionare Origini pacchetti di Gestione pacchetti> NuGet.
    3. Selezionare Aggiungi.
    4. In Nomenuget.org immettere e in Origine immettere https://api.nuget.org/v3/index.json.
    5. Seleziona Aggiorna e OK.
    6. Ricompilare il progetto.

Caricare il bot in Teams

  1. Nel repository clonato passare a Microsoft-Teams-Samples>samples>bot-conversation-sso-quickstart>csharp_dotnetcore>TeamsApp>appPackage.

  2. Creare un file .zip con i file seguenti presenti nella cartella appPackage :

    • manifest.json
    • outline.png
    • color.png

    Screenshot della cartella manifesto con la cartella zip Teams Bot evidenziata in rosso.

  3. Passare a Microsoft Teams.

    1. Nel client Teams, selezionare App.
    2. Seleziona Gestisci le tue app.
    3. Selezionare Carica un'app.
    4. Cerca l'opzione per caricare un'app personalizzata.

    Screenshot dell'app Teams con l'icona App, Gestisci le tue app, e con la selezione dell'opzione Carica un'app personalizzata evidenziata in rosso.

  4. Selezionare Apri per caricare il file .zip creato nella cartella Manifesto .

    Screenshot della cartella manifesto con l'opzione Apri per caricare il file zip del bot di Teams evidenziata in rosso.

  5. Selezionare Aggiungi per aggiungere il bot alla chat.

    Screenshot del bot di conversazione con l'opzione Aggiungi evidenziata.

  6. Scegliere Apri.

    Screenshot della finestra di dialogo di selezione dell'ambito con l'opzione Apri evidenziata.

    È possibile interagire con il bot inviandogli un messaggio. Il bot scambia un token SSO e chiama l'API Graph per conto dell'utente. Mantiene l'accesso a meno che non si invii un messaggio di disconnessione.

  7. Inviare un messaggio al bot. Il bot di conversazione chiede il consenso per la prima volta.

  8. Per desktop: selezionare Continua per concedere le autorizzazioni al client di Teams per l'accesso al bot.

    Screenshot delle autorizzazioni aggiuntive con l'opzione Continua evidenziata in rosso.

    Nota

    Ora hai configurato SSO con la tua app bot ed è l'unica volta che dovrai dare il consenso.

  9. Per dispositivi mobili: seleziona Accetta.

    Nota

    Ora hai configurato SSO con la tua app bot in dispositivi mobili ed è l'unica volta che dovrai dare il consenso.

    Screenshot dell'output di bot SSO dopo aver completato la guida dettagliata.

Ti è venuta in mente una cosa del genere?

Screenshot dell'output dopo aver completato la guida dettagliata.

Hai completato l'esercitazione per iniziare a creare un bot con l'autenticazione SSO.

Abilitare SSO per il bot

Inizio pagina

Creare la prima app di estensione messaggio con JavaScript

Iniziare a sviluppare app per Microsoft Teams con la prima app Teams usando JavaScript.

In questo tutorial imparerai quanto segue:

  • Come configurare un nuovo progetto con Microsoft 365 Agents Toolkit (noto in precedenza come Teams Toolkit).
  • Come creare un'app di estensione messaggio.
  • Come distribuire l'app.
Esercitazione: Creare la prima app di estensione messaggio con JavaScript

Questa guida dettagliata ti aiuta a creare un'app Teams di estensione messaggio con Agents Toolkit in Visual Studio Code. Al termine di questa guida, verrà visualizzato l'output seguente:

Screenshot che mostra l'output finale dell'app dell'estensione del messaggio in Teams.

Prerequisiti

Assicurarsi di installare gli strumenti seguenti per la creazione e la distribuzione delle app.

  Installare Per l'utilizzo...
Obbligatorio    
  Visual Studio Code Ambienti di compilazione JavaScript o TypeScript. Usa la versione più recente.
  Toolkit per agenti di Microsoft 365 Estensione di Microsoft Visual Studio Code che crea un'impalcatura di progetto per l'app. Usa la versione più recente.
  Node.js Ambiente di runtime JavaScript backend. Per altre informazioni, vedere Node.js tabella di compatibilità delle versioni.
  Microsoft Teams Collabora con le persone con cui lavori tramite app per chat, riunioni e chiamate in un'unica posizione.
  Microsoft Edge (scelta consigliata) o Google Chrome Un browser con strumenti di sviluppo essenziali per il debug e il test.
  Account sviluppatore di Microsoft 365 Accesso all'account di Teams con le autorizzazioni appropriate per installare un'app personalizzata.
Dati facoltativi    
  Strumenti di Azure per Visual Studio Code e l'interfaccia della riga di comando di Azure Strumenti di Azure per accedere ai dati archiviati o distribuire un back-end basato sul cloud per l'app Teams in Azure.
  Strumenti di sviluppo React per Chrome o Strumenti di sviluppo React per Microsoft Edge Un'estensione DevTools del browser per la libreria JavaScript open source React.

Preparare l'ambiente di sviluppo

Dopo aver installato gli strumenti necessari, configura l'ambiente di sviluppo.

Installare Microsoft 365 Agents Toolkit

Microsoft 365 Agents Toolkit (in precedenza noto come Teams Toolkit) aiuta a semplificare il processo di sviluppo con strumenti per il provisioning e la distribuzione di risorse cloud per l'app e la pubblicazione su Teams Store.

Puoi utilizzare Agents Toolkit con Visual Studio Code o un'interfaccia a riga di comando denominata Microsoft 365 Agents Toolkit CLI (in precedenza nota come CLI di TeamsFx).

  1. Apri Visual Studio Code e seleziona Estensioni (CTRL+MAIUSC+X o Visualizza>estensioni).

  2. Nella casella di ricerca, inserisci Microsoft 365 Agents Toolkit.

  3. Selezionare Installa.

    Screenshot che mostra l'installazione dell'estensione Agents Toolkit.

    L'icona di Microsoft 365 Agents Toolkit viene visualizzata nella barra delle attività di Visual Studio Code.

Puoi anche installare Agents Toolkit da Visual Studio Code Marketplace.

Configurare il tenant di sviluppo di Teams

Un tenant è uno spazio o un contenitore per l'organizzazione in Teams in cui si chatta, si condividono file ed si eseguono riunioni. Questo spazio è anche il luogo in cui carichi e testi la tua app. Verificare se si è pronti per lo sviluppo con il tenant.

Controlla l'opzione Carica un'app

Dopo aver creato l'app personalizzata, è necessario caricarla in Teams con l'opzione Carica un'app personalizzata . Accedere al proprio account Microsoft 365 per verificare se questa opzione è abilitata.

La procedura seguente consente di verificare se è possibile caricare app in Teams:

  1. Nel client Teams selezionare l'icona App .

  2. Seleziona Gestisci le tue app.

  3. Selezionare Carica un'app.

  4. Cerca l'opzione per caricare un'app personalizzata. Se l'opzione è visibile, è possibile caricare app personalizzate.

    Screenshot che mostra l'opzione per caricare un'app personalizzata in Teams.

    Nota

    Se non trovi l'opzione per caricare un'app personalizzata, contatta l'amministratore di Teams.

Creare un tenant di sviluppo di Teams gratuito (facoltativo)

Se non hai un account sviluppatore di Teams, partecipa al programma per sviluppatori di Microsoft 365.

  1. Passare al programma per sviluppatori di Microsoft 365.

  2. Seleziona Partecipa ora e segui le istruzioni sullo schermo.

  3. Nella schermata iniziale, seleziona Configura abbonamento E5.

  4. Configura il tuo account amministratore. Al termine, viene visualizzata la schermata seguente:

    Screenshot che mostra il Programma per sviluppatori di Microsoft 365.

  5. Accedere a Teams con l'account amministratore appena configurato. Verificare di avere l'opzione Carica un'app personalizzata in Teams.

Ottenere un account di Azure gratuito

Se si vuole ospitare l'app o accedere alle risorse in Azure, è necessario avere una sottoscrizione di Azure. Crea un account gratuito prima di iniziare.

Creare un'area di lavoro di progetto per l'app Estensione messaggio

Creare ora la prima app di estensione messaggio.

La funzionalità di estensione del messaggio consente di interagire con un servizio Web tramite pulsanti e moduli. Usare l'area di composizione del messaggio, la casella di comando o un messaggio direttamente nel client di Teams per cercare e avviare azioni in un sistema esterno. Le estensioni dei messaggi si basano sui bot per fornire una finestra di dialogo tra l'utente e il codice.

Il diagramma mostra Lo screenshot mostra i diversi tipi di funzionalità dell'app con l'estensione del messaggio evidenziata.

Esistono due tipi di estensione dei messaggi di Teams:

  • Comandi di ricerca: è possibile cercare sistemi esterni e inserire i risultati in un messaggio sotto forma di scheda.
  • Comandi di azione: è possibile presentare agli utenti un pop-up modale per raccogliere o visualizzare informazioni. Quindi, è possibile elaborare l'interazione e inviare le informazioni a Teams.

Creiamo un'app per l'estensione dei messaggi con un comando di ricerca. Prima di tutto, configurare un nuovo progetto Teams per la creazione dell'app estensione messaggio.

In questo tutorial imparerai quanto segue:

  1. Come configurare un nuovo progetto di estensione messaggio con Agents Toolkit.
  2. Informazioni sulla struttura di directory del progetto di app.

Creare l'area di lavoro del progetto di estensione messaggio

Se i prerequisiti ci sono, iniziamo!

Nota

L'interfaccia utente di Visual Studio Code visualizzata può variare a seconda del sistema operativo, della versione del Toolkit, del tema e dell'ambiente.

  1. Apri Visual Studio Code.

  2. Seleziona l'icona di Microsoft 365 Agents Toolkit nella barra delle attività di Visual Studio Code.

  3. Selezionare Crea un nuovo agente/app>App di Teams.

    Screenshot che mostra l'opzione per creare una nuova app dalla barra laterale di Agents Toolkit.

  4. Selezionare Estensione messaggio.

    Screenshot che mostra l'opzione per creare una nuova app di Teams.

  5. Selezionare Risultati di ricerca personalizzati.

    Screenshot che mostra l'opzione per selezionare le funzionalità di una nuova app.

  6. Selezionare Start with a Bot.

    Screenshot che mostra le opzioni per l'architettura dell'estensione del messaggio.

  7. Seleziona JavaScript.

    Screenshot che mostra l'opzione per selezionare il linguaggio di programmazione.

  8. Selezionare Cartella predefinita per archiviare la cartella principale del progetto nella posizione predefinita.

    Screenshot che mostra la selezione della posizione predefinita.

    Puoi anche modificare la posizione predefinita seguendo questa procedura:

    1. Selezionare Sfoglia.

      Screenshot che mostra l'opzione Sfoglia.

    2. Selezionare la posizione dell'area di lavoro del progetto.

    3. Selezionare Seleziona cartella.

      Screenshot che mostra come selezionare il percorso per la cartella dell'area di lavoro del progetto.

  9. Immettere un nome appropriato per l'app. Seleziona INVIO.

    Screenshot che mostra l'opzione per immettere il nome dell'app.

    Agents Toolkit crea l'app in pochi secondi.

    Screenshot che mostra l'app dell'estensione messaggio appena creata.

    Dopo la creazione dell'app, Agents Toolkit visualizza il seguente messaggio:

    Lo screenshot mostra una finestra di dialogo che informa che l'app di estensione del messaggio è stata creata.

Panoramica del codice sorgente dell'app Estensione messaggio

Un'estensione messaggio usa Bot Framework per interagire con il servizio tramite una conversazione. Dopo lo scaffolding, visualizzare le directory e i file del progetto in EXPLORER.

Screenshot che mostra i file dell'app Estensione messaggio.

Cartella/File Sommario
m365agents.yml Il file di progetto principale descrive la configurazione dell'applicazione e definisce il set di azioni da eseguire in ogni fase del ciclo di vita.
m365agents.local.yml Sostituzioni m365agents.yml con azioni che abilitano l'esecuzione e il debug locali.
.vscode/ File di Visual Studio Code per il debug locale.
appPackage/ Modelli per il manifesto dell'applicazione Teams.
infra/ Modelli per il provisioning delle risorse di Azure.
index.js Punto di ingresso e express gestore dell'applicazione.

Suggerimento

Acquisire familiarità con i bot e l'estensione dei messaggi all'esterno di Teams prima di integrare l'app in Teams.

Creare ed eseguire la prima app di estensione messaggio

Dopo aver configurato l'area di lavoro del progetto con Agents Toolkit, è il momento di crearlo. Devi accedere al tuo account Microsoft 365.

Accedi al tuo account Microsoft 365

Accedi con l'account amministratore che hai creato durante la partecipazione al programma per sviluppatori di Microsoft 365.

  1. Apri Visual Studio Code.

  2. Seleziona l'icona di Microsoft 365 Agents Toolkit nella barra delle attività.

  3. Seleziona Accedi a Microsoft 365 usando le tue credenziali. Il Web browser predefinito si apre per consentire l'accesso.

    Screenshot che mostra dove accedere a Microsoft 365 e Azure.

  4. Chiudere il browser dopo aver eseguito l'accesso con le credenziali.

  5. Torna a Agents Toolkit all'interno di Visual Studio Code.

Nella sezione ACCOUNT della barra laterale viene visualizzato il nome dell'account Microsoft 365. Se il caricamento di app personalizzate è abilitato per l'account Microsoft 365, Agents Toolkit mostra che il caricamento di app personalizzate è abilitato.

Lo screenshot mostra l'utente che ha eseguito l'accesso a Microsoft 365 e il messaggio di caricamento abilitato.

Ora sei pronto per creare l'app ed eseguirla in locale!

Creare ed eseguire l'app nell'ambiente locale

Ora è possibile creare ed eseguire il debug della prima app di estensione messaggi di Teams in locale.

Creare ed eseguire l'app in locale

  1. Selezionare il tasto F5 in Visual Studio Code per eseguire l'applicazione in modalità di debug.

    Nota

    Se Agents Toolkit non è in grado di verificare un particolare prerequisito, ti chiede di verificare.


    Informazioni su cosa accade quando esegui l'app in locale nel debugger.

    Quando selezioni F5, Agents Toolkit svolge le seguenti funzioni:

    1. Verifica i seguenti prerequisiti:

      1. È stato eseguito l'accesso con un account Microsoft 365.
      2. Il caricamento di app personalizzate è abilitato per l'account Microsoft 365.
      3. Supportata Node.js versione è installata.
      4. La porta richiesta dall'app bot è disponibile.

    2. Installa i pacchetti npm

    3. Avvia Dev Tunnel per creare un tunnel HTTP.

    4. Registra l'app in Microsoft Entra ID e configura l'app.

    5. Registra l'app bot in Bot Framework e configura l'app.

    6. Registra l'app nel portale per sviluppatori di Teams e configura l'app.

    7. Avvia l'app dell'estensione messaggio ospitata localmente.

    8. Avvia Teams in un Web browser e carica l'app Teams.

    Screenshot che mostra il processo di debug dell'app estensione messaggio.

    Quando si esegue il debug dell'app per la prima volta, Teams scarica le dipendenze e crea l'app. Il completamento di questo processo può richiedere da 3 a 5 minuti.

  2. Teams si apre in una finestra del browser al termine della compilazione. Accedere con il proprio account Microsoft 365, se richiesto.

  3. Si apre una finestra di dialogo che consente di aggiungere l'app Estensione messaggio a Teams. Selezionare Aggiungi.

    Screenshot che mostra l'opzione per aggiungere l'app personalizzata in Teams.

    Teams carica l'app dell'estensione messaggio.

    Screenshot che mostra l'app di estensione del messaggio aperta in una chat bot di Teams.

    Poiché le app di estensione dei messaggi si basano sui bot per abilitare la comunicazione tra l'utente e il servizio Web, l'app viene caricata in una funzionalità di chat di un bot.

    • Se un'app bot è stata creata prima di creare l'app dell'estensione del messaggio, Teams carica l'estensione del messaggio nell'app bot creata. Sono visibili i messaggi di chat precedenti dell'app bot.
    • Se è stata creata prima un'estensione del messaggio, Teams carica l'app nell'ultima chat aperta in Teams.

Testare l'app

La prima volta che viene caricata l'app, l'app dell'estensione messaggio è aperta per il test. Questa app di esempio ti consente di cercare pacchetti npm open source dal registro dei software.

Come eseguire una query di ricerca

  1. Immetti il nome di un pacchetto npm open source nella casella di ricerca dell'estensione del messaggio, ad esempio cli. Nell'estensione del messaggio viene visualizzato un elenco degli elementi corrispondenti.

    Screenshot che mostra una stringa di ricerca nell'app estensione messaggio.

  2. Selezionare uno degli elementi nell'elenco. L'app crea una scheda adattiva con l'elemento nell'area di composizione del messaggio in modo da poterlo inviare in una chat o in un canale.

    Screenshot che mostra il risultato della ricerca nell'area di composizione del messaggio.

  3. Seleziona INVIO. L'app di estensione del messaggio invia la scheda adattiva con l'elemento nella chat o nel canale.

    Screenshot che mostra il risultato della ricerca inviato in chat.

Come aprire l'app dell'estensione messaggi

La funzionalità di ricerca dell'app dell'estensione messaggio è stata testata nel passaggio precedente. Ora informazioni sui diversi modi per aprire l'app dell'estensione messaggio.

Aprire l'app dalla casella di comando

  1. INVIO / seguito dal nome dell'app dell'estensione messaggio nella casella di comando.

    Screenshot che mostra come richiamare l'app dell'estensione messaggio.

    L'app si apre nella casella di comando e puoi usarla per eseguire una query.

    Nota

    • L'uso / dell'app per aprire l'estensione del messaggio dalla casella di comando funziona solo nel nuovo client Teams.
    • Usare @ per aprire l'app di estensione messaggi dalla casella di comando nel client di Teams classico.

Aprire l'app dall'area di composizione dei messaggi

  1. Selezionare i tre puntini nella parte inferiore dell'area di composizione del messaggio.

  2. Selezionare l'app Estensione messaggi.

    Screenshot che mostra come aprire l'app dell'estensione messaggio dall'area di composizione del messaggio.

    L'app di estensione del messaggio viene caricata con le opzioni per eseguire una ricerca.


Aprire l'app da app personalizzate caricate

  1. Seleziona App>Gestisci le tue app.

  2. Seleziona l'elenco a discesa per la tua app dall'elenco delle app e seleziona App personale.

    Screenshot che mostra le app caricate in Teams.

  3. Viene visualizzata una finestra di dialogo che suggerisce di provare l'applicazione. Se selezioni "Ce l'ho", la finestra di dialogo scompare. Seleziona Prova.

    Screenshot che mostra il messaggio per provare l'app di estensione messaggi ora o in un secondo momento.

  4. Nella chat di Teams più recente viene visualizzato un elenco delle app dell'estensione messaggio. Selezionare l'app di estensione messaggi nell'elenco.

Informazioni su come risolvere i problemi se l'app non viene eseguita in locale

Per eseguire l'app in Teams, è necessario disporre di un account di sviluppo di Microsoft 365 che consenta il caricamento di app personalizzate. Per altre informazioni sul caricamento di app personalizzate, vedere la sezione Prerequisiti.

Distribuire la prima app di Teams

Distribuiamo la tua prima app di estensione del messaggio su Azure utilizzando Agents Toolkit.

Accedere all'account di Azure

Accedere all'account di Azure per accedere al portale di Azure ed effettuare il provisioning di nuove risorse cloud per supportare l'app.

  1. Apri Visual Studio Code.

  2. Aprire la cartella del progetto in cui è stata creata l'app Estensione messaggio.

  3. Seleziona l'icona di Microsoft 365 Agents Toolkit nella barra delle attività.

  4. Seleziona Accedi ad Azure usando le tue credenziali. Il Web browser predefinito si apre per consentire l'accesso.

    Suggerimento

    Se è installata l'estensione ACCOUNT AZURE e si usa lo stesso account, è possibile ignorare questo passaggio.

  5. Chiudi il browser quando richiesto e torna a Visual Studio Code.

La sezione ACCOUNT della barra laterale elenca il numero di abbonamenti di Azure utilizzabili disponibili. Assicurarsi di avere almeno una sottoscrizione di Azure utilizzabile. In caso contrario, disconnettersi e usare un altro account.

Distribuire l'app in Azure

La distribuzione consiste in due passaggi. Innanzitutto, vengono create le risorse cloud necessarie (noto anche come provisioning). Quindi, il codice dell'app viene copiato nelle risorse cloud create. L'app dell'estensione messaggi viene distribuita in questa esercitazione.

Qual è la differenza tra provisioning e distribuzione?
Il passaggio Provisioning crea risorse in Azure e Microsoft 365 per l'app, ma non viene copiato alcun codice (ad esempio HTML, CSS o JavaScript) nelle risorse. La fase Deploy copia il codice per l'app nelle risorse create durante la fase di provisioning. È comune eseguire la distribuzione più volte senza eseguire il provisioning di nuove risorse. Poiché il passaggio di provisioning richiede del tempo per essere completato, è separato dal passaggio di distribuzione.

Seleziona l'icona di Microsoft 365 Agents Toolkit nella barra delle attività di Visual Studio Code.

  1. Selezionare Provisioning.

    Screenshot che mostra la selezione del provisioning nel cloud in Toolkit agenti.

  2. Seleziona un abbonamento.

    Screenshot che mostra le opzioni del gruppo di sottoscrizioni di Azure tra cui scegliere.

  3. Selezionare un gruppo di risorse.

    Screenshot che mostra la sottoscrizione da usare per le risorse di Azure.

    Se non si ha un gruppo di risorse da selezionare, è possibile creare un nuovo gruppo di risorse seguendo questa procedura:

    1. Selezionare + Nuovo gruppo di risorse.

      Screenshot che mostra l'opzione per creare un nuovo gruppo di risorse di Azure.

    2. Selezionare il nome predefinito o immettere un nome appropriato per il gruppo di risorse.

      Screenshot che mostra il nome predefinito del nuovo gruppo di risorse di Azure.

    3. Selezionare il percorso per il gruppo di risorse.

      Screenshot che mostra le opzioni per il percorso del nuovo gruppo di risorse di Azure.

  4. Una finestra di dialogo avvisa che potrebbero essere addebitati costi per l'esecuzione di risorse in Azure. Selezionare Provisioning.

    Screenshot che mostra una finestra di dialogo che avvisa l'utente che potrebbe essere sostenuto un costo durante il provisioning delle risorse di Azure.

    Il processo di provisioning crea risorse nel cloud di Azure. Potrebbe volerci del tempo. Dopo alcuni minuti, viene visualizzato il messaggio seguente:

    Lo screenshot mostra un avviso che visualizza il provisioning dell'app dell'estensione del messaggio nel cloud.

    Se lo desideri, puoi visualizzare le risorse fornite. Per questa esercitazione non è necessario visualizzare le risorse.

    La risorsa di cui è stato eseguito il provisioning viene visualizzata in AMBIENTE.

    Screenshot che mostra la risorsa di cui viene eseguito il provisioning nella sezione ambiente.

  5. In LIFECYCLE selezionareDistribuisci.

    Screenshot che mostra la distribuzione dell'app nel cloud.

  6. Verrà visualizzata una finestra di dialogo che chiede se si desidera distribuire le risorse nell'ambiente di sviluppo. Seleziona Distribuisci.

    Screenshot che mostra la finestra di dialogo di conferma per distribuire l'app in Azure.

    Come per il provisioning, la distribuzione richiede del tempo. Dopo alcuni minuti, viene visualizzato un messaggio di completamento.

Eseguire l'app distribuita

Una volta completati i passaggi di provisioning e distribuzione, vai a Esegui ed esegui il debug (Ctrl+Maiusc+D o Visualizza > esecuzione) in Agents Toolkit.

  1. Selezionare il menu a discesa ESEGUI ED ESEGUI DEBUG .

  2. Selezionare Avvia remoto in Teams (Edge).

  3. Seleziona il pulsante ▷ .

    Screenshot che mostra l'opzione Avvia app in remoto in Teams.

  4. Si apre una finestra di dialogo per installare l'app distribuita in Teams. Selezionare Aggiungi.

    Screenshot che mostra un messaggio per aggiungere l'app distribuita.

    Teams apre l'app dell'estensione messaggio nella chat più recente.

    Screenshot che mostra l'estensione del messaggio aperta in una chat.

Informazioni su cosa accade quando si distribuisce l'app in Azure

Prima della distribuzione, l'app viene eseguita in locale.

  • Il back-end viene eseguito usando le Funzioni di Azure Core Tools.
  • L'endpoint HTTP dell'applicazione, in cui Microsoft Teams carica l'applicazione, viene eseguito in locale.

Il processo di distribuzione è previsto in due passaggi. È possibile effettuare il provisioning delle risorse in una sottoscrizione di Azure attiva e quindi distribuire o caricare il codice back-end e front-end dell'app in Azure.

  • Il back-end, se configurato, usa vari servizi di Azure, tra cui il Servizio app di Azure e Archiviazione di Azure.
  • L'app front-end viene distribuita in un account di archiviazione di Azure configurato per l'hosting Web statico.

Congratulazioni

È stata completata l'esercitazione per compilare un'app di estensione messaggio con JavaScript.

Ti è venuta in mente una cosa del genere?

Screenshot che mostra l'output finale dell'app dell'estensione del messaggio in Teams.

Creare un'app di estensione messaggio

Inizio pagina

Crea l'app per la prima scheda usando C diesis

Inizia a sviluppare app per Microsoft Teams creando la tua prima app di Teams con funzionalità a schede.

In questo tutorial imparerai quanto segue:

  • Come configurare un nuovo progetto.
  • Come creare app con funzionalità di schede utilizzando C# e Microsoft Visual Studio 2022.
Esercitazione: Crea l'app per la prima scheda con C#

Questa guida dettagliata ti aiuta a creare una scheda con Microsoft 365 Agents Toolkit (precedentemente noto come Teams Toolkit). Dopo aver completato questa guida, verrà visualizzato l'output seguente:

Screenshot che mostra l'output finale dell'app scheda Teams.

Prerequisiti per la creazione di app

Ecco un elenco degli strumenti che è necessario installare per creare e distribuire un'app di Teams.

Installare Per l'utilizzo...
Microsoft Teams Microsoft Teams per collaborare con tutti i tuoi collaboratori tramite app per chat, riunioni e chiamate, in un unico posto.
Visual Studio 2022
 È possibile installare la versione enterprise in Visual Studio 2022 e installare i carichi di lavoro di sviluppo ASP.NET e Web. Usa la versione più recente.
Toolkit per agenti di Microsoft 365 Un'estensione di Visual Studio che crea un'impalcatura del progetto per l'app. Usa la versione più recente.

Toolkit per l'installazione degli agenti

Agents Toolkit aiuta a semplificare il processo di sviluppo con strumenti per creare un'impalcatura di progetto per la tua app. Crea la struttura di directory necessaria per tutte le funzionalità selezionate con i file necessari in posizione, pronti per compilare il progetto.

È possibile scaricare il programma di installazione più recente di Visual Studio. Agents Toolkit è disponibile come estensione in Visual Studio.

Dopo aver aperto il programma di installazione di Visual Studio nella finestra popup dei carichi di lavoro:

  1. Seleziona ASP.NET e sviluppo web.

  2. In Dettagli installazione>Facoltativo, selezionare Strumenti di sviluppo di Microsoft Teams.

  3. Selezionare Installa.

    Screenshot che mostra l'installazione di Visual Studio.

  4. Seleziona Avvia. Viene visualizzata la finestra dell'app Visual Studio 2022.

    Screenshot che mostra la selezione di Avvia in Visual Studio.

  5. Passare a Gestisci>estensioni estensioni.

    Screenshot che mostra la selezione delle estensioni.

    Viene visualizzata la finestra Gestisci estensione:

    Screenshot che mostra la finestra Gestisci estensioni.

  6. Nel riquadro sinistro selezionare Installato. L'estensione Microsoft 365 Agents Toolkit è disponibile.

    Screenshot che mostra la selezione di Agents Toolkit.

Configurare il tenant di sviluppo di Teams

Un tenant è come uno spazio o un contenitore per l'organizzazione in Teams, in cui si chatta, si condividono file ed si eseguono riunioni. Questo spazio è anche il luogo in cui si carica e si testa l'app personalizzata. Verificare se si è pronti per lo sviluppo con il tenant.

Controllare l'opzione di caricamento dell'app personalizzata

Dopo aver creato l'app, è necessario caricarla in Teams senza distribuirla. Questo processo è noto come caricamento di app personalizzate. Accedi al tuo account Microsoft 365 per visualizzare questa opzione.

Nota

Il caricamento delle app personalizzate è necessario per visualizzare in anteprima e testare le app nell'ambiente locale di Teams. Se non è abilitata, non sarà possibile visualizzare in anteprima e testare l'app nell'ambiente locale di Teams.

Si ha già un tenant e l'accesso come amministratore? Controlliamo se lo fai!

Verificare se è possibile caricare app personalizzate in Teams:

  1. Apri Microsoft Teams, seleziona l'icona App .

  2. Seleziona Gestisci le tue app.

  3. Selezionare Carica un'app.

  4. Cercare l'opzione Carica un'app personalizzata . Se viene visualizzata l'opzione, il caricamento di app personalizzate è abilitato.

    La figura mostra l'opzione per caricare un'app personalizzata in Teams.

Nota

Se non trovi l'opzione per caricare un'app personalizzata, contatta l'amministratore di Teams.

Creare un tenant di sviluppo di Teams gratuito (facoltativo)

Se non hai un account Teams, puoi ottenerlo gratuitamente. Partecipa al programma per sviluppatori di Microsoft 365!

  1. Passare al programma per sviluppatori di Microsoft 365.

  2. Seleziona Partecipa ora e segui le istruzioni sullo schermo.

  3. Nella schermata iniziale, seleziona Configura abbonamento E5.

  4. Configura il tuo account amministratore. Al termine, viene visualizzata la schermata seguente:

    Screenshot che mostra un esempio di ciò che viene visualizzato dopo l'iscrizione al programma per sviluppatori di Microsoft 365.

  5. Accedere a Teams con l'account amministratore configurato. Verificare di avere l'opzione Carica un'app personalizzata in Teams.

Ottenere un account di Azure gratuito

Se si vuole ospitare l'app o accedere alle risorse in Azure, è necessario avere una sottoscrizione di Azure. Crea un account gratuito prima di iniziare.

Ora hai tutti gli strumenti per configurare il tuo account. Quindi, configuriamo il tuo ambiente di sviluppo e iniziamo a costruire! Selezionare l'app che si vuole creare per prima.

Crea un'area di lavoro di progetto per l'app a schede usando C diesis

Iniziare a sviluppare app per Microsoft Teams creando la prima app. Questa app usa la funzionalità scheda. Se i prerequisiti ci sono, iniziamo!

La procedura seguente consente di creare un'area di lavoro del progetto per l'app a schede in Visual Studio:

  1. Aprire Visual Studio.

  2. Selezionare Nuovo progetto.

    Screenshot che mostra la selezione di Nuovo progetto in Visual Studio.

  3. Nella casella di ricerca immettere Teams.

  4. Selezionare Agenti >di Microsoft 365successivamente.

    Screenshot che mostra la selezione di Teams.

  5. Immettere i dettagli seguenti per configurare il nuovo progetto.

  6. Immettere il nome del progetto richiesto in Nome progetto.

  7. Selezionare la posizione necessaria per salvare i file e le cartelle del progetto.

  8. Selezionare Crea.

    Screenshot che mostra la creazione del nome del progetto.

  9. Seleziona Crea scheda>.

    Screenshot che mostra la selezione della scheda.

L'app scheda Teams viene creata in pochi secondi.

Screenshot che mostra la creazione del progetto.

Crea ed esegui l'app della prima scheda usando C diesis

Dopo aver configurato l'area di lavoro del progetto con Agents Toolkit, crea l'app a schede.

Accedi al tuo account Microsoft 365

Usare il proprio account Microsoft 365 per accedere a Teams. Se usi un tenant del programma per sviluppatori di Microsoft 365, l'account amministratore configurato durante la registrazione è il tuo account Microsoft 365.

  1. In Esplora soluzioni, in Soluzione MyTeamsApp, fare clic con il pulsante destro del mouse su MyTeamsApp.

  2. Seleziona Microsoft 365 Agents Toolkit>Seleziona l'account Microsoft 365.

    Screenshot che mostra la selezione delle dipendenze dell'app Teams.

  3. Seleziona l'account> Microsoft 365Continua.

    Screenshot che mostra la selezione dell'account M365.

Compilare ed eseguire l'app in locale in Visual Studio

Per creare ed eseguire l'app in locale:

  1. Selezionare Debug,>Avvia debug o selezionare F5.

    Screenshot che mostra la selezione dell'azione di avvio debug.

    Visual Studio avvia il processo di debug e apre il client Web di Teams in un browser. Se richiesto, accedi con il tuo account Microsoft 365.

  2. Selezionare Aggiungi.

    Screenshot della finestra di dialogo dei dettagli dell'app per aggiungere l'app scheda a Teams.

  3. Selezionare Apri per aprire l'app nell'ambito personale.

In alternativa, puoi cercare e selezionare l'ambito richiesto oppure selezionare un canale o una chat dall'elenco e spostarti nella finestra di dialogo per selezionare Vai.

Screenshot che mostra la finestra di dialogo di selezione dell'ambito con l'elenco degli ambiti condivisi.

Congratulazioni, l'app della prima scheda è in esecuzione su Teams!

Screenshot che mostra l'output finale dell'app scheda Teams.

Informazioni su come risolvere i problemi se l'app non viene eseguita in locale.

Per eseguire correttamente l'app in Teams, assicurarsi di aver abilitato il caricamento dell'app personalizzata nell'account di Teams. Per altre informazioni sul caricamento di app personalizzate, vedere la sezione dei prerequisiti .

È stata creata correttamente un'app a schede usando C#. Agents Toolkit ha aggiunto lo scaffolding necessario alla struttura di directory della tua app. L'esercitazione è ora completa.

Creare una scheda

Creare un nuovo progetto di Teams utilizzando il Toolkit agenti di Microsoft 365

Inizio pagina

Aggiungere SSO all'app di estensione schede e messaggi

L'accesso Single Sign-On (SSO) di Microsoft Entra consente l'autenticazione facile degli utenti in Teams.

Aspetti principali di Microsoft Entra SSO:

  • Consente all'utente di accedere automaticamente dopo il primo accesso.
  • Consente all'utente di accedere ad altri dispositivi senza immettere nuovamente le credenziali.
  • Ottiene il token per l'utente connesso.
Esercitazione: Aggiungere SSO all'app di estensione schede e messaggi

Questa guida dettagliata consente di creare schede ed estensioni dei messaggi che abilitino l'autenticazione SSO di Microsoft Entra. Verrà visualizzato l'output seguente:

Screenshot dell'uscita dell'autenticazione della scheda e del messaggio con l'autenticazione SSO dopo aver completato la guida dettagliata.

Prerequisiti per l'aggiunta di SSO alle app

Assicurati di installare gli strumenti seguenti e di configurare l'ambiente di sviluppo:

# Installare Per l'utilizzo...
1. Microsoft Teams Microsoft Teams per collaborare con tutti gli utenti tramite app per chat, riunioni e chiamate in un'unica posizione.
2. Account sviluppatore di Microsoft 365 Accesso all'account di Teams con le autorizzazioni appropriate per installare un'app.
3. .NET Core SDK Associazioni personalizzate per il debug locale e le distribuzioni di app Funzioni di Azure. Se non è installata la versione più recente, installare la versione portatile.
4. Visual Studio 2022 È possibile installare la versione enterprise in Visual Studio 2022 e installare i carichi di lavoro di sviluppo ASP.NET e Web. Usa la versione più recente.
5. Tunnel di sviluppo Le funzionalità dell'app Teams (bot conversazionali, estensioni dei messaggi e webhook in ingresso) richiedono connessioni in ingresso. Un tunnel connette il sistema di sviluppo a Teams. Dev tunnel è un potente strumento per aprire in modo sicuro il tuo localhost a Internet e controllare chi ha accesso. Il tunnel di sviluppo è disponibile in Visual Studio 2022 versione 17.7.0 o successiva.
oppure
È possibile usare ngrok anche come tunnel per connettere il sistema di sviluppo a Teams. Non è necessario per le app che includono solo schede. Questo pacchetto è installato all'interno della directory del progetto (usando npm devDependencies).

Nota

Dopo aver scaricato ngrok, registrati e installa authtoken.

Configurare l'ambiente locale

  1. Apri Microsoft-Teams-samples.

  2. Selezionare il codice.

  3. Nel menu a discesa selezionare Apri con GitHub Desktop.

    Screenshot che mostra l'opzione per clonare il repository in locale.

  4. Seleziona Clona.

Registra l'app Microsoft Entra

La procedura seguente consente di creare e registrare il bot nel portale di Azure:

  • Creare e registrare l'app di Azure.
  • Creare un segreto client per abilitare l'autenticazione SSO del bot.
  • Aggiungere il canale Teams per distribuire il bot.
  • Crea un tunnel per gli endpoint del server Web usando Dev Tunnel (consigliato) o NGREK.
  • Aggiungere l'endpoint di messaggistica al tunnel di sviluppo creato.

Aggiungere la registrazione dell'app

  1. Passare al portale di Azure.

  2. Selezionare Registrazioni app.

    Screenshot che mostra i servizi di Azure per selezionare Registrazioni app.

  3. Selezionare + Nuova registrazione.

    Screenshot che mostra la pagina Nuova registrazione in Interfaccia di amministrazione di Microsoft Entra.

  4. Immettere il nome dell'app.

  5. Selezionare gli account in qualsiasi directory organizzativa (qualsiasi tenant Microsoft Entra ID - multitenant).

  6. Seleziona Registrati.

    Screenshot che mostra l'opzione per registrare il bot nell'interfaccia di amministrazione di Microsoft Entra.

    L'app è registrata in Microsoft Entra ID. Viene visualizzata la pagina Panoramica app.

    Screenshot che mostra la pagina di panoramica della registrazione dell'app.

    Nota

    Salvare l'ID app dall'ID applicazione (client) e dall'ID directory (tenant) per un ulteriore utilizzo.

Creare un tunnel

Selezionare una delle seguenti modalità per creare un tunnel:

  1. Aprire Visual Studio.

  2. Seleziona Crea un nuovo progetto.

    Screenshot che mostra la selezione per creare un nuovo progetto.

  3. Nella casella di ricerca immettere ASP.NET. Nei risultati della ricerca selezionare App Web ASP.NET Core.

  4. Selezionare Avanti.

    Screenshot che mostra la ricerca e la selezione del modello.

  5. Immettere il nome del progetto e selezionare Avanti.

    Screenshot che mostra il nome del progetto da inserire.

  6. Selezionare Crea.

    Screenshot che mostra le informazioni aggiuntive del progetto.

    Viene visualizzata una finestra di panoramica.

    Screenshot che mostra la finestra panoramica.

  7. Nell'elenco a discesa debug, selezionare Tunnel di sviluppo (nessun tunnel attivo)>Crea un tunnel....

    Screenshot che mostra l'elenco a discesa per selezionare i tunnel dev.

    Viene visualizzata una finestra popup.

  8. Aggiorna i seguenti dettagli nella finestra popup:

    1. Account: immetti un account Microsoft o GitHub.
    2. Nome: immettere un nome per il tunnel.
    3. Tipo di tunnel: dall'elenco a discesa, selezionare Temporaneo.
    4. Accesso: dall'elenco a discesa, selezionare Pubblico.

  9. Selezionare OK.

    Screenshot che mostra i dettagli da aggiornare per la creazione del tunnel.

    Viene visualizzata una finestra popup che mostra che il tunnel di sviluppo è stato creato correttamente.

  10. Selezionare OK.

    Lo screenshot mostra il messaggio popup che indica che il tunnel è stato creato.

    Puoi trovare il tunnel che hai creato nell'elenco a discesa di debug come segue:

    Lo screenshot mostra che il tunnel è attivo e selezionato.

  11. Selezionare F5 per eseguire l'applicazione in modalità di debug.

  12. Se viene visualizzata una finestra di dialogo Avviso di sicurezza , selezionare Sì.

    Screenshot che mostra la finestra di dialogo per accettare l'avviso di sicurezza.

    Viene visualizzata una finestra popup.

  13. Selezionare Continua.

    Screenshot che mostra l'URL del tunnel.

    La home page di Dev Tunnel si apre in una nuova finestra del browser e Dev Tunnel è ora attivo.

    Screenshot che mostra la pagina di benvenuto di Dev Tunnel nel browser.

  14. Passare a Visual Studio e quindi selezionare Visualizza > output.

  15. Dal menu a discesa della console di output , seleziona Dev Tunnel.

    La console di output mostra l'URL del tunnel di sviluppo.

    Screenshot che mostra l'URL nella console di output di Visual Studio.

Aggiungere un'autenticazione Web

  1. Nel riquadro sinistro, in Gestisci, selezionare Autenticazione.

  2. Selezionare Aggiungi una piattaforma>Web.

    Screenshot che mostra la selezione dell'autenticazione Web.

  3. Immettere l'URI di reindirizzamento per l'app aggiungendolo auth-end al nome di dominio completo. Ad esempio, https://your-devtunnel-domain/auth-end o https://your-ngrok-domain/auth-end.

  4. In Concessione implicita e flussi ibridi selezionare le caselle di controllo Token di accesso e Token ID .

  5. Selezionare Configura.

    Lo screenshot mostra l'opzione per aggiungere URI di reindirizzamento e selezionare la concessione implicita e i flussi ibridi.

  6. In Web selezionare Aggiungi URI.

  7. Immettere https://token.botframework.com/.auth/web/redirect.

  8. Selezionare Salva.

    Screenshot che mostra l'opzione per aggiungere l'URI di reindirizzamento e selezionare la concessione implicita e i flussi ibridi.

Creare un segreto client

Nota

Se viene visualizzato l'errore, i segreti client vengono bloccati dai criteri a livello di tenant. Per altre informazioni, contattare l'amministratore del tenant, è possibile creare un certificato. Per istruzioni dettagliate, fare riferimento a Creare un certificato per la registrazione dell'app.

  1. Nel riquadro sinistro, in Gestisci, seleziona Certificati & segreti.

  2. In Segreti client selezionare + Nuovo segreto client.

    Screenshot che mostra la selezione del nuovo segreto client.

    Viene visualizzata la finestra Aggiungi un segreto client .

  3. Immettere la descrizione.

  4. Selezionare Aggiungi.

    Screenshot che mostra l'opzione di descrizione del segreto client per aggiungerla.

  5. In Valore, selezionare Copia negli Appunti per salvare il valore del segreto client per un ulteriore utilizzo.

    Screenshot che mostra l'opzione per copiare il valore dell'ID segreto client per copiare il valore negli Appunti.

Aggiungere autorizzazioni API

  1. Nel riquadro sinistro selezionare Autorizzazioni API.

  2. Selezionare + Aggiungi un'autorizzazione.

    Lo screenshot mostra l'opzione per selezionare Aggiungi autorizzazione.

  3. Selezionare Microsoft Graph.

  4. Selezionare Autorizzazioni delegate.

  5. Selezionare Utente>User.Read.

  6. Selezionare Aggiungi autorizzazioni.

    Screenshot che mostra l'opzione per selezionare le autorizzazioni.

    Nota

    • Se a un'app non viene concesso il consenso dell'amministratore IT, gli utenti devono fornire il consenso la prima volta che usano un'app.
    • Gli utenti devono acconsentire alle autorizzazioni API solo se l'app Microsoft Entra è registrata in un tenant diverso.

Aggiungere l'URI dell'ID applicazione

  1. Nel riquadro sinistro, in Gestisci, selezionare Esponi un'API.

  2. Accanto a URI ID applicazione selezionare Aggiungi.

    Screenshot che mostra l'opzione per aggiungere l'ID applicazione URI.

  3. Aggiornare l'URI dell'IDapi://your-devtunnel-domain/botid-{AppID} applicazione nel formato o api://your-ngrok-domain/botid-{AppID} e selezionare Salva.

    Screenshot che mostra l'opzione per aggiungere l'URI di reindirizzamento e salvare.

    L'immagine seguente mostra il nome del dominio:

    Screenshot che mostra l'URI di reindirizzamento.

Aggiungere un ambito

  1. Nel riquadro sinistro, in Gestisci, selezionare Esponi un'API.

  2. Selezionare + Aggiungere un ambito.

    Lo screenshot mostra la selezione per aggiungere un ambito.

  3. Immetti access_as_user come nome dell'ambito.

  4. In Chi può fornire il consenso?, selezionare Amministratori e utenti.

  5. Aggiornare i valori per il resto dei campi come indicato di seguito:

    • Invio Teams può accedere al profilo dell'utente come nome visualizzato con il consenso dell'Amministratore.

    • INVIO Consente a Teams di chiamare le API Web dell'app come utente corrente come descrizione del consenso dell'Amministratore.

    • Invio Teams può accedere al profilo utente ed effettuare richieste per conto dell'utente come nome visualizzato per il consenso dell'utente.

    • Invio Consenti a Teams di chiamare le API di questa app con gli stessi diritti dell'utente della descrizione delconsenso dell'utente.

  6. Assicurati che lo stato sia impostato su Abilitato.

  7. Selezionare Aggiungi ambito.

    La figura seguente mostra i campi e i valori:

    Lo screenshot mostra i valori compilati nel campo per Aggiungere un ambito.

    Nota

    Il nome dell'ambito deve corrispondere all'ID applicazione URI, con /access_as_user l'aggiunta alla fine.

    Lo screenshot mostra i dettagli negli ambiti.

Aggiungere un'applicazione client

  1. Nel riquadro sinistro, in Gestisci, selezionare Esponi un'API.

    In Applicazioni client autorizzate identificare le applicazioni che si desidera autorizzare per l'applicazione Web dell'app.

  2. Selezionare + Aggiungi un'applicazione client.

    Screenshot che mostra l'opzione Seleziona applicazione client.

  3. Aggiungere Teams per dispositivi mobili o desktop e l'applicazione Web di Teams.

    1. Per Teams per dispositivi mobili o desktop: immettere l'ID client come 1fec8e78-bce4-4aaf-ab1b-5451cc387264.

      Screenshot che mostra l'applicazione ID client per dispositivi mobili o desktop.

    2. Per Teams Web: immettere l'ID client come 5e3ce6c0-2b1f-4285-8d4b-75ee78787346.

      Screenshot che mostra l'applicazione ID client Web.

  4. Selezionare la casella di controllo Ambiti autorizzati .

  5. Selezionare Aggiungi applicazione.

    Screenshot che mostra l'opzione per selezionare gli ambiti autorizzati e aggiungere l'applicazione.

    L'immagine seguente mostra l'ID client:

    Screenshot che mostra l'output delle applicazioni client.

Aggiornare il manifesto

  1. Nel riquadro sinistro selezionare Manifesto.

  2. Imposta il valore per su requestedAccessTokenVersion2 e seleziona Salva.

    Screenshot che mostra l'opzione manifesto e i dettagli del token di accesso nel portale di Azure.

Creare un bot

Creare una risorsa Bot di Azure

Nota

Se si sta già testando il bot in Teams, disconnettersi dall'app e da Teams. Per visualizzare questa modifica, accedere di nuovo.

  1. Vai alla Home.

  2. Selezionare + Crea una risorsa.

  3. Nella casella di ricerca immettere Azure Bot.

  4. Seleziona INVIO.

  5. Selezionare Bot di Azure.

  6. Selezionare Crea.

    Screenshot che mostra la creazione del bot di Azure.

  7. Immettere il nome del bot in Bot handle.

  8. Seleziona il tuo abbonamento dall'elenco a discesa.

  9. Seleziona il tuo gruppo di risorse dall'elenco a discesa.

    Screenshot che mostra l'opzione gruppo di risorse e sottoscrizione nel portale di Azure.

    Se non si ha un gruppo di risorse esistente, è possibile creare un nuovo gruppo di risorse. Per creare un nuovo gruppo di risorse, seguire questa procedura:

    1. Selezionare Crea nuovo.
    2. Immettere il nome della risorsa e selezionare OK.
    3. Selezionare una posizione nell'elenco a discesa Nuova posizione gruppo di risorse .

    Screenshot che mostra l'opzione Nuovo gruppo di risorse nel portale di Azure.

  10. In Prezzi, seleziona Cambia piano.

    Screenshot che mostra l'opzione di prezzo nel portale di Azure.

  11. Selezionare Selezione libera> FO.

    Screenshot che mostra l'opzione per selezionare gratuito.

  12. In ID app Microsoft, selezionare il tipo di app come multi-tenant.

  13. In Tipo di creazione selezionare Usa registrazione app esistente.

  14. Immettere l'ID dell'app.

    Nota

    Non è possibile creare più di un bot con lo stesso ID app Microsoft.

  15. Seleziona Rivedi + Crea.

    Screenshot che mostra la creazione di un nuovo bot.

  16. Al termine della convalida, seleziona Crea.

    Il bot richiede alcuni minuti per il provisioning.

  17. Seleziona Vai alla risorsa.

    Screenshot che mostra l'opzione Vai alla risorsa nel portale di Azure.

    Il bot di Azure è stato creato correttamente.

    Screenshot che mostra l'output di un bot.

Aggiungere un canale di Teams

  1. Nel riquadro sinistro selezionare Canali.

  2. In Canali disponibili selezionare Microsoft Teams.

    Screenshot che mostra la selezione di Teams nei canali.

  3. Seleziona la casella di controllo per accettare le condizioni d'uso.

  4. Seleziona Accetto.

    Screenshot che mostra l'accettazione delle condizioni d'uso.

  5. Selezionare Applica.

    Screenshot che mostra Microsoft Teams come messaggio da applicare.

Per aggiungere un endpoint di messaggistica

  1. Utilizza l'URL del tunnel di sviluppo nella console di output come endpoint di messaggistica.

    Screenshot che mostra l'URL nella console di output di Visual Studio.

  2. Nel riquadro sinistro, in Impostazioni, selezionare Configurazione.

  3. Aggiornare l'endpoint di messaggistica nel formato https://your-devtunnel-domain/api/messages.

    Lo screenshot mostra l'endpoint di messaggistica che aggiunge l'API.

  4. Selezionare Applica.

    È stato configurato correttamente un bot nel servizio Azure Bot.

    Nota

    Se la chiave di strumentazione di Application Insights mostra un errore, eseguire l'aggiornamento con l'ID app.

Aggiungere impostazioni di connessione OAuth

  1. Nel riquadro sinistro selezionare Configurazione.

  2. Selezionare Aggiungi impostazioni di connessione OAuth.

  3. In Nuova impostazione di connessione, aggiornare i dettagli seguenti:

    • Nome: immettere un nome per la nuova impostazione di connessione. È possibile usare il nome nelle impostazioni del codice del servizio bot.
    • Provider di servizi: nell'elenco a discesa selezionare Azure Active Directory v2.
    • ID client: aggiornare l'ID dell'app Microsoft.
    • Segreto client: aggiornare il valore dei segreti client.
    • URL di scambio token: aggiornare l'URI dell'ID applicazione.
    • ID tenant: immettere common.
    • Ambiti: Immettere User.Read.

  4. Selezionare Salva.

    Screenshot che mostra i valori aggiunti per impostare la connessione OAuth.

Configurare le impostazioni dell'app

  1. Passare al file appsettings.json nel repository clonato.

    Screenshot del file di Project con appsettings.json file evidenziato in rosso.

  2. Aprire il file appsettings.json in Visual Studio.

  3. Aggiornare le informazioni seguenti:

    • Sostituire "MicrosoftAppId" con l'ID app Microsoft del bot.
    • Sostituisci "MicrosoftAppPassword" ai segreti client del bot Valore.
    • Sostituisci "SiteUrl" con il tuo URL ngrok.
    • Sostituisci "ConnectionName" con il nome dell'impostazione di connessione OAuth.
    • Sostituisci "TenantId" con l'ID tenant del tenant in cui viene usata l'app.
    • Sostituire "ClientId" con l'ID app Microsoft del bot.
    • Sostituisci "AppSecret" ai segreti client del bot Valore.
    • Sostituisci "ApplicationIdURI" sotto forma di api://*******.ngrok.io/botid-{AppID}.

    Screenshot del file di appsettings.json con i valori immessi evidenziati in rosso.

Configurare il file manifest

  1. Passare al file manifest.json nel repository clonato.

    Screenshot della cartella manifesto con il file manifesto evidenziato in rosso.

  2. Aprire il file manifest.json in Visual Studio e apportare le modifiche seguenti:

    • Sostituisci DOMAIN-NAME con il tuo URL ngrok.

    • Sostituire YOUR-MICROSOFT-APP-ID con l'ID dell'app Microsoft del bot.

      Nota

      A seconda dello scenario [YOUR-MICROSOFT-APP-ID] e [DOMAIN-NAME] può verificarsi più volte.

    • Sostituisci resource come api://*******.ngrok.io/botid-{AppID}.

      Screenshot del file di manifest.json con i valori immessi evidenziati in rosso.

Creare ed eseguire il servizio

Per compilare ed eseguire il servizio, utilizzare Visual Studio o la riga di comando.

  1. Aprire Visual Studio.

  2. Seleziona File>Apri> *Progetto/Soluzione...

    Screenshot del menu file di Visual Studio. Le voci di menu Intitolate Apri nel menu File e Progetto/Soluzione in Apri sono evidenziate in rosso.

  3. Nella cartella csharp selezionare il file Sample.csproj di App SSO .

    Screenshot del file di progetto con il file Sample.csproj di App SSO evidenziato in rosso.

  4. Premere F5 per avviare il progetto.

  5. Selezionare Sì se viene visualizzata la finestra di dialogo seguente:

    Screenshot dell'avviso di sicurezza con l'opzione Sì evidenziata in rosso.

Viene visualizzata una pagina Web con un messaggio Il bot è pronto.

Screenshot della pagina Web che mostra che il bot è pronto.

Inizio pagina

  • Last updated on