Aracılığıyla paylaş

Hızlı Başlangıç: Sohbet uygulamanıza bot ekleme

  • Makale

Azure Bot Hizmeti'de bulunan Azure İletişim Hizmetleri Sohbet mesajlaşma kanalını kullanarak sohbet uygulamasında konuşma yapay zekası deneyimleri oluşturmayı öğrenin. Bu hızlı başlangıçta BotFramework SDK'sını kullanarak bir bot oluşturacaksınız. Ardından, İletişim Hizmetleri Sohbet SDK'sını kullanarak botu oluşturduğunuz bir sohbet uygulamasıyla tümleştirirsiniz.

Bu hızlı başlangıçta şunları yapmayı öğrenirsiniz:

Önkoşullar

Azure'da bot oluşturma ve dağıtma

Azure İletişim Hizmetleri sohbeti Azure Bot Hizmeti'da kanal olarak kullanmak için önce bir bot dağıtın. Bot dağıtmak için şu adımları tamamlarsınız:

Azure Bot Hizmeti kaynağı oluşturma

İlk olarak Azure portalını kullanarak bir Azure Bot Hizmeti kaynağı oluşturun. İletişim Hizmetleri Sohbet kanalı tek kiracılı botları, yönetilen kimlik botlarını ve çok kiracılı botları destekler.

  • Bu hızlı başlangıcın amaçları doğrultusunda bir multitenant bot kullanacağız.
  • Veya botu ayarlamak single-tenant için Bot kimlik bilgilerini gözden geçirin.managed identity
  • Bot managed identity için bot hizmeti kimliğini güncelleştirmeniz gerekebilir.

Bot uygulama kimliğini ve uygulama parolasını alma

Ardından, dağıtıldığında botunuza atanan Microsoft uygulama kimliğini ve parolasını alın. Bu değerleri sonraki yapılandırmalar için kullanırsınız.

Bot uygulaması oluşturma ve bir web uygulamasında yayımlama

Bot oluşturmak için aşağıdakilerden birini yapabilirsiniz:

Bu hızlı başlangıç için Bot Builder örneklerinden Echo Bot örneğini kullanacağız.

Bot uygulamasını tutmak için bir web uygulaması oluşturma

Web uygulamasını oluşturmak için Azure CLI kullanarak bir Azure Uygulaması Hizmeti kaynağı oluşturun veya uygulamayı Azure portalında oluşturun.

Azure portalını kullanarak bot web uygulaması oluşturmak için:

  1. Portalda Kaynak oluştur'u seçin. Arama kutusuna web uygulaması girin. Web Uygulaması kutucuğunu seçin.

    Azure portalında web uygulaması kaynağı oluşturmayı gösteren ekran görüntüsü.

  2. Web Uygulaması Oluştur bölümünde, uygulamayı dağıtmak istediğiniz bölge de dahil olmak üzere uygulamanın ayrıntılarını seçin veya girin.

    Web uygulaması dağıtımı oluşturmak için ayarlanacağı ayrıntıları gösteren ekran görüntüsü.

  3. Dağıtımı doğrulamak ve dağıtım ayrıntılarını gözden geçirmek için Gözden Geçir + Oluştur'u seçin. Ardından Oluştur’u seçin.

  4. Web uygulaması kaynağı oluşturulduğunda, kaynak ayrıntılarında gösterilen ana bilgisayar adı URL'sini kopyalayın. URL, web uygulaması için oluşturduğunuz uç noktanın bir parçasıdır.

    Web uygulaması uç noktası URL'sinin nasıl kopyalandığını gösteren ekran görüntüsü.

Bot için mesajlaşma uç noktası oluşturma

Azure Bot Hizmeti genellikle Bot Uygulaması Web Uygulaması Denetleyicisi'nin biçiminde /api/messagesbir uç nokta göstermesini bekler. Uç nokta, bota gönderilen tüm iletileri işler.

Ardından bot kaynağında bir web uygulaması mesajlaşma uç noktası oluşturun:

  1. Azure portalında Azure Bot kaynağınıza gidin. Kaynak menüsünde Yapılandırma'yı seçin.

  2. Yapılandırma'da, Mesajlaşma uç noktası için önceki bölümde kopyaladığınız web uygulamasının ana bilgisayar adı URL'sini yapıştırın. URL'yi ile ekleyin /api/messages.

  3. Kaydet'i seçin.

Web uygulaması ana bilgisayar adını kullanarak bot mesajlaşma uç noktasının nasıl oluşturulacağını gösteren ekran görüntüsü.

Web uygulamasını dağıtma

