Share via

Médiamellékletek küldése a Bot Framework SDK-val

  • Cikk

A KÖVETKEZŐKRE VONATKOZIK: SDK v4

A felhasználó és a robot között kicserélt üzenetek tartalmazhatnak médiamellékleteket, például képeket, videókat, hangokat és fájlokat. A Bot Framework SDK támogatja azt a feladatot, hogy gazdag üzeneteket küldjön a felhasználónak. A csatornák (Facebook, Slack stb.) által támogatott gazdag üzenetek típusának meghatározásához tekintse meg a csatorna dokumentációját a korlátozásokról.

Feljegyzés

A Bot Framework JavaScript, C# és Python SDK-k továbbra is támogatottak lesznek, a Java SDK-t azonban 2023 novemberében végső hosszú távú támogatással kivonják.

A Java SDK-val létrehozott meglévő robotok továbbra is működni fognak.

Új robotépítéshez fontolja meg a Power Virtual Agents használatát, és olvassa el a megfelelő csevegőrobot-megoldás kiválasztását.

További információ: A robotépítés jövője.

Előfeltételek

Mellékletek küldése

Ha a felhasználói tartalmat képként vagy videóként szeretné elküldeni, hozzáadhat mellékletet vagy mellékletlistát egy üzenethez.

Az elérhető kártyákra vonatkozó példákat a felhasználói felület tervezése című témakörben talál.

Lásd még : Mi a csatornákon átvitt fájlok méretkorlátja? című témakört a gyakori kérdések között.

Az ebben a szakaszban látható összes forráskód a Mellékletek kezelése mintán alapul.

Az Attachments objektum tulajdonsága Activity olyan objektumtömböt Attachment tartalmaz, amely az üzenethez csatolt médiamellékleteket és gazdag kártyákat jelöli. Ha médiamellékletet szeretne hozzáadni egy üzenethez, hozzon létre egy Attachment objektumot a reply tevékenységhez, és állítsa be a , ContentUrlés Name a ContentTypetulajdonságokat.

A válaszüzenet létrehozásához adja meg a szöveget, majd állítsa be a mellékleteket. A mellékletek a válaszhoz való hozzárendelése minden melléklettípus esetében ugyanaz, azonban a különböző mellékletek beállítása és definiálása másként történik, ahogyan az alábbi kódrészletekben látható. Az alábbi kód egy beágyazott melléklet válaszát állítja be:

Robotok/AttachmentsBot.cs

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

Ezután a mellékletek típusait tekintjük át. Az első egy beágyazott melléklet:

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

Ezután egy feltöltött melléklet:

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

Végül egy internetes melléklet:

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

Ha a melléklet kép, hang vagy videó, a Csatlakozás or szolgáltatás úgy fogja továbbítani a mellékletadatokat a csatornának, hogy a csatorna a beszélgetésen belül megjelenítse a mellékletet. Ha a melléklet fájl, a fájl URL-címe hivatkozásként jelenik meg a beszélgetésben.

Fő képkártya küldése

Az egyszerű kép- vagy videomellékletek mellett egy főképkártyát is csatolhat, amellyel képeket és gombokat egyesíthet egy objektumban, és elküldheti őket a felhasználónak. A Markdown a legtöbb szövegmező esetében támogatott, de a támogatás csatornánként eltérő lehet.

Ha hőskártyával és gombbal szeretne üzenetet írni, csatolhat egy objektumot HeroCard egy üzenethez.

A következő forráskód a Mellékletek kezelése mintából származik .

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

Események feldolgozása gazdag kártyákon belül

A gazdag kártyákon belüli események feldolgozásához használjon kártyaműveleti objektumokat annak meghatározására, hogy mi történjen, ha a felhasználó kiválaszt egy gombot, vagy koppintson a kártya egy szakaszára. Minden kártyaművelet típus- és értéktulajdonságokkal rendelkezik.

A helyes működéshez rendeljen hozzá egy művelettípust egy főkártya minden kattintható eleméhez. Ez a táblázat felsorolja és ismerteti a rendelkezésre álló művelettípusokat, valamint a társított érték tulajdonságban szereplő értékeket. A messageBack kártyaműveletnek általánosabb jelentése van, mint a többi kártyaműveletnek. A tevékenységséma Kártyaművelet szakaszában további információt talál az messageBack egyéb kártyaművelet-típusokról.

Típus Leírás Érték
Hívja Telefonhívást kezdeményez. A telefonhívás célhelye ebben a formátumban: tel:123123123123.
downloadFile Letölt egy fájlt. A letölteni kívánt fájl URL-címe.
imBack Üzenetet küld a robotnak, és látható választ jelenít meg a csevegésben. A küldendő üzenet szövege.
messageBack A csevegőrendszeren keresztül küldendő szöveges választ jelöli. Nem kötelező programozott érték, amely belefoglalható a létrehozott üzenetekbe.
openUrl Megnyitja az URL-címet a beépített böngészőben. A megnyitni kívánt URL-cím.
playAudio Hang lejátszása. A lejátszandó hang URL-címe.
playVideo Videó lejátszása. A lejátszandó videó URL-címe.
Visszaküldési Üzenetet küld a robotnak, és előfordulhat, hogy nem küld látható választ a csevegésben. A küldendő üzenet szövege.
showImage Kép megjelenítése. A megjelenítendő kép URL-címe.
bejelentkezés OAuth-bejelentkezési folyamatot kezdeményez. A kezdeményezni kívánt OAuth-folyamat URL-címe.

