Freigeben über

Medienanhänge mit dem Bot Framework SDK senden

  • Artikel

GILT FÜR: SDK v4

Nachrichten, die zwischen Benutzer und Bot ausgetauscht werden, können Medienanhänge enthalten, zum Beispiel Bilder, Videos, Audio und Dateien. Das Bot Framework SDK unterstützt die Aufgabe zum Senden von umfassenden Nachrichten an den Benutzer. Um den Typ der umfassenden Nachrichten zu ermitteln, die von einem Kanal (Facebook, Slack usw.) unterstützt werden, können Sie in der Dokumentation zum jeweiligen Kanal nach Informationen zu Einschränkungen suchen.

Hinweis

Die JavaScript-, C#- und Python-SDKs für Bot Framework werden weiterhin unterstützt, das Java-SDK wird jedoch eingestellt und der langfristige Support endet im November 2023.

Bestehende Bots, die mit dem Java SDK erstellt wurden, werden weiterhin funktionieren.

Für das erstellen eines neuen Bots sollten Sie Microsoft Copilot Studio verwenden und lesen, wie Sie die richtige Copilot-Lösung auswählen.

Weitere Informationen finden Sie unter Die Zukunft der Bot-Entwicklung.

Voraussetzungen

Anhänge senden

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

Siehe Entwerfen des Benutzererlebnisses für Beispiele verfügbarer Karten.

Siehe auch Wie groß darf eine Datei sein, die über Kanäle übertragen wird? in Häufig gestellte Fragen.

Der gesamte in diesem Abschnitt gezeigte Quellcode basiert auf dem Beispiel Handling Attachments.

Die Attachments-Eigenschaft des Activity-Objekts enthält ein Array von Attachment-Objekten, die die an die Nachricht angefügten Medienanhänge 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 betrachten wir die Arten von Anhängen. 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}",
    };
}

Dann, ein hochgeladener Anhang:

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

Zuletzt ein Internetanhang:

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 Hero-Karte und einer Schaltfläche zu verfassen, können Sie an eine Nachricht ein HeroCard-Objekt anfügen.

Der folgende Quellcode stammt aus dem Beispiel Behandeln von 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

Zum Verarbeiten von Ereignissen in Rich Cards verwenden Sie Objekte vom Typ Kartenaktion, um festzulegen, was passieren soll, wenn der Benutzer auf eine Schaltfläche klickt oder auf einen Abschnitt der Rich Card tippt. Jede Kartenaktion hat eine Typ- und Wert-Eigenschaft.

Weisen Sie für die korrekte Funktionsweise jedem anklickbaren 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 und anderen Kartenaktionstypen finden Sie im Abschnitt Kartenaktion des messageBack.

Typ BESCHREIBUNG Wert
call Initiiert einen Telefonanruf. Ziel für den Telefonanruf im folgenden Format: tel:123123123123.
downloadFile Lädt eine Datei herunter. Die URL der herunterzuladenden Datei.
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 wird. Ein optionaler programmgesteuerter Wert, der in generierte Nachrichten eingeschlossen werden soll.
URL öffnen Öffnet eine URL im integrierten Browser. Die zu öffnende URL.
Audio abspielen Gibt Audio wieder. Die URL des abzuspielenden Audios.
Video abspielen Spielt ein Video ab. 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.
Bild anzeigen Zeigt ein Bild an. Die URL des anzuzeigenden Bilds.
signin Initiiert einen OAuth-Anmeldevorgang. Die URL des zu initiierenden OAuth-Flusses.

Held-Karte mit verschiedenen Ereignistypen verwenden

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

Beispiele für alle verfügbaren Karten finden Sie im Abschnitt Karten verwenden.

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

Eine adaptive Karte senden

Sie können zwar die Nachrichtenfabrik verwenden, um eine Nachricht zu erstellen, die eine Anlage (beliebiger Art) enthält, eine Adaptive Karte ist jedoch ein bestimmter Anlagentyp. Nicht alle Kanäle unterstützen adaptive Karten, und einige Kanäle unterstützen adaptive Karten nur teilweise. Wenn Sie beispielsweise eine adaptive Karte in Facebook senden, funktionieren die Schaltflächen nicht, während die Texte und Bilder einwandfrei funktionieren. Die Nachrichtenfabrik ist eine Helferklasse des Bot Framework SDKs, die die Erstellungsschritte für Sie automatisiert.

Adaptive Karten sind ein offenes Kartenaustauschformat, das es Entwicklern ermöglicht, UI-Inhalte auf gemeinsame und konsistente Weise auszutauschen. Allerdings unterstützen nicht alle Kanäle adaptive Karten.

Der Designer für adaptive Karten bietet eine umfassende, interaktive Entwurfszeitumgebung zum Erstellen von adaptiven 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.

Stellen Sie sicher, dass Sie das NuGet-Paket AdaptiveCards hinzufügen, um Adaptive Cards zu verwenden.

Der folgende Quellcode stammt aus dem Beispiel Karten verwenden.

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 Karten verwenden.

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, Eingaben von Adaptive Cards innerhalb einer Bot-Dialogklasse zu verwenden. Es erweitert das Beispiel der Hero-Karten, indem es die im Textfeld vom antwortenden Client empfangenen Eingaben validiert. Zunächst müssen Sie die Texteingabe- und Schaltflächenfunktionalität zur vorhandenen adaptiven Karte hinzufügen, indem Sie den folgenden Code direkt vor der letzten Klammer der Datei 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 wird auf „Text“ festgelegt. Wenn der Benutzer OK auswählt, weist die von der adaptiven Karte generierte Nachricht eine Werteigenschaft auf, die eine Eigenschaft namens text enthält, die die Informationen enthält, die der Benutzer im Texteingabefeld der Karte eingegeben hat.

Unser Validator verwendet Newtonsoft.json, um dies zuerst in ein JObject zu konvertieren und dann eine beschnittene Textstring für den Vergleich zu erstellen. Fügen Sie also Folgendes hinzu:

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

zu MainDialog.cs, und installieren Sie das neueste stabile NuGet-Paket von Newtonsoft.Json. Im Code des Validierungssteuerelement haben wir den Logikfluss den Codekommentaren hinzugefügt. Diese ChoiceValidator-Methode wird in das Beispiel Karten verwenden direkt nach der geschlossenen Klammer nach „public“ zur Deklaration von MainDialog eingefügt:

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

Ändern Sie nun oben in der Deklaration von MainDialog Folgendes:

// 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 so aufgerufen, dass es bei jeder Erstellung einer neuen ChoicePrompt nach Eingaben für die adaptive Karte sucht.

Testen des Bots Karten verwenden

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

Nächste Schritte

Hinzufügen von Schaltflächen zum Steuern von Benutzeraktionen