検索コマンドに応答する

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

重要

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

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

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 要求を発行します。その時点で、コードは要求に対する 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 オブジェクトの基本的なtitle、text、image プロパティから抽出します。基本プロパティは、 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
      }
  };
}

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

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

既定のクエリ

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

次の手順

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

次の方法で共有

検索コマンドに応答する

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

構成応答

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

応答の例

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

既定のクエリ

コードサンプル

次の手順

関連項目

その他のリソース

次の方法で共有

検索コマンドに応答する

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

構成応答

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

応答の例

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

既定のクエリ

コード サンプル

次の手順

関連項目

その他のリソース

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

コードサンプル