Sdílet prostřednictvím

Odesílání příloh médií pomocí sady Bot Framework SDK

  • Článek

PLATÍ PRO: SDK v4

Zprávy vyměňované mezi uživatelem a robotem můžou obsahovat mediální přílohy, jako jsou obrázky, video, zvuk a soubory. Sada SDK služby Bot Framework podporuje úlohu odesílání bohatých zpráv uživateli. Pokud chcete určit typ bohatých zpráv, které kanál (Facebook, Slack atd.) podporuje, přečtěte si informace o omezeních v dokumentaci kanálu.

Poznámka:

Sady SDK služby Bot Framework JavaScript, C# a Python budou nadále podporovány, ale sada Java SDK se vyřazuje s konečnou dlouhodobou podporou končící v listopadu 2023.

Stávající roboti sestavení pomocí sady Java SDK budou i nadále fungovat.

Při vytváření nových robotů zvažte použití aplikace Microsoft Copilot Studio a přečtěte si o výběru správného řešení copilotu.

Další informace najdete v tématu Budoucnost vytváření robotů.

Požadavky

Odesílání příloh

Pokud chcete odeslat uživatelský obsah jako obrázek nebo video, můžete do zprávy přidat přílohu nebo seznam příloh.

Příklady dostupných karet najdete v tématu Návrh uživatelského prostředí .

Podívejte se také na omezení velikosti souboru přenášeného pomocí kanálů? V nejčastějších dotazech.

Veškerý zdrojový kód zobrazený v této části vychází z ukázky Zpracování příloh .

Vlastnost Attachments objektu Activity obsahuje pole Attachment objektů, které představují přílohy médií a bohaté karty připojené ke zprávě. Chcete-li přidat přílohu média do zprávy, vytvořte Attachment objekt pro reply aktivitu a nastavte ContentType, ContentUrla Name vlastnosti.

Pokud chcete vytvořit zprávu odpovědi, definujte text a nastavte přílohy. Přiřazení příloh k odpovědi je stejné pro každý typ přílohy, ale různé přílohy jsou nastaveny a definovány odlišně, jak je vidět v následujících fragmentech kódu. Níže uvedený kód nastavuje odpověď pro vloženou přílohu:

Roboti/AttachmentsBot.cs

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

Dále se podíváme na typy příloh. První je vložená příloha:

Roboti/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}",
    };
}

Pak nahranou přílohu:

Roboti/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,
    };
}

A konečně, internetová příloha:

Roboti/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",
        };
    }
}

Pokud je příloha obrázkem, zvukem nebo videem, služba Konektor bude komunikovat data přílohy do kanálu způsobem, který kanálu umožní vykreslit tuto přílohu v rámci konverzace. Pokud je příloha souborem, adresa URL souboru se v rámci konverzace vykreslí jako hypertextový odkaz.

Odeslání karty hrdiny

Kromě jednoduchých obrázků nebo video příloh můžete připojit kartu hrdiny, která umožňuje kombinovat obrázky a tlačítka v jednom objektu a odeslat je uživateli. Markdown je podporovaný pro většinu textových polí, ale podpora se může lišit podle kanálu.

Pokud chcete vytvořit zprávu s kartou a tlačítkem hrdiny, můžete k zprávě připojit HeroCard objekt.

Následující zdrojový kód pochází z ukázky Zpracování příloh .

Roboti/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);

Zpracování událostí v rámci karet s bohatými funkcemi

Pokud chcete zpracovávat události na kartách s bohatými obsahy, pomocí objektů akcí karty určete, co se má stát, když uživatel vybere tlačítko nebo klepne na oddíl karty. Každá akce karty má vlastnost typu a hodnoty .

Chcete-li správně fungovat, přiřaďte každému kliknutí na kartu hrdiny typ akce. Tato tabulka uvádí a popisuje dostupné typy akcí a to, co by mělo být ve vlastnosti přidružené hodnoty.

Akce messageBack karty má obecnější význam než ostatní akce karty. Další informace o typech messageBack akcí karty najdete v části Akce Karta schématu aktivity.

