検索コマンドに応答する

[アーティクル]
04/28/2022

重要

このセクションのコードサンプルは、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
}

class TeamsMessagingExtensionsSearch extends TeamsActivityHandler {
    async handleTeamsMessagingExtensionQuery(context, query) {
  //code to handle the query
    }
}

以下の JSON は、最も関連性の高いセクションを強調表示するために短縮されています。

{
  "type": "invoke",
  "name": "composeExtension/query",
  "value": {
    "commandId": "searchCmd",
    "parameters": [
      {
        "name": "searchKeywords",
        "value": "Toronto"
      }
    ],
    "queryOptions": {
      "skip": 0,
      "count": 25
    }
  },
...
}

ユーザー要求に応答する

ユーザーがクエリを実行すると、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プロパティ textと image プロパティ 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
      }
  };
}

class TeamsMessagingExtensionsSearchBot extends TeamsActivityHandler {
    async handleTeamsMessagingExtensionQuery(context, query) {
        const searchQuery = query.parameters[0].value;
        const response = await axios.get(`http://registry.npmjs.com/-/v1/search?${ querystring.stringify({ text: searchQuery, size: 8 }) }`);

        const attachments = [];
        response.data.objects.forEach(obj => {
            const heroCard = CardFactory.heroCard(obj.package.name);
            const preview = CardFactory.heroCard(obj.package.name);
            const attachment = { ...heroCard, preview };
            attachments.push(attachment);
        });

        return {
            composeExtension: {
                type: 'result',
                attachmentLayout: 'list',
                attachments: attachments
            }
        };
    }
}

{
  "composeExtension": {
    "type": "result",
    "attachmentLayout": "list",
    "attachments": [
      {
        "contentType": "application/vnd.microsoft.teams.card.o365connector",
        "content": {
          "sections": [
            {
              "activityTitle": "[85069]: Create a cool app",
              "activityImage&quot;: &quot;https://placekitten.com/200/200"
            },
            {
              "title": "Details",
              "facts": [
                {
                  "name": "Assigned to:",
                  "value&quot;: &quot;[Larry Brown](mailto:larryb@example.com)"
                },
                {
                  "name": "State:",
                  "value": "Active"
                }
              ]
            }
          ]
        },
        "preview": {
          "contentType": "application/vnd.microsoft.card.thumbnail",
          "content": {
            "title": "85069: Create a cool app",
            "images": [
              {
                "url": "https://placekitten.com/200/200"
              }
            ]
          }
        }
      },
      {
        "contentType": "application/vnd.microsoft.card.adaptive",
        "content": {
          "type": "AdaptiveCard",
          "body": [
            {
              "type": "Container",
              "items": [
                {
                  "type": "TextBlock",
                  "text": "Microsoft Corp (NASDAQ: MSFT)",
                  "size": "medium",
                  "isSubtle": true
                },
                {
                  "type": "TextBlock",
                  "text": "September 19, 4:00 PM EST",
                  "isSubtle": true
                }
              ]
            },
            {
              "type": "Container",
              "spacing": "none",
              "items": [
                {
                  "type": "ColumnSet",
                  "columns": [
                    {
                      "type": "Column",
                      "width": "stretch",
                      "items": [
                        {
                          "type": "TextBlock",
                          "text": "75.30",
                          "size": "extraLarge"
                        },
                        {
                          "type": "TextBlock",
                          "text": "▼ 0.20 (0.32%)",
                          "size": "small",
                          "color": "attention",
                          "spacing": "none"
                        }
                      ]
                    },
                    {
                      "type": "Column",
                      "width": "auto",
                      "items": [
                        {
                          "type": "FactSet",
                          "facts": [
                            {
                              "title": "Open",
                              "value": "62.24"
                            },
                            {
                              "title": "High",
                              "value": "62.98"
                            },
                            {
                              "title": "Low",
                              "value": "62.20"
                            }
                          ]
                        }
                      ]
                    }
                  ]
                }
              ]
            }
          ],
          "version": "1.0"
        },
        "preview": {
          "contentType": "application/vnd.microsoft.card.thumbnail",
          "content": {
            "title": "Microsoft Corp (NASDAQ: MSFT)",
            "text": "75.30 ▼ 0.20 (0.32%)"
          }
        }
      }
    ]
  }
}

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

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

async handleTeamsMessagingExtensionSelectItem(context, obj) {
        return {
            composeExtension: {
                  type: 'result',
                  attachmentLayout: 'list',
                  attachments: [CardFactory.thumbnailCard(obj.Item3)]
            }
        };
    }

{
    "name": "composeExtension/selectItem",
    "type": "invoke",
    "value": {
        "Item1": "Package_Name",
        "Item2": "Version",
        "Item3": "Package Description"
    },
    .
    .
    .
}

注意

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 メッセージ拡張機能の検索	検索コマンドを定義し、検索に応答する方法について説明します。	表示	表示

次の手順

メッセージ拡張機能に認証を追加する

検索コマンドに応答する

このページはお役に立ちましたか?