PHONE APPLI Engineer blog

エンジニアブログ

Teams Toolkit を使用して爆速で Bot を開発しリリースに漕ぎ着ける

はじめに

こんにちは。リサーチデベロップメント の後藤です。

突然ですが、先日 MS Teams の Bot について調べていたところ、Teams Toolkit という、それはそれは魅力的な開発ツールに出会い、色々と感動してしまいました。

そのため、今回はタイトルの通りは、Teams Toolkit を使用して爆速で Bot を開発しリリースに漕ぎ着ける ことで、このツールの魅力の片鱗を、少しでも皆さんにお伝えできればと思っています！

Teams Toolkit とは

さて、MS Teams の Bot に触れたことのある皆さん、Bot を開発する際に、これまでどんな工程で作業を進めていましたか？

今回ご紹介する Teams Toolkit を使用すれば、これまでの開発工程を大きく削減できるかもしれないです！

Teams Toolkit とは、Visual Studio Code もしくは Visual Studio で使用できる拡張機能、または CLI であり、MS Teams の Bot を開発〜リリースするために必要なさまざまな機能が用意されています。

docs.microsoft.com

そして現在、このTeams Toolkit というツールは、以下の方法で利用できるようです。

  1. Teams Toolkit for Visual Studio Code
  2. Teams Toolkit for Visual Studio
  3. TeamsFx CLI
  4. TeamsFx SDK for TypeScript (JavaScript)

当記事では Teams Toolkit for Visual Studio Code を使用していきます。

しかし、普段から Visual Studio Code や Visual Studio を使っていない方々もご安心ください！

TeamsFx CLI を使用すれば、これらを使わなくても以降紹介する機能群がコマンドラインで実行できるようになります。

Teams Toolkit for Visual Studio Code (or Visual Studio) や TeamsFx CLI の裏側では、teamsfx core と teamsfx api が動いているため、興味があるかたはこちらのソースコードを覗きにいくと、より挙動が理解できるかもしれません。

それでは、次項から実際にこのツールを使用し開発をしていきたいと思います。

セットアップから開発へ

今回は Bot に送信したメッセージを、そのままユーザに返信するアプリケーション、「Echo Bot」 を作っていきます。

以下がこの項での手順になります。

手順

  1. プロジェクトの生成
  2. Login (M365 & Azure)
  3. ※ アプリケーションロジックの追加
  4. F5キーによるローカルデバッグ

それでは、セットアップ・開発・デバッグの各工程を以下に説明していきます！

プロジェクトの生成

まずは、Visual Studio Code の拡張機能として、Teams Toolkit をインストールします。

marketplace.visualstudio.com

インストール後、下図のように Teams Toolkit UI が表示されるので、"create a new Teams app" を選択します。

選択後にいくつか質問があるので、今回は以下のように回答します。

  • Select at least 1 capbility → Bot
  • Select a programming language → JavaScript
  • Application Name → EchoBot

生成されたプロジェクトの全体像は以下になります。

.
├── bot
│   ├── README.md
│   ├── adaptiveCards
│   │   ├── learn.json
│   │   └── welcome.json
│   ├── images
│   │   ├── AdaptiveCard.png
│   │   ├── AtBotFromSearch.png
│   │   ├── AtBotInMessage.png
│   │   ├── LinkUnfurlingImage.png
│   │   ├── ShareMessage.png
│   │   ├── ThreeDot.png
│   │   └── ThreeDotOnMessage.png
│   ├── index.js
│   ├── package.json
│   └── teamsBot.js
├── package.json
├── permissions.json
└── templates
    ├── appPackage
    │   ├── manifest.local.template.json
    │   ├── manifest.remote.template.json
    │   └── resources
    │       ├── color.png
    │       └── outline.png
    └── azure
        ├── config.bicep
        ├── main.bicep
        ├── provision
        │   ├── bot.bicep
        │   └── identity.bicep
        ├── provision.bicep
        └── teamsFx
            └── bot.bicep

9 directories, 25 files

JavaScript の SDK であれば、以前は Yeoman ジェネレーターを使って雛形を生成する方法があったと思います。

