Senden von Medienanlagen mit dem Bot Framework SDK

GILT FÜR: SDK v4

Nachrichten, die zwischen Benutzer und Bot ausgetauscht werden, können Medienanlagen enthalten, z.B. Bilder, Videos, Audio und Dateien. Das Bot Framework SDK unterstützt die Aufgabe zum Senden von umfassenden Nachrichten an den Benutzer. Informationen zu Einschränkungen finden Sie in der Dokumentation des Kanals, um den Typ der umfangreichen Nachrichten zu bestimmen, die von einem Kanal (Facebook, Slack usw.) unterstützt werden.

Hinweis

Die Bot Framework-Python- und Java-SDKs werden eingestellt und der endgültige langfristige Support endet im November 2023. Es werden nur kritische Sicherheits- und Fehlerbehebungen innerhalb dieses Repositorys durchgeführt. Vorhandene Bots, die mit diesen SDKs erstellt wurden, funktionieren weiterhin.

Erwägen Sie für die Entwicklung neuer Bots die Verwendung von Power Virtual Agents. Weitere Informationen finden Sie unter Die Zukunft des Botaufbaus.

Voraussetzungen

Senden von Anlagen

Um Benutzerinhalte wie Bilder oder Videos zu senden, können Sie einer Nachricht eine Anlage oder eine Liste von Anlagen hinzufügen.

Beispiele für verfügbare Karten finden Sie unter Entwerfen der Benutzeroberfläche .

Weitere Informationen finden Sie unter Was ist die Größenbegrenzung einer Datei, die über Kanäle übertragen wird? in den HÄUFIG GESTELLTen Fragen.

Der gesamte Quellcode, der in diesem Abschnitt gezeigt wird, basiert auf dem Beispiel Umgang mit Anlagen .

Die Attachments-Eigenschaft des Activity-Objekts enthält ein Array von Attachment-Objekten, die die an die Nachricht angehängten Medienanlagen und Rich Cards darstellen. Um einer Nachricht eine Medienanlage hinzuzufügen, erstellen Sie ein Attachment-Objekt für die Aktivität reply, und legen Sie die Eigenschaften ContentType, ContentUrl und Name fest.

Definieren Sie den Text, und richten Sie dann die Anlagen ein, um die Antwortnachricht zu erstellen. Die Zuweisung der Anlagen zur Antwort ist für jeden Anlagentyp identisch, aber die verschiedenen Anlagen werden unterschiedlich eingerichtet und definiert. Dies ist in den folgenden Codeausschnitten zu sehen. Mit diesem Code wird die Antwort für eine Inline-Anlage eingerichtet:

Bots/AttachmentsBot.cs

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

Als Nächstes sehen wir uns die Arten von Anlagen an. Die erste Anlage ist eine Inline-Anlage:

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

Die nächste Möglichkeit ist eine hochgeladene Anlage:

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

Die letzte Anlage ist eine Internetanlage:

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

Wenn eine Anlage ein Bild, eine Audiodatei oder ein Video ist, übermittelt der Connector Anlagedaten an den Kanal so, dass der Kanal diese Anlage in der Unterhaltung rendert. Wenn es sich bei der Anlage um eine Datei handelt, wird die Datei-URL als Link in der Unterhaltung gerendert.

Senden einer Hero-Karte

Neben einfachen Bild- oder Videoanlagen können Sie auch eine Hero-Karte anhängen, mit der Sie Bilder und Schaltflächen in einem Objekt kombinieren und an Benutzer senden können. Markdown wird für die meisten Textfelder unterstützt, die Unterstützung hängt jedoch ggf. vom jeweiligen Kanal ab.

Um eine Nachricht mit einer Heldenkarte und -schaltfläche zu verfassen, können Sie ein HeroCard Objekt an eine Nachricht anfügen.

Der folgende Quellcode stammt aus dem Beispiel Umgang mit Anlagen .

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

Verarbeiten von Ereignissen auf Rich Cards

Verwenden Sie Kartenaktionsobjekte , um Ereignisse in umfangreichen Karten zu verarbeiten, um anzugeben, was geschehen soll, wenn der Benutzer eine Schaltfläche auswählt oder auf einen Abschnitt der Karte tippt. Jede Kartenaktion verfügt über eine Typ - und Werteigenschaft .

Um ordnungsgemäß zu funktionieren, weisen Sie jedem klickbaren Element auf einer Hero-Karte einen Aktionstyp zu. In der folgenden Tabelle werden die verfügbaren Aktionstypen aufgeführt und erläutert. Außerdem ist jeweils angegeben, was die zugeordnete Werteigenschaft enthalten muss. Die messageBack Kartenaktion hat eine allgemeinere Bedeutung als die anderen Kartenaktionen. Weitere Informationen zu den messageBack Kartenaktionstypen und anderen Kartenaktionstypen finden Sie im Abschnitt Kartenaktionsschema des Aktivitätsschemas.

