Créer une extension de messagerie
Dans cette unité, vous allez apprendre à créer une extension de message. Vous découvrez également comment exécuter et déboguer votre extension de message dans Microsoft Teams à l’aide du Kit de ressources Teams.
Pour créer une extension de message, vous avez besoin des composants suivants :
- Ressource Azure Bot pour inscrire votre service web en tant que bot auprès de Bot Framework
- Service web pour gérer les interactions utilisateur avec l’extension de message
- Manifeste d’application pour définir les fonctionnalités d’extension de message dans Microsoft Teams
Configurer une ressource Azure Bot
La ressource Azure Bot est utilisée pour inscrire votre service web en tant que bot auprès de Bot Framework. Une inscription d’application Microsoft Entra est nécessaire pour créer une ressource Azure Bot. L’inscription de l’application offre un moyen sécurisé d’authentifier et d’autoriser votre bot. Le service web utilise les informations d’identification d’inscription d’application Microsoft Entra pour s’authentifier auprès du service bot.
L’extrait de code suivant montre comment créer une ressource Azure Bot à l’aide de Bicep :
resource botService 'Microsoft.BotService/botServices@2021-03-01' = {
kind: 'azurebot'
location: 'global'
name: 'botService'
properties: {
displayName: 'Bot Service'
endpoint: 'https://webservice.contoso.com/api/messages'
msaAppId: '00000000-0000-0000-0000-000000000000'
}
sku: {
name: botServiceSku
}
}
La propriété endpoint spécifie le point de terminaison de messagerie exposé sur le service web que le service bot utilise pour envoyer des demandes lorsqu’un utilisateur interagit avec l’extension de message. La propriété msaAppId spécifie l’ID d’inscription d’application Microsoft Entra utilisé pour authentifier le service bot auprès du service web.
Les canaux sont utilisés pour connecter le service de bot à des plateformes de messagerie telles que Microsoft Teams, Slack, Facebook Messenger, etc.
L’extrait de code suivant montre comment configurer les canaux Microsoft Teams et Microsoft 365 (Outlook et Microsoft 365 Copilot) sur la ressource Azure Bot :
resource botServiceMsTeamsChannel 'Microsoft.BotService/botServices/channels@2021-03-01' = {
parent: botService
location: 'global'
name: 'MsTeamsChannel'
properties: {
channelName: 'MsTeamsChannel'
}
}
resource botServiceM365ExtensionsChannel 'Microsoft.BotService/botServices/channels@2022-06-15-preview' = {
parent: botService
location: 'global'
name: 'M365Extensions'
properties: {
channelName: 'M365Extensions'
}
}
Configurer le service web
Le service web est une application web qui contient le code d’extension de message. Le service web est responsable de la gestion des interactions utilisateur avec l’extension de message et utilise le Kit de développement logiciel (SDK) Bot Framework pour communiquer avec le service bot.
Pour gérer les interactions utilisateur, vous implémentez :
- Un point de terminaison de messagerie
- Un adaptateur de bot
- Gestionnaire d’activité de bot
Le point de terminaison de messagerie est utilisé pour recevoir des demandes du service bot. Le point de terminaison de messagerie est exposé sur le service web et transmet les demandes à l’adaptateur bot pour traitement.
L’extrait de code suivant montre comment configurer le point de terminaison de messagerie :
[Route("api/messages")]
[ApiController]
public class BotController : ControllerBase
{
private readonly IBotFrameworkHttpAdapter Adapter;
private readonly IBot Bot;
public BotController(IBotFrameworkHttpAdapter adapter, IBot bot)
{
Adapter = adapter;
Bot = bot;
}
[HttpPost, HttpGet]
public async Task PostAsync()
{
await Adapter.ProcessAsync(Request, Response, Bot);
}
}
L’adaptateur bot est utilisé pour connecter le service bot au service web. Bot Adapter est responsable du traitement des demandes entrantes du service bot et de l’appel du gestionnaire d’activité du bot. Le service web s’authentifie auprès du service bot à l’aide des informations d’identification d’inscription d’application Microsoft Entra utilisées pour inscrire la ressource Azure Bot auprès de Bot Framework.
L’extrait de code suivant montre comment configurer l’adaptateur bot dans le service web :
// Create the Bot Framework Authentication to be used with the Bot Adapter.
var config = builder.Configuration.Get<ConfigOptions>();
builder.Configuration["MicrosoftAppType"] = "MultiTenant";
builder.Configuration["MicrosoftAppId"] = config.BOT_ID;
builder.Configuration["MicrosoftAppPassword"] = config.BOT_PASSWORD;
builder.Services.AddSingleton<BotFrameworkAuthentication, ConfigurationBotFrameworkAuthentication>();
// Create the Bot Framework Adapter with error handling enabled.
builder.Services.AddSingleton<IBotFrameworkHttpAdapter, AdapterWithErrorHandler>();
// Create the bot as a transient. In this case the ASP Controller is expecting an IBot.
builder.Services.AddTransient<IBot, SearchApp>();
Pour traiter la requête de recherche utilisateur et retourner les résultats de la recherche, implémentez un gestionnaire d’activités bot qui hérite de la classe TeamsActivityHandler fournie par le Kit de développement logiciel (SDK) Bot Framework et remplacez la méthode OnTeamsMessagingExtensionQueryAsync .
L’extrait de code suivant montre comment configurer le gestionnaire d’activités du bot dans le service web :
public class SearchApp : TeamsActivityHandler
{
protected override async Task<MessagingExtensionResponse> OnTeamsMessagingExtensionQueryAsync(ITurnContext<IInvokeActivity> turnContext, MessagingExtensionQuery query, CancellationToken cancellationToken)
{
var text = query?.Parameters?[0]?.Value as string ?? string.Empty;
var card = await File.ReadAllTextAsync(Path.Combine(".", "Resources", "card.json"), cancellationToken);
var template = new AdaptiveCards.Templating.AdaptiveCardTemplate(card);
return new MessagingExtensionResponse
{
ComposeExtension = new MessagingExtensionResult
{
Type = "result",
AttachmentLayout = "list",
Attachments = [
new MessagingExtensionAttachment
{
ContentType = AdaptiveCard.ContentType,
Content = JsonConvert.DeserializeObject(template.Expand(new { text })),
Preview = new ThumbnailCard { Title = text }.ToAttachment()
}
]
}
};
}
}
Configurer la commande de recherche
Le manifeste de l’application est un fichier JSON qui définit les métadonnées et la configuration de l’application. Il définit les fonctionnalités que l’application fournit, telles que les extensions de message. Le manifeste de l’application est inclus dans le package d’application. Le package d’application est un fichier ZIP que vous chargez dans Microsoft Teams pour installer l’application.
L’extrait de code suivant montre comment une commande de recherche est définie dans le manifeste de l’application :
"composeExtensions": [
{
"botId": "4cc3ac43-d581-403d-8bbf-ff9c0fbf3fb2",
"commands": [
{
"id": "Search",
"type": "query",
"title": "Products",
"description": "Find products by name",
"initialRun": true,
"fetchTask": false,
"context": [
"commandBox",
"compose",
"message"
],
"parameters": [
{
"name": "ProductName",
"title": "Product name",
"description": "The name of the product as a keyword",
"inputType": "text"
}
]
}
]
}
]
Une commande peut contenir un ou plusieurs paramètres. Un paramètre est un champ affiché dans l’interface utilisateur. Dans cet exemple, la commande a un seul paramètre nommé ProductName. Le paramètre est un champ de texte que l’utilisateur remplit avec le nom du produit qu’il recherche.
Extension de kit de ressources Teams pour Visual Studio
Teams Toolkit pour Visual Studio est une extension qui fournit des outils pour créer, déboguer et déployer des applications Microsoft Teams. Teams Toolkit s’intègre à Visual Studio pour simplifier le processus de développement et fournir une expérience transparente pour la création d’applications Microsoft Teams.
Teams Toolkit crée une structure d’une solution contenant deux projets, un projet de service web et un projet d’application Teams. Le projet de service web contient le code d’extension de message et le projet d’application contient le manifeste de l’application et d’autres ressources nécessaires pour exécuter l’application dans Microsoft Teams.
Teams Toolkit s’intègre à la fonctionnalité De tunnels de développement dans Visual Studio pour permettre la communication entre le service bot et le service web exécuté localement. Les tunnels de développement exposent le service web au-delà de votre machine pour permettre au service bot de l’atteindre.
