Rövid útmutató: Robot hozzáadása a csevegőalkalmazáshoz

  • Cikk

Megtudhatja, hogyan hozhat létre beszélgetési AI-élményeket egy csevegőalkalmazásban az Azure Communication Services csevegőcsatornájával, amely az Azure Bot Service-ben érhető el. Ebben a rövid útmutatóban a BotFramework SDK használatával hozhat létre egy robotot. Ezután integrálja a robotot egy ön által létrehozott csevegőalkalmazásba a Communication Services Csevegő SDK-val.

Ezen rövid útmutató segítségével megtanulhatja a következőket:

Előfeltételek

  • Egy Azure-fiók és egy aktív előfizetés. Hozzon létre egy fiókot ingyenesen.
  • Visual Studio 2019 vagy újabb verzió.
  • A .NET Core legújabb verziója. Ebben a rövid útmutatóban a .NET Core 3.1-et használjuk. Mindenképpen telepítse a Visual Studio 32 bites vagy 64 bites példányának megfelelő verziót.
  • Bot framework SDK

Robot létrehozása és üzembe helyezése az Azure-ban

Ha az Azure Communication Services-csevegést csatornaként szeretné használni az Azure Bot Service-ben, először telepítsen egy robotot. Robot üzembe helyezéséhez hajtsa végre az alábbi lépéseket:

  • Azure Bot Service-erőforrás létrehozása
  • A robot alkalmazásazonosítójának és jelszavának lekérése
  • Webalkalmazás létrehozása a robotlogika tárolásához
  • Üzenetkezelési végpont létrehozása a robothoz

Azure Bot Service-erőforrás létrehozása

Először az Azure Portal használatával hozzon létre egy Azure Bot Service-erőforrást. A Communication Services csevegési csatornája támogatja az egybérlős robotokat, a felügyelt identitásrobotokat és a több-bérlős robotokat. Ebben a rövid útmutatóban egy több-bérlős robotot használunk.

Egybérlős vagy felügyelt identitásrobot beállításához tekintse át a robot identitásadatait.

Felügyelt identitást kezelő robot esetén előfordulhat, hogy frissítenie kell a robotszolgáltatás identitását.

A robot alkalmazásazonosítójának és alkalmazásjelszójának lekérése

Ezután szerezze be a Robothoz rendelt Microsoft-alkalmazásazonosítót és -jelszót az üzembe helyezéskor. Ezeket az értékeket későbbi konfigurációkhoz használhatja.

Webalkalmazás létrehozása a robotlogika tárolásához

Ha webalkalmazást szeretne létrehozni a robothoz, átdolgozhatja a Robot Builder-mintákat a forgatókönyvéhez, vagy a Bot Builder SDK-val webalkalmazást hozhat létre. Az egyik legegyszerűbb minta az Echo Bot.

Az Azure Bot Service általában arra számít, hogy a Bot Application Web App Controller közzéten egy végpontot az űrlapon /api/messages. A végpont kezeli a robotnak küldött összes üzenetet.

A robotalkalmazás létrehozásához vagy az Azure CLI használatával hozzon létre egy Azure-alkalmazás Service-erőforrást, vagy hozza létre az alkalmazást az Azure Portalon.

Robot webalkalmazás létrehozása az Azure Portal használatával:

  1. A portálon válassza az Erőforrás létrehozása lehetőséget. A keresőmezőbe írja be a webalkalmazást. Válassza ki a webalkalmazás csempét.

    Screenshot that shows creating a web app resource in the Azure portal.

  2. A Webalkalmazás létrehozása területen válassza ki vagy adja meg az alkalmazás részleteit, beleértve azt a régiót is, ahol telepíteni szeretné az alkalmazást.

    Screenshot that shows details to set to create a web app deployment.

  3. Válassza a Felülvizsgálat + Létrehozás lehetőséget az üzembe helyezés ellenőrzéséhez és az üzembe helyezés részleteinek áttekintéséhez. Ezután kattintson a Létrehozás elemre.

  4. A webalkalmazás-erőforrás létrehozásakor másolja ki az erőforrás részletei között látható állomásnév URL-címét. Az URL a webalkalmazáshoz létrehozott végpont része.

    Screenshot that shows how to copy the web app endpoint URL.

Üzenetkezelési végpont létrehozása a robothoz