ボリュームの違いはあれど、Teams Toolkit でもこれと同じことができるということですね！

また、ここで生成されたプロジェクト内の Bicep ファイルや、設定用の json ファイルは、ローカルデバッグや Azure へのデプロイ等の作業で用い、デバッグ以降の工程でより細かい制御ができるようになります。

Login (M365 & Azure)

プロジェクトの生成が出来たら、次は Bot をデプロイする環境の設定です。

Teams Toolkit UI の ACCOUTS から M365 と Azure にログインします。

M365 の環境は、無料で使用できる Microsoft 365 開発者プログラム を利用しました！

開発者プログラムは、継続的に開発をしていると期限が伸び、実質永年無料で使うことができるようです。

アプリケーションロジックの追加

次は実際に動作する Bot のロジックを決めましょう。

生成されたプロジェクトでは、JavaScript の Bot Framework SDK が用いられているため、これを利用して Echo する動作を記述します。

以下のように /bot/teamsBot.js の一部を追記します。

// 26行目~

switch (txt) {
    case "welcome": {
        const card = cardTools.AdaptiveCards.declareWithoutData(rawWelcomeCard).render();
        await context.sendActivity({ attachments: [CardFactory.adaptiveCard(card)] });
        break;
    }
    case "learn": {
        this.likeCountObj.likeCount = 0;
        const card = cardTools.AdaptiveCards.declare(rawLearnCard).render(this.likeCountObj);
        await context.sendActivity({ attachments: [CardFactory.adaptiveCard(card)] });
        break;
    }
    // 追記箇所：　　Bot がエコーする動作
    default: {
        await context.sendActivity(txt);
        break;
    }
}

詳しい SDK の利用方法は割愛します、気になる方は以下をご参照ください。

docs.microsoft.com

F5キーによるローカルデバッグ

さて、次は確定したロジックがどのように動作するのか、プロジェクトをローカルPC上で試してみましょう。

プロジェクト生成時に自動生成されたデバッグ構成により、F5キー１発でこれまでバラバラだった以下のような作業がまとめておこなわれます！

  • AAD へアプリの登録
  • アプリマニフェストを Developer Portal で生成
  • ローカルサーバを起動し、ngrok にてエンドポイントを外部公開
  • Web ブラウザーを起動し、Teams にアプリをサイドロード

以前は、App Studio (Developer Portal) でアプリを作成し、zip ファイルをダウンロードして...などなど、 正直面倒くさい手順を踏んでいたのですが、これのおかげでかなりの効率化ができるようになりました！

個人的には Teams Toolkit で一番 Good なポイントだと思っています！

F5キーを押すことでアプリが実行し、下図のようになります。

アプリを「追加」すれば、Bot の動作を試せます！

また、この段階で AAD には自動的に二つのアプリが登録されます。

ひとつはプロジェクト全体のアプリ、もうひとつは Bot 機能のアプリ、になります。

Bot のアプリが生成されたことは、Bot Framework のサイトや Developer Portal 上でも確認でき、ここでは Bot ID と AAD のアプリケーションID が同じになっているはずです。

デプロイからリリースへ

前項で Bot のセットアップとロジックの追加が完了したため、次は Azure へのデプロイと組織へのリリースに向けた作業をおこなっていきます。

以下がこの項での手順になります。

手順

  1. プロビジョニング
  2. デプロイ
  3. リリース

Teams Toolkit では、下図のように Teams Toolkit UI でこれらの作業を簡単におこなうことができます。

プロビジョニング

Teams Toolkit ではデプロイの前に、まずはプロビジョニングという前工程を挟みます。

これは、アプリケーションコードをデプロイする前に、前もって Azure 上で使用するリソースを作成する作業になります。

プロビジョニングで作成されるリソースについては、生成したプロジェクトの Bicep ファイル等で制御が可能です。

Bot アプリではデフォルトで以下のリソースを作成します。

  • Azure Bot Service
  • Azure App Service
  • Azure App Service サービスプラン
  • マネージドID (ユーザ割り当て)

また、これらのリソースは、既存のリソースグループ内に作成するのか、それとも新規のリソースグループを作成して、そこにリソースを作成するのか、の選択も可能です。

