Teams アプリにメッセージ拡張機能を追加する

[アーティクル]
12/17/2024

メッセージ拡張機能を使用すると、ユーザーはMicrosoft Teamsでメッセージを作成するときに Web サービスと対話できます。ユーザーは Web サービスを呼び出して、メッセージ作成ボックスまたは検索バーからメッセージの合成を支援できます。

メッセージ拡張機能は、Teams の Bot Framework アーキテクチャに基づいて構築されています。詳細については、「ビルドメッセージ拡張機能」を参照してください。

前提条件

アプリでメッセージ拡張機能を構成するには、次の前提条件が満たされていることを確認します。

Teams アプリとそのマニフェスト (以前は Teams アプリマニフェストと呼ばれる) ファイル
アプリをテストするための Microsoft 365 アカウント
Microsoft Azure アカウント

タブアプリにメッセージ拡張機能を追加するには、次の手順に従います。

Microsoft Teams Toolkit を使用してメッセージ拡張機能アプリを作成する
アプリマニフェストでメッセージ拡張機能を構成する
プロジェクトにメッセージ拡張コードを追加する
ローカルデバッグ環境のセットアップ
アプリを Azure にプロビジョニングする

Microsoft Teams Toolkit を使用してメッセージ拡張機能アプリを作成する

Teams Toolkit でメッセージ拡張機能アプリを作成するには、「Teams Toolkit を使用してメッセージ拡張機能アプリを作成する」を参照してください。

アプリマニフェストでメッセージ拡張機能を構成する

メッセージ拡張機能は、 appPackage/manifest.json ファイルで構成できます。詳細については、「アプリマニフェストスキーマ」を参照してください。

次のコードスニペットは例です。

"composeExtensions": [
    {
        "botId": "${{BOT_ID}}",
        "commands": [
            {
                "id": "createCard",
                "context": [
                    "compose"
                ],
                "description": "Command to run action to create a Card from Compose Box",
                "title": "Create Card",
                "type": "action",
                "parameters": [
                    {
                        "name": "title",
                        "title": "Card title",
                        "description": "Title for the card",
                        "inputType": "text"
                    },
                    {
                        "name": "subTitle",
                        "title": "Subtitle",
                        "description": "Subtitle for the card",
                        "inputType": "text"
                    },
                    {
                        "name": "text",
                        "title": "Text",
                        "description": "Text for the card",
                        "inputType": "textarea"
                    }
                ]
            },
            {
                "id": "shareMessage",
                "context": [
                    "message"
                ],
                "description": "Test command to run action on message context (message sharing)",
                "title": "Share Message",
                "type": "action",
                "parameters": [
                    {
                        "name": "includeImage",
                        "title": "Include Image",
                        "description": "Include image in Hero Card",
                        "inputType": "toggle"
                    }
                ]
            },
            {
                "id": "searchQuery",
                "context": [
                    "compose",
                    "commandBox"
               ],
               "description": "Test command to run query",
               "title": "Search",
                "type": "query",
                "parameters": [
                    {
                        "name": "searchQuery",
                        "title": "Search Query",
                        "description": "Your search query",
                        "inputType": "text"
                    }
                ]
            }
        ],
        "messageHandlers": [
            {
                "type": "link",
                "value": {
                    "domains": [
                        "*.botframework.com"
                    ]
                }
            }
        ]
    }
]

プロジェクトにメッセージ拡張コードを追加する

Visual Studio Code のタブプロジェクトに bot/ フォルダーを作成します。メッセージ拡張アプリのソースコードをフォルダーにコピーします。プロジェクトのフォルダー構造は次のようになります。

|--.vscode/
|--appPackage/
|--env/
|--infra/
|--public/
|--bot/           <!--message extension source code-->
|   |--index.ts
|   |--config.ts
|   |--teamsBot.ts
|   |--package.json
|   |--tsconfig.json
|   |--web.config
|   |--.Webappignore
|--src/            <!--your current source code-->
|   |--app.ts
|   |--static/
|   |--views/
|--package.json
|--tsconfig.json
|--teamsapp.local.yml
|--teamsapp.yml

フォルダー構造を次のように再構成します。

