アクティビティは、ユーザーとボットの間を流れる Teams 固有のペイロードです。 イベントがアプリ内の高レベルの出来事を説明する場合、アクティビティはチャット テキスト、カード アクション、インストール、呼び出し呼び出しなどの未加工の Teams メッセージです。
Teams SDK は Fluent ルーターを公開しているため、最小限の API を使用して専用ハンドラー メソッドでこれらのアクティビティをサブスクライブできます。
Teams SDK は Fluent ルーターを公開しているので、 @app.event("activity") でこれらのアクティビティをサブスクライブできます。
Teams SDK は Fluent ルーターを公開しているので、 app.on('<route>', …) でこれらのアクティビティをサブスクライブできます。
基本的なメッセージ ハンドラーの例を次に示します。
teams.OnMessage(async (context, cancellationToken) =>
{
await context.SendAsync($"you said: {context.Activity.Text}", cancellationToken);
});
@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]):
await ctx.send(f"You said '{ctx.activity.text}'")
app.on('message', async ({ activity, send }) => {
await send(`You said: ${activity.text}`);
});
上記の例では、 context.Activity プロパティは型 MessageActivity であり、これには Text プロパティがあります。 このハンドラーは何も返さず、代わりにメッセージを返すことでアクティビティを処理 Send。 メッセージ アクティビティの場合、Teams はアプリケーションが何も返すことを期待しません (ただし通常、何らかのわかりやすい確認を送信することをお勧めします)。
上記の例では、 ctx.activity パラメーターは MessageActivity 型であり、これには text プロパティがあります。 このハンドラーは何も返さず、代わりにメッセージを send返すことで処理していることに気づくでしょう。 メッセージ アクティビティの場合、Teams はアプリケーションが何も返すことを期待しません (ただし通常、何らかのわかりやすい確認を送信することをお勧めします)。
上記の例では、 activity パラメーターは MessageActivity 型であり、これには text プロパティがあります。 このハンドラーは何も返さず、代わりにメッセージを send返すことで処理していることに気づくでしょう。 メッセージ アクティビティの場合、Teams はアプリケーションが何も返すことを期待しません (ただし通常、何らかのわかりやすい確認を送信することをお勧めします)。
他のアクティビティ タイプには、異なるプロパティと異なる必要な結果があります。 特定のハンドラーに対して、SDK は自動的に activity の種類を判断し、正しい戻り値の型も適用します。
スラッシュ コマンド
スラッシュ コマンドは、ユーザーが作成ボックスから実行するマニフェスト宣言コマンドです。 スラッシュ コマンドを有効にするには、アプリ マニフェストの bots セクションでsupportsTargetedMessages: trueを設定します。 明示的なコマンド リストを宣言することで、明示的なコマンド リストでオプトインできます。triggers: ["slash"] でcommandListsを使用すると、ユーザーが/を入力したときにスラッシュ メニューに Teams が表示されます。 コマンド リストがなくても、ユーザーは /agent-name を介してエージェントを呼び出し、自由形式の入力を提供できます。
{
"bots": [
{
"botId": "{{BOT_ID}}",
"scopes": ["personal", "team", "groupChat"],
"supportsTargetedMessages": true,
"commandLists": [
{
"scopes": ["team", "groupChat"],
"triggers": ["slash"],
"commands": [
{ "title": "Review", "description": "Review a document" }
]
}
]
}
]
}
ユーザーがスラッシュ コマンドを送信すると、そのユーザーにのみ表示されるプライベート メッセージとして表示されます。 エージェントは、非公開で応答するか、必要に応じて、より広範なグループまたはチャネルと応答を共有することができます。
スラッシュ コマンドは、通常のメッセージ アクティビティとして到着し、アクティビティの受信者オブジェクトにターゲット フラグが設定されます。
スラッシュ コマンドがターゲット メッセージとして到着します。
Recipient.IsTargetedを確認して明示的に処理します。
teams.OnMessage(async (context, cancellationToken) =>
{
if (context.Activity.Recipient?.IsTargeted == true)
{
await context.SendAsync($"Received slash command: {context.Activity.Text}", cancellationToken);
}
});
@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]):
if ctx.activity.recipient and ctx.activity.recipient.is_targeted:
await ctx.send(f"Received slash command: {ctx.activity.text}")
return
await ctx.next()
app.on('message', async ({ activity, send, next }) => {
if (activity.recipient?.isTargeted) {
await send(`Received slash command: ${activity.text}`);
return;
}
await next();
});
アクティビティ ハンドラーのチェーン
Teams SDK for .NET では、アクティビティ ハンドラーは next() スタイルの処理チェーンを形成しません。 代わりに、アクティビティに一致するすべてのハンドラーが登録された順序で呼び出され、1 つのハンドラーでも後続の一致するハンドラーの実行を妨げることはできません。 要求処理をインターセプト、ショートサーキット、またはラッピングする必要がある場合 (条件が満たされたときに実行を停止する場合など)、 ITurnMiddleware を実装し、 nextTurn(...) を呼び出すかどうかを制御します。
eventアクティビティ ハンドラー (および属性) は、python ミドルウェアの動作と同様に、ミドルウェア パターンに従います。 つまり、アクティビティ ハンドラーごとに、次のハンドラーに制御を渡すために呼び出すことができる next 関数が渡されます。 これにより、同じアクティビティをさまざまな方法で処理できるハンドラーのチェーンを構築できます。
@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]):
"""Handle message activities using the new generated handler system."""
print(f"[GENERATED onMessage] Message received: {ctx.activity.text}")
await ctx.next()
@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]):
"""Handle message activities using the new generated handler system."""
if ctx.activity.text == "/help":
await ctx.send("Here are all the ways I can help you...")
await ctx.next()
@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]):
await ctx.send(f"You said '{ctx.activity.text}'")
on アクティビティ ハンドラーは、express ミドルウェアの動作と同様のミドルウェア パターンに従います。 つまり、アクティビティ ハンドラーごとに、次のハンドラーに制御を渡すために呼び出すことができる next 関数が渡されます。 これにより、同じアクティビティをさまざまな方法で処理できるハンドラーのチェーンを構築できます。
app.on('message', async ({ next }) => {
console.log('global logger');
next(); // pass control onward
});
app.on('message', async ({ activity, next }) => {
if (activity.text === '/help') {
await send('Here are all the ways I can help you...');
return;
}
// Conditionally pass control to the next handler
next();
});
app.on('message', async ({ activity }) => {
// Fallthrough to the final handler
await send(`Hello! you said ${activity.text}`);
});
アクティビティ リファレンス
このアプリケーションでは、さまざまなアクティビティ タイプがサポートされています。
コア アクティビティ ルート
| ルート | 責任 |
|---|---|
message |
ユーザーがアプリにメッセージを送信 |
typing |
入力インジケーターを送信して、アプリがユーザーのメッセージを受け取り、応答を計算していることを示します |
deleteUserData |
ユーザーがプライバシー規制に従ってデータの削除を要求した場合にトリガーされます |
mention |
ボットが会話で @mentioned されたときにトリガーされる |
構成ルート
| ルート | パスの呼び出し | 責任 |
|---|---|---|
config.open |
config/fetch |
アプリがインストールされると、ユーザーはダイアログを使用してアプリを構成できます |
config.submit |
config/submit |
構成ダイアログの送信 |
tab.open |
tab/fetch |
タブ構成エクスペリエンスを初期化します |
tab.submit |
tab/submit |
プロセス タブ構成の提出 |
ダイアログ ルート
| ルート | パスの呼び出し | 責任 |
|---|---|---|
dialog.open |
task/fetch |
ダイアログを開く |
dialog.submit |
task/submit |
ダイアログの送信を処理する |
認証ルート
| ルート | パスの呼び出し | 責任 |
|---|---|---|
signin.token-exchange |
signin/tokenExchange |
SSO 認証中にトークン交換が発生した場合 |
signin.verify-state |
signin/verifyState |
OAuth 後に検証に合格したとき |
メッセージの相互作用ルート
| ルート | パスの呼び出し | 責任 |
|---|---|---|
message.execute |
actionableMessage/executeAction |
アクションがメッセージに対して実行されました |
message.submit |
message/submitAction |
メッセージ アクションの送信を処理します |
card.action |
adaptiveCard/action |
ユーザーがアダプティブ カードのボタンまたはコントロールを操作するとトリガーされます |
ファイル処理ルート
| ルート | 責任 |
|---|---|
file.consent |
Teams でファイル共有許可ワークフローを管理する |
file.consent.accept |
ユーザーが共有のためのファイル同意カードを受け入れたときにトリガーされます |
file.consent.decline |
ユーザーが共有のためのファイル同意カードを拒否したときにトリガーされます |
メッセージ拡張機能のルート
| ルート | パスの呼び出し | 責任 |
|---|---|---|
message.ext.query-link |
composeExtension/queryLink |
インストールされているアプリケーションに対するリンク展開要求 |
message.ext.anon-query-link |
composeExtension/anonymousQueryLink |
匿名のリンク展開要求 |
message.ext.query |
composeExtension/query |
メッセージ拡張機能の検索クエリ |
message.ext.select-item |
composeExtension/selectItem |
メッセージ拡張機能アイテムの選択 |
message.ext.submit |
composeExtension/submitAction |
メッセージ拡張機能アクションの送信 |
message.ext.open |
composeExtension/fetchTask |
アクションのためのメッセージ拡張機能タスクのフェッチ |
message.ext.query-settings-url |
composeExtension/querySettingUrl |
メッセージ拡張機能の構成 URL を取得します |
message.ext.setting |
composeExtension/setting |
メッセージ拡張機能の設定の変更を処理します |
message.ext.card-button-clicked |
composeExtension/onCardButtonClicked |
メッセージ拡張機能でのカード ボタンのクリック処理 |
message.ext.edit |
該当なし | メッセージ拡張機能のプレビュー編集を処理します |
message.ext.send |
該当なし | メッセージ拡張機能コンテンツの送信を処理します |
ライフサイクル ルート
| ルート | 責任 |
|---|---|
install.add |
アプリがチームまたはチャットに新しくインストールされたときにトリガーされます |
install.remove |
アプリがチームまたはチャットからアンインストールされたときにトリガーされます |
install.update |
チームまたはチャットでアプリが更新されたときにトリガーされます |
handoff.action |
別のエージェントからアプリケーションへのハンドオフを管理します |
会話の更新ルート
| ルート | 責任 |
|---|---|
membersAdded |
新しいユーザーがチームに参加した場合、またはボットがアクティブなチャットに追加されたときにトリガーされます |
membersRemoved |
ユーザーがチームを退出するか、ボットがアクティブなチャットから削除されたときにトリガーされます |
channelCreated |
ボットがインストールされているチームで新しいチャネルが作成されるとトリガーされます |
channelRenamed |
ボットがインストールされているチームでチャネルの名前が変更されたときにトリガーされる |
channelDeleted |
ボットがインストールされているチームからチャネルが削除されたときにトリガーされます |
channelRestored |
以前に削除したチャネルが復元されたときにトリガーされます |
teamArchived |
チームがアーカイブされたときにトリガーされる |
teamDeleted |
ボットがインストールされている場所でチームが削除されたときにトリガーされます |
teamHardDeleted |
チームが完全に削除されたときにトリガーされます (回復不可能) |
teamRenamed |
ボットがインストールされている場所でチームの名前が変更されたときにトリガーされます |
teamRestored |
以前に削除したチームが復元されたときにトリガーされる |
teamUnarchived |
チームがアーカイブ解除されたときにトリガーされる |
messageUpdate |
ボットとの会話でメッセージが編集されたときにトリガーされます |
messageDelete |
ボットとの会話中にメッセージが削除されたときにトリガーされる |
会議ルート
| ルート | パスの呼び出し | 責任 |
|---|---|---|
meetingStart |
application/vnd.microsoft.meetingStart |
ボットが存在する Teams 会議の開始時にトリガーされる |
meetingEnd |
application/vnd.microsoft.meetingEnd |
ボットが存在する Teams 会議の終了時にトリガーされる |
meetingParticipantJoin |
application/vnd.microsoft.meetingParticipantJoin |
ボットが存在する Teams 会議に参加者が参加するとトリガーされます |
meetingParticipantLeave |
application/vnd.microsoft.meetingParticipantLeave |
ボットが存在する Teams 会議で参加者が退出するとトリガーされます |
readReceipt |
application/vnd.microsoft.readReceipt |
メッセージがユーザーによっていつ開封されたかを追跡します |