ODCからTeamsへ通知してみた ～REST APIの設定方法～（Vol.32）
- 公開日：
OutSystems Developer Cloud（以降、ODCという）では、REST APIによる連携機能を用いることで様々なシステムと連携することができます。連携先のシステムが公開しているAPIをODCに実装することで、連携先システムのデータ参照/更新などが可能となります。
本ブログ記事では、ODCのREST API連携機能の概要をご説明のうえ、業務アプリケーションとしてニーズの高いMicrosoft Teams（以降、Teamsという）への通知を実装する方法を、実際の操作画面を交えながらわかりやすく解説します。
※本ブログ記事では、ODCでの実装を前提とした解説を行っていきますが、OutSystems 11（以降、OS11という）でも同様に実装可能です。
目次
OutSystems Developer Cloud （ODC）のREST API連携機能とは？
ODC 及び OutSystems11 では、REST APIを利用した外部システムとの連携を実装することができます。
REST APIとは、Representational State Transfer の設計原則に従う Application Programming Interface の略称です。簡単に言えば、Webアプリケーションやソフトウェア同士での通信を可能にする仕組みのことです。
ODCはREST APIによる連携機能を搭載しています。また、ODC自身もREST APIを提供することが可能なため、他のWebアプリケーションからODCに対して通信を行うことも可能です。
REST APIはODCで扱うことができる技術の中でもプロコードに近い分野ですが、これを簡単に扱えるようにするためのサポート機能がいくつか備わっています。
- ODC Studio上で疎通確認が可能
REST APIをODC Studio上でセットアップする際に疎通確認ができ、設定内容に誤りがないかを素早く確認することができます。 - 疎通確認時のレスポンスを解析
疎通確認時に得られた正常系のレスポンスを分析し、APIアクションと関連要素を自動作成します。
- ビジュアライズされたフローで実行
アプリケーションの処理として実装する際は、他のノードと同じようにビジュアライズされ、ローコードのメリットを活かすことができます。
OutSystems Developer Cloud（ODC）のREST API実装方法①Teamsの準備をする
それでは、実際にODCでREST APIの呼び出しを実装してみましょう。今回はTeamsへの通知機能を実装するため、Teams連携機能の詳細にも触れていきます。
REST APIを使用する時に最も重要なのは、「連携先のAPIの情報を調べる」ことです。
メジャー製品の多くは、「製品名 API」と入れてインターネット検索を行うことで、APIリファレンスに辿り着くことができます。
例えば、ファイルストレージサービス：「Box」 のAPIドキュメントはこちらから確認することができます。APIを介して非常に多くの機能を実行できるようです。
では、Teamsで通知するAPIを探してみましょう。Microsoft社は様々なサービスを提供しているため、APIの情報を探す難易度は少し高いですが、情報を整理すると以下のようになります。
・Teamsで利用できるWorkflowsアプリを使用し、ODCから呼び出すエンドポイント（受信Webhook）を作成する方法が推奨されている。
・エンドポイントへは「アダプティブカード」形式で通知内容を送信する。
（参考）
Microsoft Teamsのワークフローを使用して受信 Webhook を作成する
アダプティブカード ツールとサンプル
受信 Webhook を使用してアダプティブ カードを送信する
それでは、各手順を詳しく見ていきましょう。
まずはご利用のTeamsを開き、サイドバーからその他のアプリとして「Workflows」を検索します。
Workflowsアプリが起動されたら、テンプレートから「Webhook要求を受信するとチャネルに投稿する」を選択して新しいフローの作成を開始します。
フローの作成ウィザードでは、通知を送信したいチームとその中のチャネルを選択し、「フローの作成」を押下します。
フローが正常に作成されると、ODCからの呼び出しに使用するエンドポイント（受信Webhook）が表示されます。値をコピーして、メモなどに保存しておきましょう。
次に、通知のデザインを作成します。Webhook要求での通知は「アダプティブカード」というTeamsで送信することのできるデザイン性に優れたメッセージカードのことです。
（アダプティブカードのサンプル）
色々なデザインが作れるため開発も難しそうに感じてしまいますが、DesignerというWebアプリを使ってローコードで簡単に作成することができます。
今回はDesignerで最初に表示されるこちらのテンプレートのデザインを、ODCを使って送信してみましょう。
実際にODCで送信する際にアダプティブカードのデザインはJSONの構文で定義されます。Designerの「CARD PAYLOAD EDITOR」に現在のデザインをJSONで表現したものが記載されており、画像やテキストなどの動的な値は${~}で表記された変数として右の「SAMPLE DATA EDITOR」で定義されています。
ODCから送信する時は実際の値まで設定されている必要があるため、「Select hostapp」を「Microsoft Teams」に変更した後、「Copy card payload」ボタンを押して値入りのJSONをコピーし、こちらもメモなどに保存しましょう。
これでTeamsへ通知を送る準備が整いました。
次章では、ODC Studioを使用して通知送信機能を実装します。
OutSystems Developer Cloud （ODC）のREST API実装方法②連携を設定する
それでは、ODC StudioでREST APIの呼び出しを実装してみましょう。
まずは適当なアプリケーションを開き、「Logic」タブの「Integrations」フォルダ内「REST」を右クリックし、「Consume REST API…」を選択します。
REST API設定のポップアップが開かれます。
追加の方法は2種類ありますが、今回は左の「Add single method」を選択します。
ドロップダウンリストから「GET」を「POST」に変更し、Method URLに前章で準備したエンドポイント（受信Webhook）の値を貼り付けます。
また、HeadersタブからRequest headersに「Content-Type」を追加します。
Teams通知のREST APIに必要な定義はこれだけです。
次に疎通確認を行います。先ほど定義した「Content-Type」には「application/json」と記載し、Body contentのRequest部分には、Designerで作成したアダプティブカードのJSONと以下のテンプレートを使ったテキストを入力します。
【テンプレート】
{
"type": "message",
"attachments": [
{
"contentType": "application/vnd.microsoft.card.adaptive",
"contentUrl": null,
"content": "この部分をDesignerで作成したJSONに置き換えてください。"
}
]
}
【テキスト入力例】
{
"type": "message",
"attachments": [
{
"contentType": "application/vnd.microsoft.card.adaptive",
"contentUrl": null,
"content": {
"type": "AdaptiveCard",
"body": [
{
"type": "TextBlock",
"size": "Medium",
"weight": "Bolder",
"text": "Publish Adaptive Card Schema"
},
{
"type": "ColumnSet",
"columns": [
{
"type": "Column",
"items": [
{
"type": "Image",
"style": "Person",
"url": "https://pbs.twimg.com/profile_images/3647943215/d7f12830b3c17a5a9e4afcc370e3a37e_400x400.jpeg",
"altText": "Matt Hidinger",
"size": "Small"
}
],
"width": "auto"
},
{
"type": "Column",
"items": [
{
"type": "TextBlock",
"weight": "Bolder",
"text": "Matt Hidinger",
"wrap": true
},
{
"type": "TextBlock",
"spacing": "None",
"text": "Created {{DATE(2017-02-14T06:08:39Z,SHORT)}}",
"isSubtle": true,
"wrap": true
}
],
"width": "stretch"
}
]
},
{
"type": "TextBlock",
"text": "Now that we have defined the main rules and features of the format, we need to produce a schema and publish it to GitHub. The schema will be the starting point of our reference documentation.",
"wrap": true
},
{
"type": "FactSet",
"facts": [
{
"title": "Board:",
"value": "Adaptive Cards"
},
{
"title": "List:",
"value": "Backlog"
},
{
"title": "Assigned to:",
"value": "Matt Hidinger"
},
{
"title": "Due date:",
"value": "Not set"
}
]
}
],
"actions": [
{
"type": "Action.ShowCard",
"title": "Set due date",
"card": {
"type": "AdaptiveCard",
"body": [
{
"type": "Input.Date",
"id": "dueDate"
},
{
"type": "Input.Text",
"id": "comment",
"placeholder": "Add a comment",
"isMultiline": true
}
],
"actions": [
{
"type": "Action.Submit",
"title": "OK"
}
],
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json"
}
},
{
"type": "Action.OpenUrl",
"title": "View",
"url": "https://adaptivecards.io"
}
],
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
"version": "1.5"
}
}
]
}「Test」ボタンを押下してみましょう。「Response test result」に「HTTP/1.1 202 Accepted～」と表示され、Teamsで設定したチャネルに通知が届きました。
正常に疎通確認が取れたので、「Body」タブの「Request」欄に先ほどのテスト時のJSONテキストを貼付して「Finish」を押下します。ここまでに設定した メソッド / エンドポイント / ヘッダー / リクエストの内容を解析し、ODCが自動でREST APIメソッドを作成してくれました。
尚、ポート443の指定によりURL Pathで構文エラーが表示されてしまうので、「:443」は「REST API」の「Base URL」末尾に移動しておきましょう。
OutSystems Developer Cloud （ODC）のREST API実装方法③ロジックフローで使用する
設定ができたら、実際に画面から通知できる処理を実装します。
アプリケーションに送信ボタンを配置した画面を用意しましょう。
送信ボタンのScreen Actionでは、先ほど作成したREST APIメソッドを配置します。パラメータはテストした時と同じものを設定していけば良いのですが、JSONの項目量が多いため全てを設定するのは少し手間です。こんな時には、「JSON Desirialize」を使用します。
JSON Stringプロパティには先ほどのRequestに使ったJSON文字列を記載しますが、元のJSONのままではダブルクォーテーション(”)がOutSystemsのTextの始端/終端と判別されてしまうため、コードエディターなどを使ってエスケープされるよう(””)に置換しておきます。
「Data Type」には、REST API設定時に自動作成されたRequestパラメータのストラクチャを指定しましょう。
「JSON Desirialize」のOutputをREST APIメソッドのRequestプロパティに設定します。「ContentType」はテスト時と同様「”application/json”」です。
これでロジック部分が完成しました。アプリケーションをPublishし、動作を確認します。
見事、テスト時とに画面から通知を送信することができました！
まとめ
さてここまで、ODCのREST API連携機能の概要と、Teamsへの通知機能の実装方法を解説して参りました。
アプリケーションの機能としてTeams通知を開発する時は、通知内容を動的に変更できる必要があります。また、通知先のチャネルを変更できたり、自分で作ったアダプティブカードを使えたりした方がより便利です。これらをODC上で適切に設計し実装するには、ODCのアーキテクチャを理解し、広い視点から機能を抽象化するスキルが求められます。
弊社はODCの複数の導入実績があるほか、積極的にODCの調査/検証を行っております。また、OS11も含むOutSystemsの様々な導入/開発の知見をもとに、お客様の社内でOutSystemsの活用を推進するCenter of Excellence（CoE）チームを組成し、スムーズな導入と環境全体の統制、そして利用範囲の拡大をご支援するサービスをご提供しております。CoEチームの有用性や組成方法についてご興味のある方は、是非、弊社までお問い合わせください。
電通総研では、ローコード開発プラットフォーム：OutSystemsの導入/活用を支援する様々なサービスメニューをご用意しております。
ローコード開発のはじめの一歩を、電通総研と一緒に踏み出してみませんか？
電通総研のOutSystems関連サービスページ：https://itsol.dentsusoken.com/outsystems/service/
本ブログは、2024年11月1日時点の情報をもとに作成しています。
OutSystemsに関する詳しいお問い合わせは、弊社Webサイトからお問い合わせください。
https://itsol.dentsusoken.com/outsystems/inquiry/
＜筆者＞
氏名：岡村 一輝
所属：株式会社電通総研 エンタープライズIT事業部
経歴：2019年よりOutSystems開発者として様々な案件に参画。
OutSystemsを用いた業務アプリケーション開発のリーダー、
内製開発者の育成を目的とした技術支援・トレーニングの豊富な経験有。
保持資格：
– Mobile Developer Specialist (OutSystems 11 and ODC)
– Architecture Specialist (OutSystems 11)
– Associate Tech Lead (OutSystems 11)
– Expert Traditional Web Developer (OutSystems 11)