İnceleme ara yazılımı ile botta hata ayıklama

ŞUNLAR IÇIN GEÇERLIDIR: SDK v4

Bu makalede, inceleme ara yazılımını kullanarak bir botta hata ayıklama işlemi açıklanır. Bu özellik, Bot Framework Emulator'ın bota gelen ve giden trafikte hata ayıklamasına ve botun geçerli durumunu görmesine olanak tanır. Öykünücüye veri göndermek ve ardından konuşmanın herhangi bir sırasında botunuzun durumunu incelemek için izleme iletisi kullanabilirsiniz.

Botun ileti durumunun hatalarını ayıklamayı ve incelemeyi göstermek için Bot oluşturma hızlı başlangıcındaki Bot Framework v4 kullanılarak yerel olarak oluşturulmuş bir EchoBot kullanıyoruz. Ayrıca Bot Framework Öykünücüsü ile IDE kullanarak botta hata ayıklama veya Hata Ayıklama da yapabilirsiniz, ancak hata ayıklama durumu için botunuza inceleme ara yazılımı eklemeniz gerekir. İnceleme botu örnekleri C#, JavaScript, Java ve Python için kullanılabilir.

Not

Bot Framework JavaScript, C# ve Python SDK'ları desteklenmeye devam edecektir, ancak Java SDK'sı son uzun vadeli destek Kasım 2023'te sona erecek şekilde kullanımdan kaldırılacaktır.

Java SDK ile oluşturulan mevcut botlar çalışmaya devam edecektir.

Yeni bot derlemesi için Power Virtual Agents'ı kullanmayı göz önünde bulundurun ve doğru sohbet botu çözümünü seçme hakkında bilgi edinin.

Daha fazla bilgi için bkz . Bot oluşturmanın geleceği.

Önkoşullar

• Bot Ara Yazılımı ve Yönetim durumu hakkında bilgi
• SDK öncelikli bir botta hata ayıklama ve Öykünücü ile test etme ve hata ayıklama hakkında bilgi
• Bot Framework Öykünücüsü yüklemesi
• Ngrok yükleme (Azure'da yapılandırılan bir botta diğer kanalları kullanacak şekilde hata ayıklamak istiyorsanız)
• C#, JavaScript, Java veya Python için inceleme botu örneğinin bir kopyası

Öykünücünüzü en son sürüme güncelleştirme

Botunuzda hata ayıklamak için bot denetleme ara yazılımını kullanmadan önce Öykünücünüzü 4.5 veya sonraki bir sürüme güncelleştirin. Güncelleştirmeler için en son sürümü denetleyin.

Öykünücünüzün sürümünü denetlemek için Yardım'ı ve ardından menüden Hakkında'yı seçin. Öykünücünüzün geçerli sürümünü görürsünüz.

Bot kodunuzu güncelleştirme

C#

İnceleme durumu ve inceleme ara yazılımı Startup.cs dosyasında yapılandırılır ve ardından bağdaştırıcı tarafından kullanılır.

Startup.cs

});

services.AddSingleton<ConversationState>();

// Create the Bot Framework Authentication to be used with the Bot Adapter.

AdapterWithInspection.cs