Ezután a roboterőforrásban hozzon létre egy webalkalmazás-üzenetkezelési végpontot:

  1. Az Azure Portalon nyissa meg az Azure Bot-erőforrást. Az erőforrás menüjében válassza a Konfiguráció lehetőséget.

  2. Az Üzenetkezelési végpont konfigurációjában illessze be az előző szakaszban másolt webalkalmazás állomásnév URL-címét. Fűzze hozzá az URL-címet a következővel /api/messages: .

  3. Válassza a Mentés parancsot.

Screenshot that shows how to create a bot messaging endpoint by using the web app hostname.

A webalkalmazás üzembe helyezése

A robot létrehozásának utolsó lépése a webalkalmazás üzembe helyezése. Ehhez a rövid útmutatóhoz használja az Echo Bot-mintát. Az Echo Bot funkciója a felhasználói bemenet visszhangzására korlátozódik. A következőképpen helyezheti üzembe a webalkalmazásban az Azure-ban:

  1. A Git használatával klónozhatja ezt a GitHub-adattárat:

    git clone https://github.com/Microsoft/BotBuilder-Samples.git
cd BotBuilder-Samples

  2. Nyissa meg az Echo Bot projektet a Visual Studióban.

  3. A Visual Studio-projektben nyissa meg az Appsettings.json fájlt. Illessze be a korábban másolt Microsoft-alkalmazásazonosítót és alkalmazásjelszót :

       {
     "MicrosoftAppId": "<App-registration-ID>",
     "MicrosoftAppPassword": "<App-password>"
   }

    Ezután a Visual Studio for C#-robotokkal telepítheti a robotot.

    Az Azure-robot üzembe helyezéséhez parancssori ablak is használható.

  4. A Visual Studióban a Megoldáskezelő kattintson a jobb gombbal az EchoBot projektre, és válassza a Közzététel lehetőséget:

    Screenshot that shows publishing your web app from Visual Studio.

  5. Új közzétételi profil létrehozásához válassza az Új lehetőséget. Célként válassza az Azure-t:

    Screenshot that shows how to select Azure as target in a new publishing profile.

    Az adott célhoz válassza a Azure-alkalmazás Szolgáltatást:

    Screenshot that shows how to select Azure App Service as the specific target.

  6. Az üzembe helyezési konfigurációban válassza ki a webalkalmazást az Azure-fiókba való bejelentkezés után megjelenő eredmények között. A profil befejezéséhez válassza a Befejezés, majd a Közzététel lehetőséget az üzembe helyezés elindításához.

    Screenshot that shows setting the deployment configuration with the web app name.

Communication Services-erőforrás lekérése

A robot létrehozása és üzembe helyezése után hozzon létre egy Communication Services-erőforrást a Communication Services-csatorna beállításához:

  1. Végezze el a Communication Services-erőforrás létrehozásához szükséges lépéseket.

  2. Hozzon létre egy Communication Services-felhasználót, és adjon ki egy felhasználói hozzáférési jogkivonatot. Ügyeljen arra, hogy a hatókört csevegésre állítsa. Másolja ki a jogkivonat-sztringet és a felhasználói azonosító sztringet.

A Communication Services csevegési csatornájának engedélyezése

Ha rendelkezik Communication Services-erőforrással, beállíthat egy Communication Services-csatornát a roboterőforrásban. Ebben a folyamatban a rendszer létrehoz egy felhasználói azonosítót a robothoz.

  1. Az Azure Portalon nyissa meg az Azure Bot-erőforrást. Az erőforrás menüjében válassza a Csatornák lehetőséget. Az elérhető csatornák listájában válassza az Azure Communications Services – Csevegés lehetőséget.

    Screenshot that shows opening the Communication Services Chat channel.

  2. Válassza a Csatlakozás az előfizetésében elérhető Communication Services-erőforrások listájának megtekintéséhez.

    Screenshot that shows how to connect a Communication Service resource to the bot.

  3. Az Új Csatlakozás ion panelen válassza a Communication Services csevegési erőforrását, majd válassza az Alkalmaz lehetőséget.

    Screenshot that shows how to save the selected Communication Service resource to create a new Communication Services user ID.

  4. Az erőforrás részleteinek ellenőrzésekor a Bot Azure Communication Services Id oszlopában megjelenik egy robotazonosító. A robotazonosítóval egy csevegőszálban ábrázolhatja a robotot a Communication Services Chat AddParticipant API-val. Miután hozzáadta a robotot egy csevegéshez résztvevőként, a robot megkezdi a csevegéssel kapcsolatos tevékenységek fogadását, és képes válaszolni a csevegési szálon.

    Screenshot that shows the new Communication Services user ID assigned to the bot.

