外部システム連携機能を使いたい – DialogPlay - TIS株式会社

外部システム連携機能を使用することで、他の外部システムサービスとの連携、業務システムとの連携、指定したメールアドレスにメールを送信するなどの処理が可能になります。
連携タイプはいくつか用意されていますが、ここでは、「HTTP(S)プロトコル」と「Google Spreadsheet」のタイプを使用した連携方法について説明します。
「HTTP(S)」、「Google Spreadsheet」以外の各利用手順は、以下をご覧ください。

Email：【シナリオの中でメール送信を行いたい】
Excel(OneDrive)：【OneDriveと連携したシナリオを作成したい】
Office 365：【チャットボット作成（Ⅳ.Office 365連携編）】

はじめに、外部システム連携画面の設定項目について説明します。

項目説明（共通項目）

左メニューの『チャットボット一覧』より設定を行うチャットボットを選択し、『外部システム連携』タブから”新規作成“ボタンをクリックしてください。

『外部システム連携』設定画面の共通項目について説明します。

①『外部システム連携先』に連携先名を入力してください。
シナリオ作成時、「外部システム連携」アクションで選択する際に表示される項目名になりますので、わかりやすい名前をつけてください。

②『説明』に作成する外部システム連携の説明を入力してください。

③『タイプ』のリストから外部システム連携に使用するタイプを選択します。
（使用するタイプにより、設定項目が変わります。）
[タイプ一覧]

タイプ	説明
HTTP(S)	HTTP(S)通信を使用してデータの入出力を行います
Google Spreadsheet	Google Spreadsheetへデータ登録を行います
Email	アカウント設定でメール送信先に登録されたアドレスに電子メールを送信します
Excel(OneDrive)	MicrosoftのOneDriveを利用してExcelデータの参照・登録・更新・削除を行います
Office 365	Microsoft Graph APIを使用してOffice 365と連携し、データの入出力を行います
Salesforce	Salesforceと連携し、データの入出力を行います

項目説明（HTTP(S)）

HTTP(S)の設定項目について説明します。

① 『タイプ』より「HTTP(S)」を選択してください。

② 『URL』に外部システムへ接続するためのURLを入力してください。

③ 『Method』に外部連携先へ送信するリクエストの種類を選択してください。
[Method設定項目]

メソッド名	説明	例
GET	送信するデータをURLに追加する	『URL』に記述 http: //〇〇〇〇.co.jp/?key1=value1&key2=value2
POST	送信するデータをリソースに追加する	『Request Body』に記述 key1=value1&key2=value2
PUT	リソースを新規作成・更新をする	同上
DELETE	指定したURIのリソースを削除する	同上
OPTIONS	URIに対して利用できるメソッドの一覧を取得する	同上
PATCH	URIの一部を更新する	同上

④ 『Headers』に外部連携先へ送信するデータのヘッダ名と値を入力してください。
※ 『Headers』に{{変数}}を設定することも可能です。DialogPlayで取得した情報を、外部連携先へ送信する情報（AccessToken等）として利用したい場合にお使いください。
[Headers設定例]

名前	説明
Content-Type	送信するデータのファイル形式

値	説明
text/plain	テキストファイル
text/csv	CSVファイル
text/html	HTMLファイル
application/json	JSONファイル

⑤ 『Request Body』に外部連携先へ送信する内容を入力してください。

⑥ 『Response Type』にレスポンスの形式を指定してください。
※ 現在、JSON形式のみ取得可能です。

⑦ 『Response Map』に外部連携先から取得したデータを、シナリオ内で変数として使用するための変換情報を入力してください。
[Response Map設定項目]

項目名	説明
変換元	外部連携先から取得したデータのキー名を入力します
変換先	変換元で指定したキーの値を保存する変数名を入力します（この変数はシナリオの『外部システム連携』アクションで利用可能です）

[Response Map設定例]
以下の設定により、取得データの「key1」＝ “value1”が、シナリオ内では、「変数1」＝ “value1”として利用されます。
『Response値』　　 { “key1” : “value1”, “key2” : “value2” }
『項目入力』

項目説明（Google Spreadsheet）

Google Spreadsheetの設定項目について説明します。

① 『タイプ』に「Google Spreadsheet」を選択してください。

