検索コマンドに応答する

重要

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

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

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

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

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

プロパティ名 用途
commandId アプリ マニフェストで宣言されているコマンドの 1 つに一致する、ユーザーによって呼び出されるコマンドの名前。
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 要求を発行します。 その時点で、コードは 5 要求に対する HTTP 応答を提供するのに数秒かかります。 この間、サービスは追加のルックアップ、または要求の処理に必要なその他のビジネス ロジックを実行できます。

サービスは、ユーザー クエリと一致する結果で応答する必要があります。 応答は、HTTP 状態コードと、次の 200 OK プロパティを持つ有効なアプリケーションまたは 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

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

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

カードの理解と概要を理解するには、カード の概要を確認してください。

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

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

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

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

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

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

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

応答の例

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

注意

OnTeamsMessagingExtensionSelectItemAsync はモバイル チーム アプリケーションではトリガーされません。

既定のクエリ

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

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

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

コード サンプル

サンプルの名前 説明 .NET Node.js
Teams メッセージ拡張機能アクション アクション コマンドを定義し、タスク モジュールを作成し、タスク モジュール送信アクションに応答する方法について説明します。 表示 表示
Teams メッセージ拡張機能の検索 検索コマンドを定義し、検索に応答する方法について説明します。 表示 表示

次の手順

関連項目

メッセージ拡張機能に構成を追加する