Csevegőalkalmazás létrehozása és a robot hozzáadása résztvevőként

Most, hogy rendelkezik a robot Communication Services-azonosítójával, létrehozhat egy csevegési szálat a robottal résztvevőként.

Új C#-alkalmazás létrehozása

  1. Futtassa a következő parancsot egy C#-alkalmazás létrehozásához:

    dotnet new console -o ChatQuickstart

  2. Módosítsa a könyvtárat az új alkalmazásmappára, és használja a dotnet build parancsot az alkalmazás fordításához:

    cd ChatQuickstart
dotnet build

Telepítse a(z) csomagot

Telepítse a Communication Services Chat SDK for .NET-et:

dotnet add package Azure.Communication.Chat

Csevegőügyfél létrehozása

Csevegőügyfél létrehozásához használja a Communication Services-végpontot és a korábban létrehozott felhasználói hozzáférési jogkivonatot. CommunicationIdentityClient Az Identity SDK osztályával hozzon létre egy felhasználót, és adjon ki egy jogkivonatot a csevegési ügyfélnek való továbbításhoz. A hozzáférési jogkivonatok az alábbi utasítások alapján hozhatók létre a portálon.

Másolja ki a következő kódot, és illessze be a Program.cs forrásfájlba:

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

Csevegési szál indítása a robottal

createChatThread A módszer használatával hozzon chatClient létre egy csevegési szálat. Cserélje le az azonosítót a robot Communication Services-azonosítójára.

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;

Csevegőszál-ügyfél lekérése

A GetChatThreadClient metódus egy már létező szálügyfélt ad vissza:

string threadId = "<THREAD_ID>";
ChatThreadClient chatThreadClient = chatClient.GetChatThreadClient(threadId: threadId);

Üzenet küldése csevegési szálra

SendMessage Üzenet küldése egy szálra:

SendChatMessageOptions sendChatMessageOptions = new SendChatMessageOptions()
{
    Content = "Hello World",
    MessageType = ChatMessageType.Text
};

SendChatMessageResult sendChatMessageResult = await chatThreadClient.SendMessageAsync(sendChatMessageOptions);

string messageId = sendChatMessageResult.Id;

Csevegőüzenetek fogadása csevegőszálból

A csevegőüzenetek lekérdezhetők a GetMessages csevegőszál-ügyfélen megadott időközönként:

AsyncPageable<ChatMessage> allMessages = chatThreadClient.GetMessagesAsync();
await foreach (ChatMessage message in allMessages)
{
    Console.WriteLine($"{message.Id}:{message.Content.Message}");
}

Ellenőrizze a robot ""Helló világ!" alkalmazás" válaszának üzenetlistáját.

A bejövő üzenetértesítésekre a JavaScript vagy az Azure mobil SDK-k használatával iratkozhat fel:

// Open notifications channel
await chatClient.startRealtimeNotifications();
// Subscribe to new notifications
chatClient.on("chatMessageReceived", (e) => {
  console.log("Notification chatMessageReceived!");
  // Your code here
});

A csevegési szál törlése

Ha befejezte a csevegési szál használatát, törölje a szálat:

chatClient.DeleteChatThread(threadId);

A C#-csevegőalkalmazás üzembe helyezése

A csevegőalkalmazás üzembe helyezése:

  1. Nyissa meg a csevegőprojektet a Visual Studióban.

  2. Kattintson a jobb gombbal a ChatQuickstart projektre , és válassza a Közzététel lehetőséget:

    Screenshot that shows deploying the chat application to Azure from Visual Studio.

  3. Miután közzétette a megoldást, futtassa, és ellenőrizze, hogy az Echobot visszhangozza-e a parancssorban megjelenő felhasználói üzenetet. Most, hogy már rendelkezik a megoldással, folytathatja a különböző tevékenységekkel, amelyek szükségesek a megoldandó üzleti forgatókönyvekhez.

