Freigeben über


Senden von Medienanlagen mit 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. 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 des Bot-Design.

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 verfügbarer Karten (Cards) finden Sie unter Entwerfen der Benutzeroberfläche.

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 der Handling Attachments (Behandeln von 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 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 messageBack und anderen Kartenaktionstypen finden Sie im Abschnitt Kartenaktion des Aktivitätsschemas.

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 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 wird. 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-Anmeldevorgang. 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 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;
}

Senden adaptiver Karten

Sie können zwar die Nachrichten-Zuordnungsinstanz 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 Nachrichten-Zuordnungsinstanz ist eine Helferklasse des Bot Framework SDKs, mit der die Erstellungsschritte für Sie automatisiert werden.

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.

Fügen Sie das NuGet-Paket AdaptiveCards hinzu, um adaptive Karten 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 in adaptive Karten 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 Validierungssteuerelement verwendet Newtonsoft.json zum Konvertieren in ein JObject und anschließenden Erstellen einer abgeschnittenen Textzeichenfolge für den Vergleich. 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