uncategorized

如何使用Office 365 API Connectors

在Office 365提供了webhooks的功能，讓外部系統可以與Office 365進行溝通，因此，只要能開發相容或是本身有相容webhooks定義，就可以讓外部系統把訊息傳遞到Office 365，因此，了解Office 365 webhook可接受的傳遞的格式就很重要。由於本身webhooks是透過Http協定，所以，在哪一種平台上去開發，就部會是障礙，而格式內容是使用json方式，這樣操作起來就更容易，在訊息Header要加上

1
"Content-Type" : "application/json"

我們發送一個簡單文字格式，例如:

1
2
3
{
   "text":"Hello world" 
}

這樣就可以把訊息傳到O365中，不過，只是單純這樣的訊息似乎也太寒酸，所以，在整個O365的json訊息中，又可以分為幾大塊模組，讓我們組出想要的訊息內容，只是每個欄位名稱必須符合O365定義，大概可以分成下面主要的幾大塊

  • title
  • Actions
  • Sections

利用這些區塊就可以組出我們想要的資訊內容

title & text

title算是整個訊息的標題，不過，在不同服務內呈現樣貌會有一點不同，如果只有輸入下面這樣指令是不會Work的，若只想單純文字，只要用text就可以

1
2
3
{
    "title":"我是Title"
}

還必須加上內容才可以，內容用text加入，不然是發送不出去

1
2
3
4
{
     "title":"我是Title",
     "text":"第一個訊息"
}

若是要在文字中加入超連結，這是可以，其寫法就跟寫Markdown的超連結語法相同，用[]()組合，像是

1
2
3
4
{
     "title":"我是Title",
     "text":"第一個訊息[Link](http://www.google.com)"
}

就可以做到具有超連結的文字

Actions

Actions的概念就像是在訊息中間帶入一個button，可以讓人去點擊，不過，實作上在某些開發編輯器或是服務上會認為這樣語法是有錯誤，主要是因為有用到@context和@type這兩個屬性會被視為錯誤的json格式，導致無法發送，這裡@type中可以用的選項，可以參考http://schema.org/ViewAction了解有那些可以用

1
2
3
4
5
6
7
8
9
10
11
{
    "text":"第一個訊息[Link](http://www.google.com)",
      "potentialAction": [
    {
      "@context": "http://schema.org",
      "@type": "ViewAction",
      "name": "拜訪Google",
      "target": ["https://www.google.com"]
    }
  ]
}

Sections

前面使用text用來描述相關資訊，感覺似乎有一點點少，畢竟，某些時候這樣的資訊是不夠我們使用，因此，便會想要我擴充資訊內容，這時候就可以用Sections加上Fact的搭配，Sections內則使用activityTitle ,activitySubtitle,和activityText做摘要性的描述，詳細描述則透過Fact方式的Key & Value概念去放入必要的資訊，另外，在使用Sections時候，必須要先有title和text，只有單純sections是會發生錯誤

1
2
3
4
5
6
7
8
9
10
{
  "title":"我是Title",
  "text":"第一個訊息[Link](http://www.google.com)",
  "sections": [
    {
      "activityTitle": "Office 365 API",
      "activitySubtitle": "如何使用",
      "activityText": "透過API傳遞資訊"
  }]
}

這時候，再配上Fact則可以填入更多的訊息，而Fact內是搭配name和value方式把資訊填入，且可以有多組的Fact，如果資訊過長，還會自動幫你摺疊訊息

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
{
     "title":"我是Title",
     "text":"第一個訊息[Link](http://www.google.com)",
  "sections": [
    {
      "activityTitle": "Office 365 API",
      "activitySubtitle": "如何使用",
      "activityText": "透過API傳遞資訊"
  }
  ,{
      "title": "人員1",
      "facts": [
        {
          "name": "姓名",
          "value": "王大明"
        },
        {
          "name": "電話",
          "value": "1000000"
        }
      ]
    },
    {
      "title": "人員2",
      "facts": [
        {
          "name": "姓名",
          "value": "王大明"
        },
        {
          "name": "電話",
          "value": "1000000"
        }  
      ]
    }
  ]
}

利用webhook方式再搭配json資訊格式，看來要與Office 365做整合也就不是那樣困難了

參考資訊

1.https://dev.outlook.com/connectors/reference
2.http://schema.org/ViewAction

Share