Node.js için Azure Bot Framework SDK'dan Microsoft 365 Aracıları SDK'sı'ya geçiş kılavuzu

Bu makalede, Node.js için Bot Framework SDK'sından geçiş yapmak için gerekli değişiklikler açıklanmaktadır.

Önkoşullar

  • Node.js sürüm 20 veya üstü
  • Mevcut Bot Framework SDK'sı projesi
  • Azure Bot Hizmeti kaynağı (geçiş sırasında değişmeden kalır)

NodeJS SDK'sı kod değişiklikleri

Bu bölümdeki değişiklikler, Azure Bot Framework SDK ile Microsoft 365 Aracıları SDK'sı JavaScript arasındaki farklar nedeniyledir.

Azure kaynakları

Azure kaynaklarınız değişmeden kalır. MicrosoftAppType, MicrosoftAppId, MicrosoftAppPassword ve MicrosoftAppTenantId için appsettings özelliklerinize başvurmanız gerekir. Ancak bu ayar adları artık kullanılmaz ve daha sonra silinebilir. Ortam yapılandırması hakkında daha fazla bilgi edinin

İlk adımlar

Çoğu farklılığı gidermek için önce aşağıdaki değişiklikleri uygulayın. Bu değişiklikleri uyguladıktan sonra yine de hata ayıklamanız ve diğer farklılıkları kontrol etmeniz gerekecektir.

Paket bağımlılıklarını güncelleştirme

Bu değişiklik, gerekli tüm ad alanlarının yerleşmesini sağlamaz ancak büyük bir kısmını kapsar.

