Office 365 Connectors 的使用与自定义开发

前言

我相信很多人都看过《三国演义》，里面有很多引人入胜的故事和栩栩如生的人物，对我而言，曹操手下的一员猛将典韦实在让我印象深刻。例如，书中有一段描写典韦的作战经历：

时西面又急，韦进当之，贼弓弩乱发，矢至如雨，韦不视，谓等人曰：“虏来十步，乃白之。”等人曰：“十步矣。”又曰：“五步乃白。”等人惧，疾言“虏至矣”！韦手持十余戟，大呼起，所抵无不应手倒者。布众退。

箭如雨下喊声四起，典韦以寡敌众，“贼至五步乃呼我”，如狼似虎，连吕布都要避其锋芒。我今天在写这篇文章时，又不由得联想起来这个让人血脉喷张的画面。Office 365 Connector正是一个有意思的类似场景，而且它也属于Office 365 开发四场场景之一，如下图所示：

它通常是在Office 365应用程序内部（目前支持Office 365 Group，Yammer和Microsoft Teams）中需要接收外部系统的一些通知消息时，能够以一种灵活的方式来连接起来。所以，它的中文名称就是“连接器”，换言之，当用户关注的某些业务系统（或者任何消息源)有一些新的状态，他可以自动地得到通知。

本文将包括如下的内容

1. 在Office 365 Group中使用Office 365 Connectors
2. 在Yammer中使用Office 365 Connectors
3. 在Microsoft Teams中使用Office 365 Connectors
4. 自定义Office 365 Connectors

在Office 365 Group中使用Office 365 Connectors

这是Office 365 Connectors最早的使用场景，用户可以自己在Outlook客户端，或者OWA中进行配置，并且通过邮件的方式得到通知。

关于Office 365 Group的详细信息，请参考 https://support.office.com/zh-cn/article/%E4%BA%86%E8%A7%A3%E6%9C%89%E5%85%B3-office-365-%E7%BB%84-b565caa1-5c40-40ef-9915-60fdb2d97fa2?ui=zh-CN&rs=zh-CN&ad=CN

下图展示了在Outlook中添加连接器的界面：

图中的“连接线”翻译不准确，应该为“连接器”

下图展示了在OWA中添加连接器的界面：

目前内置提供了超过100个连接器，包括很多企业级应用平台，也包括了很多互联网应用。下面演示一个从Github上面获取通知的连接器配置和使用效果。

点击第一个“添加”按钮，然后在下图中配置你的Github账号（通常会弹出一个登陆框，请你输入用户名和密码）

在这个界面中选择你要关联的代码库（repositories），并且勾选想要用来接收通知的事件，然后点击“保存”即可。

你会在“连接测试组”中收到一个配置成功的邮件：

下面我可以尝试往这个代码库提交一次更新，我们可以很快在连接器测试组中看到一个推送的通知。

在Yammer中使用Office 365 Connectors

Yammer是Office 365中的一个企业级社交网络，你可以根据需要创建各种各样的群组（Yammer Group），讨论不同的话题。在Yammer群组中，你也可以通过在“组操作”中选择“添加或删除应用”这个操作，如下图所示

这里显示的连接器列表其实跟在Outlook里面看到的是一样的

本例演示添加“RSS”这个连接器，例如我关注Office 产品组的更新博客，就可以通过下面的方式订阅他们的RSS feed

点击“保存”后，会在Yammer群组中看到一个通知

在设定的时间，RSS引擎会把博客链接发送到Yammer群组中来

在Microsoft Teams中使用Office 365 Connectors

Microsoft Teams是Office 365 Connectors另外一个使用场景，它的用法略有不同：它是在频道中添加连接器的，一个团队可以有多个频道，一个频道有可以添加多个连接器，这样就带来了更加灵活的可能性。

选择某个团队的某个频道，在它右侧的“...”菜单中选择“连接器”，你可以看到跟之前很类似的一个界面

在本例中，我演示的是如何配置Yammer这个连接器以便在Teams中能收到Yammer讨论组的消息。

和Github类似，添加Yammer这个连接器后，要进行详细的配置，如下图所示

你可以设置要关注的组，事件类型，关注的用户和关键字，以及通知的频率等等，保存后，当Yammer组有状态更新时，在频道里面就可以收到通知：

在这里可以直接点赞，或者回复，不过似乎这些还不能双向地同步到Yammer里面来。

自定义Office 365 Connectors

上面演示了使用Office 365 Connectors的场景（Outlook，Yammer，Microsoft Teams），我们都是使用目前内置的Connectors，那么如果我们自己有一个应用系统，也想通过这种方式进行连接（在必要的时候推送消息和更新动态），应该怎么来做呢？这方面，目前Office 365平台提供了三种机制。

