Etkinlik Protokollerini Anlama

Etkinlik protokolü, microsoft genelinde birçok Microsoft SDK'sında, hizmetlerinde ve istemcilerinde kullanılan iletişim protokolü ve standart protokoldür. Buna Microsoft 365 Copilot, Microsoft Copilot Studio ve Microsoft 365 Aracıları SDK'sı dahildir. Etkinlik protokolü, bir Activity öğesinin şeklini ve iletilerin, olayların ve etkileşimlerin kanaldan, kodunuzla aradaki diğer her yere nasıl aktığını tanımlar. Aracılar, kullanıcılarla etkileşim kurmak ve diğer aracılarla çalışmak için bir veya daha fazla kanala bağlanabilir. Etkinlik protokolü, Microsoft ve üçüncü taraf istemciler de dahil olmak üzere çalıştığınız tüm istemciler arasındaki iletişim protokolünü standartlaştırdığından, çalıştığınız kanal başına özel mantık oluşturmanız gerekmez.

Etkinlik nedir?

, Activity bir kullanıcı ile aracınız arasındaki tüm etkileşimleri temsil eden yapılandırılmış bir JSON nesnesidir. Etkinlikler yalnızca metin tabanlı iletiler değildir; birden çok kullanıcıyı destekleyen istemciler için bir kullanıcının katılması veya ayrılması, yazma göstergeleri, dosya yüklemeleri, kart eylemleri ve geliştiricilerin kendilerini tasarladıkları özel olaylar gibi çeşitli etkileşim türlerini içerebilir.

Her etkinlik aşağıdakiler hakkında meta veriler içerir:

Kim gönderdi (kimden)
Bunu kim almalıdır (alıcı)
Konuşma bağlamı
Kaynaklandığı kanal
Etkileşim türü
Yük verileri

Etkinlik şeması - anahtar özellikleri

Bu belirtim, Etkinlik protokolü: Etkinlik protokolü - Etkinlik'i tanımlar. Etkinlik protokolünde tanımlanan temel özelliklerden bazıları şunlardır:

Mülkiyet	Description
`Id`	Genellikle bir kanaldan geliyorsa kanal tarafından oluşturulur
`Type`	Tür, bir etkinliğin anlamını denetler, örneğin ileti türü
`ChannelID`	`ChannelID` etkinliğin kaynaklandığı kanala referans verir. Örneğin: `msteams`.
`From`	Etkinliğin göndereni (kullanıcı veya aracı olabilir)
`Recipient`	Etkinliğin hedeflenen alıcısı
`Text`	İletinin metin içeriği
`Attachment`	Kartlar, dosya görüntüleri gibi zengin içerik

Etkinlik Verilerine Erişme

Geliştiricilerin, TurnContext nesnesinden eylemleri tamamlamak için etkinlik içindeki verilere erişmesi gerekir.

Microsoft 365 Agents SDK'sının her dil sürümünde bir TurnContext sınıf bulabilirsiniz:

.NET: TurnContext
Python: TurnContext
JavaScript: TurnContext

Uyarı

Bu makaledeki kod parçacıkları C# kullanır. JavaScript ve Python sürümleri için söz dizimi ve API yapısı benzerdir.

TurnContext, Microsoft 365 Aracıları SDK'sı içindeki her konuşmada kullanılan önemli bir nesnedir. Gelen etkinliğe, yanıt gönderme yöntemlerine, konuşma durumu yönetimine ve tek bir konuşma turunu işlemek için gereken bağlama erişim sağlar. Bağlamı korumak, uygun yanıtlar göndermek ve kullanıcılarınızla istemcilerinde/kanallarında etkili bir şekilde etkileşimde olmak için kullanılır. Aracınız bir kanaldan her yeni etkinlik aldığında Aracılar SDK'sı yeni TurnContext bir örnek oluşturur ve bunu kayıtlı işleyicilerinize/yöntemlerinize geçirir. Bu bağlam nesnesi tek dönüş sırasında bulunur ve dönüş sona erdikten sonra atılır.

Dönüş, istemciden gönderilen bir mesajın kodunuza yolculuk yapması ve kodunuzun bu verileri işlemesi olarak tanımlanır. Kodunuz isteğe bağlı olarak dönüşü tamamlamak için bir yanıt gönderebilir. Bu gidiş dönüş şu şekilde bölünebilir:

Gelen Etkinlik: Kullanıcı bir ileti gönderir veya etkinlik oluşturan bir eylem gerçekleştirir.
Kodunuz etkinliği alır ve etmen bunu TurnContext kullanarak işler.
Ajanınız bir veya daha fazla etkinliği geri gönderir.
Dönüş biter ve TurnContext atılır.

TurnContext gibi uygulamalardan verilere erişin, örneğin:

