Udostępnij za pośrednictwem

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

  • Artykuł

DOTYCZY: ZESTAW 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 języka JavaScript, C# i Python platformy Bot Framework będą nadal obsługiwane, jednak zestaw SDK języka Java jest wycofywany z ostatecznym długoterminowym wsparciem kończącym się w listopadzie 2023 r.

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

W przypadku tworzenia nowych botów rozważ użycie programu Microsoft Copilot Studio i przeczytaj o wyborze odpowiedniego rozwiązania copilot.

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 Activity obiektu zawiera tablicę Attachment obiektów reprezentujących załączniki multimediów i rozbudowane karty dołączone do wiadomości. Aby dodać załącznik multimediów do wiadomości, utwórz Attachment obiekt dla reply działania i ustaw ContentTypewłaściwości , ContentUrli 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 przekazany 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 kanał 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ść za pomocą karty bohatera i przycisku, możesz dołączyć HeroCard obiekt 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 przetworzyć zdarzenia na kartach bogatych, użyj obiektów akcji karty, aby określić, co powinno się zdarzyć, gdy użytkownik wybierze przycisk lub naciśnij sekcję karty. Każda akcja karty ma właściwość typu i 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 messageBack karty ma bardziej uogólnione znaczenie niż inne akcje karty. Aby uzyskać więcej informacji na temat messageBack i innych typów akcji kart, zobacz sekcję Akcja karty schematu działania.

Type Opis Wartość
call Inicjuje połączenie telefoniczne. Miejsce docelowe połączenia telefonicznego w tym formacie: tel:123123123123.
downloadFile 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.
messageBack 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.
playAudio Odtwarza dźwięk. Adres URL dźwięku do odtwarzania.
playVideo 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.
showImage Wyświetla obraz. Adres URL obrazu do wyświetlenia.
signin Inicjuje proces logowania OAuth. Adres URL przepływu OAuth do zainicjowania.

Karta bohatera korzystająca z różnych typów zdarzeń

Poniższy kod przedstawia przykłady z użyciem różnych zaawansowanych zdarzeń kart.

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. Jeśli na przykład wyślesz kartę adaptacyjną na Facebooku, przyciski nie będą działać, gdy teksty i obrazy będą działać dobrze. 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.

Projektant kart adaptacyjnych zapewnia zaawansowane, interaktywne środowisko 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, jednak 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ładowe karty hero, sprawdzając dane wejściowe odebrane w polu tekstowym od odpowiadającego klienta. 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ć go na JObjectelement , a następnie utworzyć przycięty ciąg tekstowy 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 jest umieszczana w przykładzie Using cards tuż po publicznie zamkniętego nawiasu klamrowego 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 modułu sprawdzania poprawności w celu wyszukania danych wejściowych karty adaptacyjnej za każdym razem, gdy zostanie utworzony nowy monit o wybór.

Testowanie bota używającego kart

  1. Uruchom przykładowe karty Using (Używanie kart) lokalnie 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

Dodawanie przycisków do akcji użytkownika