② 『サービスアカウントキー』に〔 Google API Console 〕のサービスアカウントキー作成時にダウンロードした、JSON形式ファイルのデータを、修正を加えず貼り付けしてください。

③ 『シートID』にGoogle SpreadsheetのURLに表示されている「シートID」を入力してください。
[入力例]
https://docs.google.com/spreadsheets/d/【シートID】/edit#gid=0

④ 『値』にGoogle Spreadsheetの各列に挿入するデータを入力してください。

HTTP(S)のGET、POSTを使用した外部システム連携実装手順について説明します。

実装手順例（HTTP(S) － GET）

（外部API）外部システム連携設定
JSONを返すAPIを用意してください。
本手順では、各種気象データの無料APIを提供するオンラインサービス〔 OpenWeatherMap 〕を利用します。
※ ライセンスは、OpenStreetMapのクリエイティブ・コモンズCC-BY-SA2.0に準じます。
※ 他社が提供しているAPIを利用する場合は、必ずサービス提供元の利用規約を確認の上、ご利用下さい。
1. API利用にはAPIキーが必要です。OpenWeatherMapへアクセスし、ユーザー登録をしてください。
  
  ① ユーザー名を入力してください。
  
  ② メールアドレスを入力してください。
  
  ③ パスワードを入力してください。
  
  ④ パスワードを再度入力してください。
  
  ⑤ 年齢を確認後、チェックを入れてください。
  
  ⑥ 利用規約とプライバシーポリシーを確認後、チェックを入れてください。
  
  ⑦ ニュース、アップデート、オファーに関するメールを受け取る場合は、チェックを入れて
  ください。
  
  ⑧ チェック入れた後、表示されるメッセージに従って、ロボットではないことを証明してください。
  
  ⑨ “Create Account“ボタンをクリックしてください。
2. ログイン後、”API Keys“タブをクリックしてください。
3. 『Key』をコピーして控えてください。
（DialogPlay）チャットボット作成
1. 左メニューの『チャットボット一覧』を選択し、”新規作成“ボタンをクリックしてください。
2. 『チャットボット名』と必要に応じて『初期発言』を入力し、”保存“ボタンをクリックしてください。
（DialogPlay）外部システム連携設定
ユーザーが入力した地域を元に、該当地域の気象データを取得する外部システム連携を作成します。
1. 『外部システム連携』タブから”新規作成“ボタンをクリックしてください。
2. 『外部システム連携先』に外部システム連携名、『説明』に作成する外部システム連携の説明を入力してください。
3. 以下の例を参考に、各項目を入力してください。
  
  ① 『タイプ』に「HTTP(S)」を選択してください。
  
  ② 『URL』に接続先URLを入力してください。
  [入力例]
  http://api.openweathermap.org/data/2.5/forecast?q={{エリア}},JP&units=metric&APPID=【API Key】
  【API Key】は、「（外部API）外部システム連携設定」手順1-3でコピーしたKeyを入力してください。
  
  ③ 『Method』に「GET」を選択してください
  
  ④ 『Headers』はGETのため、空白としてください。
  
  ⑤ 『Request Body』はGETのため、空白としてください。
4. 外部連携先から取得する値を、以下の例を参考に各項目を入力してください。
  
  ① 『Response Type』に、デフォルトで「JSON」が選択されます。
  
  ② 『Response Map』の『変換元』に、JSONのキー（外部システムから取得する値）を入力し、『変換先』にシナリオ内で変数として使用するための変換情報を入力してください。
  [入力例]
  
  No 変換元変換先
  
  1 city.name エリア
  
  2 list[1].weather[0].main 予報
  
  3 list[1].main.temp 気温
  
  4 list[1].main.humidity 湿度
  - Response値について
    今回のシナリオでは、3時間後の気象データを利用するため、リスト番号（list[1]）を設定しています。
    ※ パラメーターに関する詳細は、〔 OpenWeatherMap 〕をご覧ください。
5. “保存“ボタンをクリックしてください。
6. 作成した外部連携が問題なく動作しているかどうか、テストを行うことができます。
  動作テストを行う場合は、”テスト“ボタンをクリックしてください。
  
  [外部連携の実行画面]