További teendők robottal

A robotok egy Communications Services-csevegőcsatornában lévő felhasználótól több egyszerű szöveges üzenetet is fogadhatnak. A robot által a felhasználóktól kapott tevékenységek némelyike a következők:

  • Beszélgetés frissítése
  • Üzenetfrissítés
  • Üzenet törlése
  • Gépelésjelző
  • Eseménytevékenység
  • Különböző mellékletek, beleértve az adaptív kártyákat
  • Robotcsatorna adatai

A következő szakaszok néhány példát mutatnak be ezeknek a funkcióknak a szemléltetésére.

Üdvözlő üzenet küldése, ha új felhasználót ad hozzá a szálhoz

Az Echo Bot jelenlegi logikája elfogadja a felhasználó bemenetét, és visszahangosítja azt. Ha további logikát szeretne hozzáadni, például válaszolni szeretne egy résztvevő által hozzáadott Communication Services-eseményre, másolja ki a következő kódot, és illessze be az EchoBot.cs forrásfájlba:

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

Adaptív kártya küldése

Megjegyzés:

Az adaptív kártyák csak olyan Azure Communication Services-használati esetekben támogatottak, amelyekben a csevegés összes résztvevője Azure Communication Services-felhasználó, és nem a Teams interoprability használati eseteihez.

Az előjegyzés és a hatékonyság növelése érdekében adaptív kártyát küldhet a csevegési szálra. Az adaptív kártya különböző módokon is segít a felhasználókkal való kommunikációban. A robotból adaptív kártyát úgy küldhet el, hogy hozzáadja a kártyát robottevékenység-mellékletként.

Íme egy példa adaptív kártya küldésére:

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

Minta hasznos adatok beolvasása adaptív kártyákhoz a mintákban és sablonokban.

Csevegőfelhasználók esetén a Communication Services csevegőcsatornája hozzáad egy mezőt az üzenet metaadataihoz, amely azt jelzi, hogy az üzenet melléklettel rendelkezik. A metaadatokban a microsoft.azure.communication.chat.bot.contenttype tulajdonság értéke azurebotservice.adaptivecard.

Íme egy példa egy csevegőüzenetre, amelyhez csatolva van egy adaptív kártya:

{
    "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"
}

Üzenet küldése a felhasználótól a robotnak

Egyszerű szöveges üzenetet küldhet a felhasználótól a robotnak ugyanúgy, mint egy másik felhasználónak.

Ha azonban egy felhasználótól egy robothoz mellékletet tartalmazó üzenetet küld, adja hozzá ezt a jelzőt a Communication Services csevegési metaadataihoz:

"microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.adaptivecard"

Ha eseménytevékenységet szeretne küldeni egy felhasználótól egy robotnak, adja hozzá ezt a jelzőt a Communication Services csevegési metaadataihoz:

"microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.event"

Az alábbi szakaszok a felhasználó és a robot közötti csevegési üzenetek mintaformátumait mutatják be.

Egyszerű szöveges üzenet

{
    "content":"Simple text message",
    "senderDisplayName":"Acs-Dev-Bot",
    "metadata":{
        "text":"random text",
        "key1":"value1",
        "key2":"{\r\n  \"subkey1\": \"subValue1\"\r\n
        "}, 
    "messageType": "Text"
}

Üzenet melléklettel

{
    "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"
}

Eseménytevékenységgel rendelkező üzenet

Az esemény hasznos adatai az üzenet tartalmának összes JSON-mezőjét tartalmazzák, kivéve Namea . A Name mező az esemény nevét tartalmazza.

Az alábbi példában a rendszer elküldi a hasznos adatokat "{field1":"value1", "field2": { "nestedField":"nestedValue" }} tartalmazó eseménynevet endOfConversation a robotnak:

{
    "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"
}

A metaadatmező microsoft.azure.communication.chat.bot.contenttype csak egy felhasználótól egy robotnak küldött üzenetben szükséges.

Támogatott robottevékenység-mezők

A következő szakaszok a robotok által támogatott tevékenységmezőket ismertetik a robotok közötti folyamatokhoz és a felhasználók közötti folyamatokhoz.

Robot–felhasználó folyamat

A robotok tevékenységeinek alábbi mezői támogatottak a robotok felhasználónkénti folyamataihoz.

