(영문 버전은 여기에:English Version)
마이크로소프트 팀즈 (Microsoft Teams)에 대해서 들어본 적이 있으신가요?
많은 기업들과 학교들이 기관 내에서 커뮤니케이션과 협력을 위해서 팀즈라는 제품을 많이 쓰고 있는데요, 이 팀즈라는 어플리케이션은 무엇일까요?
마이크로소프트 팀즈란?
마이크로소프트 팀즈 (이하 팀즈)는 채팅을 기본으로한 협력 플랫폼(chat-based collaboration platform)인데요, 문서 공유, 커뮤니케이션 그리고 온라인 미팅 등, 다른 사람들과 서로 협력할 때 유용한 기능과 툴을 사용할 수 있습니다.
팀즈 자체가 이러한 기능들을 제공하는 것 뿐만 아니라, 많은 API들을 제공해서 외부 어플리케이션 (third party applications)들이 팀즈 플랫폼과 연동될 수 있는 옵션도 제공하고 있습니다. 팀즈 플랫폼에서 작동하고자 하는 어플리케이션들은 다음과 같은 기능들을 구현해서 각자가 원하고자 하는 서비스를 제공할 수 있습니다.
각 앱은 저 위의 기능들 중에서 제공하고자 하는 서비스에 맞게 선택적으로 몇 가지를 선택하여 팀즈에서 제공하는 API를 사용해 팀즈와 연동시킬 수 있습니다.
오늘 이 포스트에서는 봇의 기능만을 가진 아주 간단한 앱을 만들어서 팀즈 플랫폼에 설치하여 사용하는 방법을 공유하고자 합니다. 이 포스트를 읽은 누군가에게 팀즈 앱을 만드는 프로젝트의 좋은 시작점이 되었으면 하는 바람입니다.
Target Audience
- 한번도 마이크로소프트 팀즈를 사용해보시지 않으셨지만, 한번 팀즈라는 제품에서 앱 개발에 대해서 관심이 있으신 분.
- 마이크로소프트 봇 개발에 관해서 배우고 싶으신 분.
결과물
이 포스트에서 주어진 스탭을 다 마치시고 나시면, 여러분이 보낸 메세지를 똑같이 프린트 해주는, 에코 봇(Echo Bot)을 만들 수 있습니다.
이 포스트에서 사용하는 Dev Environment
- Set-Up:
- Windows 10, Visual Studio*
- *Visual Studio 버전: 이 포스트에서 제공하는 팀즈 개발 과정은 ASP.NET Core Runtime 3.1를 필요로합니다. 이 3.1 버전은 Visual Studio 2019 최신 버전을 설치하셨다면, 자동적으로 설치 되어있습니다. 만약 예전 Visual Studio를 사용하고 계시다면, 따로 ASP.Net Core Runtime 3.1을 여기로 부터 다운받으실 수 있습니다.
- Visual Studio 각 버전이 어떤 버전이 ASP.Net Core Runtime 버전을 가지고 계신지 궁금하시다면, 위 같은 웹사이트에서 확인하실 수 있습니다.
- Windows 10, Visual Studio*
- Ngrok (또는 ngrok과 비슷한 다른 tunneling tool)
- Ngrok이나 다른 tunneling tool을 설치하지 않으셨다면, ngrok을 꼭 설치해주시길 바랍니다. 설치 방법은 여러가지가 있는데요, 저는 윈도우 환경에서는 Chocolatey 패키지 매니저를 사용해서 설치하는 것을 선호합니다. ngrok을 설치하는 다양한 방법은 여기서 확인하실 수 있습니다.
- .Net/C#
- 이 포스트에서 저는 .Net 플랫폼과 Bot Frameowrk SDK (가장 최신 버전 v4) C# 버전을 사용해서 봇을 만들려고 합니다.
- Bot Framework SDK는 C#뿐 아니라 다른 언어와 프레임워크에서 사용할 수 있도록 다양한 옵션들을 제공해주고 있습니다. 다른 옵션들은 여기에서 확인할 수 있습니다.
Step 1: 팀즈 무료버전 (Teams Free) 사인업하기
만약 팀즈를 한번도 사용해보시지 않으셨다면, 먼저 팀즈 사인업을 시작하도록 하겠습니다. 마이크로소프트 팀즈는 무료버전을 제공해주는데요, 이 무료버전에서도 팀즈의 코어 기능들을 사용하실 수 있습니다. (팀즈 무료버전과 유료버전의 차이점에 대해서 아시고 싶으시다면, 여기에서 확인하실 수 있습니다.)
팀즈 무료버전 사인업은 다음 포스트에 있는 설명서 순서를 따라 하시면 사인업을 하실 수 있습니다:
Sign up for Teams free
만약 Microsoft 365 Developer Subscription을 이미 가지고 계시다면, 여기서 오늘 봇을 만들기 위한 태스팅 팀즈를 만드는 방법에는 두 가지 초이스가 있습니다.
(1) 지금 현재 가지고 있는 팀즈가 있으시다면, 같은 팀즈를 사용하실 수 있습니다.
(2) 또는 무료로 testing tenant을 만드시는 방법이 있습니다.
- Testing Tenant 만드는 방법: Create an Office 365 Test Tenant (
Creating a test tenant섹션을 확인해주세요.)
Note: 이 포스트에서 제공하는 봇 만들기 실습 후, 테스팅 목적으로 만들어진 팀즈 어카운트를 지우고 싶다면 여기 포스트에서 제공하는 스탭을 따라하시면 됩니다.
Step 2: (optional) 팀즈 안에서 팀 만들기.
팀즈를 사인업 하신 후, 이제는 팀즈안에서 팀을 하나 만들어보도록 해봅시다. 비록 이 포스트에서는 봇을 1:1 chat에서 설치하는 것을 보여주지만, 같은 봇을 쉽게 팀 안에서 설치 하실 수도 있습니다.
이 포스트에서는 봇을 만드는 과정에 더 집중 하기 위해서, 팀즈 안에서 팀을 어떻게 만드는지 상세한 설명은 이 글 자체에서는 하지 않고 자세한 설명을 담고 있는 다른 포스트 링크를 쉐어도록 하겠습니다.
팀즈에서 팀 만드는 방법 : Create a team from scratch
Step 3: Bot Framework v4 SDK Template Visual Studio Extension 설치하기
Bot Framework V4 SDK 탬플릿 (template)은 봇 만드는 과정을 아주 쉽게 만들어주는데요, Visual Studio extension으로 설치하실 수 있습니다. 이 Extension은 여러분이 봇을 쉽게 개발 할 수 있도록 작동하는 봇을 만들기 위해 필요로하는 기본적인 파일들과 설치 환경을 제공해줍니다.
Template extension은 여기서 다운받으실 수 있씁니다.
Step 4: Echo Bot (Bot Framework v4- .Net Core 3.1) 탬플랫으로 프로젝트 만들기.
Extension 다운로드가 끝나고 나면, 다음과 같이 프로젝트를 만들어줍니다.
Visual Studio 열기 ->
Create a new project클릭하기 ->Echo Bot (Bot Framework v4- .Net Core 3.1)찾고 설치하기.
Step 5: appsettings.json 파일 열기.
프로젝트를 만들고 나면, 다음과 같은 파일 구조를 보실 수 있습니다.
여기서 appsettings.json 파일이 하이라이트 된 이유는, 이 파일의MicrosoftAppId 와 MicrosoftAppPassword를 곧 업데이트해야 되기 때문입니다.
한가지 좋은 소식을 미리 스포일러하자면 이 포스트에서는 필요한 유일한 코딩은 바로 이 두 가지 필드를 업데이트하는 것 뿐이라는 것입니다 :)
Step 6: Command Prompt에서 ngrok http -host-header=rewrite 3978 명령 돌리기.
위 명령을 command prompt에서 돌리시게 될 경우, 다음과 같이 ngrok이 public url이 command prompt에 나타나짐을 보실 수 있습니다.
이 public url은 조금있다가 사용될 예정이니, 이 프람트를 닫지 마시고 열어주세요.
Note: 우리가 여기서 포트 3978을 사용하는 이유는 이 포트가 탬플릿과 함께오는 기본 값이기 때문입니다. 이 포트 값은 Properties 폴더 안에 있는 launchSettings.json 파일에서 정해져있는데요, 만약 이 포트 값을 바꾸시고 싶으시다면, 바꾸셔도 됩니다.
Step 7: App Studio라는 앱을 팀즈 클라이언트에 설치하기
Ngrok을 돌리시고 나신 후, 다시 팀즈 클라인어트로 돌아와서 App Studio라는 앱을 설치해주세요.
이 앱은 마이크로소프트 팀즈 앱을 만들거나 본인이 가지고 있는 다른 서비스를 팀즈에 인터그레이트 (integrate) 시킬 때 굉장히 유용한 앱입니다.
그래서 저는 개인적으로 이 앱은 여러분의 팀즈 클라이언트에 핀(pin)을 해도 좋을 것 같습니다. (App Studio에 대한 더 많은 정보는 여기 서 확인하실 수 있습니다.)
Step 8: App Studio 앱 클릭 -> Manifest 탭 클릭 -> Create a new app 클릭
Step 9: App Details 폼(form) 채우기.
Create a new app을 클릭하고 나면, App Details라는 페이지가 보이실텐데요, 이 페이지는 여러분이 팀즈에 설치하고자 하는 앱에 대한 정보를 적는 곳입니다. 여기서 필요로하는 대부분의 칸은 채워주세요.
Notes:
- Asterisk sign(*)이 있는 곳은 꼭 채워주세요. must be filled out.
- 여기서 보이는
App ID는appsettings.json에 필요로하는 값이 아닙니다. 따라서 이 앱 아이디 값은 복사할 필요가 없어요. - 테스팅 목적으로서는 진짜 값을 넣을 필요가 없습니다. Placeholder 값을 넣으셔도 됩니다. (ex: https://www.teams.com/privacy)
- 만약이
App Detils페이지가 제대로 작성되지 않으면,Test Distribute섹션에 에러 메세지가 뜨게 됩니다.
Step 10: Bots 클릭하고 Set Up 클릭하기.
Step 11: Set up 클랙했을 때 나오는 팝업 폼 작성하기.
테스트 목적으로, 봇이 1:1 챗, 팀, 그리고 그룹 챗에 설치 될 수 있도록 허락합니다. 그리고 Click Bot을 클릭하세요.
Step 12: 봇 이름 밑에 있는 id를 복사해서 appsettings.json에 있는 MicrosoftAppId의 value로 붙여넣기.
Create bot을 누르자마자, 봇 아이디가 생성되신 것을 보실 수 있을 실 거에요 (첫 번째 스크린샷) 이 아이디가 바로 우리에게 필요한 아이디입니다. 이 아이디를 appsettings.json파일에 첫 번째 key인 MicrosoftAppId value 값으로 넣어주세요 (두 번째 스크린 샷)
Step 13: Generate New Password 클릭해서 앱 패스워드 값 생성하기.
Generate New Password를 누른 후 생성되는 패스워드의 값은 한번만 보여지니, 값이 보일 때 복사를 해서, appsettings.json 파일에 있는 MicrosoftAppPassword 의 값으로 넣어주세요.
Step 14: 봇 서비스를 local 환경에서 돌리기.
자 이제 여러분의 첫 번째 봇 서비스인, Echobot이 완성이 되었습니다. 이제 F5를 누르거나 Visual Studio에서 보이는 start를 눌러 서비스를 local 환경에서 돌아갈 수 있도록합니다. 만약 모든 것이 다 제대로 컴파일 되서 작동을 한다면, 여러분의 브라우저에서 localhost::3978 page를 보실 수 있습니다.
Step 15: 다시 App Studio의 Bot section으로 돌아와서, Messaging Endpoint를 <ngrok url>/api/messages value로 작성하기.
Step 6에서 우리는 ngrok을 통해서 localhost::3978을 연결 (tunneling)해주는 public url을 생성하였습니다. 이제 그 값을 복사해서, Bot endpoint address에 붙여주세요. 붙이고 난 후, 꼭 /api/messages를 ngrok public url 다음에 적어줍니다. 이유는 이 /api/messages가 바로 bot service가 request를 들을 수 있는 endpoint이기 때문입니다.
자 이제 우리는 여러분의 봇을 팀즈 플랫폼에 설치할 준비가 다 끝났습니다. 이제 봇을 여러분의 팀즈에 애드(add)해서 봇과 함께 interaction할 수 있도록 해봅시다.
Step 16: Test and distribute 섹션으로 가서, Description 칸에 아무 메세지도 없는지 확인하기.
Description 칸에 아무것도 보이시지 않으신다면, 팀즈에서 필요로하는 모든 정보가 제대로 작성되었다는 것을 의미합니다. 만약 메세지를 보신다면, 그 메세지가 말하는 부분을 꼭 고쳐주세요.
Step 17: Install 대신에 Download 를 클릭하기.
유료의 팀즈의 경우거나, Microsoft Developer Program Subscription을 사용하셔서 testing tenant을 만든 경우에는 Install을 클릭하셔서 봇을 원하는 공간(ex: 1:1 챗, 그룹 챗, 팀)에 추가하시면 됩니다. 그러나 팀즈 무료버전의 경우에는, 이렇게 바로 추가할 수 있는 권한이 사용자들에게 없습니다 ㅠ. 만약 Install을 클릭하신다면, 다음과 같은 에러가 나타납니다.
팀즈 무료버전의 어드민 권한 또한 굉장히 제한적이라서, 어드민이 사용자들이 custom apps을 설치 할 수 있도록 허락이 안됩니다. 그럼 팀즈 무료에서 일반 사용자의 경우, 어떻게 자신이 만든 앱을 설치해서 테스트 해볼 수 있을까요?
이 경우에는 앱의 Microsoft Teams manifest를 다운 받아서, 팀즈의 App Store를 통해서 이 Manifest를 업로드하시면 됩니다. 우리도 이 방법을 통해서 봇과 함께 챗방을 만들 예정입니다.
Test and Distribute에서 Download를 클릭하시면, 하나의 zip file이 여러분의 Downloads폴더에 다운로드 되신 것을 보실 수 있습니다.
Step 18: Apps 페이지를 클릭한 후, Upload a custom app 클릭해서 manifest 업로드하기.
Upload a custom app을 클릭하면 Explorer Dialog가 팝업 되는데, 여기서 Step 17에서 다운받으신 zip file을 올리시면 됩니다. 업로드가 끝나고 나면, App 페이지에서 여러분의 앱을 다음과 같이 보실 수 있습니다.
Step 19: 테스트 앱을 클릭한 후, Add클릭하기.
테스트 봇을 클릭하시면, 다음과 같이 팝업 dialog가 뜹니다. 여기서 Add를 클릭하시면, 봇과 함께 1:1인 챗이 만들어집니다.
오늘 이 포스팅 목적으로는 이렇게 퍼스널 챗 (1:bot)이 충분하지만, 만약 다른 공간에 봇을 추가하고 싶으시다면 top-down 화살표를 눌러주시면 다양한 scope에 봇을 설치하실 수 있습니다. (ex: team, a group chat).
Add를 클릭하시면, 봇이 여러분과 1:1 챗을 만들건데요, 이건 바로 봇이 proactive welcome message를 보내도록 코드가 짜여져있기 때문입니다. 이 코드가 궁금하신 분은 Visual Studio로 돌아가셔서 Echobot.cs 파일을 가보시면, OnMembersAddedAsync function을 확인해주세요.
Step 20: Congratulations! You officially built your own bot and installed it on Teams Platform!
축하합니다! 이제 마이크로소프트 팀즈에서 우리가 탬플릿으로 구현한 에코 봇을 사용할 수 있게 되었습니다. 이 봇은 여러분이 보내는 메세지를 다시 똑같이 되풀이 하도록 짜여져있습니다.
봇에게 다른 명령을 주거나, 또는 다른 로직을 구현하고 싶으시다면, Echobot.cs에서 OnMessageActivityAsync 함수를 변형시키시면서 구현을 하실 수가 있습니다. (관련된 예제/API resource에 관한 링크는 밑에 있습니다).
정리
이 포스트에서는 어떻게 아주 간단한 봇 서비스를 local 환경에서 구현한 후, 팀즈 플랫폼에 설치 할 수 있는지에 대해서 공유해보았습니다. 이 포스트가 더 재미있고, 더 많은 로직을 핸들링 할 수 있는 팀즈 봇을 구현하고픈 그 누군가에게 좋은 시작점이 될 수 있으면 좋겠습니다.
팀즈는 개발자분이 더 유용한 어플리케이션을 자체 환경에서 개발 할 수 있도록 많은 API들을 제공하고 있습니다. 팀즈와 관련된 API가 궁금하시다면 다음 두 곳에서 더 많은 정보를 보실 수 있습니다.
- Build apps for Microsoft Teams: 팀즈 플랫폼 개발 Ecosystem에 대해서 전반적인 지식을 얻을 수 있는 곳 입니다.
- Microsoft Teams developer documentation: 팀즈 플랫폼에서 개발 할 때 필요한 문서와 리소스가 한 곳에 모여져있는 곳입니다.
팀즈 봇을 개발하기 위해 필요한 API들에 대해서 더 궁금하시다면, 여기를 확인해주세요. (제가 개발에 참여한 몇 개의 API도 있답니다 :))
P.S: 많은 유저들에게 임팩드를 주는 프로덕트를 만드는 과정에 참여하고시픈 분이나, 아주 재미있고 멋진 분들과 함께 일하는 것을 사랑하시는 분이라면, Microsoft Teams Platform이 함께 할 많은 분들을 찾고 있습니다!
관심있으신 분은 Careers at Microsoft 관련된 포지션들을 찾아서 지원해주세요 :D
