Skicka mediebilagor med Bot Framework SDK

  • Artikel

GÄLLER FÖR: SDK v4

Meddelanden som utbyts mellan användare och robot kan innehålla mediebilagor, till exempel bilder, video, ljud och filer. Bot Framework SDK stöder uppgiften att skicka omfattande meddelanden till användaren. Information om begränsningar finns i kanalens dokumentation för att fastställa vilken typ av omfattande meddelanden en kanal (Facebook, Slack och så vidare) stöder.

Kommentar

Bot Framework JavaScript-, C#- och Python-SDK:erna fortsätter att stödjas, men Java SDK dras tillbaka med slutligt långsiktigt stöd som slutar i november 2023.

Befintliga robotar som skapats med Java SDK fortsätter att fungera.

Om du vill skapa en ny robot bör du överväga att använda Power Virtual Agents och läsa om hur du väljer rätt chattrobotlösning.

Mer information finns i Framtiden för robotbygge.

Förutsättningar

Skicka bifogade filer

Om du vill skicka användarinnehåll som en bild eller en video kan du lägga till en bifogad fil eller lista med bifogade filer i ett meddelande.

Se Designa användarupplevelsen för exempel på tillgängliga kort.

Se även Vad är storleksgränsen för en fil som överförs med hjälp av kanaler? i Vanliga frågor och svar.

All källkod som visas i det här avsnittet baseras på exemplet Hantera bifogade filer .

Egenskapen Attachments för Activity objektet innehåller en matris med Attachment objekt som representerar mediebilagor och rtF-kort som är kopplade till meddelandet. Om du vill lägga till en mediebilaga i ett meddelande skapar du ett Attachment objekt för reply aktiviteten och anger ContentTypeegenskaperna , ContentUrloch Name .

Om du vill skapa svarsmeddelandet definierar du texten och konfigurerar sedan de bifogade filerna. Att tilldela bifogade filer till svaret är detsamma för varje typ av bifogad fil, men de olika bilagorna konfigureras och definieras på olika sätt, enligt följande kodfragment. Koden nedan konfigurerar svaret för en infogad bifogad fil:

Robotar/AttachmentsBot.cs

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

Därefter tittar vi på typerna av bifogade filer. Först är en infogad bifogad fil:

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

Sedan en uppladdad bifogad fil:

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

Slutligen en bifogad internetbilaga:

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

Om en bifogad fil är en bild, ett ljud eller en video kommunicerar Anslut eller-tjänsten bifogade data till kanalen på ett sätt som gör att kanalen kan återge den bifogade filen i konversationen. Om den bifogade filen är en fil återges fil-URL:en som en hyperlänk i konversationen.

Skicka ett hero-kort

Förutom enkla bild- eller videobilagor kan du bifoga ett hero-kort, som gör att du kan kombinera bilder och knappar i ett objekt och skicka dem till användaren. Markdown stöds för de flesta textfält, men stödet kan variera beroende på kanal.

Om du vill skapa ett meddelande med ett hero-kort och en knapp kan du koppla ett HeroCard objekt till ett meddelande.

Följande källkod kommer från exemplet Hantera bifogade filer .

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

Bearbeta händelser inom omfattande kort

Om du vill bearbeta händelser inom rich cards använder du kortåtgärdsobjekt för att ange vad som ska hända när användaren väljer en knapp eller trycker på en del av kortet. Varje kortåtgärd har en typ - och värdeegenskap .

Om du vill fungera korrekt tilldelar du en åtgärdstyp till varje klickbart objekt på ett hero-kort. Den här tabellen visar och beskriver tillgängliga åtgärdstyper och vad som ska finnas i den associerade värdeegenskapen. Kortåtgärden messageBack har en mer generaliserad betydelse än de andra kortåtgärderna. Mer information om messageBack och andra kortåtgärdstyper finns i avsnittet Kortåtgärd i aktivitetsschemat.