（DialogPlay）シナリオ作成
1. チャットボット画面に戻り、『シナリオ一覧』タブから”新規作成“ボタンをクリックしてください。
2. 『シナリオ名』と『ユーザー発言例（発言例タブ）』を入力してください。
3. 『シナリオの流れ』エリアの中にあるリストから「テキスト発言」を選択し、”アクションを追加“ボタンをクリックしてください。
4. 『発言内容』に以下の例を参考に入力してください。
  
  [入力例]
  3時間後の天気予報をお知らせします。
5. 『シナリオの流れ』エリアの中にあるリストから『ヒアリング』アクションを追加し、『ヒアリング項目』に以下の例を参考に、各項目を入力してください。
  
  [入力例]
  
  No ヒアリング項目名タイプ項目ごとの質問文
  
  1 エリア @text 地域をローマ字で入力してください。（札幌市の場合はSapporoまたはSapporo-shi）
6. 『シナリオの流れ』エリアの中にあるリストから『外部システム連携』アクションを追加し、『連携先』に手順3で作成した「3時間後の天気」を選択し、『変数一覧』に手順3-4で設定した変換先が、変数として表示されていることを確認してください。
7. 『シナリオの流れ』エリアの中にあるリストから『テキスト発言』アクションを追加し、『発言内容』に以下の例を参考に入力してください。
  『変数一覧』に表示されている変数名を、{{}}で囲って記述することで変数として利用できます。
  
  [入力例]
```
3時間後の{{エリア}}の天気は、以下の通りです。
天気：{{予報}}
気温：{{気温}}
湿度：{{湿度}}
```
8. 保存後、「学習データが更新されています。反映するには学習ボタンを押してください。」というメッセージが表示されますので、”保存してチャットボットを学習“ボタンをクリックしてください。
『シミュレーター』機能で動作を確認してください。

実装手順例（HTTP(S) － POST）

（DialogPlay）チャットボット作成
1. 左メニューの『チャットボット一覧』を選択し、”新規作成“ボタンをクリックしてください。
2. 『チャットボット名』と必要に応じて『初期発言』を入力し、”保存“ボタンをクリックしてください。
（DialogPlay）外部システム連携設定
ユーザーが入力した情報を社員名簿に登録、登録した値を取得する外部システム連携を作成します。
本手順では、例として〔 DummyAPI 〕を利用します。
※ 他社が提供しているAPIを利用する場合は、必ずサービス提供元の利用規約を確認の上、ご利用下さい。
1. 『外部システム連携』タブから”新規作成“ボタンをクリックしてください。
2. 『外部システム連携先』に外部システム連携名、『説明』に作成する外部システム連携の説明を入力してください。
3. 以下の例を参考に、各項目を入力してください。
  
  ① 『タイプ』に「HTTP(S)」を選択してください。
  
  ② 『URL』に接続先URLを入力してください。
  [入力例]
  http://dummy.restapiexample.com/api/v1/create
  
  ③ 『Method』に「POST」を選択してください
  
  ④ 『Headers』に送信するデータのヘッダ名と値を、以下の例を参考に入力してください。
  [入力例]
  
  No 名前値
  
  1 Content-Type application/json
  
  ⑤ 『Request Body』に、送信する内容を、以下の例を参考に入力してください。
  シナリオ内で使用する変数名を{{}}で囲って記述することで、ユーザーとの会話からヒアリングした情報を、受け渡すことが可能になります。
  [入力例]
```
{
 "name":"{{名前}}",
 "salary":"{{給料}}",
 "age":"{{年齢}}"
}
```
4. 外部連携先から取得する値を、以下の例を参考に各項目を入力してください。
  
  ① 『Response Type』に、デフォルトで「JSON」が選択されます。
  
  ② 『Response Map』の『変換元』に、JSONのキー（外部システムから取得する値）を入力し、『変換先』にシナリオ内で変数として使用するための変換情報を入力してください。
  [入力例]
  
  No 変換元変換先
  
  1 id ユーザーID
  
  2 name 社員名
  
  3 salary 社員給料
  
  4 age 社員年齢
5. “保存“ボタンをクリックしてください。
6. 作成した外部連携が問題なく動作しているかどうか、テストを行うことができます。
  動作テストを行う場合は、”テスト“ボタンをクリックしてください。
  
  [外部連携の実行画面]