{
    public class AdapterWithInspection : CloudAdapter
    {
        public AdapterWithInspection(BotFrameworkAuthentication auth, IConfiguration configuration, InspectionState inspectionState, UserState userState, ConversationState conversationState, ILogger<IBotFrameworkHttpAdapter> logger)
            : base(auth, logger)
        {
            // Inspection needs credentials because it will be sending the Activities and User and Conversation State to the emulator
            var credentials = new MicrosoftAppCredentials(configuration["MicrosoftAppId"], configuration["MicrosoftAppPassword"]);

            Use(new InspectionMiddleware(inspectionState, userState, conversationState, credentials));

            OnTurnError = async (turnContext, exception) =>
            {
                // Log any leaked exception from the application.
                logger.LogError(exception, $"[OnTurnError] unhandled error : {exception.Message}");

                // Send a message to the user
                await turnContext.SendActivityAsync("The bot encountered an error or bug.");
                await turnContext.SendActivityAsync("To continue to run this bot, please fix the bot source code.");

                // Send a trace activity, which will be displayed in the Bot Framework Emulator
                await turnContext.TraceActivityAsync("OnTurnError Trace", exception.Message, "https://www.botframework.com/schemas/error", "TurnError");
            };
        }

EchoBot.cs dosyasında bot sınıfını güncelleştirin.

EchoBot.cs

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    var conversationStateProp = _conversationState.CreateProperty<CustomState>("customState");
    var convProp = await conversationStateProp.GetAsync(turnContext, () => new CustomState { Value = 0 }, cancellationToken);

    var userStateProp = _userState.CreateProperty<CustomState>("customState");
    var userProp = await userStateProp.GetAsync(turnContext, () => new CustomState { Value = 0 }, cancellationToken);

    await turnContext.SendActivityAsync(MessageFactory.Text($"Echo: {turnContext.Activity.Text} conversation state: {convProp.Value} user state: {userProp.Value}"), cancellationToken);

    convProp.Value++;
    userProp.Value++;
}

JavaScript

Botunuzun kodunu güncelleştirmeden önce, terminalinizde aşağıdaki komutu yürüterek paketlerini en son sürümlere güncelleştirin:

npm install --save botbuilder@latest

Ardından JavaScript botunuzun kodunu aşağıdaki gibi güncelleştirmeniz gerekir. Burada daha fazla bilgi edinebilirsiniz: Botunuzun kodunu güncelleştirin veya GitHub'da İnceleme ara yazılımı örneğine bakın.

index.js

İnceleme durumunu ayarlayın ve index.js dosyasındaki bağdaştırıcıya denetim ara yazılımını ekleyin.

// Import required bot services.
// See https://aka.ms/bot-services to learn more about the different parts of a bot.
const {
    CloudAdapter,
    ConversationState,
    InspectionMiddleware,
    InspectionState,
    MemoryStorage,
    UserState,
    ConfigurationBotFrameworkAuthentication
} = require('botbuilder');

const { MicrosoftAppCredentials } = require('botframework-connector');

const botFrameworkAuthentication = new ConfigurationBotFrameworkAuthentication(process.env);

// Create adapter.
// See https://aka.ms/about-bot-adapter to learn more about how bots work.
const adapter = new CloudAdapter(botFrameworkAuthentication);

// Create the Storage provider and the various types of BotState.
const memoryStorage = new MemoryStorage();
const inspectionState = new InspectionState(memoryStorage);
const userState = new UserState(memoryStorage);
const conversationState = new ConversationState(memoryStorage);

// Create and add the InspectionMiddleware to the adapter.
adapter.use(new InspectionMiddleware(inspectionState, userState, conversationState, new MicrosoftAppCredentials(process.env.MicrosoftAppId, process.env.MicrosoftAppPassword)));

// Catch-all for errors.
adapter.onTurnError = async (context, error) => {
    // This check writes out errors to console log .vs. app insights.
    // NOTE: In production environment, you should consider logging this to Azure
    //       application insights. See https://aka.ms/bottelemetry for telemetry
    //       configuration instructions.
    console.error(`\n [onTurnError] unhandled error: ${ error }`);

bot.js

bot.js dosyasında bot sınıfını güncelleştirin.

this.onMessage(async (context, next) => {
    // get the state objects
    const testConversationState = await this.conversationStateAccessor.get(context, { count: 0 });
    const testUserState = await this.userStateAccessor.get(context, { count: 0 });

    // print the current state to the reply to show we are incrementing it
    await context.sendActivity(`You said '${ context.activity.text }' conversation-state: ${ testConversationState.count } user-state: ${ testUserState.count }`);

    // do the actual increment
    testConversationState.count++;
    testUserState.count++;

    // By calling next() you ensure that the next BotHandler is run.
    await next();
});

Java

İnceleme durumunu ayarlayın ve Application.java dosyasındaki bağdaştırıcıya denetim ara yazılımını ekleyin. İnceleme durumu, BotDependencyConfiguration temel sınıfı tarafından sağlanan varsayılan BotFrameworkHttpAdapter'ı geçersiz kılacak @Primary şekilde ayarlanmış BotFrameworkHttpAdapter'ı sağlamak için yeni bir Spring @Bean sağlanarak ayarlanır. Aşağıdaki kod güncelleştirmesine bakın veya GitHub'da Denetleme ara yazılımı örneğine bakın.

Application.java

/**
 * Create an adapter with InspectionMiddleware.
 *
 * <p>
 * NOTE: This is marked as @Primary to override the default Bean.
 * </p>
 *
 * @param configuration     The configuration.
 *                          {@link BotDependencyConfiguration#getConfiguration()}
 * @param inspectionState   The InspectionState.
 *                          {@link BotDependencyConfiguration#getInspectionState(Storage)}
 * @param userState         The UserState.
 *                          {@link BotDependencyConfiguration#getUserState(Storage)}
 * @param conversationState The ConversationState.
 *                          {@link BotDependencyConfiguration#getConversationState(Storage)}
 * @return An AdapterWithInspection object.
 */
@Bean
@Primary
public BotFrameworkHttpAdapter getInspectionBotFrameworkHttpAdapter(
    Configuration configuration,
    InspectionState inspectionState,
    UserState userState,
    ConversationState conversationState
) {
    return new AdapterWithInspection(
        configuration,
        inspectionState,
        userState,
        conversationState
    );
}

AdapterWithInspection, com.microsoft.bot.integration paketinin bir parçası olarak uygulanır ve Java SDK kaynak kodundan gözden geçirilebilir.

EchoBot.java dosyasındaki bot sınıfını güncelleştirin.

EchoBot.java

@Override
protected CompletableFuture<Void> onMessageActivity(TurnContext turnContext) {
    // Get state data from ConversationState.
    StatePropertyAccessor<CustomState> dataAccessor =
        conversationState.createProperty("customState");
    CompletableFuture<CustomState> convStateFuture =
        dataAccessor.get(turnContext, CustomState::new);

    // Get profile from UserState.
    StatePropertyAccessor<CustomState> profileAccessor =
        userState.createProperty("customState");
    CompletableFuture<CustomState> userStateFuture =
        profileAccessor.get(turnContext, CustomState::new);

    return convStateFuture.thenCombine(userStateFuture, (convProp, userProp) -> {
        convProp.setValue(convProp.getValue() + 1);
        userProp.setValue(userProp.getValue() + 1);

        return turnContext.sendActivity(
            MessageFactory.text(
                String.format(
                    "Echo: %s conversation state %d user state %d",
                    turnContext.getActivity().getText(), convProp.getValue(),
                    userProp.getValue()
                )
            )
        );
    }).thenApply(resourceResponse -> null);
}

Python

Botunuzun kodunu güncelleştirmeden önce, terminalde aşağıdaki komutları çalıştırarak gerekli PyPI paketlerini yükleyin:

pip install aiohttp
pip install botbuilder-core>=4.7.0

Bağdaştırıcıya ara yazılım ekleyerek app.py dosyasında inceleme durumunu ayarlayın.

app.py

from botbuilder.core import (
    ConversationState,
    MemoryStorage,
    TurnContext,
    UserState,
)
from botbuilder.core.inspection import InspectionMiddleware, InspectionState
from botbuilder.core.integration import aiohttp_error_middleware
from botbuilder.integration.aiohttp import CloudAdapter, ConfigurationBotFrameworkAuthentication
from botbuilder.schema import Activity, ActivityTypes
from botframework.connector.auth import MicrosoftAppCredentials

# Create adapter.
# See https://aka.ms/about-bot-adapter to learn more about how bots work.
ADAPTER = CloudAdapter(ConfigurationBotFrameworkAuthentication(CONFIG))

# Catch-all for errors.
USER_STATE = UserState(MEMORY)
CONVERSATION_STATE = ConversationState(MEMORY)

# Create InspectionMiddleware
INSPECTION_MIDDLEWARE = InspectionMiddleware(
    inspection_state=InspectionState(MEMORY),
    user_state=USER_STATE,
    conversation_state=CONVERSATION_STATE,
    credentials=MicrosoftAppCredentials(
        app_id=CONFIG.APP_ID, password=CONFIG.APP_PASSWORD
    ),
)
ADAPTER.use(INSPECTION_MIDDLEWARE)

# Create Bot
BOT = EchoBot(CONVERSATION_STATE, USER_STATE)

echo_bot.py dosyasında bot sınıfını güncelleştirin.

botlar/echo_bot.py

async def on_message_activity(self, turn_context: TurnContext):
    # Get the state properties from the turn context.
    user_data = await self.user_state_accessor.get(turn_context, CustomState)
    conversation_data = await self.conversation_state_accessor.get(
        turn_context, CustomState
    )

    await turn_context.send_activity(
        MessageFactory.text(
            f"Echo: {turn_context.activity.text}, "
            f"conversation state: {conversation_data.value}, "
            f"user state: {user_data.value}"
        )
    )

    user_data.value = user_data.value + 1
    conversation_data.value = conversation_data.value + 1

Botunuzu yerel olarak test edin

Kodu güncelleştirdikten sonra botunuzu yerel olarak çalıştırabilir ve hata ayıklama özelliğini iki Öykünücü kullanarak test edebilirsiniz: biri ileti göndermek ve almak için, diğeri hata ayıklama modunda iletilerin durumunu incelemek için. Botunuzu yerel olarak test etmek için:

1. Bir terminalde botunuzun dizinine gidin ve aşağıdaki komutu yürüterek botunuzu yerel olarak çalıştırın:

   C#

   dotnet run
   

   JavaScript

   npm start
   

   Java

   mvn package
   java -jar .\target\bot-inspection-sample.jar 
   

   Python

   python app.py
   

2. Öykünücünüzü açın. Botu Aç'ı seçin. Bot URL'sini http://localhost:3978/api/messages ve MicrosoftAppId ile MicrosoftAppPassword değerlerini doldurun. JavaScript botunuz varsa bu değerleri botunuzun .env dosyasında bulabilirsiniz. C# botu varsa bu değerleri appsettings.json dosyasında bulabilirsiniz. Java botu için bu değerleri application.properties dosyasında bulabilirsiniz. Bağlan'ı seçin.

3. Şimdi başka bir Öykünücü penceresi açın. Bu ikinci Öykünücü penceresi hata ayıklayıcı olarak çalışır. Önceki adımda açıklandığı gibi yönergeleri izleyin. Hata ayıklama modunda aç'ı işaretleyin ve Bağlan'i seçin.

4. Bu noktada, hata ayıklama Öykünücünüzde benzersiz tanımlayıcıya (/INSPECT attach <identifier>) sahip bir komut görürsünüz. Hata ayıklama Öykünücüsünün tanımlayıcısıyla komutun tamamını kopyalayın ve ilk Öykünücünün sohbet kutusuna yapıştırın.

   Not

   Botunuzun koduna inceleme ara yazılımını ekledikten sonra Öykünücü hata ayıklama modunda başlatıldığında benzersiz bir tanımlayıcı oluşturulur.

5. Artık ilk Öykünücünüzün sohbet kutusunda ileti gönderebilir ve hata ayıklama Öykünücüsü'ndeki iletileri inceleyebilirsiniz. İletilerin durumunu incelemek için hata ayıklama Öykünücüsü'nde Bot Durumu'nu seçin ve doğru JSON penceresinde değerleri açın. Hata ayıklama Öykünücüsü'nde botunuzun durumunu görürsünüz:

   

Azure'da yapılandırılan bir botun durumunu inceleme

Azure'da yapılandırılan ve kanallara (Teams gibi) bağlı olan botunuzun durumunu incelemek istiyorsanız ngrok'u yükleyip çalıştırmanız gerekir.

ngrok çalıştırma

Bu noktada Öykünücünüzü en son sürüme güncelleştirdiniz ve botunuzun koduna inceleme ara yazılımını eklediniz. Sonraki adım ngrok'u çalıştırmak ve yerel botunuzu yapılandırmaktır. ngrok çalıştırmadan önce botunuzu yerel olarak çalıştırmanız gerekir.

Botunuzu yerel olarak çalıştırmak için:

1. Terminalde botunuzun klasörüne gidin ve npm kaydınızı en son derlemeleri kullanacak şekilde ayarlayın

2. Botunuzu yerel olarak çalıştırın. Botunuzun gibi 3978bir bağlantı noktası numarasını kullanıma çıkardiğini göreceksiniz.

3. Başka bir komut istemi açın ve botunuzun proje klasörüne gidin. Şu komutu çalıştırın:

   ngrok http 3978
   

4. ngrok artık yerel olarak çalışan botunuza bağlı. Güvenli (HTTPS) genel IP adresini kopyalayın.

   

Bot kaynağınızı güncelleştirme

Yerel botunuz ngrok'a bağlı olduğuna göre Azure'daki bot kaynağınızı ngrok URL'sini kullanacak şekilde yapılandırabilirsiniz.

1. Azure'da bot kaynağınıza gidin. Soldaki menüde, Ayarlar altında Yapılandırma'yı seçin.

   1. Mesajlaşma uç noktasını kopyaladığınız ngrok IP adresine ayarlayın. Gerekirse IP adresinden sonra /api/messages ekleyin. Örneğin, https://e58549b6.ngrok.io/api/messages.

   2. Akış Uç Noktasını Etkinleştir'i seçin.

      

   3. Yaptığınız değişiklikleri kaydetmek için Apply'ı (Uygula) seçin.

      İpucu

      Uygula etkin değilse Akış Uç Noktasını Etkinleştir'in işaretini kaldırıp Uygula'yı seçip Akış Uç Noktasını Etkinleştir'i işaretleyip yeniden Uygula'yı seçebilirsiniz. Akış Uç Noktasını Etkinleştir seçeneğinin işaretli olduğundan ve uç nokta yapılandırmasının kaydedildiğinden emin olmanız gerekir.

2. Botunuzun kaynak grubuna gidin.

   1. Dağıtım'ı ve ardından daha önce başarıyla dağıtılan bot kaynağını seçin. Botunuzla ilişkilendirilmiş web uygulamasının MicrosoftAppId ve MicrosoftAppPassword değerlerini almak için sol menüden Şablon'u seçin.

      

   2. Botunuzun yapılandırma dosyasını (C# için appsettings.json veya JavaScript için .env) MicrosoftAppId ve MicrosoftAppPassword ile güncelleştirin.

3. Öykünücünüzü başlatın, Botu Aç'ı seçin ve Bot URL'sini girinhttp://localhost:3978/api/messages. Microsoft Uygulama Kimliği ve Microsoft Uygulama parolasını botumuzun yapılandırma dosyasına eklediğiniz MicrosoftAppId ve MicrosoftAppPassword ile doldurun. Ardından Bağlan'ı seçin.

4. Çalışan botunuz artık Azure'daki bot kaynağınıza bağlı. Botunuzu Azure'da Web Sohbeti test etmek için bot kaynaklarınıza gidin, Web Sohbeti'de test et'i seçin ve botunuza ileti gönderin.

Hata ayıklama modunu etkinleştirme

1. Öykünücünüzde Hata Ayıkla'yı ve ardından Hata Ayıklamayı Başlat'ı seçin.

2. Bot URL'si için ngrok IP adresini (/api/messages eklemeyi unutmayın) girin (örneğin, https://e58549b6.ngrok.io/api/messages ).

   1. Microsoft Uygulama Kimliği için botunuzun uygulama kimliğini girin.
   2. Microsoft Uygulama parolası için botunuzun uygulama gizli dizisini girin.
   3. Hata ayıklama modunda aç'ın da işaretli olduğundan emin olun.
   4. Bağlan'ı seçin.

3. Hata ayıklama modu etkinleştirildiğinde Öykünücü bir UUID oluşturur. UUID, Öykünücünüzde hata ayıklama modunu her başlattığınızda oluşturulan benzersiz bir kimliktir.

4. UUID'yi kopyalayıp kanalınızın sohbet kutusunun Web Sohbeti sohbet kutusunda test et kutusuna yapıştırın. Sohbet kutusunda "Oturuma eklendi, tüm trafik inceleme için çoğaltılıyor" iletisini görürsünüz.

Yapılandırılan kanalın sohbet kutusunda ileti göndererek botunuzda hata ayıklamaya başlayabilirsiniz. Yerel Öykünücünüz, hata ayıklamaya yönelik tüm ayrıntılarla iletileri otomatik olarak güncelleştirir. Botunuzun ileti durumunu incelemek için Bot Durumu'nu seçin ve değerleri doğru JSON penceresinde açın.

Sonraki adımlar

• Transkript dosyalarını kullanarak botunuzda hata ayıklamayı öğrenin.
• Beceri veya beceri tüketicisinde hata ayıklamayı öğrenin.