次の方法で共有

Bot Framework SDK を使用してメディア添付ファイルを送信する

対象範囲: SDK v4

ユーザーとボットの間のメッセージ交換には、イメージ、ビデオ、オーディオ、ファイルなどのメディア添付ファイルを含めることができます。 Bot Framework SDK では、ユーザーにリッチ メッセージを送信するタスクがサポートされています。 チャネル (Facebook、Slack など) がサポートするリッチ メッセージの種類を確認するには、チャネルのドキュメントで制限事項に関する情報を参照してください。

注

AI サービス、オーケストレーション、知識を選択してエージェントを構築するには、Microsoft 365 Agents SDK の使用を検討してください。 Agents SDK では、C#、JavaScript、または Python がサポートされています。 Agents SDK の詳細については、 aka.ms/agents を参照してください。 SaaS ベースのエージェント プラットフォームをお探しの場合は、 Microsoft Copilot Studio を検討してください。 Bot Framework SDK を使用して構築された既存のボットがある場合は、ボットを Agents SDK に更新できます。 Bot Framework SDK から Agents SDK への移行ガイダンスで、主要な変更と更新プログラムを確認できます。 Bot Framework SDK のサポート チケットは、2025 年 12 月 31 日の時点で提供されなくなります。

前提条件

添付ファイルを送信する

イメージやビデオなどのユーザー コンテンツを送信するには、添付ファイルまたは添付ファイルのリストをメッセージに追加します。

使用可能なカードの例については、「ユーザー エクスペリエンスの設計」をご覧ください。

FAQ の「チャネルを使用して転送されるファイルのサイズ制限を教えてください」も参照してください。

このセクションのソース コードは全て、添付ファイルの処理のサンプルに基づいています。

Attachments オブジェクトの Activity プロパティには、メッセージに添付するメディア添付ファイルやリッチ カードを表す Attachment オブジェクトが格納されます。 メディア添付ファイルをメッセージに追加するには、Attachment アクティビティ用の reply オブジェクトを作成し、ContentType、ContentUrl、Name の各プロパティを設定します。

返信メッセージを作成するには、テキストを定義し、添付ファイルを設定します。 添付ファイルを返信に割り当てる場合、添付ファイルの種類ごとに同じ操作を行いますが、次のスニペットに示すように、添付ファイルの設定と定義はそれぞれ異なります。 次のコードでは、インラインの添付ファイル用の返信が設定されます。

Bots/AttachmentsBot.cs

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

次に、添付ファイルの種類を見ていきます。 最初はインラインの添付ファイルです。

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

次は、アップロードされた添付ファイルです。

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

最後は、インターネットの添付ファイルです。

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

添付ファイルがイメージ、オーディオ、またはビデオの場合、コネクタ サービスにより、チャネルでの会話内の添付ファイルがレンダリングできる方法で、添付ファイルのデータがチャネルに通信されます。 添付ファイルがファイルである場合は、ファイルの URL が会話内にハイパーリンクとしてレンダリングされます。

ヒーロー カードを送信する

シンプルなイメージ添付ファイルまたはビデオ添付ファイルだけでなく、ヒーロー カードを添付することもできます。これにより、1 つのオブジェクトに含まれるイメージとボタンを結合してユーザーに送信することができます。 Markdown はほとんどのテキスト フィールドでサポートされていますが、サポート状況はチャネルごとに異なる場合があります。

ヒーロー カードとボタンを使用してメッセージを作成するには、HeroCard オブジェクトをメッセージに添付します。

次のソース コードは、添付ファイルの処理サンプルからのものです。

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

リッチカード内でイベントを処理する

リッチなカード内のイベントを処理するには、カード アクション オブジェクトを使用して、ユーザーがボタンを選択したり、またはカードのセクションをタップしたりしたときのアクションを指定します。 各カード アクションには type と value プロパティがあります。

正常に機能させるために、ヒーロー カード上のクリック可能な各アイテムにアクション タイプを割り当てます。 この表では、使用できるアクションの種類と、関連付けられている value プロパティに含める内容を一覧にまとめ、説明しています。

messageBack カード アクションは、他のカード アクションよりも一般化された意味を持ちます。 およびその他のカード アクションの種類の詳細については、アクティビティ スキーマの「messageBack」セクションを参照してください。

