Aracılığıyla paylaş

Bot Framework SDK'sı ile medya ekleri gönderme

AŞAĞIDAKİLER İÇİN GEÇERLİDİR: SDK v4

Kullanıcı ve bot arasında alışveriş yapılan iletiler görüntü, video, ses ve dosyalar gibi medya ekleri içerebilir. Bot Framework SDK'sı, kullanıcıya zengin iletiler gönderme görevini destekler. Bir kanalın (Facebook, Slack vb.) desteklediği zengin iletilerin türünü belirlemek için sınırlamalar hakkında bilgi için kanalın belgelerine bakın.

Not

Yapay zeka hizmetleri, düzenleme ve bilgi seçiminizle aracılar oluşturmak için Microsoft 365 Aracıları SDK'sını kullanmayı göz önünde bulundurun. Aracılar SDK'sı C#, JavaScript veya Python desteğine sahiptir. SDK hakkında daha fazla bilgiyi aka.ms/agents adresinde bulabilirsiniz. SaaS tabanlı bir aracı platformu arıyorsanız Microsoft Copilot Studio'yu göz önünde bulundurun. Bot Framework SDK'sı ile oluşturulmuş mevcut bir botunuz varsa botunuzu Aracılar SDK'sına güncelleştirebilirsiniz. Bot Framework SDK'sını Aracılar SDK'sına geçirme kılavuzunda temel değişiklikleri ve güncelleştirmeleri gözden geçirebilirsiniz. Bot Framework SDK'sı için destek biletleri artık 31 Aralık 2025 itibarıyla hizmet verilmeyecektir.

Önkoşullar

Ekleri gönderme

Kullanıcıya resim veya video gibi içerik göndermek için iletiye ek veya ek listesi ekleyebilirsiniz.

Kullanılabilir kart örnekleri için bkz . Kullanıcı deneyimini tasarlama.

Ayrıca SSS bölümünde Kanallar kullanılarak aktarılan bir dosyanın boyut sınırı nedir? konusuna bakın.

Bu bölümde gösterilen tüm kaynak kodu, Ekleri işleme örneğini temel alır .

Attachments nesnesinin Activity özelliği, iletiye eklenmiş medya eklerini ve zengin kartları temsil eden Attachment nesneleri içeren bir dizi içerir. İletiye medya eki eklemek için etkinlik için bir Attachment nesne oluşturun ve , replyve ContentType özelliklerini ayarlayınContentUrl.Name

Yanıt iletisini oluşturmak için metni tanımlayın ve ekleri ayarlayın. Eklerin yanıta atanma işlemi her ek türü için aynıdır, ancak aşağıdaki kod parçacıklarında görüldüğü gibi çeşitli ekler farklı şekilde ayarlanır ve tanımlanır. Aşağıdaki kod, satır içi ek dosya için yanıtı hazırlıyor.

Botlar/AttachmentsBot.cs

{
    reply = MessageFactory.Text("This is an inline attachment.");

Ardından, eklerin türlerine bakacağız. İlk ek dosya satır içidir:

Botlar/AttachmentsBot.cs

{
    var imagePath = Path.Combine(Environment.CurrentDirectory, @"Resources", "architecture-resize.png");
    var imageData = Convert.ToBase64String(File.ReadAllBytes(imagePath));

    return new Attachment
    {
        Name = @"Resources\architecture-resize.png",
        ContentType = "image/png",
        ContentUrl = $"data:image/png;base64,{imageData}",
    };
}

Ardından, karşıya yüklenmiş bir ek dosya:

Botlar/AttachmentsBot.cs

{
    if (string.IsNullOrWhiteSpace(serviceUrl))
    {
        throw new ArgumentNullException(nameof(serviceUrl));
    }

    if (string.IsNullOrWhiteSpace(conversationId))
    {
        throw new ArgumentNullException(nameof(conversationId));
    }

    var imagePath = Path.Combine(Environment.CurrentDirectory, @"Resources", "architecture-resize.png");

    var connector = turnContext.TurnState.Get<IConnectorClient>() as ConnectorClient;
    var attachments = new Attachments(connector);
    var response = await attachments.Client.Conversations.UploadAttachmentAsync(
        conversationId,
        new AttachmentData
        {
            Name = @"Resources\architecture-resize.png",
            OriginalBase64 = File.ReadAllBytes(imagePath),
            Type = "image/png",
        },
        cancellationToken);

    var attachmentUri = attachments.GetAttachmentUri(response.Id);

    return new Attachment
    {
        Name = @"Resources\architecture-resize.png",
        ContentType = "image/png",
        ContentUrl = attachmentUri,
    };
}

Son olarak, bir internet eki:

Botlar/AttachmentsBot.cs

    {
        // ContentUrl must be HTTPS.
        return new Attachment
        {
            Name = @"Resources\architecture-resize.png",
            ContentType = "image/png",
            ContentUrl = "https://docs.microsoft.com/en-us/bot-framework/media/how-it-works/architecture-resize.png",
        };
    }
}