Bot oluşturmanın son adımı web uygulamasını dağıtmaktır. Bu hızlı başlangıç için Echo Bot örneğini kullanın. Yankı Botu işlevselliği, kullanıcı girişinin yankılanmasıyla sınırlıdır. Azure'da web uygulamanıza şu şekilde dağıtabilirsiniz:

  1. Git'i kullanarak bu GitHub deposunu kopyalayın:

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

  2. Visual Studio'da Echo Bot projesini açın.

  3. Visual Studio projesinde Appsettings.json dosyasını açın. Daha önce kopyaladığınız Microsoft uygulama kimliğini ve uygulama parolasını yapıştırın:

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

    Ardından, botu dağıtmak için C# botları için Visual Studio veya VS Code kullanın.

    Azure botu dağıtmak için Komut İstemi penceresini de kullanabilirsiniz.

  4. Visual Studio'da Çözüm Gezgini EchoBot projesine sağ tıklayın ve Yayımla'yı seçin:

    Web uygulamanızı Visual Studio'dan yayımlamayı gösteren ekran görüntüsü.

  5. Yeni yayımlama profili oluşturmak için Yeni'yi seçin. Hedef için Azure'ı seçin:

    Yeni yayımlama profilinde hedef olarak Azure'ın nasıl seçildiğini gösteren ekran görüntüsü.

    Belirli bir hedef için Azure Uygulaması Hizmeti'ni seçin:

    Belirli bir hedef olarak Azure Uygulaması Hizmeti'nin nasıl seçildiğini gösteren ekran görüntüsü.

  6. Dağıtım yapılandırmasında, Azure hesabınızda oturum açtığınızda görüntülenen sonuçlarda web uygulamasını seçin. Profili tamamlamak için Son'u ve ardından Yayımla'yı seçerek dağıtımı başlatın.

    Dağıtım yapılandırmasını web uygulaması adıyla ayarlamayı gösteren ekran görüntüsü.

İletişim Hizmetleri kaynağı alma

Botunuz oluşturulduğuna ve dağıtıldığından, İletişim Hizmetleri kanalını ayarlamak için kullanılacak bir İletişim Hizmetleri kaynağı oluşturun:

  1. İletişim Hizmetleri kaynağı oluşturma adımlarını tamamlayın.

  2. İletişim Hizmetleri kullanıcısı oluşturun ve bir kullanıcı erişim belirteci gönderin. Kapsamı sohbet olarak ayarladığınızdan emin olun. Belirteç dizesini ve kullanıcı kimliği dizesini kopyalayın.

İletişim Hizmetleri Sohbet kanalını etkinleştirme

İletişim Hizmetleri kaynağınız olduğunda, bot kaynağında bir İletişim Hizmetleri kanalı ayarlayabilirsiniz. Bu işlemde bot için bir kullanıcı kimliği oluşturulur.

  1. Azure portalında Azure Bot kaynağınıza gidin. Kaynak menüsünde Kanallar'ı seçin. Kullanılabilir kanallar listesinde Azure Communications Services - Sohbet'i seçin.

    İletişim Hizmetleri Sohbet kanalını açmayı gösteren ekran görüntüsü.

  2. Aboneliğinizde kullanılabilen İletişim Hizmetleri kaynaklarının listesini görmek için Bağlan'ı seçin.

    İletişim Hizmeti kaynağının bota nasıl bağlandığını gösteren ekran görüntüsü.

  3. Yeni Bağlantı bölmesinde İletişim Hizmetleri sohbet kaynağını ve ardından Uygula'yı seçin.

    Yeni bir İletişim Hizmetleri kullanıcı kimliği oluşturmak için seçilen İletişim Hizmeti kaynağının nasıl kaydedildiğini gösteren ekran görüntüsü.

  4. Kaynak ayrıntıları doğrulandığında Bot Azure İletişim Hizmetleri Kimliği sütununda bir bot kimliği gösterilir. İletişim Hizmetleri Sohbet AddParticipant API'sini kullanarak bot kimliğini kullanarak botu sohbet yazışmasında temsil edebilirsiniz. Botu bir sohbete katılımcı olarak ekledikten sonra bot sohbetle ilgili etkinlikleri almaya başlar ve sohbet yazışmasında yanıt verebilir.

    Bota atanan yeni İletişim Hizmetleri kullanıcı kimliğini gösteren ekran görüntüsü.

Sohbet uygulaması oluşturma ve botu katılımcı olarak ekleme

Artık bot'un İletişim Hizmetleri Kimliğine sahip olduğunuz için, katılımcı olarak botla bir sohbet yazışması oluşturabilirsiniz.