Typ Popis Hodnota
call Zahájí telefonní hovor. Cíl pro telefonní hovor v tomto formátu: tel:123123123123.
downloadFile Stáhne soubor. Adresa URL souboru, který chcete stáhnout.
imBack Odešle robotovi zprávu a publikuje viditelnou odpověď v chatu. Text zprávy, kterou chcete odeslat.
messageBack Představuje textovou odpověď, která se má odeslat prostřednictvím chatovacího systému. Volitelná programová hodnota, která se má zahrnout do vygenerovaných zpráv.
openUrl Otevře adresu URL v integrovaném prohlížeči. Adresa URL, která se má otevřít.
playAudio Přehraje zvuk. Adresa URL zvuku, který se má přehrát.
playVideo Přehraje video. Adresa URL videa, která se má přehrát.
postBack Odešle robotovi zprávu a nemusí v chatu publikovat viditelnou odpověď. Text zprávy, kterou chcete odeslat.
showImage Zobrazí obrázek. Adresa URL obrázku, který se má zobrazit.
signin Zahájí proces přihlášení OAuth. Adresa URL toku OAuth, který se má zahájit.

Karta Hero s využitím různých typů událostí

Následující kód ukazuje příklady použití různých událostí s bohatými kartami.

Příklady všech dostupných karet najdete v ukázce Používání karet .

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

Odeslání adaptivní karty

I když můžete pomocí objektu pro vytváření zpráv vytvořit zprávu, která obsahuje přílohu (libovolného druhu), adaptivní karta je jedním konkrétním typem přílohy. Ne všechny kanály podporují adaptivní karty a některé kanály můžou adaptivní karty podporovat pouze částečně. Pokud například pošlete adaptivní kartu na Facebooku, tlačítka nebudou fungovat, zatímco texty a obrázky dobře fungují. Objekt pro vytváření zpráv je pomocná třída sady SDK služby Bot Framework, která se používá k automatizaci kroků vytváření za vás.

Adaptivní karty jsou otevřený formát výměny karet, který umožňuje vývojářům vyměňovat si obsah uživatelského rozhraní běžným a konzistentním způsobem. Ne všechny kanály však podporují adaptivní karty.

Návrhář adaptivních karet poskytuje bohaté interaktivní prostředí pro navrhování adaptivních karet.

Poznámka:

Tuto funkci byste měli otestovat pomocí kanálů, které robot použije k určení, jestli tyto kanály podporují adaptivní karty.

Pokud chcete použít adaptivní karty, nezapomeňte přidat AdaptiveCards balíček NuGet.

Následující zdrojový kód pochází z ukázky using karet .

Cards.cs

Tento příklad načte JSON adaptivní karty ze souboru a přidá ho jako přílohu.

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

Zprávy můžou také obsahovat více příloh v karuselovém rozložení, které umístí přílohy vedle sebe a umožní uživateli posouvání.

Následující zdrojový kód pochází z ukázky using karet .

Dialogy/MainDialog.cs

Nejprve vytvořte odpověď a definujte přílohy jako seznam.

// 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);

Pak přidejte přílohy a nastavte typ rozložení na karusel. Tady je přidáváme po jednom, ale můžete s ním manipulovat a přidat karty, které dáváte přednost.

// 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());

Po přidání příloh můžete odpověď odeslat stejně jako jakoukoli jinou.

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

Ukázka kódu pro zpracování vstupu adaptivní karty

Následující ukázka ukazuje jeden ze způsobů použití vstupů adaptivní karty v rámci třídy dialogového okna robota. Rozšíří ukázku karet hero ověřením vstupu přijatého v textovém poli z reagujícího klienta. Nejdřív je potřeba přidat funkci textového vstupu a tlačítka do existující adaptivní karty tak, že přidáte následující kód těsně před poslední hranatá závorka adaptiveCard.json, která se nachází ve složce prostředků:

"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"
        }
      ]
    }
  }
]

ID textového vstupního pole je nastavené na text. Když uživatel vybere OK, zpráva, kterou adaptivní karta vygeneruje, bude mít hodnotu vlastnost s názvem text , která obsahuje informace, které uživatel zadal do textového vstupního pole karty.

Náš validátor používá Newtonsoft.json k prvnímu převodu na a JObjectpotom vytvoří oříznutý textový řetězec pro porovnání. Proto přidejte:

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

pro MainDialog.cs a instalaci nejnovějšího stabilního balíčku NuGet newtonsoft.json. V kódu validátoru jsme do komentářů ke kódu přidali tok logiky. Tato ChoiceValidator metoda je umístěna do vzorku Using karty těsně po uzavřené složené závorce pro deklaraci MainDialog:

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

Teď nad změnou MainDialog deklarace:

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

na:

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

Tím se vyvolá validátor, který bude hledat vstup adaptivní karty při každém vytvoření nové výzvy k volbě.

Testování robota Using Cards

  1. Spusťte ukázku Pomocí karet místně a otevřete robota v bot Framework Emulatoru.
  2. Podle pokynů v robotovi zobrazte typ karty, jako je adaptivní karta.

Další kroky

Přidání tlačítek pro akci uživatele