Bir ek bir görüntü, ses veya video ise Bağlayıcı hizmeti, ek verilerini kanalın bu eki konuşma içinde sunabilmesini sağlayacak şekilde kanala iletir. Ek bir dosyaysa, dosya URL'si konuşmanın içinde köprü olarak işlenir.

Kahraman kartı gönderme

Basit görüntü veya video eklerinin yanı sıra, görüntüleri ve düğmeleri tek bir nesnede birleştirmenizi ve kullanıcıya göndermenizi sağlayan bir hero kartı ekleyebilirsiniz. Markdown çoğu metin alanında desteklenir, ancak destek kanala göre farklılık gösterebilir.

Hero kartı ve düğmesiyle ileti oluşturmak için, iletiye nesne HeroCard ekleyebilirsiniz.

Aşağıdaki kaynak kodu Ekleri işleme örneğinden alınmalıdır .

Botlar/AttachmentsBot.cs


      private static async Task DisplayOptionsAsync(ITurnContext turnContext, CancellationToken cancellationToken)
      {
          // Create a HeroCard with options for the user to interact with the bot.
          var card = new HeroCard
          {
              Text = "You can upload an image or select one of the following choices",
              Buttons = new List<CardAction>
              {
                  // Note that some channels require different values to be used in order to get buttons to display text.
                  // In this code the emulator is accounted for with the 'title' parameter, but in other channels you may
                  // need to provide a value for other parameters like 'text' or 'displayText'.
                  new CardAction(ActionTypes.ImBack, title: "1. Inline Attachment", value: "1"),
                  new CardAction(ActionTypes.ImBack, title: "2. Internet Attachment", value: "2"),
                  new CardAction(ActionTypes.ImBack, title: "3. Uploaded Attachment", value: "3"),
              },
          };

          var reply = MessageFactory.Attachment(card.ToAttachment());
          await turnContext.SendActivityAsync(reply, cancellationToken);

Zengin içerikli kartlar üzerinde olayları işleme

Zengin kartlar içindeki olayları işlemek için, kullanıcı bir düğme seçtiğinde veya kartın bir bölümüne dokunduğunda ne olacağını belirtmek için kart eylem nesnelerini kullanın. Her kart eyleminin bir tür ve değer özelliği vardır.

Düzgün çalışması için, bir hero kartındaki her tıklanabilir öğeye bir eylem türü atayın. Bu tabloda kullanılabilir eylem türleri ve ilişkili değer özelliğinde olması gerekenler listelenip açıklanmaktadır.

Kart messageBack eylemi, diğer kart eylemlerinden daha genelleştirilmiş bir anlama sahiptir. ve diğer kart eylem türleri hakkında daha fazla bilgi için Etkinlik şemasınınbakın.

Türü Açıklama Değer
arama Bir telefon araması başlatır. Telefon görüşmesinin hedefi bu biçimdedir: tel:123123123123.
Dosyayı İndir Bir dosya indirir. İndirilmesi gereken dosyanın URL'si.
imBack Bota bir ileti gönderir ve sohbette görünür bir yanıt gönderir. Gönderilecek iletinin metni.
mesaj geri gönder Sohbet sistemi aracılığıyla gönderilecek metin yanıtını temsil eder. Oluşturulan iletilere eklenecek isteğe bağlı bir program değeri.
URL'yi Aç Yerleşik tarayıcıda bir URL açar. Açılacak URL.
playAudio Ses dosyasını çalar. Çalınacak sesin URL'si.
videoOynat Video oynatır. Yürütülecek videonun URL'si.
geri gönderim Bota bir ileti gönderir ve sohbette görünür bir yanıt göndermeyebilir. Gönderilecek iletinin metni.
GörselGörüntüle Bir görüntü gösterir. Görüntülenecek görüntünün URL'si.
oturum açma OAuth oturum açma işlemini başlatır. Başlatılacak OAuth akışının URL'si.

Çeşitli olay türlerini kullanan Hero kartı

Aşağıdaki kod, çeşitli zengin kart olaylarının kullanıldığı örnekleri gösterir.

Tüm mevcut kartlara ait örnekler için, Kartları Kullanma örneğine bakın.

Cards.cs

public static HeroCard GetHeroCard()
{
    var heroCard = new HeroCard
    {
        Title = "BotFramework Hero Card",
        Subtitle = "Microsoft Bot Framework",
        Text = "Build and connect intelligent bots to interact with your users naturally wherever they are," +
               " from text/sms to Skype, Slack, Office 365 mail and other popular services.",
        Images = new List<CardImage> { new CardImage("https://sec.ch9.ms/ch9/7ff5/e07cfef0-aa3b-40bb-9baa-7c9ef8ff7ff5/buildreactionbotframework_960.jpg") },
        Buttons = new List<CardAction> { new CardAction(ActionTypes.OpenUrl, "Get Started", value: "https://docs.microsoft.com/bot-framework") },
    };

    return heroCard;
}

Cards.cs

public static SigninCard GetSigninCard()
{
    var signinCard = new SigninCard
    {
        Text = "BotFramework Sign-in Card",
        Buttons = new List<CardAction> { new CardAction(ActionTypes.Signin, "Sign-in", value: "https://login.microsoftonline.com/") },
    };

    return signinCard;
}

Uyarlamalı Kart Gönderme

İleti fabrikasını kullanarak ek içeren bir ileti (herhangi bir türde) oluşturabilirsiniz ancak Uyarlamalı Kart belirli bir ek türüdür. Tüm kanallar Uyarlamalı Kartları desteklemez ve bazı kanallar Uyarlamalı Kartları yalnızca kısmen destekleyemeyebilir. Örneğin, Facebook'ta Uyarlamalı Kart gönderirseniz, metinler ve resimler düzgün çalışırken düğmeler çalışmaz. İleti fabrikası, oluşturma adımlarını sizin için otomatikleştirmek için kullanılan bir Bot Framework SDK yardımcı sınıfıdır.

Uyarlamalı Kartlar, geliştiricilerin kullanıcı arabirimi içeriğini ortak ve tutarlı bir şekilde paylaşmalarını sağlayan açık bir kart değişim biçimidir. Ancak, tüm kanallar Uyarlamalı Kartları desteklemez.

Uyarlamalı Kartlar Tasarımcısı, uyarlamalı kartlar yazmak için zengin, etkileşimli bir tasarım zamanı deneyimi sağlar.

Not

Bu özelliği botunuzun uyarlamalı kartları destekleyip desteklemediğini belirlemek için botunuzun kullanacağı kanallarla test etmelisiniz.

Uyarlamalı Kartlar'ı kullanmak için NuGet paketini eklediğinizden AdaptiveCards emin olun.

Aşağıdaki kaynak kodu, Kartları kullanma örneğinden alınmalıdır .

Cards.cs

Bu örnek, uyarlamalı kart JSON dosyasını bir dosyadan okur ve ek olarak ekler.

public static Attachment CreateAdaptiveCardAttachment()
{
    // combine path for cross platform support
    var paths = new[] { ".", "Resources", "adaptiveCard.json" };
    var adaptiveCardJson = File.ReadAllText(Path.Combine(paths));

    var adaptiveCardAttachment = new Attachment()
    {
        ContentType = "application/vnd.microsoft.card.adaptive",
        Content = JsonConvert.DeserializeObject(adaptiveCardJson),
    };

    return adaptiveCardAttachment;
}

İletiler, ekleri yan yana yerleştirip kullanıcının kaydırmasına olanak tanıyan karusel düzeninde birden çok ek de içerebilir.

Aşağıdaki kaynak kodu, Kartları kullanma örneğinden alınmalıdır .

Diyaloglar/MainDialog.cs

İlk olarak yanıtı oluşturun ve ekleri liste olarak tanımlayın.

// Cards are sent as Attachments in the Bot Framework.
// So we need to create a list of attachments for the reply activity.
var attachments = new List<Attachment>();

// Reply to the activity we received with an activity.
var reply = MessageFactory.Attachment(attachments);

Ardından ekleri ekleyin ve düzen türünü döngü olarak ayarlayın. Burada bunları birer birer ekliyoruz, ancak istediğiniz gibi kartları eklemek için listeyi değiştirmekte çekinmeyin.

// Display a carousel of all the rich card types.
reply.AttachmentLayout = AttachmentLayoutTypes.Carousel;
reply.Attachments.Add(Cards.CreateAdaptiveCardAttachment());
reply.Attachments.Add(Cards.GetAnimationCard().ToAttachment());
reply.Attachments.Add(Cards.GetAudioCard().ToAttachment());
reply.Attachments.Add(Cards.GetHeroCard().ToAttachment());
reply.Attachments.Add(Cards.GetOAuthCard().ToAttachment());
reply.Attachments.Add(Cards.GetReceiptCard().ToAttachment());
reply.Attachments.Add(Cards.GetSigninCard().ToAttachment());
reply.Attachments.Add(Cards.GetThumbnailCard().ToAttachment());
reply.Attachments.Add(Cards.GetVideoCard().ToAttachment());

Ekler eklendikten sonra, yanıtı diğer tüm yanıtlar gibi gönderebilirsiniz.

// Send the card(s) to the user as an attachment to the activity
await stepContext.Context.SendActivityAsync(reply, cancellationToken);

Uyarlamalı Kart girişini işlemek için kod örneği

Aşağıdaki örnekte, bot iletişim kutusunda Uyarlamalı Kart girişlerini kullanmanın bir yolu gösterilmektedir. Yanıt veren istemcinin metin alanında sağladığı girişi doğrulayarak kahraman kartları örneğini genişletir. İlk olarak, kaynaklar klasöründe bulunan adaptiveCard.json dosyasının son köşeli ayracından hemen önce aşağıdaki kodu ekleyerek mevcut uyarlamalı karta metin girişi ve düğme işlevselliğini eklemeniz gerekir.

"actions": [
  {
    "type": "Action.ShowCard",
    "title": "Text",
    "card": {
      "type": "AdaptiveCard",
      "body": [
        {
          "type": "Input.Text",
          "id": "text",
          "isMultiline": true,
          "placeholder": "Enter your comment"
        }
      ],
      "actions": [
        {
          "type": "Action.Submit",
          "title": "OK"
        }
      ]
    }
  }
]

Metin giriş alanının kimliği "text" olarak ayarlanır. Kullanıcı OK'yi seçtiğinde, Uyarlamalı Kart'ın oluşturduğu ileti, kartın metin girişi alanına kullanıcının girdiği bilgileri içeren ve adı olan bir özelliğe sahip bir text özelliğine sahip olur.

Doğrulayıcımız Newtonsoft.json kullanarak bunu önce bir JObject'ya dönüştürür ve ardından karşılaştırma için kırpılmış bir metin dizesi oluşturur. Bu nedenle ekleyin:

using System;
using System.Linq;
using Newtonsoft.Json.Linq;

MainDialog.cs'ye gidin ve Newtonsoft.Json'un en son kararlı NuGet paketini yükleyin. Doğrulayıcı kodunda, kod açıklamalarına mantıksal akışı ekledik. Bu ChoiceValidator yöntem, MainDialog bildiriminde kapalı küme ayracından sonra, Using cards örneğine yerleştirilir.

private async Task ChoiceValidator(
    PromptValidatorContext promptContext,
    CancellationToken cancellationToken)
{
    // Retrieves Adaptive Card comment text as JObject.
    // looks for JObject field "text" and converts that input into a trimmed text string.
    var jobject = promptContext.Context.Activity.Value as JObject;
    var jtoken = jobject?["text"];
    var text = jtoken?.Value().Trim();

    // Logic: 1. if succeeded = true, just return promptContext
    //        2. if false, see if JObject contained Adaptive Card input.
    //               No = (bad input) return promptContext
    //               Yes = update Value field with JObject text string, return "true".
    if (!promptContext.Recognized.Succeeded && text != null)
    {
        var choice = promptContext.Options.Choices.FirstOrDefault(
        c => c.Value.Equals(text, StringComparison.InvariantCultureIgnoreCase));
        if (choice != null)
        {
            promptContext.Recognized.Value = new FoundChoice
            {
                Value = choice.Value,
            };
            return true;
        }
    }
    return promptContext.Recognized.Succeeded;
}

Şimdi yukarıda MainDialog bildiriminde değişiklik yapın:

// Define the main dialog and its related components.
AddDialog(new ChoicePrompt(nameof(ChoicePrompt)));

yerine şunu yazın:

// Define the main dialog and its related components.
AddDialog(new ChoicePrompt(nameof(ChoicePrompt), ChoiceValidator));

Bu, her yeni seçenek istemi oluşturulduğunda Uyarlamalı Kart girişini aramak için doğrulayıcınızı çağırır.

Kart Kullanma botunu test edin

  1. Kart kullanma örneğini yerel olarak çalıştırın ve botu Bot Framework Öykünücüsü'nde açın.
  2. Uyarlamalı Kart gibi bir kart türünü görüntülemek için bottaki istemleri izleyin.

Sonraki adımlar

Kullanıcı eylemine kılavuzluk etmek için düğme ekleme