次の方法で共有


検索コマンドに応答する

重要

このセクションのコード サンプルは、v4.6 以降のバージョンの Bot Framework SDK に基づいています。 以前のバージョンのドキュメントをお探しの場合は、ドキュメントの Resources フォルダーにある メッセージ拡張機能 - v3 SDK セクションを参照してください。

ユーザーが検索コマンドを送信すると、Web サービスは、検索パラメーターを持つvalue オブジェクトを含むcomposeExtension/query呼び出しメッセージを受け取ります。 呼び出しは、次の条件でトリガーされます。

  • 検索ボックスに文字が入力されます。
  • initialRunアプリ マニフェスト で true に設定され、検索コマンドが呼び出されるとすぐに呼び出しメッセージが表示されます。 詳細については、「既定の クエリ」を参照してください。

このドキュメントでは、カードとプレビューの形式でユーザーの要求に応答する方法と、Microsoft Teamsが既定のクエリを発行する条件について説明します。

要求パラメーターは、要求の value オブジェクトにあります。これには、次のプロパティが含まれます。

プロパティ名 用途
commandId ユーザーによって呼び出されるコマンドの名前。アプリ マニフェストで宣言されているコマンドのいずれかと一致します。
parameters パラメーターの配列。 各パラメーター オブジェクトには、パラメーター名と、ユーザーによって提供されるパラメーター値が含まれます。
queryOptions 改ページ パラメーター:
skip: このクエリのカウントをスキップする
count: 返す要素の数。
protected override async Task<MessagingExtensionResponse> OnTeamsMessagingExtensionQueryAsync(ITurnContext<IInvokeActivity> turnContext, MessagingExtensionQuery query, CancellationToken cancellationToken)
{
  // Code to handle the query.
}

ユーザーの要求に応答する

ユーザーがクエリを実行すると、Microsoft Teamsはサービスに同期 HTTP 要求を発行します。 その時点で、コードは要求に対する HTTP 応答を提供するために 5 秒です。 この間、サービスは、より多くの参照、または要求を処理するために必要なその他のビジネス ロジックを実行できます。

サービスは、ユーザー クエリと一致する結果で応答する必要があります。 応答は、 200 OK の HTTP 状態コードと、次のプロパティを持つ有効なアプリケーションまたは JSON オブジェクトを示す必要があります。

プロパティ名 用途
composeExtension 最上位レベルの応答エンベロープ。
composeExtension.type 応答の種類。 次の種類がサポートされています。
result: 検索結果の一覧を表示します
auth: ユーザーに認証を求めるメッセージ
config: メッセージ拡張機能の設定をユーザーに求めるメッセージ
message: プレーン テキスト メッセージを表示します
composeExtension.attachmentLayout 添付ファイルのレイアウトを指定します。 型 resultの応答に使用されます。
次の種類がサポートされています。
list: サムネイル、タイトル、テキスト フィールドを含むカード オブジェクトの一覧
grid: サムネイル画像のグリッド
composeExtension.attachments 有効な添付ファイル オブジェクトの配列。 型 resultの応答に使用されます。
次の種類がサポートされています。
application/vnd.microsoft.card.thumbnail
application/vnd.microsoft.card.hero
application/vnd.microsoft.teams.card.o365connector
application/vnd.microsoft.card.adaptive
composeExtension.suggestedActions 推奨されるアクション。 auth型またはconfig型の応答に使用されます。
composeExtension.text 表示するメッセージ。 型 messageの応答に使用されます。

構成応答

構成応答は、メッセージング プラットフォーム内でメッセージ拡張機能を構成して有効にするために、サーバーまたはアプリケーションによって返されるデータです。 次のコードは、メッセージ拡張機能の構成の例です。

