天天看點

Microsoft Teams的Outgoing Webhook開發入門

Microsoft Teams的應用程式有幾種形式:

  1. Tabs
  2. Bots
  3. Connectors
  4. Messaging extensions
  5. Activity feed integrations
  6. Outgoing web hooks

這篇我們主要介紹如何使用 ASP.NET Core來開發最簡單的Outgoing web hook。

什麼是outgoing webhook

Outgoing webhooks allow you to create a simple bot for basic interaction, like kicking off a workflow or other simple commands you may need. Outgoing webhooks live only in the team in which you create them and are intended for simple processes specific to your company’s workflow. 

If you’ve worked with outgoing webhooks or slash commands in other chat platforms, you can now bring what you have developed over to Microsoft Teams via outgoing webhooks. Outgoing webhooks are an easy way of extending your team without having to go through the full process of creating a bot via the Microsoft Bot Framework. You can use them for custom workflows and commands such as kicking off a build or checking the latest set of livesite issues.

You also have an effective way of ensuring that your service is accessible only by authorized users, as the security token used by your outgoing webhook will only be scoped to the team in which it has been added

上面是微軟官方對outgoing webhook的說明,其實簡單來說,outgoing webhook就是當我們想要建立一個Bot應用時,可以不必使用微軟Bot Framework來建立,這個應用可以執行我們團隊的一些自定義工作流和簡單指令。

如何在teams裡面建立outgoing webhook

要建立一個outgoing webhook, 進入到Teams應用, 導航到“團隊” Tab頁, 選中需要建立的Channel, 選中“應用”這個Tab,點選最下方的“建立傳出webhook”(英文版本叫Outgoing Webhook), 如下圖所示:

Microsoft Teams的Outgoing Webhook開發入門

在“建立傳出webhook”對話框中,可以配置傳出webhook在頻道中的顯示方式

  • 名稱 将顯示為機器人的标題,也是使用者将如何命名機器人
  • 回調URL 是将從團隊接收消息的端點
  • 說明 是一個詳細的字元串,它将顯示在配置檔案卡和團隊級應用程式儀表闆中
  • 配置檔案圖檔是 傳出webhook的可選顯示圖檔
Microsoft Teams的Outgoing Webhook開發入門

這裡我們建立一個名為“TestBot”的程式,填入ngrok中的https的位址(關于ngrok下文會詳細說到),單擊“建立”,将在目前團隊中提供傳出webhook。它不會在任何其他團隊中提供。下一個對話框将顯示一個安全令牌,您将使用該令牌驗證來自Microsoft Teams的請求

Microsoft Teams的Outgoing Webhook開發入門

這裡我們把這個Security Token複制,儲存起來。一旦關閉這個頁面以後我們無法再進入到這個頁面複制,如果需要拿到這個Token,必須重新建立新的傳出webhook。

讓我們來試一下新鮮出爐的webhook。将傳出webhook添加到團隊後,它的外觀和行為就像機器人一樣,我們可以輕松地進行互動。它使用帶有webhook名稱的@mention監聽消息,并可以回複豐富的消息,包括圖像和卡片等

Microsoft Teams的Outgoing Webhook開發入門
Microsoft Teams的Outgoing Webhook開發入門

開發傳出webhook的後端服務

上面我們講到如何在Teams中建立webhook的應用,那當我們發送@這個機器人,并且發送消息時,這個bot應用是如何接受到消息,并且響應這個消息的呢。這裡我們基于dotnet core搭建這個bot的後端響應服務程式。

如果你開發機器上還沒有安裝 dontnet,那可以到 http://www.dot.net 下載下傳官方SDK,下載下傳完成後,進入到windows标準的安裝, 一路“下一步”直到完成。 進入到cmd,輸入 

dotnet --version

,可以看到我們安裝的目前dotnet core的版本:

c:\Users\demouser> dotnet --version
2.1.300
           

這裡我們看到顯示的版本時2.1.300,這個版本是 .NET Core 2.1, 如果是2.1.301,則是 .NET Core 2.1.1

dotnet --info

,我們可以看到整個開發環境的詳細資訊:

c:\Users\demouser> dotnet --info     
           

安裝完dotnet core後,我們就可以開始建立web api項目。