Tevékenységek

  • Üzenet
  • Gépelés

Üzenettevékenység mezői

  • Text
  • Attachments
  • AttachmentLayout
  • SuggestedActions
  • From.Name (Átalakítva Kommunikációs szolgáltatásokká SenderDisplayName.)
  • ChannelData (Át lett alakítva Kommunikációs szolgáltatásokká Chat Metadata. Ha a leképezési ChannelData értékek objektumok, JSON formátumban szerializálják őket, és sztringként küldik el őket.)

Felhasználó–robot folyamat

Ezek a robottevékenység-mezők támogatottak a felhasználó–robot folyamatok esetében.

Tevékenységek és mezők

  • Üzenet

    • Id (Communication Services csevegőüzenet azonosítója)
    • TimeStamp
    • Text
    • Attachments

  • Beszélgetés frissítése

    • MembersAdded
    • MembersRemoved
    • TopicName

  • Üzenetfrissítés

    • Id (Frissített Kommunikációs szolgáltatások csevegőüzenet-azonosítója)
    • Text
    • Attachments

  • Üzenet törlése

    • Id (Törölt Kommunikációs szolgáltatások csevegőüzenet-azonosítója)

  • Esemény

    • Name
    • Value

  • Gépelés

Egyéb gyakori mezők

  • Recipient.Id és Recipient.Name (Communication Services Chat felhasználói azonosító és megjelenítendő név)
  • From.Id és From.Name (Communication Services Chat felhasználói azonosító és megjelenítendő név)
  • Conversation.Id (A Communication Services csevegési szálazonosítója)
  • ChannelId (Kommunikációs szolgáltatások csevegése, ha üres)
  • ChannelData (A Communication Services csevegőüzenetének metaadatai)

Robot átadási mintái

Néha a robotok nem értik a kérdéseket, vagy nem tudnak válaszolni egy kérdésre. Az ügyfél megkérheti a csevegésben, hogy kapcsolódjon egy emberi ügynökhöz. Ezekben a helyzetekben a csevegési szálat a robotból egy emberi ügynöknek kell átadni. Az alkalmazást úgy tervezheti meg, hogy egy beszélgetést egy robotról egy emberre váltson át.

Robotok közötti kommunikáció kezelése

Bizonyos használati esetekben két robotot kell hozzáadni ugyanahhoz a csevegési szálhoz, hogy különböző szolgáltatásokat nyújtson. Ebben a forgatókönyvben előfordulhat, hogy egy robotnak nem kell automatikus válaszokat küldenie egy másik robot üzeneteibe. Ha nem megfelelően kezelik, a robotok egymás közötti automatikus interakciója végtelen üzenethurkot eredményezhet.

A tevékenység tulajdonságában ellenőrizheti az üzenetküldő Kommunikációs szolgáltatások felhasználói identitását From.Id . Ellenőrizze, hogy egy másik robothoz tartozik-e. Ezután végezze el a szükséges műveletet a robotok közötti kommunikáció megakadályozásához. Ha ez a forgatókönyv nagy hívásmennyiséget eredményez, a Communication Services csevegőcsatornája szabályozza a kéréseket, és a robot nem tud üzeneteket küldeni és fogadni.

További információ a szabályozás korlátairól.

Hibaelhárítás

Az alábbi szakaszok ismertetik a gyakori forgatókönyvek hibaelhárításának módjait.

A csevegőcsatorna nem vehető fel

A Microsoft Bot Framework fejlesztői portálján lépjen a Configuration>Bot Messaging webhelyre, és ellenőrizze, hogy a végpont megfelelően lett-e beállítva.

A robot tiltott kivételt kap egy üzenet megválaszolásakor

Ellenőrizze, hogy a robot Microsoft-alkalmazásazonosítója és jelszava megfelelően van-e mentve a webalkalmazásba feltöltött robotkonfigurációs fájlban.

A robot nem vehető fel résztvevőként

Ellenőrizze, hogy a robot Communication Services-azonosítója helyesen van-e használva, amikor a rendszer egy robot csevegőszálhoz való hozzáadására irányuló kérést küld.

További lépések

Próbálja ki a csevegőrobot bemutató alkalmazását egy 1:1-es csevegéshez egy csevegőfelhasználó és egy robot között a BotFramework WebChat felhasználói felületének összetevőjén keresztül.