{
    "name": "composeExtension/submitAction",
    "type": "invoke",
    "timestamp": "2024-03-08T14:10:47.575Z",
    "localTimestamp": "2024-03-08T19:40:47.575+05:30",
    "id": "f:7dfe18de-94e3-9f38-5d44-adeb31cd8243",
    "channelId": "msteams",
    "serviceUrl": "https://smba.trafficmanager.net/amer/",
    "from": {
        "id": "29:1PBlnIsEROUYzpFjULDVodMHrnpujmfhBdQAf0pcO1EkaDkhI0_Pj_ql-jZUYOGdSc3_KcqaIIjzbleraVJ2Z3g",
        "name": "MOD Administrator",
        "aadObjectId": "ce9def33-d7fc-444c-8728-be1f95e6b6f2"
    },
    "conversation": {
        "isGroup": true,
        "conversationType": "groupChat",
        "tenantId": "4ad59956-0f88-4b88-a9d0-570b6eb4e66b",
        "id": "19:1dd50ba7-e5bd-46ea-b34e-80a415148de7_ce9def33-d7fc-444c-8728-be1f95e6b6f2@unq.gbl.spaces"
    },
    "recipient": {
        "id": "28:9a2b01fc-88c1-40e1-bf87-5079c8e35626",
        "name": "PSDAzureBot"
    },
    "entities": [
        {
            "locale": "en-GB",
            "country": "GB",
            "platform": "Web",
            "timezone": "Asia/Calcutta",
            "type": "clientInfo"
        }
    ],
    "channelData": {
        "tenant": {
            "id": "4ad59956-0f88-4b88-a9d0-570b6eb4e66b"
        },
        "source": {
            "name": "compose"
        }
    },
    "value": {
        "commandId": "razorView",
        "commandContext": "compose",
        "data": {
            "Title": "Welcome to RazorView!",
            "DisplayData": " Today&#x27;s date is 8-3-2024, Friday"
        },
        "context": {
            "theme": "default"
        }
    },
    "locale": "en-GB",
    "localTimezone": "Asia/Calcutta"
}

次の応答は、ユーザーが compose 拡張機能と対話するときに表示される構成応答です。

{
    "composeExtension": {
        "type": "config",
        "suggestedActions": {
            "actions": [
                {
                    "type": "openUrl",
                    "value": "https://7a03-2405-201-a00c-7191-b472-ff64-112d-f806.ngrok-free.app"
                }
            ]
        }
    }
}

スクリーンショットは、メッセージ拡張機能の構成応答を示しています。

応答カードの種類とプレビュー

注:

メッセージ拡張機能の検索結果では、パディングはサポートされていません。

Teams では、次のカードの種類がサポートされています。

カードについて理解と概要を理解するには、カード とは何かを参照してください。

サムネイルとヒーロー カードの種類を使用する方法については、「 カードとカードアクションを追加する」を参照してください。

Microsoft 365 グループのコネクタ カードの詳細については、「Microsoft 365 グループのコネクタ カードの使用」を参照してください。

結果の一覧は、各項目のプレビューを含むMicrosoft Teams UI に表示されます。 プレビューは、次の 2 つの方法のいずれかで生成されます。

  • attachment オブジェクト内で preview プロパティを使用する。 previewの添付ファイルには、ヒーローカードまたはサムネイル カードのみを使用できます。
  • attachment オブジェクトの基本的なtitletextimage プロパティから抽出します。 基本プロパティは、 preview プロパティが指定されていない場合にのみ使用されます。

ヒーローまたはサムネイル カードの場合、ボタンやタップなどの他のアクションを呼び出す操作を除き、プレビュー カードではサポートされていません。

Microsoft 365 グループのアダプティブ カードまたはコネクタ カードを送信するには、プレビューを含める必要があります。 previewプロパティはヒーローカードまたはサムネイルカードである必要があります。 attachment オブジェクトで preview プロパティを指定しない場合、プレビューは生成されません。

ヒーロー カードとサムネイル カードの場合、プレビュー プロパティを指定する必要はありません。プレビューは既定で生成されます。

応答の例