'Uygulamanıza Sohbet Ekleme' hızlı başlangıcını izleyin

Sohbet uygulaması oluşturmak için Uygulamanıza Sohbet Ekleme hızlı başlangıcındaki adımları izleyin.

  1. Resource_Endpoint>, İletişim Hizmeti Kaynağı Al adımındaki İletişim Hizmetleri uç noktasıyla değiştirin<.
  2. Access_Token> yerine İletişim Hizmeti Kaynağı Al adımındaki kullanıcı erişim belirtecini yazın<.
  3. İletişim Hizmetleri Sohbet kanalını etkinleştirme adımındaki Access_ID> ACS_ID botlarla değiştirin<.

C# sohbet uygulamasını yerel olarak çalıştırma

Sohbet uygulamasını yerel olarak çalıştırmak için komutunu dotnet run kullanın:

dotnet run

Konsolda bottan "Merhaba Dünya" yazan bir ileti almalısınız.

Örnek çıkış:

1730405535010:Hello World

Botla yapabileceğiniz diğer işlemler

Bot, Communications Services Sohbet kanalındaki bir kullanıcıdan düz metin iletisinden fazlasını alabilir. Botun bir kullanıcıdan alabileceği etkinliklerden bazıları şunlardır:

  • Konuşma güncelleştirmesi
  • İleti güncelleştirmesi
  • İleti silme
  • Yazma göstergesi
  • Olay etkinliği
  • Uyarlamalı kartlar da dahil olmak üzere çeşitli ekler
  • Bot kanalı verileri

Sonraki bölümlerde bu özellikleri göstermek için bazı örnekler gösterilir.

İş parçacığına yeni bir kullanıcı eklendiğinde hoş geldiniz iletisi gönderme

Geçerli Yankı Botu mantığı, kullanıcıdan gelen girişleri kabul eder ve geri yankılar. Katılımcı tarafından eklenen bir İletişim Hizmetleri olayına yanıt verme gibi daha fazla mantık eklemek istiyorsanız, aşağıdaki kodu kopyalayın ve EchoBot.cs kaynak dosyasına yapıştırın:

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

Uyarlamalı kart gönderme

Not

Uyarlamalı kartlar yalnızca tüm sohbet katılımcılarının Azure İletişim Hizmetleri kullanıcı olduğu Azure İletişim Hizmetleri kullanım örnekleri içinde desteklenir; Teams birlikte çalışabilirlik kullanım örnekleri için desteklenmez.

Etkileşimi ve verimliliği artırmak için sohbet yazışmasına uyarlamalı bir kart gönderebilirsiniz. Uyarlamalı kart, kullanıcılarla çeşitli yollarla iletişim kurmanıza da yardımcı olur. Kartı bot etkinlik eki olarak ekleyerek bottan uyarlamalı kart gönderebilirsiniz.

Uyarlamalı kart gönderme örneği aşağıda verilmişti:

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

Uyarlamalı kartlar için örnek yükleri Örnekler ve şablonlar'da bulabilirsiniz.

Sohbet kullanıcısı için İletişim Hizmetleri Sohbet kanalı ileti meta verilerine iletinin eki olduğunu belirten bir alan ekler. Meta verilerde özelliği microsoft.azure.communication.chat.bot.contenttype olarak azurebotservice.adaptivecardayarlanır.

Uyarlamalı kart eklenmiş bir sohbet iletisi örneği aşağıda verilmiştir:

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

Kullanıcıdan bota ileti gönderme

Bir kullanıcıdan bota, başka bir kullanıcıya kısa mesaj gönderdiğiniz gibi temel bir kısa mesaj gönderebilirsiniz.

Ancak, bir kullanıcıdan bota eki olan bir ileti gönderdiğinizde, İletişim Hizmetleri Sohbeti meta verilerine bu bayrağı ekleyin:

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

Bir kullanıcıdan bota olay etkinliği göndermek için bu bayrağı İletişim Hizmetleri Sohbeti meta verilerine ekleyin:

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

Aşağıdaki bölümlerde kullanıcıdan bota sohbet iletileri için örnek biçimler gösterilmektedir.

Basit kısa mesaj

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

Eki olan ileti

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

Olay etkinliği içeren ileti

Olay yükü, ileti içeriğindeki dışındaki Nametüm JSON alanlarını içerir. alanı Name olayın adını içerir.

Aşağıdaki örnekte yüke "{field1":"value1", "field2": { "nestedField":"nestedValue" }} sahip olay adı endOfConversation bota gönderilir:

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

