外部サービス作成(設定画面)

外部サービスと連携する設定を行う画面です。外部サービスの接続設定は、各エージェントの[設定] – [外部サービス一覧]の画面で管理を行うことができます。

I/F情報（入力項目）

外部サービス名（integration名）

APIを呼び出すための名前です。トピックエディタ上での呼び出し方はサービス実行(エディタ画面)を参照ください

Request情報

method	GetやPostの指定
url	APIアクセスURL
header	Content-Type等、ヘッダーの情報（複数設定可）
body	ボディの情報(JSON形式)

※APIからのレスポンスとして受け取れる形式はjson（application/json）となります。テキストは非推奨となりますのでご注意ください。multipart(binary)には対応しておりません。

※入力されたURLはURLエンコードされて保存されます。

アクセス元IPアドレス

設定したAPIに対しては、以下のIPアドレスからのアクセスが発生します。IPアドレスを制限している場合は、以下のIPアドレスからのリクエストを許可する設定を行ってください。

35.74.207.53/32

※2021/06/04のメンテナンス以降アクセス元IPは変更されております。変更前18.182.254.136/32

リクエストの作成方法

リクエストボディにはトピックエディタで扱っている変数が利用可能です。以下の仕様に沿って動的なリクエストを作成しましょう。

入力方法

#から始まる変数名を入力して下さい。#を入力すると自動的に既存の変数がサジェストされます。新しい変数を設定したい場合は変数名を入力した上で、サジェストウィンドウ下部の「変数の追加」をクリックして新たに変数を作成して下さい。

利用可能箇所

JSON内の各属性の値として利用できます。キー名としては利用できません。

設定画面で準備した外部サービスを@integrationで呼び出すことが可能です。設定したintegration名や、レスボンスのキー名を.(ピリオド)で連結して取得します。特定のコンポーネントでのみ利用可能です。

初期値

初期値はundefinedです。APIを実行するタイミングで変数に値が入っていない場合はundefinedが送信されます。API実行のタイミングに関してはエディタ画面での利用方法を参照して下さい。

制限事項

変数と通常文字列を組み合わせて、一つの属性の値の中に設定することはできません。

外部サービス実行(エディタ)

使用可能コンポーネント

• 前処理(右辺)
• 条件分岐(左辺、右辺)
• アクション[メッセージ・コマンド]
• 後処理(右辺)

実行のタイミング

1つのintegrationにつき、1回の対話で1回のみリクエストを実施します。一つのセクションの中で最初に呼び出されたタイミングでAPIリクエストを実施します。変数を利用する場合はそれ以前に変数に値を格納しておく必要がありますのでご注意下さい。

レスポンスのキャッシュについて

取得した値はセッション毎に自動的にクリアされます。取得した値を保存しておきたい場合は、前処理もしくは後処理で変数に値を格納してください。

エラー処理に関して

APIから返却されるHTTPステータスコードは@integration.{integration名}.statusに格納されます。エラーハンドリングを行う場合は条件セクションでこちらを利用して下さい。

レスポンスの取得方法

APIレスポンスのHTTPステータスコードとレスポンスボディがそれぞれstatusとbodyに格納されます。具体的な取り出し方は以下の表を参照して下さい。

用途	設定する文字列	レスポンス例	取得できる値
オブジェクト全体を取得	@integration.{integration名}	{“key”:”value”}	“{\”status\”:\”200\”, \”body\”:{\”key\”:\”value\”}}”
ステータスコードを取得	@integration.{integration名}.status	–	“200”,”400″,”500″ etc…
APIのレスポンスボディ全体を取得	@integration.{integration名}.body	{“key”:”value”}	“{\”key\”:\”value\”}”
キーを指定して値を取得	@integration.{integration名}.body.{key}	{“key”:”value”}	“value”
ネストオブジェクトを指定して値を取得	@integration.{integration名}.body.key1.key2	{“key1”:{“key2″:”value2”}}	“value2”

※配列も格納可能ですが、要素の取り出しには対応しておりません。

より高度な使い方

PredicateStore関数の使用

predstoreタグを利用し、連携ボット側でAPIの実行結果にアクセスすることが可能です。外部API連携におけるpredstoreの変数名は、以下のような規則に従います。

integrations.{integration_id}

integration_idに関しては設定画面のintegration名の右側をご確認下さい。

用意されている関数を利用し、タグ内でデータ操作を行うことができます。predstoreタグの利用方法に関する詳細はSUNABAをご参照ください。