（DialogPlay）シナリオ作成

チャットボット画面に戻り、『シナリオ一覧』タブから”新規作成“ボタンをクリックしてください。
『シナリオ名』と『ユーザー発言例（発言例タブ）』を入力してください。
『シナリオの流れ』エリアの中にあるリストから「テキスト発言」を選択し、”アクションを追加“ボタンをクリックしてください。
『発言内容』に以下の例を参考に入力してください。

[入力例]
社員情報を名簿に登録します。

『シナリオの流れ』エリアの中にあるリストから『ヒアリング』アクションを追加し、『ヒアリング項目』に以下の例を参考に、各項目を入力してください。

[入力例]

No	ヒアリング項目名	タイプ	項目ごとの質問文
1	名前	@text	社員名を入力してください。（例：ダイアログ太郎）
2	給料	@number	給料を入力してください。（例：270000）
3	年齢	@number	年齢を入力してください。（例：30）

『シナリオの流れ』エリアの中にあるリストから『外部システム連携』アクションを追加し、『連携先』に手順2で作成した「社員名簿」を選択し、『変数一覧』に手順2-4で設定した変換先が、変数として表示されていることを確認してください。
『シナリオの流れ』エリアの中にあるリストから『テキスト発言』アクションを追加し、『発言内容』に以下の例を参考に入力してください。
『変数一覧』に表示されている変数名を、{{}}で囲って記述することで変数として利用できます。

[入力例]
```
以下の内容で情報を登録しました。
ユーザーID：{{ユーザーID}}
社員名：{{社員名}}
給料：{{社員給料}}
年齢：{{社員年齢}}
```
保存後、「学習データが更新されています。反映するには学習ボタンを押してください。」というメッセージが表示されますので、”保存してチャットボットを学習“ボタンをクリックしてください。

『シミュレーター』機能で動作を確認してください。
※ 公開されているAPIの為、他ユーザーが実施した多くの情報が登録されています。
その為、既にデータ内に存在する名前（例：山田太郎）を登録しようとすると、エラーが返ってくる場合があります。
エラーが返ってきた場合は、被らない名前を使用して再度お試しください。

Google Spreadsheetの外部システム連携実装手順について説明します。

実装手順例（Google Spreadsheet）

（外部API）外部システム連携設定 - 前準備
1. 〔 Google API Console 〕へアクセスし、”プロジェクトの選択“をクリックしてください。
2. “新しいプロジェクト“をクリックしてください。
3. 『プロジェクト名』を入力し、必要に応じて『場所』を入力後、”作成“ボタンをクリックしてください。
4. “認証情報“をクリックしてください。
5. “認証情報を作成“ボタンをクリックし、”サービスアカウントキー“を選択してください。
6. 『サービスアカウント』に「新しいサービスアカウント」を選択してください。
7. 以下の例を参考に、各項目を入力してください。
  
  ① 『サービスアカウント名』に、わかりやすい名前を入力してください。
  
  ② 『役割』に任意の役割を選択してください。
  
  ③ 『キーのタイプ』に「JSON」を選択してください。
8. “作成“ボタンをクリックした後、サービスアカウントキーファイルがダウンロードされます。
  ※ サービスアカウントキーファイルは、一度しかダウンロードできない為、紛失した場合は再度サービスアカウントキーを作成する必要があります。
