検索コマンドに応答する
重要
このセクションのコード サンプルは、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.
}
ユーザーの要求に応答する
ユーザーがクエリを実行すると、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'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
}
};
}
タップ アクションを有効にして処理する
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 }
}
});
}
既定のクエリ
マニフェストで を に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 メッセージ拡張機能の認証と構成 | このサンプルでは、構成ページがあり、検索要求を受け入れ、ユーザーがサインインした後に結果を返すメッセージ拡張機能を示します。 また、ゼロアプリインストールリンクが展開され、通常のリンクが展開されるのも紹介されています | 表示 | 表示 | 表示 |
次の手順
関連項目
Platform Docs
フィードバック
https://aka.ms/ContentUserFeedback」を参照してください。
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「フィードバックの送信と表示