アクティビティの聞き取り

アクティビティは、ユーザーとボットの間を流れる Teams 固有のペイロードです。 イベントがアプリ内の高レベルの出来事を説明する場合、アクティビティはチャット テキスト、カード アクション、インストール、呼び出し呼び出しなどの未加工の Teams メッセージです。

Teams SDK は Fluent ルーターを公開しているため、最小限の API を使用して専用ハンドラー メソッドでこれらのアクティビティをサブスクライブできます。

Teams SDK は Fluent ルーターを公開しているので、 @app.event("activity") でこれらのアクティビティをサブスクライブできます。

Teams SDK は Fluent ルーターを公開しているので、 app.on('<route>', …) でこれらのアクティビティをサブスクライブできます。

アプリ サーバーに到達する Teams イベントを示すフローチャート。アプリ サーバーは、アクティビティ ハンドラーを呼び出すアクティビティ ルーター (app.on()) にアクティビティ イベントを送信します。

基本的なメッセージ ハンドラーの例を次に示します。

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 メッセージがユーザーによっていつ開封されたかを追跡します