Udostępnij za pośrednictwem

Wysyłanie załączników multimediów za pomocą zestawu Bot Framework SDK

  • Artykuł

DOTYCZY: SDK w wersji 4

Komunikaty wymieniane między użytkownikiem a botem mogą zawierać załączniki multimediów, takie jak obrazy, wideo, dźwięk i pliki. Zestaw SDK platformy Bot Framework obsługuje zadanie wysyłania rozbudowanych komunikatów do użytkownika. Aby określić typ zaawansowanych wiadomości, które obsługuje kanał (Facebook, Slack itd.), zapoznaj się z dokumentacją kanału, aby uzyskać informacje o ograniczeniach.

Uwaga

Zestawy SDK dla języka JavaScript, C# i Python platformy Bot Framework będą nadal obsługiwane, jednak SDK dla języka Java jest wycofywane, przy czym ostateczne wsparcie długoterminowe zakończy się w listopadzie 2023 r.

Istniejące boty utworzone za pomocą zestawu JAVA SDK będą nadal działać.

Przy tworzeniu nowych botów rozważ użycie Microsoft Copilot Studio i przeczytaj o wyborze odpowiedniego rozwiązania copilota.

Aby uzyskać więcej informacji, zobacz Przyszłość tworzenia botów.

Wymagania wstępne

Wysyłanie załączników

Aby wysłać zawartość użytkownika, na przykład obraz lub wideo, możesz dodać załącznik lub listę załączników do wiadomości.

Zobacz Projektowanie środowiska użytkownika, aby zapoznać się z przykładami dostępnych kart.

Zobacz też Jaki jest limit rozmiaru pliku przesyłanego za pomocą kanałów? w często zadawanych pytaniach.

Cały kod źródłowy pokazany w tej sekcji jest oparty na przykładzie Obsługa załączników .

Właściwość Attachments obiektu Activity zawiera tablicę obiektów Attachment, które reprezentują załączniki multimedialne i rozbudowane karty dołączone do wiadomości. Aby dodać załącznik multimedialny do wiadomości, utwórz obiekt Attachment dla działania reply i ustaw właściwości ContentType, ContentUrl oraz Name.

Aby utworzyć wiadomość odpowiedzi, zdefiniuj tekst, a następnie skonfiguruj załączniki. Przypisywanie załączników do odpowiedzi jest takie samo dla każdego typu załącznika, jednak różne załączniki są konfigurowane i definiowane inaczej, jak pokazano w poniższych fragmentach kodu. Poniższy kod konfiguruje odpowiedź dla wbudowanego załącznika:

Boty/AttachmentsBot.cs

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

Następnie przyjrzymy się typom załączników. Najpierw jest załącznik wbudowany:

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

Następnie przesłany załącznik:

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

Na koniec załącznik internetowy:

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

Jeśli załącznik jest obrazem, dźwiękiem lub wideo, usługa łącznika przekaże dane załącznika do kanału w sposób umożliwiający ten kanał na renderowanie tego załącznika w konwersacji. Jeśli załącznik jest plikiem, adres URL pliku będzie renderowany jako hiperlink w konwersacji.

Wysyłanie karty bohatera

Oprócz prostych obrazów lub załączników wideo można dołączyć kartę bohatera, która umożliwia łączenie obrazów i przycisków w jednym obiekcie i wysyłanie ich do użytkownika. Język Markdown jest obsługiwany w przypadku większości pól tekstowych, ale obsługa może się różnić w zależności od kanału.

Aby utworzyć wiadomość zawierającą kartę bohatera i przycisk, możesz dołączyć obiekt HeroCard do wiadomości.

Poniższy kod źródłowy pochodzi z przykładu Obsługa załączników .

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

Przetwarzanie zdarzeń na kartach bogatych

Aby przetwarzać zdarzenia w obrębie kart bogatych, użyj obiektów akcji karty, aby określić, co powinno się zdarzyć, gdy użytkownik wybierze przycisk lub dotknie sekcji karty. Każda akcja karty ma właściwość typu i właściwość wartości.

Aby prawidłowo działać, przypisz typ akcji do każdego elementu, który można kliknąć na karcie bohatera. W tej tabeli wymieniono i opisano dostępne typy akcji oraz właściwości, które powinny znajdować się we skojarzonej właściwości wartości.

Akcja karty messageBack ma bardziej ogólne znaczenie niż akcje innych kart. Aby uzyskać więcej informacji na temat messageBack i innych typów akcji kart, zobacz sekcję Akcja karty w schemacie Aktywności.

Typ Opis Wartość
call Inicjuje połączenie telefoniczne. Miejsce docelowe połączenia telefonicznego w tym formacie: tel:123123123123.
pobierzPlik Pobiera plik. Adres URL pliku do pobrania.
imBack Wysyła wiadomość do bota i publikuje widoczną odpowiedź na czacie. Tekst wiadomości do wysłania.
wiadomośćZwrotna Reprezentuje odpowiedź tekstową, która ma zostać wysłana za pośrednictwem systemu czatów. Opcjonalna wartość programowa do uwzględnienia w wygenerowanych komunikatach.
openUrl Otwiera adres URL w wbudowanej przeglądarce. Adres URL do otwarcia.
odtwórzDźwięk Odtwarza dźwięk. Adres URL dźwięku do odtwarzania.
odtwórzWideo Odtwarza wideo. Adres URL wideo do odtwarzania.
postBack Wysyła wiadomość do bota i może nie publikować widocznej odpowiedzi na czacie. Tekst wiadomości do wysłania.
pokaż obraz Wyświetla obraz. Adres URL obrazu do wyświetlenia.
logowanie Inicjuje proces logowania OAuth. Adres URL przepływu OAuth do zainicjowania.

