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