Meta veri alanı microsoft.azure.communication.chat.bot.contenttype yalnızca kullanıcıdan bota gönderilen bir iletide gereklidir.

Desteklenen bot etkinlik alanları

Aşağıdaki bölümlerde, bot-kullanıcı akışları ve kullanıcıdan bota akışlar için desteklenen bot etkinlik alanları açıklanmaktadır.

Bot-kullanıcı akışı

Bot-kullanıcı akışları için aşağıdaki bot etkinlik alanları desteklenir.

Aktiviteler

  • İleti
  • Yazım

İleti etkinliği alanları

  • Text
  • Attachments
  • AttachmentLayout
  • SuggestedActions
  • From.Name (İletişim Hizmetlerine SenderDisplayNameDönüştürülür.)
  • ChannelData (İletişim Hizmetleri'ne Chat Metadatadönüştürülür. Herhangi bir ChannelData eşleme değeri nesneyse, JSON biçiminde serileştirilir ve dize olarak gönderilir.)

Kullanıcıdan bota akış

Bu bot etkinlik alanları, kullanıcıdan bota akışlar için desteklenir.

Etkinlikler ve alanlar

  • İleti

    • Id (İletişim Hizmetleri Sohbet ileti kimliği)
    • TimeStamp
    • Text
    • Attachments

  • Konuşma güncelleştirmesi

    • MembersAdded
    • MembersRemoved
    • TopicName

  • İleti güncelleştirmesi

    • Id (Güncelleştirilmiş İletişim Hizmetleri Sohbet ileti kimliği)
    • Text
    • Attachments

  • İleti silme

    • Id (Silinmiş İletişim Hizmetleri Sohbet ileti kimliği)

  • Etkinlik

    • Name
    • Value

  • Yazım

Diğer ortak alanlar

  • Recipient.Id ve Recipient.Name (İletişim Hizmetleri Sohbeti kullanıcı kimliği ve görünen adı)
  • From.Id ve From.Name (İletişim Hizmetleri Sohbeti kullanıcı kimliği ve görünen adı)
  • Conversation.Id (İletişim Hizmetleri Sohbet yazışma kimliği)
  • ChannelId (İletişim Hizmetleri Sohbeti boşsa)
  • ChannelData (İletişim Hizmetleri Sohbet iletisi meta verileri)

Bot iletim desenleri

Bazen bot bir soruyu anlamaz veya bir soruyu yanıtlayamaz. Müşteri sohbette bir insan temsilciyle bağlantı kurulmasını isteyebilir. Bu senaryolarda sohbet yazışmasının bottan bir insan temsilciye devredilmesi gerekir. Bir konuşmayı bottan insana geçirecek şekilde uygulamanızı tasarlayabilirsiniz.

Bot-bot iletişimlerini işleme

Bazı kullanım örneklerinde, farklı hizmetler sağlamak için aynı sohbet yazışmasına iki bot eklenmesi gerekir. Bu senaryoda, botların başka bir bota ait iletilere otomatik yanıt göndermediğinden emin olmanız gerekebilir. Düzgün işlenmezse botların kendi aralarındaki otomatik etkileşimi sonsuz bir ileti döngüsüne neden olabilir.

Etkinliğin From.Id özelliğinde ileti gönderenin İletişim Hizmetleri kullanıcı kimliğini doğrulayabilirsiniz. Başka bir bota ait olup olmadığını denetleyin. Ardından bot-bot iletişim akışını önlemek için gerekli eylemi gerçekleştirin. Bu tür bir senaryo yüksek arama birimleriyle sonuçlanırsa İletişim Hizmetleri Sohbet kanalı istekleri kısıtlar ve bot ileti gönderip alamaz.

Kısıtlama sınırları hakkında daha fazla bilgi edinin.

Sorun giderme

Aşağıdaki bölümlerde yaygın senaryolarda sorun giderme yolları açıklanmaktadır.

Sohbet kanalı eklenemiyor

Uç noktanın doğru ayarlandığını doğrulamak için Microsoft Bot Framework geliştirici portalında Yapılandırma>Botu Mesajlaşması'na gidin.

Bot, bir iletiyi yanıtlarken yasak bir özel durum alıyor

Bot'un Microsoft uygulama kimliğinin ve parolasının web uygulamasına yüklediğiniz bot yapılandırma dosyasına doğru şekilde kaydedildiğini doğrulayın.

Bot katılımcı olarak eklenemiyor

Botu sohbet yazışmasına ekleme isteği gönderildiğinde bot İletişim Hizmetleri Kimliğinin doğru kullanıldığını doğrulayın.