（外部API）外部システム連携設定 - Google Spreadsheet
1. ””をクリックしてください。
2. 『IAMと管理』を選択し、”サービスアカウント“をクリックしてください。
3. 手順2-7で使用するため、『メール』をコピーしてください。
4. 〔Google Spreadsheet〕へアクセス後、”空白“をクリックしてください。
5. “共有“ボタンをクリックしてください。
6. ファイルが未保存の場合、保存画面が表示されますので、ファイル名を入力し、”保存“ボタンをクリックしてください。
7. 『ユーザー』に手順2-3で取得したメールアドレスを入力し、”送信“ボタンをクリックしてください。
8. 〔Google API Console〕へアクセスし、『検索窓』に「Google Sheets API」と入力し、表示された候補をクリックしてください。
9. “有効にする“ボタンをクリックしてください。
（DialogPlay）チャットボット作成
1. 左メニューの『チャットボット一覧』を選択し、”新規作成“ボタンをクリックしてください。
2. 『チャットボット名』と必要に応じて『初期発言』を入力し、”保存“ボタンをクリックしてください。
（DialogPlay）外部システム連携設定
ユーザーが入力した情報をGoogle Spreadsheetに登録する外部システム連携を作成します。
1. 『外部システム連携』タブから”新規作成“ボタンをクリックしてください。
2. 『外部システム連携先』に外部システム連携名、『説明』に作成する外部システム連携の説明を入力してください。
3. 以下の例を参考に、各項目を入力してください。
  
  ① 『タイプ』に「Google Spreadsheet」を選択してください。
  
  ② 『サービスアカウントキー』に手順1-8で取得した、サービスアカウントキーファイルの内容を、修正を加えず貼り付けしてください。
  
  ③ 【シートID】に手順2-4で作成した、Google SpreadsheetのURLに記載されている、シートIDを入力してください。
  [入力例]
  https://docs.google.com/spreadsheets/d/【シートID】/edit#gid=0
4. 『値』に、Google Spreadsheetに出力する値を、以下の例を参考に入力してください。
  シナリオ作成時に定義した変数名を、{{}}で囲って記述することで変数として利用できます。
  ※ 変数の定義は、手順5-5で実施しますが、先行して入力しています。
  
  [入力例]
  
  列ID 値
  
  A {{項目1}}
  
  B {{項目2}}
  
  C {{項目3}}
5. “保存“ボタンをクリックしてください。
6. 作成した外部連携が問題なく動作しているかどうか、テストを行うことができます。
  動作テストを行う場合は、”テスト“ボタンをクリックしてください。
  
  [外部連携の実行画面]

（DialogPlay）シナリオ作成

チャットボット画面に戻り、『シナリオ一覧』タブから”新規作成“ボタンをクリックしてください。
『シナリオ名』と『ユーザー発言例（発言例タブ）』を入力してください。
『シナリオの流れ』エリアの中にあるリストから「テキスト発言」を選択し、”アクションを追加“ボタンをクリックしてください。
『発言内容』に以下の例を参考に入力してください。

[入力例]
Google Spreadsheetへ値を挿入します。

『シナリオの流れ』エリアの中にあるリストから『ヒアリング』アクションを追加し、『ヒアリング項目』に以下の例を参考に、各項目を入力してください。
入力した項目名が『変数一覧』に、変数として表示されていることを確認してください。

[入力例]

No	ヒアリング項目名	タイプ	項目ごとの質問文
1	項目1	@text	項目1に挿入する値を教えてください。
2	項目2	@text	項目2に挿入する値を教えてください。
3	項目3	@text	項目3に挿入する値を教えてください。

『シナリオの流れ』エリアの中にあるリストから『外部システム連携』アクションを追加し、『連携先』に手順4で作成した「Google Spreadsheetへ値挿入」を選択してください。
『シナリオの流れ』エリアの中にあるリストから『テキスト発言』アクションを追加し、『発言内容』に以下の例を参考に入力してください。
『変数一覧』に表示されている変数名を、{{}}で囲って記述することで変数として利用できます。

[入力例]
```
Google Spreadsheetに以下の内容を登録しました。
A：{{項目1}}
B：{{項目2}}
C：{{項目3}}
```
保存後、「学習データが更新されています。反映するには学習ボタンを押してください。」というメッセージが表示されますので、”保存してチャットボットを学習“ボタンをクリックしてください。

『シミュレーター』機能で動作を確認してください。
1. シミュレーター画面で、シナリオ開始後、各項目の値をチャット欄に入力してください。
2. 〔 Google Spreadsheet 〕へアクセスし、入力したデータが登録されていることを確認してください。

No	変換元	変換先
1	city.name	エリア
2	list[1].weather[0].main	予報
3	list[1].main.temp	気温
4	list[1].main.humidity	湿度

No	変換元	変換先
1	id	ユーザーID
2	name	社員名
3	salary	社員給料
4	age	社員年齢

列ID	値
A	{{項目1}}
B	{{項目2}}
C	{{項目3}}