Typ Beskrivning Värde
call Initierar ett telefonsamtal. Målet för telefonsamtalet i det här formatet: tel:123123123123.
downloadFile Laddar ned en fil. URL:en för filen som ska laddas ned.
imBack Skickar ett meddelande till roboten och publicerar ett synligt svar i chatten. Text på meddelandet som ska skickas.
messageBack Representerar ett textsvar som ska skickas via chattsystemet. Ett valfritt programmatiskt värde som ska inkluderas i genererade meddelanden.
openUrl Öppnar en URL i den inbyggda webbläsaren. Url:en som ska öppnas.
playAudio Spelar upp ljud. URL:en för det ljud som ska spelas upp.
playVideo Spelar upp en video. URL:en för videon som ska spelas upp.
postBack Skickar ett meddelande till roboten och kanske inte publicerar ett synligt svar i chatten. Text på meddelandet som ska skickas.
showImage Visar en bild. URL:en för den bild som ska visas.
signin Initierar en OAuth-inloggningsprocess. URL:en för OAuth-flödet som ska initieras.

Hero-kort med olika händelsetyper

Följande kod visar exempel med olika rich card-händelser.

Exempel på alla tillgängliga kort finns i exemplet Använda kort .

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

Skicka ett adaptivt kort

Du kan använda meddelandefabriken för att skapa ett meddelande som innehåller en bifogad fil (av alla slag), men ett adaptivt kort är en specifik typ av bifogad fil. Alla kanaler stöder inte adaptiva kort, och vissa kanaler kanske bara delvis stöder adaptiva kort. Om du till exempel skickar ett adaptivt kort på Facebook fungerar inte knapparna medan texter och bilder fungerar bra. Meddelandefabriken är en Bot Framework SDK-hjälpklass som används för att automatisera skapandesteg åt dig.

Adaptiva kort är ett öppet kortutbytesformat som gör det möjligt för utvecklare att utbyta UI-innehåll på ett gemensamt och konsekvent sätt. Alla kanaler stöder dock inte adaptiva kort.

Designern för adaptiva kort ger en omfattande, interaktiv designtidsupplevelse för redigering av adaptiva kort.

Kommentar

Du bör testa den här funktionen med de kanaler som roboten använder för att avgöra om dessa kanaler stöder adaptiva kort.

Om du vill använda adaptiva kort måste du lägga AdaptiveCards till NuGet-paketet.

Följande källkod kommer från exemplet Använda kort .

Cards.cs

Det här exemplet läser JSON för adaptivt kort från en fil och lägger till den som en bifogad fil.

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

Meddelanden kan också innehålla flera bifogade filer i en karuselllayout, vilket placerar bilagorna sida vid sida och gör att användaren kan rulla över.

Följande källkod kommer från exemplet Använda kort .

Dialogrutor/MainDialog.cs

Skapa först svaret och definiera de bifogade filerna som en lista.

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

Lägg sedan till de bifogade filerna och ange layouttypen till karusell. Här lägger vi till dem en i taget, men du kan ändra listan för att lägga till korten hur du vill.

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

När de bifogade filerna har lagts till kan du skicka svaret precis som andra.

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

Kodexempel för bearbetning av adaptiva kortindata

Följande exempel visar ett sätt att använda adaptiva kortindata i en robotdialogruta. Det utökar hero-kortexemplet genom att validera indata som tas emot i textfältet från den svarande klienten. Du måste först lägga till textinmatnings- och knappfunktionen i det befintliga adaptiva kortet genom att lägga till följande kod precis innan den sista hakparentesen för adaptiveCard.json, som finns i resursmappen:

"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:t för textinmatningsfältet är inställt på "text". När användaren väljer OK kommer meddelandet som det adaptiva kortet genererar att ha en värdeegenskap som har en egenskap med namnet text som innehåller den information som användaren angav i kortets textinmatningsfält.

Vår validerare använder Newtonsoft.json för att först konvertera detta till en JObject, och sedan skapa en trimmad textsträng för jämförelse. Lägg till:

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

för att MainDialog.cs och installera det senaste stabila NuGet-paketet newtonsoft.Json. I valideringskoden lade vi till logikflödet i kodkommentarna. Den här ChoiceValidator metoden placeras i exemplet Using cards (Använda kort ) strax efter den stängda klammerparentesen för deklaration av 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;
}

Nu ovan i deklarationsändringen MainDialog :

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

till:

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

Detta anropar validatorn för att söka efter adaptiva kortindata varje gång en ny alternativprompt skapas.

Testa roboten Använda kort

  1. Kör exemplet Använda kort lokalt och öppna roboten i Bot Framework-emulatorn.
  2. Följ anvisningarna i roboten för att visa en korttyp, till exempel ett adaptivt kort.

Nästa steg

Lägga till knappar för att vägleda användaråtgärder