protected override async Task<MessagingExtensionResponse> OnTeamsMessagingExtensionQueryAsync(ITurnContext<IInvokeActivity> turnContext, MessagingExtensionQuery query, CancellationToken cancellationToken) 
{
  var text = query?.Parameters?[0]?.Value as string ?? string.Empty;

  // Searches NuGet for a package.
  var obj = JObject.Parse(await (new HttpClient()).GetStringAsync($"https://azuresearch-usnc.nuget.org/query?q=id:{text}&prerelease=true"));
  var packages = obj["data"].Select(item => (item["id"].ToString(), item["version"].ToString(), item["description"].ToString()));

  // We take every row of the results and wrap them in cards wrapped in in MessagingExtensionAttachment objects.
  // The Preview is optional, if it includes a Tap, that will trigger the OnTeamsMessagingExtensionSelectItemAsync event back on this bot.
  var attachments = packages.Select(package => new MessagingExtensionAttachment
      {
          ContentType = HeroCard.ContentType,
          Content = new HeroCard { Title = package.Item1 },
          Preview = new HeroCard { Title = package.Item1, Tap = new CardAction { Type = "invoke", Value = package } }.ToAttachment()
      })
      .ToList();

  // The list of MessagingExtensionAttachments must we wrapped in a MessagingExtensionResult wrapped in a MessagingExtensionResponse.
  return new MessagingExtensionResponse
  {
      ComposeExtension = new MessagingExtensionResult
      {
          Type = "result",
          AttachmentLayout = "list",
          Attachments = attachments
      }
  };
}

タップ アクションを有効にして処理する

protected override Task<MessagingExtensionResponse> OnTeamsMessagingExtensionSelectItemAsync(ITurnContext<IInvokeActivity> turnContext, JObject query, CancellationToken cancellationToken)
{
    // The Preview card's Tap should have a Value property assigned, this will be returned to the bot in this event.
    var (packageId, version, description, projectUrl, iconUrl) = query.ToObject<(string, string, string, string, string)>();

    var card = new ThumbnailCard
    {
        Title = "Card Select Item",
        Subtitle = description
    };

    var attachment = new MessagingExtensionAttachment
    {
        ContentType = ThumbnailCard.ContentType,
        Content = card,
    };

    return Task.FromResult(new MessagingExtensionResponse
    {
        ComposeExtension = new MessagingExtensionResult
        {
            Type = "result",
            AttachmentLayout = "list",
            Attachments = new List<MessagingExtensionAttachment> { attachment }
        }
    });
}

既定のクエリ

マニフェストで initialRuntrue に設定Microsoft Teams、ユーザーが最初にメッセージ拡張機能を開いたときに 既定 のクエリを発行します。 サービスは、事前設定された結果のセットを使用して、このクエリに応答できます。 これは、検索コマンドで認証または構成が必要な場合、最近表示されたアイテム、お気に入り、またはユーザー入力に依存しないその他の情報を表示する場合に便利です。

既定のクエリは通常のユーザー クエリと同じ構造で、 name フィールドは initialRun に設定され、 value 次のオブジェクトに示すように true に設定されます。

{
  "type": "invoke",
  "name": "composeExtension/query",
  "value": {
    "commandId": "searchCmd",
    "parameters": [
      {
        "name": "initialRun",
        "value": "true"
      }
    ],
    "queryOptions": {
      "skip": 0,
      "count": 25
    }
  },
  ⋮
}

コード サンプル

サンプルの名前 説明 .NET Node.js マニフェスト
Teams メッセージ拡張機能検索 このサンプルでは、検索ベースのメッセージ拡張機能を構築する方法を示します。 これは、ナッゲット パッケージを検索し、検索ベースのメッセージング拡張機能で結果を表示します。 表示 表示 表示
Teams メッセージ拡張機能の認証と構成 このサンプルでは、構成ページがあり、検索要求を受け入れ、ユーザーがサインインした後に結果を返すメッセージ拡張機能を示します。 また、ゼロアプリインストールリンクが展開され、通常のリンクが展開されるのも紹介されています 表示 表示 表示

次の手順

関連項目