タイプ 説明 価値
呼び出し 電話を発信します。 電話の発信先 (形式は tel:123123123123)。
ファイルをダウンロード ファイルをダウンロードします。 ダウンロードするファイルの URL。
imBack ボットにメッセージを送信し、目に見える応答をチャットに投稿します。 送信するメッセージのテキスト。
メッセージ返信 チャット システムを介して送信されるテキスト応答を表しています。 生成されたメッセージに含めるオプションのプログラム値。
URLを開く 組み込みのブラウザーで URL を開きます。 開くためのURL。
オーディオを再生 オーディオを再生します。 再生するオーディオの URL。
ビデオを再生する ビデオを視聴します。 再生するビデオの URL。
ポストバック ボットにメッセージを送信します。目に見える応答はチャットに投稿できません。 送信するメッセージのテキスト。
画像を表示 画像を表示します。 表示する画像の URL。
サインイン OAuth サインイン プロセスを開始します。 開始する OAuth フローの URL。

さまざまな種類のイベントを使用するヒーロー カード

次のコードでは、さまざまなリッチ カード イベントを使用する例を示します。

使用可能なすべてのカードの例については、カードの使用 サンプルをご覧ください。

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

アダプティブ カードを送信する

メッセージ ファクトリを使用して添付ファイル (任意の種類) を含むメッセージを作成できますが、アダプティブ カードは添付ファイルの一種です。 アダプティブ カードをサポートするのは一部のチャネルのみで、チャネルによってはアダプティブ カードが部分的にしかサポートされない可能性があります。 たとえば、Facebook でアダプティブ カードを送信する場合、テキストと画像は適切に機能しますが、ボタンは機能しません。 メッセージ ファクトリは、作成手順を自動化するための、Bot Framework SDK のヘルパー クラスです。

アダプティブ カードは、開発者が UI コンテンツを共通で一貫した方法で交換できるようにする、オープンなカード交換フォーマットです。 ただし、すべてのチャネルでアダプティブ カードがサポートされているわけではありません。

アダプティブ カード デザイナーを使用すると、アダプティブ カードの作成にりっちでインタラクティブなデザイン タイム体験を実現できます。

注

ご自分のボットで使用されるチャネルにおいてこの機能をテストして、それらのチャネルでアダプティブ カードがサポートされているかどうかを判断する必要があります。

アダプティブ カードを使用するには、必ず AdaptiveCards NuGet パッケージを追加してください。

次のソース コードは、カードの使用サンプルのものです。。

Cards.cs

この例では、ファイルからアダプティブ カード JSON を読み取り、添付ファイルとして追加します。

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

また、メッセージには複数の添付ファイルをカルーセル レイアウトで含めることもできます。このレイアウトでは、添付ファイルが左右に並べて配置され、ユーザーは全体をスクロールすることができます。

次のソース コードは、カードの使用サンプルのものです。。

Dialogs/MainDialog.cs

最初に、返信を作成し、添付ファイルをリストとして定義します。

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

次に、添付ファイルを追加し、レイアウトの種類をカルーセルに設定します。 ここでは 1 つずつ追加しますが、必要に応じて、リストを使ってカードを追加することもできます。

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

添付ファイルが追加されると、他と同じように返信を送信できます。

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

アダプティブ カード入力を処理するためのコード サンプル

以下のサンプル コードは、ボット ダイアログ クラス内でアダプティブ カードの入力を使用する 1 つの方法を示しています。 テキスト フィールドで受け取った、応答クライアントからの入力を検証することで、ヒーロー カードのサンプルを拡張します。 まず、resources フォルダーにある adaptiveCard.json の最後の括弧の直前に次のコードを追加することにより、既存のアダプティブ カードにテキスト入力およびボタン機能を追加する必要があります。

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

テキスト入力フィールドの ID は "text" に設定されます。 ユーザーが [OK] を選択すると、アダプティブ カードによって生成されるメッセージには、ユーザーがカードのテキスト入力フィールドに入力した情報を含むプロパティを持つ、 という名前のtextプロパティがあります。

検証コントロールでは、Newtonsoft.json を使用して最初にこれを JObject に変換し、次に比較のためにトリミングされたテキスト文字列を作成します そのため、次のコードを

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

MainDialog.cs に追加して、Newtonsoft.Json の最新の安定版 NuGet パッケージをインストールします。 検証コントロールのコードでは、コード コメントにロジック フローを追加しました。 この ChoiceValidator メソッドは、Using cards サンプルにある、MainDialog の宣言用の閉じ括弧の public の直後に配置されています。

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

次に、上記のMainDialog 宣言を変更して

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

この行を次のように変更します。

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

これにより、新しい選択プロンプトが作成されるたびに、検証コントロールが呼び出されてアダプティブ カード入力が検索されます。

Using Cards ボットをテストする

  1. カードの使用サンプルをローカルで実行し、Bot Framework Emulator でボットを開きます。
  2. ボットのプロンプトに従って、アダプティブ カードなどのカードの種類を表示します。

次のステップ

ユーザー アクションをガイドするボタンを追加する

  • Last updated on