var messageText = turnContext.Activity.Text
var channelID = turnContext.Activity.ChannelId

Bu kod parçacığı tam dönüş örneği gösterir:

agent.OnActivity(ActivityTypes.Message, async (turnContext, turnState, cancellationToken) =>
{
    var userMessage = turnContext.Activity.Text'
    var response = $"you said: {userMessage}";
    await turnContext.SendActivityAsync(MessageFactory.Text(response), cancellationToken);
});

sınıfının içinde TurnContext yaygın olarak kullanılan anahtar bilgileri şunları içerir:

Etkinlik: Etkinlikten bilgi edinmenin ana yolu
Bağdaştırıcı: Etkinliği oluşturan kanal bağdaştırıcısı
TurnState: Dönüş durumu

Etkinlik türleri

Bir etkinliğin türü, istemciler, kullanıcılar ve aracılar arasındaki etkinliğin geri kalanında nelerin gerekli olduğunu veya beklendiğini tanımladığı için önemlidir.

Message

Yaygın bir etkinlik türü, metin, ekler ve bu tür için birkaç yaygın kullanımı adlandırmak için önerilen eylemleri içerebilen İleti türüdür Activity.

agent.OnActivity(ActivityTypes.Message, async (turnContext, turnState, cancellationToken) =>
{
    var userMessage = turnContext.Activity.Text'
    var response = $"you said: {userMessage}";
    await turnContext.SendActivityAsync(MessageFactory.Text(response), cancellationToken);
});

SohbetGüncellemesi

ConversationUpdate türü, üyeler bir konuşmaya katıldığında veya konuşmadan ayrıldığında aracınızı bilgilendirir. Tüm istemciler bunu desteklemez; önemli bir istemci Microsoft Teams'dir.

Aşağıdaki kod parçacığı bir konuşmada yeni üyeleri karşılar:

agent.OnActivity(ActivityTypes.ConversationUpdate, async (turnContext turnState, cancellationToken) =>
{
    var membersAdded = turnContext.Activity.MembersAdded
    if (membersAdded != null)
    {
        foreach (var member in membersAdded)
        {
            if (member.Id != turnContext.Activity.Reciepient.Id)
            {
                await turnContext.SendActivityAsync(MessageFactory.Text($"Welcome {member.Name}!"), cancellationToken);
            }
        }
    }
})

Events

Olay türüActivity, kanalların veya istemcilerin aracınıza yapılandırılmış veriler göndermesine olanak tanıyan ve yük yapısında Activity önceden tanımlanmış olmayan özel olaylardır.

Belirli Event bir tür için bir yöntem/yol işleyicisi oluşturmanız ve ardından aşağıdakilere göre istenen mantığı yönetmeniz gerekir:

Ad - Olay adı veya istemciden gelen tanımlayıcı Değer - Genellikle bir JSON nesnesi olan olay yükü

agent.OnActivity(ActivityTypes.Event, async (turnContext turnState, cancellationToken) =>)
{
    var eventName = turnContext.Activity.Name
    var eventValue = turnContext.Activity.Value

    // custom event (E.g. a switch on eventName)
}

Invoke

Invoke türüActivity, istemcinin yalnızca bir ileti değil, komut veya işlem gerçekleştirmek için aracıya çağırdığı belirli bir etkinlik türüdür. Bu tür etkinliklerin örnekleri task/fetch ve task/submit için Microsoft Teams'de yaygındır. Tüm kanallar bu tür etkinlikleri desteklemez.

Yazma

Yazma şeklindeki bir tür, birinin sohbet sırasında yazdığını belirten bir faaliyet sınıflandırmasıdır. Bu, örneğin Microsoft Teams istemcisinde insandan insana yapılan konuşmalar arasında yaygın olarak görülür. Yazma etkinlikleri her istemcide desteklenmez ve özellikle Microsoft 365 Copilot yazma etkinliklerini desteklemez.

await turnContext.SendActivityAsync(new Activity { Type = ActivityTypes.Typing }, cancellationToken); 
await Task.Delay(2000);
await turnContext.SendActivityAsync(MessageFactory.Text("Here is your answer..."), cancellationToken)

Etkinlik oluşturma ve gönderme

'TurnContext' yanıt göndermek için kullanıcıya yanıt göndermek için birden çok yöntem sağlar.

agent.OnActivity(ActivityTypes.Message, async (turnContext, turnState, cancellationToken))
{
    await turnContext.SendActivityAsync("hello!", cancellationToken: CancellationToken) // uses string directly
    await turnContext.SendActivityAsync(MessageFactory.Text("Hello"), cancellationToken) // uses Message Factory
    await turnContext.SendActivitiesAsync(activities, cancellationToken) // send multiple activities in an Activity array
}

Eklerle çalışma