ヒント

ルート package.json ファイルを作成するには、コマンド npm init -yを使用します。

|--.vscode/
|--appPackage/
|--env/
|--infra/
|--bot/            <!--message extension source code-->
   |--index.ts
|   |--config.ts
|   |--teamsBot.ts
|   |--package.json
|   |--tsconfig.json
|   |--web.config
|   |--.Webappignore
|--tab/           <!--move your current source code to a new sub folder-->
|   |--src/
|   |   |--app.ts
|   |   |--static/
|   |   |--views/
|   |--package.json
|   |--tsconfig.json
|--package.json <!--root package.json-->
|--teamsapp.local.yml
|--teamsapp.yml

ルート package.jsonに次のコードを追加します。

"scripts": {
  "test": "echo \"Error: no test specified\" && exit 1",
  "install:bot": "cd bot && npm install",
  "install:tab": "cd tab && npm install",
  "install": "concurrently \"npm run install:bot\" \"npm run install:tab\"",
  "dev:bot": "cd bot && npm run dev",
  "start:tab": "cd tab && npm run start",
  "build:tab": "cd tab && npm run build",
  "build:bot": "cd bot && npm run build",
  "build": "concurrently \"npm run build:tab\" \"npm run build:bot\""
},
"dependencies": {
    "concurrently": "^7.6.0"
},

注:

JavaScript プロジェクトでは、 build フォルダーなしでプロジェクトを実行できます。 build:bot スクリプトを削除し、build スクリプトをnpm run build:tabに更新する必要があります。

ローカルデバッグ環境のセットアップ

.vscode/tasks.jsonを次のように更新します。

Start local tunnel、Start bot、Start frontendの 3 つの新しいタスクを追加します。
Start botとStart frontendを含むように、Start application タスクのdependsOn配列を更新します。
Start botとStart frontendのcwd オプションを構成します。このアクションは、フォルダー構造の再構成中にタブとボットのコードをそれぞれのフォルダーに移動したので必要です。
Start Teams App Locally タスクの dependsOn 配列にStart local tunnelを追加します。

"tasks":[
        {
            // Start the local tunnel service to forward public URL to local port and inspect traffic.
            // See https://aka.ms/teamsfx-tasks/local-tunnel for the detailed args definitions.
            "label": "Start local tunnel",
            "type": "teamsfx",
            "command": "debug-start-local-tunnel",
            "args": {
                "type": "dev-tunnel",
                "ports": [
                    {
                        "portNumber": 3978,
                        "protocol": "http",
                        "access": "public",
                        "writeToEnvironmentFile": {
                            "endpoint": "BOT_ENDPOINT", // output tunnel endpoint as BOT_ENDPOINT
                            "domain": "BOT_DOMAIN" // output tunnel domain as BOT_DOMAIN
                        }
                    }
                ],
                "env": "local"
            },
            "isBackground": true,
            "problemMatcher": "$teamsfx-local-tunnel-watch"
        },
        {
            "label": "Start bot",
            "type": "shell",
            "command": "npm run dev:teamsfx",
            "isBackground": true,
            "options": {
                "cwd": "${workspaceFolder}/bot"
            },
            "problemMatcher": {
                "pattern": [
                    {
                        "regexp": "^.*$",
                        "file": 0,
                        "location": 1,
                        "message": 2
                    }
                ],
                "background": {
                    "activeOnStart": true,
                    "beginsPattern": "[nodemon] starting",
                    "endsPattern": "restify listening to|Bot/ME service listening at|[nodemon] app crashed"
                }
            }
        },
        {
           "label": "Start frontend",
           "type": "shell",
           "command": "npm run dev:teamsfx",
           "isBackground": true,
           "options": {
                "cwd": "${workspaceFolder}/tab"
            },
            "problemMatcher": {
                "pattern": {
                    "regexp": "^.*$",
                    "file": 0,
                    "location": 1,
                    "message": 2
                },
                "background": {
                    "activeOnStart": true,
                    "beginsPattern": ".*",
                    "endsPattern": "listening to|Compiled|Failed|compiled|failed"
                }
            }
        },
         {
             "label": "Start application",
             "dependsOn": [
                 "Start bot",
                 "Start frontend"
             ]
         },
         {
             "label": "Start Teams App Locally",
             "dependsOn": [
                 "Validate prerequisites",
                 "Start local tunnel",
                 "Provision",
                 "Deploy",
                 "Start application"
             ],
             "dependsOrder": "sequence"
         },
]

