Etkinlik Protokollerini Anlama

Etkinlik Protokolü, birçok Microsoft SDK'sında, hizmetinde ve istemcisinde kullanılan bir standart iletişim protokolüdür. Etkinlik Protokolü Microsoft 365 Copilot, Microsoft Copilot Studio ve Microsoft 365 Aracıları SDK'sı tarafından kullanılır. Etkinlik Protokolü, bir Activity öğesinin yapısını ve iletilerin, olayların ve etkileşimlerin bir 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 Microsoft olmayan istemciler de dahil olmak üzere çalıştığınız tüm istemcilerle iletişim protokollerini standartlaştırır, böylece her kanal için ö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 metin tabanlı iletilerde sınırlı değildir. Bunlar, birden çok kullanıcıyı destekleyen istemciler için bir kullanıcının katılması veya ayrılması gibi olaylar, yazma göstergeleri, dosya yüklemeleri, kart eylemleri ve geliştiricilerin 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:

Özellik	Açıklama
`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

Nesneden eylemleri tamamlamak için geliştiricilerin TurnContext etkinlik içindeki verilere erişmesi gerekir.

Microsoft 365 Aracıları SDK'sı'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ı'de her konuşma turunda 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ız ile istemcilerinde veya kanallarında etkili bir şekilde etkileşimde olmak için bunu kullanın. 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 veya yöntemlerinize geçirir. Bu bağlam nesnesi tek dönüş sırasında bulunur ve dönüş sona erdikten sonra atılır.

Tur, istemciden gönderilen bir iletinin sizin kodunuza kadar olan gidiş dönüşü olarak tanımlanır. Kodunuz bu verileri işler ve isteğe bağlı olarak dönüşü tamamlamak için geri bir yanıt gönderebilir. Bu gidiş dönüş aşağıdaki adımlara ayrılabilir:

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

Etkinliğin türü, etkinliğin geri kalanının istemciler, kullanıcılar ve aracılar arasında ne gerektirdiğini veya beklediğini tanımlar.

Bunlar şunları içerir:

İleti
SohbetGüncellemesi
Etkinlik
Çağır
Yazma

İleti

Yaygın bir etkinlik türü, İleti türüdür Activity. Bu Activity tür metin, ekler ve önerilen eylemleri içerebilir.

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 bu bildirimi desteklemez, ancak Microsoft Teams destekler.

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.Recipient.Id)
            {
                await turnContext.SendActivityAsync(MessageFactory.Text($"Welcome {member.Name}!"), cancellationToken);
            }
        }
    }
})

Olaylar

Olay türü, kanallar veya istemcilerin aracınıza yapılandırılmış veri göndermek için kullandığı özel bir olaydır. Bu veriler yük yapısında Activity önceden tanımlanmış değildir.

Belirli Event bir tür için bir yöntem veya yol işleyicisi oluşturmanız gerekir. Ardından, aşağıdakilere göre istediğiniz mantığı yönetin:

Ad: İstemcinin olay adı veya tanımlayıcısı
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)
});

Çağır

Invoke türüActivity, istemcinin bir komut veya işlem gerçekleştirmek için aracıya çağırdığı belirli bir etkinlik türüdür. Bu sadece bir mesaj değil. 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 etkinlik, örneğin Microsoft Teams istemcide insandan insana yapılan konuşmalar arasında yaygın olarak görülür. Yazma etkinlikleri her istemcide desteklenmez. Ö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

Yanıt göndermek için, TurnContext 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 genellikle kullanıcıların (hatta diğer aracıların) gönderdiği eklerle çalışır. İstemci ek içeren bir Message etkinlik gönderir (belirli bir etkinlik türü değildir). Kodunuzun eki içeren iletiyi almayı işlemesi, meta verileri okuması ve dosyayı istemcinin sağladığı URL'den güvenli bir şekilde getirmesi gerekir. Genellikle, dosyayı kendi depolama alanınıza taşırsınız.

Ek almak için

Aşağıdaki kod, bir ek dosyasının nasıl alınacağını göstermektedir.

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

Ekteki belgeyi almak için, istemci genellikle gerçek içeriği almak üzere kimliği doğrulanmış bir GET istek gönderir. Her bağdaştırıcının bu verileri almak için kendi yolu vardır. Örneğin, Teams, OneDrive vb. Bu URL'lerin genellikle kısa ömürlü olduğunu bilmek de önemlidir ve bu nedenle URL'lerin uzun süre geçerli kaldığını varsaymayın. Bu sınırlama, içeriği daha sonra başvurmanız gerekiyorsa kendi depolama alanınıza geçmenin önemli olmasının nedenidir.

Alıntılar

Ek ve Alıntı'nın aynı nesne türü olmadığını bilmeniz önemlidir. Microsoft Teams gibi istemciler alıntıları kendi yöntemleriyle işler. Entities özelliğiniActivitykullanırlar. Siz activity.Entities.Add ile alıntılar ekleyebilir ve istemcinize dayalı belirli bir Entity tanımına sahip yeni bir Citation nesne ekleyebilirsiniz. İstemcinin istemcide nasıl işlendiğini temel alarak seri durumdan çıkardığı bir JSON nesnesi olarak seri hâle getirilir. Temel olarak, Ekler mesajlardır ve Alıntılar eklere başvurabilir ve Activity yükünün Entities'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 any istemcisiyle çalışabilen aracılar oluşturmak için kullandığı bir 'Hub' olarak oluşturulur. Geliştiricilerin aynı çerçeveyi kullanarak kendi kanal bağdaştırıcılarını oluşturmaları için araçlar sağlar. Bu mimari, geliştiricilere aracılar konusunda geniş seçenekler sunar ve istemcilere bu hub'a bağlanmaları için genişletilebilirlik sunar; bu da Microsoft Teams, Slack ve benzeri gibi bir veya birden fazla istemci olabilir.

Farklı kanalların farklı özellikleri ve sınırlamaları vardır.

Etkinliği aldığınız kanalı, Activity içindeki channelId özelliğini inceleyerek denetleyebilirsiniz.

Kanallar, tüm kanallardaki genel Activity yüke uymayan belirli veriler içerir. Bu verilere, kodunuzda kullanmak üzere değişkenlere dönüştürerek özelliğinden TurnContext.[Activity.ChannelData](/dotnet/api/microsoft.agents.core.models.activity.channeldata) erişebilirsiniz.

Aşağıdaki bölümlerde ortak istemcilerle çalışırken dikkat edilmesi gerekenler özetlenmektedir.

Microsoft Ekipleri

Gelişmiş özelliklerle zengin Uyarlamalı Kartlar desteği sağlar.
İleti güncelleştirmelerini ve silmeleri destekler.
Teams özellikleri için, bahsetmeler ve toplantı bilgileri gibi belirli kanallara ait verileri içerir.
Görev modülleri için çağırma etkinliklerini destekler.

Microsoft 365 Copilot

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

Web Sohbeti/DirectLine

Web Sohbeti, aracıların HTTPS üzerinden iletişim kurmak için kullanabileceği bir HTTP protokolüdür.

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

Microsoft olmayan kanallar

Bu kanallar 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.
Her zaman belirli kanal belgelerini kontrol edin.

Sonraki Adımlar

AgentApplication hakkında bilgi edinin

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-04-29