type Beschreibung Wert
Aufruf Initiiert einen Telefonanruf. Ziel für den Telefonanruf im folgenden Format: tel:123123123123.
downloadFile Lädt eine Datei herunter. Die URL der herunterzuladenden Bilds.
imBack Sendet eine Nachricht an den Bot und veröffentlicht eine sichtbare Antwort im Chat. Text der zu sendenden Nachricht.
messageBack Stellt eine Textantwort dar, die über das Chatsystem gesendet werden soll. Ein optionaler programmgesteuerter Wert, der in generierte Nachrichten eingeschlossen werden soll.
openUrl Öffnet eine URL im integrierten Browser. Die zu öffnende URL.
playAudio Gibt Audio wieder. Die URL des wiederzugebenden Audios.
playVideo Gibt ein Video wieder. Die URL des wiederzugebenden Videos.
postBack Sendet eine Nachricht an den Bot und veröffentlicht ggf. keine sichtbare Antwort im Chat. Text der zu sendenden Nachricht.
showImage Zeigt ein Bild an. Die URL des anzuzeigenden Bilds.
signin Initiiert einen OAuth-Anmeldeprozess. Die URL des zu initiierenden OAuth-Flusses.

Verwenden einer Hero-Karte mit verschiedenen Ereignistypen

Der folgende Code zeigt Beispiele für verschiedene Rich Card-Ereignisse.

Beispiele für alle verfügbaren Karten finden Sie im Beispiel Verwenden von Karten .

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

Senden adaptiver Karten

Während Sie die Nachrichtenfactory verwenden können, um eine Nachricht zu erstellen, die eine Anlage (beliebiger Art) enthält, ist eine adaptive Karte ein bestimmter Anlagetyp. Nicht alle Kanäle unterstützen adaptive Karten, und einige Kanäle unterstützen möglicherweise nur teilweise adaptive Karten. Wenn Sie beispielsweise eine adaptive Karte in Facebook senden, funktionieren die Schaltflächen nicht, während die Texte und Bilder einwandfrei funktionieren. Die Message Factory ist eine Bot Framework SDK-Hilfsklasse, die zum Automatisieren von Erstellungsschritten für Sie verwendet wird.

Adaptive Karten sind ein offenes Kartenaustauschformat, mit dem Entwickler UI-Inhalte auf einheitliche und konsistente Weise austauschen können. Allerdings unterstützen nicht alle Kanäle adaptive Karten.

Der Designer für adaptive Karten bietet eine umfassende, interaktive Entwurfszeitumgebung für die Erstellung adaptiver Karten.

Hinweis

Sie sollten diese Funktion mit den Kanälen testen, die Ihr Bot verwenden wird, um festzustellen, ob diese Kanäle adaptive Karten unterstützen.

Fügen Sie das NuGet-Paket AdaptiveCards hinzu, um adaptive Karten zu verwenden.

Der folgende Quellcode stammt aus dem Beispiel Verwenden von Karten .

Cards.cs

In diesem Beispiel wird der JSON-Code für adaptive Karten aus einer Datei gelesen und als Anlage hinzugefügt.

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

Nachrichten können auch mehrere Anlagen im Karusselllayout enthalten. Die Anlagen werden nebeneinander platziert und der Benutzer kann zwischen ihnen wechseln.

Der folgende Quellcode stammt aus dem Beispiel Verwenden von Karten .

Dialogs/MainDialog.cs

Erstellen Sie zunächst die Antwort, und definieren Sie dann die Anlagen als Liste.

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

Fügen Sie dann die Anlagen hinzu, und legen Sie den Layouttyp auf Karussell fest. Hier fügen wir sie einzeln hinzu, aber Sie können die Liste auch ändern, um die Karten wie gewünscht hinzuzufügen.

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

Nachdem die Anlagen hinzugefügt wurden, können Sie die Antwort wie gewohnt senden.

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

Codebeispiel für die Verarbeitung der Eingabe in adaptive Karten

Das folgende Beispiel zeigt eine Möglichkeit, adaptive Karteneingaben in einer Bot-Dialogklasse zu verwenden. Es erweitert das Beispiel für Hero-Karten, indem die Eingabe überprüft wird, die im Textfeld vom antwortenden Client empfangen wurde. Zuerst müssen Sie die Texteingabe- und Schaltflächenfunktionalität der vorhandenen adaptiven Karte hinzufügen, indem Sie den folgenden Code unmittelbar vor der letzten Klammer von adaptiveCard.json im Ordner resources hinzufügen:

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

Die ID des Texteingabefelds ist auf "text" festgelegt. Wenn der Benutzer OK auswählt, weist die von der adaptiven Karte generierte Meldung eine value-Eigenschaft mit einer Eigenschaft namens text auf, die die Informationen enthält, die der Benutzer in das Texteingabefeld der Karte eingegeben hat.

Unser Validierungssteuerelement verwendet Newtonsoft.json , um dies zuerst in einen JObjectzu konvertieren und dann eine gekürzte Textzeichenfolge für den Vergleich zu erstellen. Fügen Sie also Folgendes hinzu:

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

in MainDialog.cs , und installieren Sie das neueste stabile NuGet-Paket von Newtonsoft.Json. Im Validierungscode haben wir den Codekommentaren den Logikflow hinzugefügt. Diese ChoiceValidator Methode wird im Beispiel Using cards direkt nach der geschlossenen Klammer public für die Deklaration von MainDialog platziert:

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

Jetzt oben in der MainDialog Deklaration ändern:

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

in:

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

Dadurch wird Ihr Validierungssteuerelement aufgerufen, um bei jedem Erstellen einer neuen Auswahlaufforderung nach der Eingabe adaptiver Karten zu suchen.

Testen des Bots "Using Cards"

  1. Führen Sie das Beispiel Verwenden von Karten lokal aus, und öffnen Sie den Bot im Bot Framework Emulator.
  2. Befolgen Sie die Anweisungen im Bot, um einen Kartentyp anzuzeigen, z. B. eine adaptive Karte.

Nächste Schritte