Karta bohatera wykorzystująca różne typy zdarzeń

Poniższy kod przedstawia przykłady wykorzystania różnych zdarzeń związanych z kartami.

Przykłady wszystkich dostępnych kart można znaleźć w przykładzie Korzystanie z kart .

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

Wysyłanie karty adaptacyjnej

Chociaż możesz użyć fabryki komunikatów do utworzenia komunikatu zawierającego załącznik (dowolnego rodzaju), karta adaptacyjna jest jednym konkretnym typem załącznika. Nie wszystkie kanały obsługują karty adaptacyjne, a niektóre kanały mogą obsługiwać tylko częściowo karty adaptacyjne. Na przykład, jeśli wyślesz kartę adaptacyjną na Facebooku, przyciski nie będą działać, podczas gdy teksty i obrazy będą działać poprawnie. Fabryka komunikatów to klasa pomocnika zestawu SDK platformy Bot Framework używana do automatyzowania kroków tworzenia.

Karty adaptacyjne to format wymiany kart otwartych, umożliwiający deweloperom spójną i spójną wymianę zawartości interfejsu użytkownika. Jednak nie wszystkie kanały obsługują karty adaptacyjne.

Adaptive Cards Designer zapewnia bogate, interaktywne środowisko dla projektowania kart adaptacyjnych.

Uwaga

Należy przetestować tę funkcję za pomocą kanałów używanych przez bota, aby określić, czy te kanały obsługują karty adaptacyjne.

Aby użyć kart adaptacyjnych, pamiętaj, aby dodać AdaptiveCards pakiet NuGet.

Poniższy kod źródłowy pochodzi z przykładu Używanie kart .

Cards.cs

W tym przykładzie odczytuje kod JSON karty adaptacyjnej z pliku i dodaje go jako załącznik.

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

Komunikaty mogą również zawierać wiele załączników w układzie karuzeli, który umieszcza załączniki obok siebie i umożliwia użytkownikowi przewijanie.

Poniższy kod źródłowy pochodzi z przykładu Używanie kart .

Okna dialogowe/MainDialog.cs

Najpierw utwórz odpowiedź i zdefiniuj załączniki jako listę.

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

Następnie dodaj załączniki i ustaw typ układu na karuzeli. W tym miejscu dodajemy je pojedynczo, ale możesz manipulować listą, aby dodać karty, jak wolisz.

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

Po dodaniu załączników możesz wysłać odpowiedź tak samo jak każda inna.

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

Przykład kodu do przetwarzania danych wejściowych karty adaptacyjnej

Poniższy przykład przedstawia jeden ze sposobów użycia danych wejściowych karty adaptacyjnej w klasie okna dialogowego bota. Rozszerza przykład kart bohatera poprzez weryfikację danych wejściowych otrzymanych w polu tekstowym od klienta odpowiadającego. Najpierw należy dodać funkcję wprowadzania tekstu i przycisku do istniejącej karty adaptacyjnej, dodając następujący kod tuż przed ostatnim nawiasem adaptiveCard.json znajdującym się w folderze resources:

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

Identyfikator pola wprowadzania tekstu jest ustawiony na "tekst". Gdy użytkownik wybierze przycisk OK, komunikat Wygenerowana karta adaptacyjna będzie zawierać właściwość wartości o nazwie text zawierającą informacje wprowadzone przez użytkownika w polu wprowadzania tekstu karty.

Nasz moduł sprawdzania poprawności używa Newtonsoft.json, aby najpierw przekonwertować to na JObject, a następnie utworzyć przyciętą wersję ciągu tekstowego do porównania. Dodaj więc:

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

aby MainDialog.cs i zainstalować najnowszy stabilny pakiet NuGet Newtonsoft.Json. W kodzie modułu sprawdzania poprawności dodaliśmy przepływ logiki do komentarzy kodu. Ta ChoiceValidator metoda została umieszczona w przykładzie Using cards bezpośrednio po zamknięciu nawiasu klamrowego public dla deklaracji 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;
}

Teraz powyżej w deklaracji MainDialog zmień:

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

na:

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

Spowoduje to wywołanie walidatora w celu wyszukania danych wejściowych karty adaptacyjnej za każdym razem, gdy zostanie utworzone nowe zapytanie o wybór.

Testowanie bota używającego kart

  1. Uruchom lokalnie przykład Korzystanie z kart i otwórz bota w aplikacji Bot Framework Emulator.
  2. Postępuj zgodnie z monitami bota, aby wyświetlić typ karty, taki jak karta adaptacyjna.

Następne kroki

Dodaj przyciski, aby prowadzić działania użytkownika