Senaryo Bot Framework SDK'sı Aracıları SDK'sı
Çekirdek barındırma botbuilder @microsoft/agents-hosting
Etkinlik şeması botframework-schema @microsoft/agents-activity
Dialogs botbuilder-dialogs @microsoft/agents-hosting-dialogs
Azure Cosmos DB veritabanı botbuilder-azure @microsoft/agents-hosting-storage-cosmos
Azure Blob Depolama (Microsoft'un bulut depolama hizmeti) botbuilder-azure-blobs @microsoft/agents-hosting-storage-blob
Ekspres sunucu yardımcı programları El ile kurulum @microsoft/agents-hosting-express

Teams kullanan botlar

Botunuz Teams kullanıyorsa, için bir paket bağımlılığı ekleyin @microsoft/agents-hosting-extensions-teams

İçeri aktarmaları/gereksinimleri güncelleştirme

Aşağıdaki değişiklikleri yapmak için bul ve değiştir seçeneğini kullanın:

Bot Framework Aracıları SDK'sı
require('botframework-schema'); require('@microsoft/agents-activity')
require('botbuilder'); require('@microsoft/agents-hosting')
require('botbuilder-dialogs'); require('@microsoft/agents-hosting-dialogs')

Aracılar SDK'sı Etkinlik sınıfı

@microsoft/agents-activity paketi, zod temelinde ayrıştırma gerçekleştirmek için Etkinlik sınıfını içerir. Özel etkinliklerinizi Activity.fromJson() ile JSON'dan veya Activity.fromObject() ile gerçek JavaScript nesnelerinden ayrıştırabilir ve doğrulayabilirsiniz.

Ayrıca, Activity sınıfı, getConversationReference gibi etkinlik yüküyle ilgili tüm işlemleri merkezileştirir. Aşağıdaki tabloda yer alan yöntemler TurnContext konumundan taşınmıştır ve artık geçerli etkinlik örneği üzerinde çalışmaktadır:

Bot Framework statik yöntemi Aracılar SDK'sı örnek yöntemi
TurnContext.applyConversationReference activity.applyConversationReference
TurnContext.getConversationReference activity.getConversationReference
TurnContext.getReplyConversationReference activity.getReplyConversationReference
TurnContext.removeRecipientMention activity.removeRecipientMention
TurnContext.getMentions activity.getMentions
TurnContext.removeMentionText activity.removeMentionText

Başlangıç ve Yapılandırma

Aracılar SDK'sı yapılandırma sistemi ConfigurationBotFrameworkAuthentication sınıfını AuthConfiguration arabirimi ile değiştirir.

Yapılandırmayı varsayılan .env dosyasından yüklemek için loadAuthConfigFromEnv kullanılır.

Önemli

Yapılandırma değişkenleri JavaScript'te kimlik doğrulamayı yapılandırma bölümünde açıklanmaktadır.

Ortam Yapılandırması

Aşağıdaki değişkenleri içeren bir .env dosyası oluşturun:

# Required for Azure Bot Service
clientId=your-app-id
clientSecret=your-app-secret  
tenantId=your-tenant-id

# Optional - for local debugging
PORT=3978
DEBUG=true

Geçiş Notu: Ortam değişkeni adlarınızı aşağıdaki tabloda gösterildiği gibi güncelleştirin:

Bot Framework SDK'sı Aracıları SDK'sı
MicrosoftAppId clientId
MicrosoftAppPassword clientSecret
MicrosoftAppTenantId tenantId

Kimlik Doğrulama ve Güvenlik

Bot Framework SDK'sı gelen istekleri yetkilendirdiğinde, yığına JSON Web Belirteci (JWT) yetkilendirme belirteçleri ekler. Agents SDK desteklemez. Ekspres gibi bir web sunucusu çalışma zamanı kullanırken, JWT Taşıyıcı belirtecine dayalı olarak gelen istekleri yetkilendirmek için bir JWT ara yazılımı yapılandırmanız gerekir, Aracılar SDK'sı, authorizeJWT(AuthConfiguration) yöntemini sağlar.

JWT Ara Yazılımı (Üretim için gereklidir):

import { authorizeJWT, loadAuthConfigFromEnv } from '@microsoft/agents-hosting'

const authConfig = loadAuthConfigFromEnv()
server.use(authorizeJWT(authConfig))

Yerel Geliştirme:

Yerel hata ayıklama için JWT doğrulaması devre dışı bırakılabilir:

// Only for local development - NEVER in production
if (process.env.NODE_ENV === 'development') {
    // JWT validation disabled for local testing
} else {
    server.use(authorizeJWT(authConfig))
}

Sunucu Kurulum Seçenekleri

Aracılar SDK'sı, sunucunuzu kurmak için iki yaklaşım sunar:

startServer yöntemini kullanma

Minimal bir kurulum istediğinizde ve özel ara katman yazılımına ihtiyaç duymadığınızda yeni projeler için bu basitleştirilmiş yaklaşımı kullanın.

Başlatma kodunuzu botbuilder üzerinden güncelleştirin:

const { EchoBot } = require('./bot');
const {
    CloudAdapter,
    ConfigurationBotFrameworkAuthentication
} = require('botbuilder');
const botFrameworkAuthentication = new ConfigurationBotFrameworkAuthentication(process.env);
const adapter = new CloudAdapter(botFrameworkAuthentication);
const myBot = new EchoBot();
const server = express();
server.use(express.json());
server.post('/api/messages', async (req, res) => 
    await adapter.process(req, res, (context) => 
      myBot.run(context));
);

startServer() ile barındıran aracılara:

const { EchoBot } = require('./bot');
const { startServer } = require('@microsoft/agents-hosting-express')
startServer(new EchoBot());

El ile Ekspres kurulumu

Mevcut botları taşırken, özel ara katman yazılımına ihtiyaç duyarken, Ekspres yapılandırma üzerinde tam kontrol isterken bu yaklaşımı kullanın

const { EchoBot } = require('./bot');
const {
    CloudAdapter,
    loadAuthConfigFromEnv, // Update
    authorizeJWT // Update
} = require('@microsoft/agents-hosting'); // Update
const authConfig = loadAuthConfigFromEnv(); // Update
const adapter = new CloudAdapter(authConfig); // Update
const myBot = new EchoBot();
const server = express();
server.use(express.json());
server.use(authorizeJWT(authConfig)); // Update
server.post('/api/messages', async (req, res) => 
    await adapter.process(req, res, (context) => 
      myBot.run(context));
);

const port = process.env.PORT || 3978;
server.listen(port, () => {
    console.log(`Server listening on port ${port}`);
}).on('error', (err) => {
    console.error('Server failed to start:', err);
    process.exit(1);
});

ActivityHandler desteği

Bot Framework SDK ile oluşturulan botların çoğu botbuilder-core.ActivityHandler temel sınıfını temel alır.

Aracılar SDK'sı, daha kolay geçiş için aynı API yüzeyini koruyan uyumlu bir agents-hosting.ActivityHandler sağlar.

Önemli farklar

Bot Framework SDK ile Aracılar SDK'sı arasındaki bazı temel farklar şunlardır:

İşleyici Parametreleri:

SDK İşleyici Tipi
Bot Framework SDK'sı BotHandler
Aracıları SDK'sı AgentHandler

Aracılar SDK'sındaki Ek Yöntemler:

Yöntem Açıklama
onMessageDelete Mesaj silme etkinliklerini yönetir
onMessageUpdate İleti güncelleştirme etkinliklerini yönetir
onSignInInvoke Oturum açma çağırma etkinliklerini işler

Aracılar SDK'sındaki Eksik Yöntemler:

Yöntem Nedeni
onCommand Komut etkinlikleri desteklenmiyor
onCommandResult Komut sonucu etkinlikleri desteklenmiyor
onEvent Genel olay işleme (onTokenResponseEvent gibi belirli olay türleri hala desteklenmektedir)
onTokenResponseEvent OAuth belirteci yanıt olayları

Yöntem İmzası Değişiklikleri:

Tüm işleyici yöntemleri, yöntem zincirleme için ActivityHandler yerine this döndürür. İşleyici işlevleri, AgentHandler ile aynı imzaya sahip olan BotHandler türünü kullanır

Geçiş Örneği:

Bot Framework SDK'sı:

const { ActivityHandler } = require('botbuilder');

class MyBot extends ActivityHandler {
    constructor() {
        super();
        this.onMessage(async (context, next) => {
            await context.sendActivity('Hello!');
            await next();
        });
    }
}

Geçiş çoğunlukla basittir, ana değişiklik içe aktarma deyimi ve işleyici türüdür. Mevcut ActivityHandler tabanlı botların çoğu minimum değişiklikle çalışmalıdır.

Önemli

ActivityHandler, yeni AgentApplication sınıfı lehine kullanımdan kaldırılmıştır

ActivityHandler'den AgentApplication'ye geçiş

Geriye dönük uyumluluk için ActivityHandler desteklense de, önerilen yaklaşım AgentApplication kullanmaktır:

ActivityHandler kullanma:

import { ActivityHandler } from '@microsoft/agents-hosting'

class MyBot extends ActivityHandler {
    constructor() {
        super()
        this.onMessage(async (context, next) => {
            await context.sendActivity('Hello!')
            await next()
        })
        
        this.onMembersAdded(async (context, next) => {
            await context.sendActivity('Welcome!')
            await next()
        })
    }
}

Temel Farklılıklar

Aşağıdaki tabloda ActivityHandler ve AgentApplication arasındaki temel özellik farklılıkları açıklanmaktadır:

Özellik ActivityHandler AgentApplication
Durum Yönetimi El ile durum yönetimi gerekli Yerleşik durum yönetimi sağlanmıştır
Olay İşleme Genel olay işleyiciler (örneğin, onMembersAdded) Daha spesifik olay işleyiciler (örneğin, membersAdded)
Sonraki İşlev İşleyiciler çağırma gerektirir next() İşleyiciler çağırma gerektirmez next()
Depolama El ile depolama yapılandırması Otomatik durum sürekliliği ile yerleşik depolama desteği

Yaygın Geçiş Kalıpları

Bazı yaygın geçiş modelleri şunlardır:

Basit Echo Bot

Bot Framework

const { ActivityHandler } = require('botbuilder')

class EchoBot extends ActivityHandler {
    constructor() {
        super()
        this.onMessage(async (context, next) => {
            await context.sendActivity(`You said: ${context.activity.text}`)
            await next()
        })
    }
}

Durum Yönetimi

AgentApplication kullanma:

import { AgentApplication, MemoryStorage } from '@microsoft/agents-hosting'

const agent = new AgentApplication({
    storage: new MemoryStorage()
})

agent.onMessage('/count', async (context, state) => {
    const count = state.conversation.count ?? 0
    state.conversation.count = count + 1
    await context.sendActivity(`Count: ${state.conversation.count}`)
})

AgentApplication'dan devralma

Daha karmaşık senaryolar için AgentApplication üzerinden devralınan bir sınıf oluşturabilirsiniz:

import { AgentApplication, MemoryStorage, MessageFactory } from '@microsoft/agents-hosting'

class MyAgent extends AgentApplication {
    constructor() {
        super({
            storage: new MemoryStorage()
        })
        this.setupRoutes()
    }
    
    setupRoutes() {
        this.onMessage('/help', this.handleHelp)
        this.onMessage('/status', this.handleStatus)
        this.onMessage('/reset', this.handleReset)
        
        this.onActivity('message', this.handleDefault)
        this.onConversationUpdate('membersAdded', this.handleWelcome)
    }
    
    handleHelp = async (context, state) => {
        const helpText = `
                Available commands:
                - /help - Show this help message
                - /status - Show current status
                - /reset - Reset conversation state
        `
        await context.sendActivity(MessageFactory.text(helpText))
    }
    
    handleStatus = async (context, state) => {
        const messageCount = state.conversation.messageCount ?? 0
        await context.sendActivity(`Messages processed: ${messageCount}`)
    }
    
    handleReset = async (context, state) => {
        state.deleteConversationState()
        await context.sendActivity('Conversation state has been reset.')
    }
    
    handleWelcome = async (context, state) => {
        const welcomeText = 'Welcome! Type /help to see available commands.'
        await context.sendActivity(MessageFactory.text(welcomeText))
    }
    
    handleDefault = async (context, state) => {
        // Increment message counter
        const messageCount = (state.conversation.messageCount ?? 0) + 1
        state.conversation.messageCount = messageCount
        
        const replyText = `Echo: ${context.activity.text} (Message #${messageCount})`
        await context.sendActivity(MessageFactory.text(replyText))
    }
}

export default new MyAgent()

Bu kalıbın avantajları

Kazanç Açıklama
Daha iyi düzen Farklı işleyiciler için ayrı yöntemler
Yeniden Kullanılabilirlik Kolayca genişletilebilir veya daha fazla devralınabilir
Test edilebilirlik Yöntemler ayrı ayrı birim testine tabi tutulabilir
Maintainability Karmaşık botlar için daha temiz kod yapısı
Ok işlevleri this gerekmeden .bind() bağlamını otomatik olarak bağlama

İlgili İçerik

  • Last updated on