logo头像

Edward.K Thinking

如何使用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時候,必須要先有titletext,只有單純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內是搭配namevalue方式把資訊填入,且可以有多組的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

上一篇