teamsapp.local.yml ファイルの下:

[ provision] で、 botAadApp/create と botFramework/create アクションを追加します。
[ deploy] で、 file/createOrUpdateEnvironmentFile アクションのコードを更新します。

provision:
  - uses: botAadApp/create
    with:
      # The Microsoft Entra application's display name
      name: bot-${{TEAMSFX_ENV}}
    writeToEnvironmentFile:
      # The Microsoft Entra application's client id created for bot.
      botId: BOT_ID
      # The Microsoft Entra application's client secret created for bot.
      botPassword: SECRET_BOT_PASSWORD 

  # Create or update the bot registration on dev.botframework.com
  - uses: botFramework/create
    with:
      botId: ${{BOT_ID}}
      name: bot
      messagingEndpoint: ${{BOT_ENDPOINT}}/api/messages
      description: ""
      channels:
        - name: msteams
deploy:
  - uses: file/createOrUpdateEnvironmentFile # Generate runtime environment variables
    with:
      target: ./tab/.localConfigs
      envs:
        BROWSER: none
        HTTPS: true
        PORT: 53000
        SSL_CRT_FILE: ${{SSL_CRT_FILE}}
        SSL_KEY_FILE: ${{SSL_KEY_FILE}}

  - uses: file/createOrUpdateEnvironmentFile # Generate runtime environment variables
    with:
      target: ./bot/.localConfigs
      envs:
        BOT_ID: ${{BOT_ID}}
        BOT_PASSWORD: ${{SECRET_BOT_PASSWORD}}

詳細については、「サンプルアプリ」を参照してください。

[実行とデバッグ] で、[デバッグ (Edge)] または [デバッグ (Chrome)] を選択します。
F5 キーを選択して、Teams アプリをローカルでデバッグしてプレビューします。

アプリを Azure にプロビジョニングする

botRegistration/ フォルダーをコピーし、[infra/] の下に追加します。

azure.bicep ファイルに次のコードを追加します。

param resourceBaseName2 string
param webAppName2 string = resourceBaseName2
@maxLength(42)
param botDisplayName string
@description('Required when create Azure Bot service')
param botAadAppClientId string
@secure()
@description('Required by Bot Framework package in your bot project')
param botAadAppClientSecret string
resource webApp2 'Microsoft.Web/sites@2021-02-01' = {
  kind: 'app'
  location: location
  name: webAppName2
  properties: {
    serverFarmId: serverfarm.id
    httpsOnly: true
    siteConfig: {
      alwaysOn: true
      appSettings: [
        {
          name: 'WEBSITE_RUN_FROM_PACKAGE'
          value: '1' // Run Azure APP Service from a package file
        }
        {
          name: 'WEBSITE_NODE_DEFAULT_VERSION'
          value: '~18' // Set NodeJS version to 18.x for your site
        }
        {
          name: 'RUNNING_ON_AZURE'
          value: '1'
        }
        {
          name: 'BOT_ID'
          value: botAadAppClientId
        }
        {
          name: 'BOT_PASSWORD'
          value: botAadAppClientSecret
        }
      ]
      ftpsState: 'FtpsOnly'
    }
  }
}
// Register your web service as a bot with the Bot Framework
module azureBotRegistration './botRegistration/azurebot.bicep' = {
  name: 'Azure-Bot-registration'
  params: {
    resourceBaseName: resourceBaseName
    botAadAppClientId: botAadAppClientId
    botAppDomain: webApp2.properties.defaultHostName
    botDisplayName: botDisplayName
  }
}
// The output will be persisted in .env.{envName}. Visit https://aka.ms/teamsfx-actions/arm-deploy for more details.
output BOT_AZURE_APP_SERVICE_RESOURCE_ID string = webApp2.id
output BOT_DOMAIN string = webApp2.properties.defaultHostName