首先，对于一些简单的场景，你可以直接使用“Incoming Webhook”这个内置的连接器来定义，如下图所示

通常你只需要提供一个名称即可完成连接器的定义

点击“创建”，会产生一个Url，这就是可以用来推送消息的地址了

那么，如何使用这个自定义的连接器呢？很简单，我们只要在应用程序内部，通过Post的方法，给这个地址发送消息即可。通常的代码如下：

using System;
using System.Net.Http;

namespace connectorconsole
{
    class Program
    {
        static void Main(string[] args)
        {

            var client = new HttpClient();
            var request = new HttpRequestMessage(HttpMethod.Post,"https://outlook.office.com/webhook/f2bde2a5-8459-4acd-b92c-c55947422146@72f988bf-86f1-41af-91ab-2d7cd011db47/IncomingWebhook/9bc2989885fe475fa3d5578796f7dd05/f3b94dd3-20cc-49a3-98ce-b1287658e8cf");
            request.Content = new StringContent("{"text":"通过程序推送的消息"}");
            client.SendAsync(request);

            Console.Read();
        }
    }
}

运行这个小程序，就可以在目标应用中收到一个通知的消息，如下图所示

如果只是作为测试，你甚至都无需写代码，而是使用一些工具来发起请求，例如Fiddler,Postman,curl等，这里就不演示了。

以上这种场景特别适合于简单的环境，并不适合于大规模分发使用，因为这个地址是要用户来生成的，然后再告诉开发人员，而且这个地址每次生成都是不一样的。如果想要更好地解决这个问题，例如你可以做一个自己的连接器，让尽可能多的用户去使用它，那么是时候考虑真正地自定义一个连接器。

你需要使用Office 365账号登录 https://outlook.office.com/connectors/publish 来创建一个自定义的连接器，如下图所示

这个页面中的关键信息是Redirect Urls这个地址，然后你可以看到目前它仅支持Outlook和Microsoft Teams，暂时不支持Yammer。

点击“保存”后，接下来就可以进行测试了。值得说明的是，你需要准备一个用来响应用户请求的网站，例如本例我会用本地运行的一个站点做演示（http://localhost:5000)

我用了dotnet core创建了一个最简单的网站，用来响应用户的关联请求，并且将用户相关信息打印出来（真实场景下会将这些信息保存起来，用来推送消息）

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.DependencyInjection;
using System.Text;
using System.Net.Http;

namespace connectorhost
{
    public class Startup
    {
        // This method gets called by the runtime. Use this method to add services to the container.
        // For more information on how to configure your application, visit https://go.microsoft.com/fwlink/?LinkID=398940
        public void ConfigureServices(IServiceCollection services)
        {
        }

        // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
        public void Configure(IApplicationBuilder app, IHostingEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }

            app.Run(async (context) =>
            {
                //打印出来用户关联信息
                var sb = new StringBuilder();
                foreach (var item in context.Request.Query)
                {
                    sb.AppendLine($"{item.Key}={item.Value}");
                }
                await context.Response.WriteAsync(sb.ToString());

                //推送一个欢迎消息
                var url = context.Request.Query["webhook_url"];
                var client = new HttpClient();
                var request = new HttpRequestMessage(HttpMethod.Post,url);
                request.Content = new StringContent("{"text":"欢迎关联我的连接器，你将会收到很多消息推送"}");
                await client.SendAsync(request);

            });
        }
    }
}

为了让用户可以关联我们开发的自定义连接器，你可以在注册连接器的页面上，点击"Copy code"，如下图所示

然后将复制得到的代码，保存为一个html文件，在浏览器中打开它的效果如下

你可以将这段代码嵌入到任意网站中去

用户点击页面上这个“Connect to Office 365”的按钮后，会被要求登录Office 365，然后可以选择Outlook中的收件箱或者组来进行关联

点击“Allow”后，Office 365后台做好必要的处理后，页面会被重定向到注册时提供的Redirect Urls（我演示的例子是 http://localhost:5000）

与此同时，在对应的组中，也立即收到了一个欢迎消息

这样就完成了一个开发人员自定义连接器，用户自行关联连接器的流程。连接器的宿主应用程序，可以把用户的信息保存起来，然后再在必要的时候给用户推送消息。

最后，如果你希望将你的自定义连接器发布给全世界所有的Office 365用户去使用，则需要发布到微软的Office 365 Connectors商店中去，你可以在注册页面中点击“Publish to store”按钮

你按照需要填写信息，然后“submit”即可