検索コマンドに応答する

[アーティクル]
03/26/2024

重要

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

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

検索ボックスに文字が入力されます。
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.
}

サンプルコードリファレンス

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`の応答に使用されます。

構成応答

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

{
    "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 つの方法のいずれかで生成されます。

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

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

Microsoft 365 グループのアダプティブカードまたはコネクタカードを送信するには、プレビューを含める必要があります。プロパティは preview Hero または Thumbnail カードである必要があります。オブジェクトに 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
      }
  };
}

サンプルコードリファレンス

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": "https://placekitten.com/200/200"
            },
            {
              "title": "Details",
              "facts": [
                {
                  "name": "Assigned to:",
                  "value": "[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"
    },
    .
    .
    .
}

既定のクエリ

マニフェストでをにtrue設定initialRunした場合、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 メッセージ拡張機能検索	このサンプルでは、Search ベースのメッセージ拡張機能を構築する方法を示します。これは、ナッゲットパッケージを検索し、検索ベースのメッセージング拡張機能で結果を表示します。	表示	表示	表示
Teams メッセージ拡張機能の認証と構成	このサンプルでは、構成ページがあり、検索要求を受け入れ、ユーザーがサインインした後に結果を返すメッセージ拡張機能を示します。また、ゼロアプリインストールリンクが展開され、通常のリンクが展開されるのも紹介されています	表示	表示	表示

次の手順

メッセージ拡張機能にサードパーティ認証を追加する

検索コマンドに応答する

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

構成応答

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

応答の例

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

既定のクエリ

コードサンプル

次の手順

関連項目

フィードバック

その他のリソース

検索コマンドに応答する

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

構成応答

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

応答の例

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

既定のクエリ

コード サンプル

次の手順

関連項目

フィードバック

その他のリソース

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

コードサンプル