Aracıların, kullanıcılar (hatta diğer aracılar) tarafından gönderilen eklerle çalışması yaygındır. İstemci ek içeren bir Message etkinlik gönderir (belirli bir etkinlik türü değildir) ve kodunuzun eki içeren iletiyi almayı işlemesi, meta verileri okuması ve dosyayı istemcinin sağladığı URL'den güvenli bir şekilde getirmesi gerekir. Daha sonra dosyayı kendi depolama alanınıza taşımak normaldir.

Ek almak için

Aşağıdaki kod, nasıl alınıp ek yapılacağını gösterir

agent.OnActivity(ActivityTypes.Message, async(turnContext, turnState, cancellationToken)) =>
{
    var activity = turnContext.Activity;
    if (activity.Attachments != null && activity.Attachments.Count >0)
    {
        foreach (var attachment in activity.Attachments)
        {
            // get metadata as required e.g. attachment.ContextType or attachment.ContentUrl
            // use the URL to securely download the attachment and complete your business logic
        }
    }
}

Genellikle, ekteki belgeyi almak için istemci, gerçek içeriği almak üzere kimliği doğrulanmış GET bir istek gönderir; her bağdaştırıcının bu verileri elde etme yöntemi farklıdır, örneğin Teams, OneDrive gibi. Bu URL'lerin genellikle kısa ömürlü olduğunu bilmek de önemlidir ve bu nedenle orada kalacaklarını varsaymayın; bu nedenle daha sonra başvurmanız gerekirse kendi depolama alanınıza geçmeniz önemlidir.

Alıntı

Ek ve Alıntı'nın aynı nesne türü olmadığını bilmeniz önemlidir. Alıntılar, Microsoft Teams gibi İstemciler tarafından kendi yöntemleriyle işlenir ve 'ün Activity özelliğini kullanır ve activity.Entities.Add ile eklenebilir ve istemcinize bağlı olarak belirli Entity tanımına sahip yeni bir Citation nesnesi ekleyebilirsiniz. İstemcinin istemcide nasıl işlendiğini temel alarak seri durumdan çıkardığı bir JSON nesnesi olarak seri hale getirilir. Temel olarak, Ekler mesajlardır ve Alıntılar eklere başvurabilir ve Entities yükünün Activity'inde gönderilen başka bir nesnedir.

Kanala özgü dikkat edilmesi gerekenler

Microsoft 365 Aracıları SDK'sı, geliştiricilerin desteklediğimiz istemciler de dahil olmak üzere herhangi bir istemciyle çalışabilecek aracılar oluşturmasına ve geliştiricilerin aynı çerçeveyi kullanarak kendi kanal bağdaştırıcılarını oluşturmasına yönelik araçlar sağlamasına olanak tanıyan bir 'Hub' olarak oluşturulur. Bu, geliştiricilere ajanlar konusunda geniş bir yelpaze sunar ve istemcilere, Microsoft Teams, Slack ve benzerleri gibi bir veya birden çok istemciyi bu hub'a bağlayarak genişletilebilirlik imkanı sağlar.

Farklı kanalların farklı özellikleri ve sınırlamaları vardır ve aşağıdakiler ortak istemcilerle çalışırken dikkat edilmesi gereken noktaların bir özetidir.

Aldığınız etkinliğin kanalını, channelId içindeki Activity özelliğini inceleyerek kontrol edebilirsiniz.

Kanallar, tüm kanallarda genel Activity yüke uymayan belirli veri içerir ve bu verilere TurnContext'in Activity.ChannelData'sinden erişilebilir. Daha sonra kodunuzda kullanmak için özel olarak değişkenlere dönüştürün.

Microsoft Ekipleri

Gelişmiş özelliklere sahip zengin Uyarlamalı Kartları destekler
İleti güncelleştirmelerini ve silmeleri destekler
Teams özellikleri (bahsetmeler, toplantı bilgileri vb.) için belirli kanal verilerine sahiptir
Görev modülleri için çağırma etkinliklerini destekler

Microsoft 365 Copilot

Öncelikli olarak ileti etkinliklerine odaklanmış
Yanıtlarda alıntıları ve referansları destekler
Akış yanıtları gerektirir
Zengin kartlar/uyarlamalı kartlar için sınırlı destek

WebChat/DirectLine

Web Sohbeti, aracıların HTTPS üzerinden konuşmaları için kullanılan bir HTTP protokolüdür

Tüm etkinlik türleri için tam destek
Özel kanal verilerini destekler

Üçüncü taraf kanallar

Bunlar Slack, Facebook ve daha fazlasını içerir.

Belirli etkinlik türleri için sınırlı desteğe sahip olabilir
Kart işleme farklı veya desteklenmiyor olabilir
Belirli kanal belgelerini her zaman kontrol edin

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2025-10-21