c:\demo> dotnet new webapi -n WebhookSample
           

用vs code打開我們建立的項目的檔案夾,可以看到 .Net Core通過模闆,為我們建立的web api的項目結構:

Microsoft Teams的Outgoing Webhook開發入門

修改

Startup.cs

檔案,注釋其中

app.UseHttpsRedirection()

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    else
    {
        app.UseHsts();
    }

    //app.UseHttpsRedirection();
    app.UseMvc();
}
           

這裡注意下:去掉

app.UseHttpsRedirection()

的原因是為了簡化一些配置自簽名證書,如果大家已經配置過了,這個不注釋掉也可以。

修改

ValuesController.cs

檔案,改為如下所示的代碼:

[ApiController]
public class ValuesController : ControllerBase
{
    [HttpPost]
    [Route("api/message")]
    public Activity Post([FromBody]Activity request)
    {
        return new Activity()
        {
            Text = $"you send message is {request.Text}"
        };
    }
}
           

執行

dotnet run

指令來運作項目,預設本地是以 

http://localhost:5000

 端口運作

到這裡我們的web api項目就整個跑起來了,那麼如何和我們在Teams中配置的webhook機器人産生互動呢?這裡需要借助于我們上面說到的ngrok這個工具了。

ngrok 是一個反向代理,通過在公共端點和本地運作的 Web 伺服器之間建立一個安全的通道,實作内網主機的服務可以暴露給外網。

ngrok 可捕獲和分析所有通道上的流量,便于後期分析和重放 

簡單來說就是,我們在webhook中配置了一個https的外網位址,需要将bot的資訊轉發到我們内網localhost:5000提供的web api服務,以響應Teams中的消息

ngrok官網下載下傳: https://ngrok.com/ 

運作ngrok.exe,輸入指令 ```ngrok http 5000`` 這個指令是讓ngrok的伺服器把請求轉發到本地的5000端口,協定使用HTTP。 

從下面的截圖,我們可以看到工具為我們提供的http和https的兩個外網轉發位址,兩個位址都是指向我們本地的localhost:5000端口 

Microsoft Teams的Outgoing Webhook開發入門

這裡的https位址,就是我們上面在Teams中配置webhook時候需要填入的位址,為了讓webhook中的消息轉發到我們本地,并且識别資訊,進行響應。那我們重複上文中的步驟:在Teams的channel中輸入

@Testbot

,然後再輸入

come on

, 此時我們會收到一個響應消息,如下圖:

Microsoft Teams的Outgoing Webhook開發入門

ngrok還為我們提供了一個非常實用的控制台,打開你喜歡的浏覽器,輸入

http://localhost:4000

,ngrok就會列出所有轉發的請求和響應:

Microsoft Teams的Outgoing Webhook開發入門

點選任何一個請求,在右邊就會顯示這個請求的詳細資訊和它所對應的服務響應内容。

Microsoft Teams的Outgoing Webhook開發入門
Microsoft Teams的Outgoing Webhook開發入門

此時,我們把本地的web api服務停止掉(在運作服務的視窗按Ctrl + C),看是否還能響應消息,同樣在Teams中發送消息

Microsoft Teams的Outgoing Webhook開發入門

這裡我們看到Bot響應失敗了,檢視ngrok的控制台,看到響應報了 

502 Bad Gateway

 的錯誤

Microsoft Teams的Outgoing Webhook開發入門

**總結一下,整個的邏輯是: 我們在webhook中填入服務的響應位址(必須是https的),随後通過ngrok轉發到我們本地5000端口運作的web api程式,程式處理後傳回,然後ngrok再傳回給teams,teams server再傳回給你。

Microsoft Teams的Outgoing Webhook開發入門

總結

這篇文章主要是講解什麼是outgoing webhook,如何在Teams中建立一個webhook,如何使用ASP.NET Core開發webhook後端服務程式,并且通過ngrok這個橋梁,把Teams和你本地運作的服務串聯起來。

在下一篇文章中,我們将會講到,如何使用dotnet template快速開發帶card功能的outgoing webhook

官網連結

  • Outgoing webhook
  • Code samples for the Microsoft Teams developer platform
  • Add bots to Microsoft Teams apps

繼續閱讀