必要なパラメーターが正しく設定されていることを確認するには、次のコードを使用して azure.parameters.json ファイルを更新します。

{
"$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
"contentVersion": "1.0.0.0",
"parameters": {
  "resourceBaseName": {
    "value": "tab${{RESOURCE_SUFFIX}}"
  },
  "webAppSku": {
    "value": "B1"
  },
  "botAadAppClientId": {
    "value": "${{BOT_ID}}"
  },
  "botAadAppClientSecret": {
    "value": "${{SECRET_BOT_PASSWORD}}"
  },
  "botDisplayName": {
    "value": "bot"
  },
  "resourceBaseName2":{
    "value": "bot${{RESOURCE_SUFFIX}}"
  }
}

teamsapp.yml ファイルの下:

[ provision] で、 botAadApp/create アクションを追加します。詳細については、「サンプルアプリ」を参照してください。
[ deploy ] セクションで、次のコードを追加します。

deploy:
  - uses: cli/runNpmCommand # Run npm command
    with:
      args: install
  - uses: cli/runNpmCommand # Run npm command
    with:
      args: run build
  # Deploy bits to Azure Storage Static Website
  - uses: azureAppService/zipDeploy
    with:
      workingDirectory: ./tab
      # Deploy base folder
      artifactFolder: .
      # Ignore file location, leave blank will ignore nothing
      ignoreFile: .webappignore
      # The resource id of the cloud resource to be deployed to.
      # This key will be generated by arm/deploy action automatically.
      # You can replace it with your existing Azure Resource id
      # or add it to your environment variable file.
      resourceId: ${{TAB_AZURE_APP_SERVICE_RESOURCE_ID}}
  - uses: azureAppService/zipDeploy
    with:
      workingDirectory: ./bot
      # Deploy base folder
      artifactFolder: .
      # Ignore file location, leave blank will ignore nothing
      ignoreFile: .webappignore
      # The resource id of the cloud resource to be deployed to.
      # This key will be generated by arm/deploy action automatically.
      # You can replace it with your existing Azure Resource id
      # or add it to your environment variable file.
      resourceId: ${{BOT_AZURE_APP_SERVICE_RESOURCE_ID}}

[表示>コマンドパレット.... に移動するか、Ctrl + Shift + P キーを押します。
「 Teams: Provision 」と入力して、bicep を Azure に適用します。
「 Teams: Deploy 」と入力して、タブアプリコードを Azure にデプロイします。
[ 実行とデバッグ] で、[ リモートの起動 (Edge)] または [ リモートの起動 (Chrome)] を選択します。
F5 キーを選択して、Teams アプリをデバッグしてプレビューします。

メッセージ拡張機能は Bot Framework 上に構築されているため、メッセージ拡張機能機能をボットアプリに簡単に追加できます。

ボットアプリにメッセージ拡張機能を追加するには、次の手順に従います。

Teams Toolkit を使用してメッセージ拡張機能アプリを作成する
アプリマニフェストでメッセージ拡張機能を構成する
メッセージ拡張コードをプロジェクトに追加する

Teams Toolkit を使用してメッセージ拡張機能を作成する

メッセージ拡張機能アプリを作成するには、「 Teams Toolkit を使用してメッセージ拡張機能アプリを作成する」を参照してください。

アプリマニフェストでメッセージ拡張機能を構成する

メッセージ拡張機能は、 appPackage/manifest.jsonで構成できます。詳細については、「アプリマニフェストスキーマ」を参照してください。

次のコードスニペットは例です。

"composeExtensions": [
    {
        "botId": "${{BOT_ID}}",
        "commands": [
            {
                "id": "createCard",
                "context": [
                    "compose"
                ],
                "description": "Command to run action to create a Card from Compose Box",
                "title": "Create Card",
                "type": "action",
                "parameters": [
                    {
                        "name": "title",
                        "title": "Card title",
                        "description": "Title for the card",
                        "inputType": "text"
                    },
                    {
                        "name": "subTitle",
                        "title": "Subtitle",
                        "description": "Subtitle for the card",
                        "inputType": "text"
                    },
                   {
                        "name": "text",
                        "title": "Text",
                        "description": "Text for the card",
                        "inputType": "textarea"
                    }
                ]
            },
            {
                "id": "shareMessage",
                "context": [
                    "message"
                ],
                "description": "Test command to run action on message context (message sharing)",
                "title": "Share Message",
                "type": "action",
                "parameters": [
                    {
                        "name": "includeImage",
                        "title": "Include Image",
                        "description": "Include image in Hero Card",
                        "inputType": "toggle"
                    }
                ]
            },
            {
                "id": "searchQuery",
                "context": [
                    "compose",
                    "commandBox"
                ],
                "description": "Test command to run query",
                "title": "Search",
                "type": "query",
                "parameters": [
                    {
                        "name": "searchQuery",
                        "title": "Search Query",
                        "description": "Your search query",
                        "inputType": "text"
                    }
                ]
            }
        ],
        "messageHandlers": [
            {
                "type": "link",
                "value": {
                    "domains": [
                        "*.botframework.com"
                    ]
               }
            }
        ]
    }
]

メッセージ拡張コードをプロジェクトに追加する

ボットアプリには、 TeamsActivityHandlerを拡張するクラスが含まれています。メッセージ拡張機能アプリから Visual Studio Code のこのクラスにメッセージ拡張関数をコピーします。次のコードは、Teams Toolkit で作成されたメッセージ拡張機能アプリの関数を含むボットの例です。

  class YourHandler extends TeamsActivityHandler {
  /**
   * your own code
   */
  //message extension code
  // Action.
  public async handleTeamsMessagingExtensionSubmitAction(
    context: TurnContext,
    action: any
  ): Promise<any> {}
  // Search.
  public async handleTeamsMessagingExtensionQuery(
    context: TurnContext,
    query: any
  ): Promise<any> {}
  public async handleTeamsMessagingExtensionSelectItem(
    context: TurnContext,
    obj: any
  ): Promise<any> {}
  // Link Unfurling.
  public async handleTeamsAppBasedLinkQuery(
    context: TurnContext,
    query: any
  ): Promise<any> {}
}
async function createCardCommand(
  context: TurnContext,
  action: MessagingExtensionAction
): Promise<MessagingExtensionResponse> {}
async function shareMessageCommand(
  context: TurnContext,
  action: MessagingExtensionAction
): Promise<MessagingExtensionResponse> {}

[表示>コマンドパレット.... に移動するか、Ctrl + Shift + P キーを押します。
「 Teams: Provision 」と入力して、bicep を Azure に適用します。
「 Teams: Deploy 」と入力して、タブアプリコードを Azure にデプロイします。
[ 実行とデバッグ] で、[ リモートの起動 (Edge)] または [ リモートの起動 (Chrome)] を選択します。
F5 キーを選択して、Teams アプリをデバッグしてプレビューします。

次の手順

機能を追加するためのハウツーガイド

次の方法で共有

Teams アプリにメッセージ拡張機能を追加する

前提条件

Teams アプリにメッセージ拡張機能を追加する

Microsoft Teams Toolkit を使用してメッセージ拡張機能アプリを作成する

アプリマニフェストでメッセージ拡張機能を構成する

プロジェクトにメッセージ拡張コードを追加する

ローカルデバッグ環境のセットアップ

アプリを Azure にプロビジョニングする

Teams Toolkit を使用してメッセージ拡張機能を作成する

アプリマニフェストでメッセージ拡張機能を構成する

メッセージ拡張コードをプロジェクトに追加する

次の手順

関連項目

その他のリソース

次の方法で共有

Teams アプリにメッセージ拡張機能を追加する

前提条件

Teams アプリにメッセージ拡張機能を追加する

Microsoft Teams Toolkit を使用してメッセージ拡張機能アプリを作成する

アプリ マニフェストでメッセージ拡張機能を構成する

プロジェクトにメッセージ拡張コードを追加する

ローカル デバッグ環境のセットアップ

アプリを Azure にプロビジョニングする

次の手順

関連項目

その他のリソース

アプリマニフェストでメッセージ拡張機能を構成する

ローカルデバッグ環境のセットアップ