Teams Toolkit ではこのプロビジョニング工程を 1クリック でおこなえます。

DEPLOYMENT の "Provision in the cloud" を押下します。

デプロイ

次はアプリケーションコードを前工程でプロビジョニングした App Service にデプロイします。

Teams Toolkit なら、これも 1クリック でおこなえます。

DEPLOYMENT の "Deploy to the cloud" を押下します。

また、このタイミングでF5キーによるローカルデバッグと同様に、AAD にアプリが二つ生成され、最終的には下図のように四つのアプリが登録されている状態になると思います。

リリース

最後に M365 の組織へのリリース作業をおこないます。

これまでと同じく Teams Toolkit UI のボタンをクリックするだけの簡単な作業になります。

DEPLOYMENT の "Publish to Teams" を押下します。

組織の Teams 管理者にアプリケーションの申請が届き、申請が通れば組織で Echo Bot を使用できるようになります！

以上で作業は終了です、後半は本当に簡単な作業でしたね！

おまけ：CI/CD (GitHub Actions)

Teams Toolkit UI で簡単に Azure に Bot をデプロイできましたが、実際の開発現場ではビルドやデプロイをおこなう際に、他にも様々なタスクが必要になってくると思います。

Teams Toolkit では、CI/CD のサポートもバッチリなので、そのような懸念も解消できます！

今回は GitHub Actions を使い、Azure へのデプロイを自動化してみます！

Teams Toolkit には GitHub Actions で利用できる、専用のアクションが用意されており、CI/CD のワークフローも簡単に作成が可能です。

M365 と Azure のクレデンシャルを GitHub のシークレットに設定し、以下のようなワークフローを構成すると、main ブランチへの push をトリガーに Azure へデプロイがおこなわれます。

name: Continuous Deployment

on:
  push:
    branches:
      - main

jobs:

  build-and-deploy:
    runs-on: ubuntu-latest
    env:
      M365_ACCOUNT_NAME: ${{secrets.M365_ACCOUNT_NAME}}
      M365_ACCOUNT_PASSWORD: ${{secrets.M365_ACCOUNT_PASSWORD}}
      M365_TENANT_ID: ${{secrets.M365_TENANT_ID}}
      # To specify the env name for multi-env feature.
      TEAMSFX_ENV_NAME: YOUR_ENV
      
    steps:
      # Setup environment.
      - uses: actions/setup-node@v2
        with:
          node-version: '14'
          
      - name: Checkout the code
        uses: actions/checkout@v2

      # Login Azure by service principal 
      - uses: OfficeDev/teamsfx-cli-action@v1
        with:
          commands: account login azure 
          service-principal: true
          username: ${{secrets.AZURE_SERVICE_PRINCIPAL_NAME}}
          password: ${{secrets.AZURE_SERVICE_PRINCIPAL_PASSWORD}}
          tenant: ${{secrets.AZURE_TENANT_ID}}
 
      # Deploy the code.
      - uses: OfficeDev/teamsfx-cli-action@v1
        with:
          commands: deploy
          env: ${{env.TEAMSFX_ENV_NAME}}

ベタな構成かもしれないですが、これだけでも十分便利ですね！

GitHub を用いた CI/CD をより詳しく知りたい方は、こちらを参照してみてください！

GitHub - OfficeDev/teamsfx-cli-action: teasmfx CI/CD action

おわりに

これまでの Teams アプリ開発を大幅に効率化する Teams Toolkit の魅力を、少しでもお伝えできていれば嬉しいです！

現在 (2022/02)、Teams Toolkit はプレビューのようですが、公式ドキュメントの文量も多いので、今後はこの Teams Toolkit が Teams アプリ開発のスタンダードになるのではないかと、個人的に思っています。

また、今回は試してみませんでしたが、M365 との関係が密接なため、Graph API の利用も簡単におこなえるようです。 Graph API が使えると、できることの幅が一気に広がるので是非試してみたいですね！

今後も Teams Toolkit の情報をキャッチアップし、この他のトピックも発信できればと思っています。

是非みなさんも一度 Teams Toolkit を使ってみてください！


PHONE APPLIについて

phoneappli.net
phoneappli.net