Hőskártya különböző eseménytípusok használatával

Az alábbi kód különböző gazdag kártyaeseményeket használó példákat mutat be.

Az összes elérhető kártya példáiért lásd a Kártyák használata mintát.

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

Adaptív kártya küldése

Bár az üzenet-előállítóval bármilyen mellékletet tartalmazó üzenetet hozhat létre, az Adaptív kártya egy adott melléklettípus. Nem minden csatorna támogatja az Adaptív kártyákat, és egyes csatornák csak részben támogatják az adaptív kártyákat. Ha például adaptív kártyát küld a Facebookon, a gombok nem fognak működni, miközben a szövegek és képek jól működnek. Az üzenet-előállító egy Bot Framework SDK-segédosztály, amellyel automatizálhatja a létrehozási lépéseket.

Az adaptív kártyák nyílt kártyacsere formátumot jelentenek, amely lehetővé teszi a fejlesztők számára a felhasználói felületi tartalmak közös és konzisztens cseréjét. Azonban nem minden csatorna támogatja az adaptív kártyákat.

Az Adaptív kártyák Tervező gazdag, interaktív tervezési időt biztosít az adaptív kártyák készítéséhez.

Feljegyzés

Ezt a funkciót a robot által használt csatornákkal kell tesztelnie annak megállapításához, hogy ezek a csatornák támogatják-e az adaptív kártyákat.

Adaptív kártyák használatához mindenképpen vegye fel a AdaptiveCards NuGet-csomagot.

A következő forráskód a Kártyák használata mintából származik.

Cards.cs

Ez a példa beolvassa az Adaptive Card JSON-t egy fájlból, és mellékletként adja hozzá.

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

Az üzenetek több mellékletet is tartalmazhatnak a körhinta elrendezésben, amelyek egymás mellett helyezik el a mellékleteket, és lehetővé teszik a felhasználó számára a görgetést.

A következő forráskód a Kártyák használata mintából származik.

Párbeszédpanelek/MainDialog.cs

Először hozza létre a választ, és adja meg listaként a mellékleteket.

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

Ezután adja hozzá a mellékleteket, és állítsa be az elrendezés típusát körhintára. Itt egyenként adjuk hozzá őket, de nyugodtan módosíthatja a listát, hogy tetszés szerint adja hozzá a kártyákat.

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

A mellékletek hozzáadása után ugyanúgy küldheti el a választ, mint bármelyik másikat.

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

Kódminta adaptív kártya bemenetének feldolgozásához

Az alábbi minta bemutatja, hogyan használhat adaptív kártya bemeneteket egy robot párbeszédpanel-osztályán belül. Kibővíti a főképkártyák mintáját a válaszul szolgáló ügyfél szövegmezőjében kapott bemenet érvényesítésével. Először hozzá kell adnia a szövegbeviteli és gombfunkciókat a meglévő adaptív kártyához, ha a következő kódot adja hozzá a adaptiveCard.json utolsó zárójele előtt, amely az erőforrások mappájában található:

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

A szövegbeviteli mező azonosítója "szöveg". Amikor a felhasználó az OK gombot választja, az Adaptív kártya által generált üzenet egy olyan értéktulajdonságú tulajdonságot text fog kapni, amely tartalmazza a felhasználó által a kártya szövegbeviteli mezőjébe beírt adatokat.

Az érvényesítő Newtonsoft.json használ, hogy először átalakítsa ezt egy JObject, majd hozzon létre egy levágott szöveges sztringet az összehasonlításhoz. Így adja hozzá:

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

a Newtonsoft.Json legújabb stabil NuGet-csomagjának MainDialog.cs és telepítéséhez. Az érvényesítő kódban hozzáadtuk a logikai folyamatot a kód megjegyzéseihez. Ezt ChoiceValidator a metódust a Rendszer a Kártyák használata mintába helyezi a MainDialog deklarálásához szükséges zárt kapcsos zárójelek után:

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

Most fent a MainDialog deklaráció módosításában:

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

erre:

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

Ez meghívja az érvényesítőt, hogy minden új választási kérés létrehozásakor keresse meg az adaptív kártya bemenetét.

A Kártyák használata robot tesztelése

  1. Futtassa helyileg a Kártyák használata mintát, és nyissa meg a robotot a Bot Framework Emulatorban.
  2. A robotban megjelenő utasításokat követve megjeleníthet egy kártyatípust, például egy adaptív kártyát.

Következő lépések

Gombok hozzáadása a felhasználói művelet irányításához