Démarrage rapide : Ajout d’un bot à une application de conversation
Découvrez comment créer des expériences d’intelligence artificielle conversationnelle dans notre application de conversation en utilisant le canal de messagerie Azure Communication Services – Conversation disponible dans Azure Bot Service. Dans ce guide de démarrage rapide, vous créez un bot à l’aide du Kit de développement logiciel (SDK) BotFramework. Ensuite, vous intégrez le bot à une application de conversation que vous créez à l’aide du Kit de développement logiciel (SDK) Communication Services Chat.
Dans ce guide de démarrage rapide, vous apprenez à :
- Créer et déployer un bot dans Azure
- Obtenir une ressource Communication Services
- Activer le canal Conversation de Communication Services pour le bot
- Créer une application de conversation et ajouter le bot aux participants
- Explorer davantage de fonctionnalités pour votre bot
Prérequis
- Un compte et un abonnement Azure actifs. Créez un compte gratuitement.
- Visual Studio 2019 ou ultérieur.
- La dernière version de .NET Core. Dans ce guide de démarrage rapide, nous utilisons .NET Core 3.1. Veillez à installer la version qui correspond à votre instance de Visual Studio, 32 bits ou 64 bits.
- Kit de développement logiciel (SDK) Bot Framework
Créer et déployer un bot dans Azure
Pour utiliser la conversation Azure Communication Services comme canal dans Azure Bot Service, déployez d’abord un bot. Pour déployer un bot, procédez comme suit :
- Créer une ressource d’Azure Bot Service
- Obtenir l’ID d’application et le mot de passe du bot
- Créer une application web pour contenir la logique du bot
- Créer un point de terminaison de messagerie pour le bot
Créer une ressource d’Azure Bot Service
Tout d’abord, utilisez le Portail Azure pour créer une ressource Azure Bot Service. Le canal de conversation Communication Services prend en charge les bots monolocataires, les bots d’identité managée et les bots multilocataires. Pour les besoins de ce démarrage rapide, nous allons utiliser un bot multilocataire.
Pour configurer un bot d’identité managée ou monolocataire, passez en revue les informations d’identité du bot.
Pour les bots d’identité managée, vous devrez peut-être mettre à jour l’identité du service de bot.
Obtenir l’ID d’application et le mot de passe d’application du bot
Ensuite, obtenez l’ID d’application et le mot de passe Microsoft qui sont attribués à votre bot lors de son déploiement. Vous utilisez ces valeurs pour les configurations ultérieures.
Créer une application web pour contenir la logique du bot
Pour créer une application web pour votre bot, vous pouvez réviser des exemples Bot Builder pour votre scénario ou utiliser le Kit de développement logiciel (SDK) Bot Builder pour créer une application web. L’un des exemples les plus simples est Echo Bot.
Azure Bot Service s’attend généralement à ce que le contrôleur d’application web du bot pour exposer un point de terminaison dans le formulaire /api/messages
. Le point de terminaison gère tous les messages envoyés au bot.
Pour créer l’application bot, utilisez Azure CLI pour créer une ressource Azure App Service ou créez l’application dans le Portail Azure.
Pour créer une application web de bot à l’aide du Portail Azure :
Dans le portail, sélectionnez Créer une ressource. Dans la zone de recherche, entrez application web. Sélectionnez la vignette Application web.
Dans Créer une application web, sélectionnez ou entrez les détails de l’application, y compris la région dans laquelle vous souhaitez déployer l’application.
Sélectionnez Réviser + Créer pour valider le déploiement et passer en revue les détails du déploiement. Sélectionnez ensuite Create (Créer).
Lorsque la ressource d’application web est créée, copiez l’URL du nom d’hôte qui s’affiche dans les détails de la ressource. L’URL fait partie du point de terminaison que vous créez pour l’application web.
Créer un point de terminaison de messagerie pour le bot
Ensuite, dans la ressource de bot, créez un point de terminaison de messagerie d’application web :
Dans le portail Azure, accédez à votre ressource Azure Bot. Dans le menu Ressource, sélectionnez Configuration.
Dans Configuration, pour Point de terminaison de messagerie, collez l’URL du nom d’hôte de l’application web que vous avez copiée dans la section précédente. Ajoutez à l’URL avec
/api/messages
.Cliquez sur Enregistrer.
Déployer l’application web
La dernière étape pour créer un bot consiste à déployer l’application web. Pour ce démarrage rapide, utilisez l’exemple Echo Bot. La fonctionnalité Echo Bot se limite à l’écho de l’entrée utilisateur. Voici comment le déployer sur votre application web dans Azure :
Utilisez Git pour cloner ce référentiel GitHub :
git clone https://github.com/Microsoft/BotBuilder-Samples.git cd BotBuilder-Samples
Dans Visual Studio, ouvrez le projet Echo Bot.
Dans le projet Visual Studio, ouvrez le fichier Appsettings.json. Collez l’ID d’application Microsoft et le mot de passe d’application que vous avez copiés précédemment :
{ "MicrosoftAppId": "<App-registration-ID>", "MicrosoftAppPassword": "<App-password>" }
Ensuite, utilisez les bots Visual Studio pour C# pour déployer le bot.
Vous pouvez également utiliser une fenêtre d’invite de commandes pour déployer un bot Azure.
Dans Visual Studio, dans l’Explorateur de solutions, cliquez avec le bouton droit sur le projet EchoBot, puis sélectionnez Publier :
Sélectionnez Nouveau pour créer un profil de publication. Pour Cible, sélectionnez Azure :
Pour la cible spécifique, sélectionnez Azure App Service :
Dans la configuration du déploiement, sélectionnez l’application web dans les résultats qui s’affichent une fois que vous vous êtes connecté à votre compte Azure. Pour terminer le profil, sélectionnez Terminer, puis sélectionnez Publier pour lancer le déploiement.
Obtenir une ressource Communication Services
Maintenant que votre bot est créé et déployé, créez une ressource Communication Services à utiliser pour configurer un canal Communication Services :
Effectuez les étapes pourcréer une ressource Communication Services.
Créez un utilisateur Communication Services et émettez un jeton d’accès utilisateur. Veillez à définir l’étendue sur conversation. Copiez la chaîne de jeton et la chaîne d’ID utilisateur.
Activer le canal Conversation de Communication Services
Lorsque vous disposez d’une ressource Communication Services, vous pouvez configurer un canal Communication Services dans la ressource de bot. Dans ce processus, un ID utilisateur est généré pour le bot.
Dans le portail Azure, accédez à votre ressource Azure Bot. Dans le menu de ressources, sélectionnez Canaux. Dans la liste des canaux disponibles, sélectionnez Azure Communications Services - Conversation.
Sélectionnez Se connecter pour afficher la liste des ressources Communication Services disponibles dans votre abonnement.
Dans le volet Nouvelle connexion, sélectionnez la ressource de conversation Communication Services, puis sélectionnez Appliquer.
Lorsque les détails de la ressource sont vérifiés, un ID de bot s’affiche dans la colonne ID Azure Communication Services du bot. Vous pouvez utiliser l’ID de bot pour représenter le bot dans un fil de conversation à l’aide de l’API AddParticipant de conversation Communication Services. Une fois que vous avez ajouté le bot à une conversation en tant que participant, le bot commence à recevoir des activités liées à la conversation, et il peut répondre dans le fil de conversation.
Créer une application de conversation et ajouter le bot aux participants
Maintenant que vous disposez de l’ID Communication Services du bot, vous pouvez créer un fil de conversation qui compte le bot parmi les participants.
Créer une application C#
Utilisez la commande suivante pour créer l’application C# :
dotnet new console -o ChatQuickstart
Remplacez votre répertoire par le nouveau dossier d’application, puis utilisez la commande
dotnet build
pour compiler votre application :cd ChatQuickstart dotnet build
Installer le package
Installez le SDK Conversation Communication Services pour .NET :
dotnet add package Azure.Communication.Chat
Créer un client de conversation
Pour créer un client de conversation, utilisez votre point de terminaison Communication Services ainsi que le jeton d’accès d’utilisateur que vous avez généré précédemment. Utilisez la classe CommunicationIdentityClient
du kit de développement logiciel (SDK) Identity pour créer un utilisateur et émettre un jeton à transmettre à votre client de conversation. Les jetons d’accès peuvent être générés dans le portail à l’aide des instructions suivantes.
Copiez le code suivant et collez-le dans le fichier source Program.cs :
using Azure;
using Azure.Communication;
using Azure.Communication.Chat;
using System;
namespace ChatQuickstart
{
class Program
{
static async System.Threading.Tasks.Task Main(string[] args)
{
// Your unique Communication Services endpoint
Uri endpoint = new Uri("https://<RESOURCE_NAME>.communication.azure.com");
CommunicationTokenCredential communicationTokenCredential = new CommunicationTokenCredential(<Access_Token>);
ChatClient chatClient = new ChatClient(endpoint, communicationTokenCredential);
}
}
}
Lancement d’un thread de conversation avec le bot
Utilisez la méthode createChatThread
sur chatClient
pour créer un fil de conversation. Remplacez l’ID par l’ID Communication Services du bot.
var chatParticipant = new ChatParticipant(identifier: new CommunicationUserIdentifier(id: "<BOT_ID>"))
{
DisplayName = "BotDisplayName"
};
CreateChatThreadResult createChatThreadResult = await chatClient.CreateChatThreadAsync(topic: "Hello Bot!", participants: new[] { chatParticipant });
ChatThreadClient chatThreadClient = chatClient.GetChatThreadClient(threadId: createChatThreadResult.ChatThread.Id);
string threadId = chatThreadClient.Id;
Obtenir un client de fil de conversation
La méthode GetChatThreadClient
retourne un client de fil pour un fil qui existe déjà :
string threadId = "<THREAD_ID>";
ChatThreadClient chatThreadClient = chatClient.GetChatThreadClient(threadId: threadId);
Envoyer un message à un fil de conversation
Utiliser SendMessage
pour envoyer un message à un fil de conversation :
SendChatMessageOptions sendChatMessageOptions = new SendChatMessageOptions()
{
Content = "Hello World",
MessageType = ChatMessageType.Text
};
SendChatMessageResult sendChatMessageResult = await chatThreadClient.SendMessageAsync(sendChatMessageOptions);
string messageId = sendChatMessageResult.Id;
Recevoir les messages de conversation d’un fil de conversation
Vous pouvez recevoir les messages de conversation en interrogeant la méthode GetMessages
sur le client de fil de conversation selon des intervalles définis :
AsyncPageable<ChatMessage> allMessages = chatThreadClient.GetMessagesAsync();
await foreach (ChatMessage message in allMessages)
{
Console.WriteLine($"{message.Id}:{message.Content.Message}");
}
Vérifiez la liste des messages pour la réponse d’écho du bot à « Hello World ».
Vous pouvez utiliser JavaScript ou les kits SDK mobiles Azure pour vous abonner aux notifications de messages entrants :
// Open notifications channel
await chatClient.startRealtimeNotifications();
// Subscribe to new notifications
chatClient.on("chatMessageReceived", (e) => {
console.log("Notification chatMessageReceived!");
// Your code here
});
Nettoyer le fil de conversation
Lorsque vous avez terminé d’utiliser le fil de conversation, supprimez le fil :
chatClient.DeleteChatThread(threadId);
Déploiement de l’application de conversation en C#
Déployer l’application de conversation :
Dans Visual Studio, ouvrez le projet de conversation.
Cliquez avec le bouton droit sur le projet ChatQuickstart, puis sélectionnez Publier:
Une fois que vous avez publié la solution, exécutez-la et vérifiez si Echobot fait écho au message utilisateur à l’invite de commandes. Maintenant que vous disposez de la solution, vous pouvez continuer à jouer avec les différentes activités nécessaires pour les scénarios métier que vous avez besoin de résoudre.
Autres possibilités offertes par les bots
Un bot peut recevoir plus qu’un message en texte brut d’un utilisateur dans un canal de conversation Communications Services. Voici quelques-unes des activités qu’un bot peut recevoir d’un utilisateur :
- Mise à jour de conversation
- Mise à jour de message
- Suppression de message
- Indicateur de saisie
- Activité d’événement
- Diverses pièces jointes, y compris les cartes adaptatives
- Données de canal de bot
Les sections suivantes présentent des exemples pour illustrer ces fonctionnalités.
Envoi d’un message d’accueil lorsqu’un nouvel utilisateur est ajouté au thread
La logique actuelle d’Echo Bot accepte l’entrée de l’utilisateur et la renvoie. Si vous souhaitez ajouter une logique supplémentaire (par exemple la réponse à un événement Communication Services ajouté par un participant), copiez le code suivant et collez-le dans le fichier source EchoBot.cs :
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Bot.Builder;
using Microsoft.Bot.Schema;
namespace Microsoft.BotBuilderSamples.Bots
{
public class EchoBot : ActivityHandler
{
public override async Task OnTurnAsync(ITurnContext turnContext, CancellationToken cancellationToken)
{
if (turnContext.Activity.Type == ActivityTypes.Message)
{
var replyText = $"Echo: {turnContext.Activity.Text}";
await turnContext.SendActivityAsync(MessageFactory.Text(replyText, replyText), cancellationToken);
}
else if (ActivityTypes.ConversationUpdate.Equals(turnContext.Activity.Type))
{
if (turnContext.Activity.MembersAdded != null)
{
foreach (var member in turnContext.Activity.MembersAdded)
{
if (member.Id != turnContext.Activity.Recipient.Id)
{
await turnContext.SendActivityAsync(MessageFactory.Text("Hello and welcome to chat with EchoBot!"), cancellationToken);
}
}
}
}
}
}
}
Envoi d’une carte adaptative
Remarque
Les cartes adaptatives sont uniquement prises en charge dans les cas d’utilisation d’Azure Communication Services où tous les participants au chat sont des utilisateurs Azure Communication Services, et non pour les cas d’utilisation d’interopérabilité Teams.
Vous pouvez envoyer une carte adaptative au fil de conversation pour augmenter l’engagement et l’efficacité. Une carte adaptative vous permet également de communiquer avec les utilisateurs de différentes façons. Vous pouvez envoyer une carte adaptative à partir d’un bot en ajoutant la carte en tant que pièce jointe d’activité de bot.
Voici un exemple d’envoi d’une carte adaptative :
var reply = Activity.CreateMessageActivity();
var adaptiveCard = new Attachment()
{
ContentType = "application/vnd.microsoft.card.adaptive",
Content = {/* the adaptive card */}
};
reply.Attachments.Add(adaptiveCard);
await turnContext.SendActivityAsync(reply, cancellationToken);
Trouvez des exemples de charges utiles pour les cartes adaptatives dans Exemples et modèles.
Pour un utilisateur de conversation, le canal de conversation Communication Services ajoute un champ aux métadonnées du message qui indique que le message a une pièce jointe. Dans les métadonnées, la propriété de microsoft.azure.communication.chat.bot.contenttype
est définie sur azurebotservice.adaptivecard
.
Voici un exemple de message de conversation auquel une carte adaptative est jointe :
{
"content": "{\"attachments\":[{\"contentType\":\"application/vnd.microsoft.card.adaptive\",\"content\":{/* the adaptive card */}}]}",
"senderDisplayName": "BotDisplayName",
"metadata": {
"microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.adaptivecard"
},
"messageType": "Text"
}
Envoyer un message d’utilisateur à bot
Vous pouvez envoyer un message texte basique de l’utilisateur au bot de la même façon que vous envoyez un message texte à un autre utilisateur.
Toutefois, pendant l’envoi d’un message contenant une pièce jointe entre un utilisateur et un bot, ajoutez cet indicateur aux métadonnées de conversation Communication Services :
"microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.adaptivecard"
Pour envoyer une activité d’événement d’un utilisateur à un bot, ajoutez cet indicateur aux métadonnées de conversation Communication Services :
"microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.event"
Les sections suivantes présentent des exemples de formats pour les messages de conversation d’un utilisateur vers un bot.
Envoyer un message texte simple
{
"content":"Simple text message",
"senderDisplayName":"Acs-Dev-Bot",
"metadata":{
"text":"random text",
"key1":"value1",
"key2":"{\r\n \"subkey1\": \"subValue1\"\r\n
"},
"messageType": "Text"
}
Message avec une pièce jointe
{
"content": "{
\"text\":\"sample text\",
\"attachments\": [{
\"contentType\":\"application/vnd.microsoft.card.adaptive\",
\"content\": { \"*adaptive card payload*\" }
}]
}",
"senderDisplayName": "Acs-Dev-Bot",
"metadata": {
"microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.adaptivecard",
"text": "random text",
"key1": "value1",
"key2": "{\r\n \"subkey1\": \"subValue1\"\r\n}"
},
"messageType": "Text"
}
Message avec une activité d’événement
Une charge utile d’événement inclut tous les champs JSON dans le contenu du message, à l’exception de Name
. Le champ Name
contient le nom de l’événement.
Dans l’exemple suivant, le nom de l’événement endOfConversation
avec la charge utile "{field1":"value1", "field2": { "nestedField":"nestedValue" }}
est envoyé au bot :
{
"content":"{
\"name\":\"endOfConversation\",
\"field1\":\"value1\",
\"field2\": {
\"nestedField\":\"nestedValue\"
}
}",
"senderDisplayName":"Acs-Dev-Bot",
"metadata":{
"microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.event",
"text":"random text",
"key1":"value1",
"key2":"{\r\n \"subkey1\": \"subValue1\"\r\n}"
},
"messageType": "Text"
}
Le champ de métadonnées microsoft.azure.communication.chat.bot.contenttype
est requis uniquement dans un message envoyé d’un utilisateur à un bot.
Champs d’activité de bot pris en charge
Les sections suivantes décrivent les champs d’activité de bot pris en charge pour les flux de bot à utilisateur et d’utilisateur à bot.
Flux de bot à utilisateur
Les champs d’activité de bot suivants sont pris en charge pour les flux de bot à utilisateur.
Activités
- Message
- Saisie
Champs d’activité de message
Text
Attachments
AttachmentLayout
SuggestedActions
From.Name
(Converti en Communication ServicesSenderDisplayName
.)ChannelData
(Converti en Communication ServicesChat Metadata
. Si des valeurs de mappageChannelData
sont des objets, elles sont sérialisées au format JSON et envoyées sous forme de chaîne.)
Flux d’utilisateur à bot
Ces champs d’activité de bot sont pris en charge pour les flux d’utilisateur à bot.
Activités et champs
Message
Id
(ID de message de conversation Communication Services)TimeStamp
Text
Attachments
Mise à jour de conversation
MembersAdded
MembersRemoved
TopicName
Mise à jour de message
Id
(ID de message de conversation Communication Services mis à jour)Text
Attachments
Suppression de message
Id
(ID de message de conversation Communication Services supprimé)
Événement
Name
Value
Saisie
Autres champs communs
Recipient.Id
etRecipient.Name
(ID d’utilisateur et nom d’affichage de conversation Communication Services)From.Id
etFrom.Name
(ID d’utilisateur et nom d’affichage de conversation Communication Services)Conversation.Id
(ID de fil de conversation Communication Services)ChannelId
(conversation avec Communication Services si vide)ChannelData
(métadonnées de message de conversation Communication Services)
Modèles de transfert de bot
Parfois, un bot ne comprend pas une question ou ne peut pas répondre à une question. Un client peut demander dans la conversation à être mis en relation avec un agent humain. Dans ces scénarios, le fil de conversation doit être transféré du bot à un agent humain. Vous pouvez concevoir votre application pour faire passer la conversation d’un bot à un humain.
Gérer la communication de bot à bot
Dans certains cas d’usage, deux bots doivent être ajoutés au même fil de conversation pour fournir des services différents. Dans ce scénario, vous devrez peut-être vous assurer qu’un bot n’envoie pas de réponses automatisées aux messages d’un autre bot. Si elle n’est pas gérée correctement, l’interaction automatisée des bots entre eux peut entraîner une boucle infinie de messages.
Vous pouvez vérifier l’identité de l’utilisateur Communication Services d’un expéditeur de message dans la propriété From.Id
de l’activité. Vérifiez s’il appartient à un autre bot. Ensuite, effectuez l’action requise pour empêcher un flux de communication bot à bot. Si ce type de scénario entraîne des volumes d’appels élevés, le canal de conversation Communication Services limite les demandes et un bot ne peut pas envoyer et recevoir des messages.
En savoir plus sur les limites de l’accélérateur.
Dépanner
Les sections suivantes décrivent les différentes façons de résoudre les scénarios courants.
Impossible d’ajouter le canal de conversation
Dans le portail des développeurs Microsoft Bot Framework, accédez à Configuration>messagerie Bot pour vérifier que le point de terminaison a été correctement défini.
Le bot obtient une exception d’interdiction lors de la réponse à un message
Vérifiez que l’ID et le mot de passe de l’application Microsoft du bot sont correctement enregistrés dans le fichier de configuration du bot que vous chargez dans l’application web.
Le bot ne peut pas être ajouté comme participant
Vérifiez que l’ID Communication Services du bot est utilisé correctement pendant l’envoi d’une demande d’ajout de bot à un fil de conversation.
Étapes suivantes
Essayez l’application de démonstration de bot de conversation pour une conversation individuelle entre un utilisateur de conversation et un bot via le composant d’interface utilisateur BotFramework WebChat.
Commentaires
https://aka.ms/ContentUserFeedback.
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultezEnvoyer et afficher des commentaires pour