本文書は機械翻訳された文書で、語彙、構文、文法に誤りが生じます。 専門家の翻訳が完了したら修正される予定です。
気になる点は、お問い合わせでお問い合わせください。
便利なサービスの提供に最善を尽くします。
목차
アクションメソッドを使用ガイド
チェトボトで外部のシステムのデータを連動する方法は、アクションメソッド(ActionMethod)を介して可能です。
重要!
アクションメソッドを便利に使用するにはREST API呼び出しなど、事前の開発の知識が必要です。 また、チェトボトのアクションメソッドの呼び出しに応答することができるBackend System環境の準備が必要です。(チェトボトサービスと連動する顧客のBackend System環境がすべて異なっているためです。)
CLOVA Chatbotサービスでは、アクションメソッドGEP/ POSTスペックを提供していますが、これを連動するようにBackendサーバーを実装することは、お客様の開発領域であり、CLOVA Chatbotサービス提供範囲に含まれていません。
開発利便性を高めるために、アクションメソッドでどのような形式でBackend ServerにGET/ POSTを送信するか、アクションメソッドRequestを確認する方法(echo)を提供しています。
アクションメソッドを理解する
アクションメソッドを使用するときはチェトボトでEntity値を定義し、Entityにマップされたユーザーの入力値を一緒に送信されます。ユーザーが入力した値(エンティティのマッピングされた値)を、外部のBackend Serverと連動するための方法を提供することです。
つまり、エンティティとして認識された値の情報をBackend Serverに転送して処理したり、その情報に基づいて照会して、ユーザーに回答をする場合に活用されます。
また、Backend Serverでは、アクションメソッドの呼び出し時に一緒に送信されるパラメータを処理して、どの応答を与えるあらかじめ設計しなければします。
アクションメソッドのパラメータ
アクションメソッドを介してBackendSystemに情報を送信するには定義されたパラメータの形式が必要です。この時、「エンティティ」が使用されます。
事前定義されたentityは、ユーザーのデータをマッピングするkeyであり、アクションメソッドの使用のためには「エンティティ」が必須で一緒に定義されて動作する必要があります。
事前定義されたentityをアクションメソッドでも使用することができます。
- ドメインエンティティ:ユーザーが定義したエンティティです。
- システムエンティティ:システムに登録された共通のエンティティです。
- APIエンティティ:APIを介して外部DBに保存されたエンティティデータを使用することができます。
アクションメソッドを使用例
簡単なアクションメソッドを使用例を挙げてみましょう。
まず、$ {ピザの注文を更新}というアクションメソッドを作成します。
例えばピザ数量」というドメインのエンティティを事前に定義してノトアトゴ、ピザ数量を問う質問にユーザーが「第2版」と答えをしました。
この場合、チェトボトでは「entitykey '=' entityvalue」の形で「ピザ数量」=「2版」の情報が作成されます。
入力された情報をActionMethodを通じてサーバーに送信する場合は、アクションメソッド$ {ピザの注文の更新}を呼び出すことになります。
アクションメソッド$ {ピザの注文を更新}の呼び出しのためには既定のされたBackend Systemの呼び出しURLを設定する必要があります。
すぐに確認のためecho機能によりActionMethod V1.0、Get方式で配信する場合は、次のようにすることができます
parameter1にピザ数量entityの値「2版」を入れてボネヌ場合には、
次のようにparameter1 = $ [ピザ数量]に設定します。
ex) http://chatbot.ncloud.com/?parameter1=$[피자수량]
実際の呼び出し時に$[ピザ数量]は「2版」に置き換えされることになります。
http://chatbot.ncloud.com/?parameter1=2版
また、${ピザの注文を更新}アクションメソッドを呼び出すときにGET/ POSTメソッドのHttp header(X-KAA-USERENTITY)もentity情報が含まれます。(下ActionMethod詳細に説明されます。)
このように、アクションメソッドにentityマッピングされた情報が転送された後、アクションメソッドが呼び出されるとチェトボトでBackendSystemサーバーでくれる応答を待ちます。ActionMethodの呼び出しtimeoutデフォルトの設定は、200msです。
Backend SystemでActionMethodの応答として「注文(アップデート)完了」という応答を転送します。
このように呼び出されたアクションメソッドは、回答フィールドに入力されたように、回答が応答されるタイミングに呼び出されます。
お客様の回答フィールドに入力:${ピザの注文を更新}されました。 実際のチェトボト回答:注文(アップデート)完了しました。
アクションメソッドの詳細スペック
アクションメソッドは2つのspecを提供します。
Version | 説明 | 例示 |
---|---|---|
アクションメソッドV1.0 | 一度の呼び出しで一度の値だけを受けることができる、GET/ POSTメソッドを提供 | 例:「現在亭子洞の天気は${weather}導入します。」 |
アクションメソッドV2.0 | 一度の呼び出しで複数の値を得ることができていること、POSTメソッドを提供 | 例:「${membership.name}お客様の残りのポイントは、${membership.point}ポイントです。」 |
アクションメソッドV1.0
アクションメソッドは、${ActionMethodName}
の形で定義されます。
GET方式
名前:アクションメソッドの名前を入力します。
URL:呼び出すURLを入力します。
応答の形式は次のとおりです。
HttpMethod: GET Http Headers: { X-KAA-USERENTITY=test_date%3dsaturday%26test_time%3d3o%27clock%26test_num%3d2people, X-KAA-USERKEY=4d4cf7425f5b4769807fb4cba66bd987, X-KAA-USERMSG=%E3%85%87, X-KAA-USERID=9ff4-b49e74ea22e4 } body ={}
- X-KAA-USERKEY:ハッシュされたユーザのキー値を渡します
- X-KAA-USERENTITY:タスクが終了されたり、スロットが進行中であるとき、登場したエンティティの情報が含まれています
エンティティキー=実体値&エンティティキー=エンティティの値&...
のような形式で含まれておりutf-8エンコードされています。 - X-KAA-USERMSG:ユーザーの発火が含まれています。主観式フォームが登場したとき、ユーザが入力した場合のみ動作します。 utf-8でエンコードされています
- X-KAA-USERID:ユーザーのoriginal userIdが含まれています。
- X-KAA-CLOVA-OAUTH-ACCESS-TOKEN:CLOVAプラットフォームに要求が来た場合、そのドメインが外部認証を使用している場合は、認証トークンがCLOVA要求込められてくるようになります。その値を流通に設定したアクションメソッドを呼び出した場合は、このヘッダーを使用して、そのトークンの値を渡します。
- X-KAA-SESSION-ATTRIBUTES:ActionMethodの応答値で、この値をキーしたヘッダの値がある場合、エンジンはしばらくの間、その値を記憶しているが、この値を伝達してほしいというフラグがonであるアクションメソッドが呼び出された場合ヘッダに受けた値をそのまま込めお届けします
そう作成したアクションメソッドは、回答フィールドに入力して、回答が応答されるタイミングに呼び出されます。
- 例えば、回答を「現在亭子洞の天気は${weather}導入します。」と定義した場合、${weather}の値は、定義されたURLを呼び出してResponseに戻ってくる情報です。この値が「24」であればチェトボトは「現在亭子洞の天気は、24度です。」と答えています。
- ただし、アクションメソッドV1.0は、回答に最大2個まで入力可能です。
JSON(POST)方式
JSON(POST)方式は、GETメソッドと同じか、URL、呼び出しにデータを含む送信することができます。データを送信する形式は、JSON形式です。
要求の形式は次のとおりです。
HttpMethod: POST Http Headers: { X-KAA-USERENTITY=test_date%3dsaturday%26test_time%3d3o%27clock%26test_num%3d2people, X-KAA-USERKEY=4d4cf7425f5b4769807fb4cba66bd987, X-KAA-USERMSG=%E3%85%87, X-KAA-USERID=9ff4-b49e74ea22e4 } body ={"state": "korea", "country": "seoul"}
- もしアクションメソッドV1.0をテストしたい場合は、echo呼び出しをクリックしてください。
アクションメソッドV1.0は、エンティティデータのほか、特定の値を一緒に送信することができます。
CLOVA OAuth Access Tokenの設定を有効にしてCLOVA Extensionで認証されたユーザーアカウントのAccess tokenを渡すことができます。
Session Attributesの設定を有効にして、特定の文字列を、X-KAA-SESSION-ATTRIBUTESヘッダーに含めて渡すことができます。この時、文字列はUTF-8でURLエンコードする必要があります。
- チェトボトサーバーが呼び出されたアクションメソッドの応答値のヘッダにX-KAA-SESSION-ATTRIBUTES値が存在する場合は、チェトボトサーバーは、その文字列を、各ユーザごとにキャッシュしておきます
- アクションメソッドの作成時にSession Attributes設定を有効にした場合は、最後にキャッシュされた文字列を、X-KAA-SESSION-ATTRIBUTESヘッダーに含めて送信します。
アクションメソッドV2.0
アクションメソッドV1.0との違いは、一回の呼び出しで複数の値を取得することができるという点です。
アクションメソッドV2.0は、JSON(POST)方式のみをサポートします。
名前:アクションメソッドの名前を入力します。
URL:呼び出すURLを入力します。
要求の形式は次のとおりです。
{ "actionMethod": { "name": "アクションメソッドの名前です", "methods": [ { "args": [ "arg1", "age2" ], "variableName": "回答に含まれている変数名です1" }, { "variableName": "回答に含まれている変数名です2" } ] }, "userInfo": { "id": "メッセンジャーから受信したユーザーのIDをが含まれています", "key": "サービングエンジン内部で使用するユーザーの一意のキーをハッシュした値です", "query": "ユーザーが今回のターンに入力された発火です", "entities": { "エンティティコード1": "ユーザーが入力したエンティティ1", "エンティティコード2": "ユーザーが入力したエンティティ2" }, "taskEntities": { "エンティティ名1": "タスクのスロットに満たされたエンティティ1", "エンティティ名2": "タスクのスロットに満たされたエンティティ2" } } }
応答の形式は次のとおりです。
{ "data": [ { "variableName": "変数名に対応する部分です", "value": "variableNameに対応する変数をどのような値で置換するかどうかを決定します" } ] }
そう作成したアクションメソッドは、回答フィールドに入力して、回答が応答されるタイミングに呼び出されます。
- 回答にアクションメソッドV2.0を入力するときは、
$ 2 {アクションメソッド2名}
または$ 2 {アクションメソッド2名。変数名}
の形式で入力します。 - たとえば、回答を「$ {membership.name}お客様の残りのポイントは、$ {membership.point}ポイントです。」と定義した場合、$ {membership.name}と$ {membership.point}の値は、定義されたURLを呼び出してResponseに戻ってくるvariableNameのvalueです。
name
のvlaueがホン・ギルドン '、' point
のvalueが1000
だったら、チェトボトは「ホン・ギルドンお客様の残りのポイントは1000ポイントです。」と答えています。
- 回答にアクションメソッドV2.0を入力するときは、
もしアクションメソッドV2.0をテストしたい場合は、echo呼び出しをクリックしてください。
$ 2 {アクションメソッド名.method}
を入力する場合は、POSTをエコーします。$ 2 {アクションメソッド名.body}
を入力する場合はbodyをエコーします。