Web フックの定義

ダイアログに対して1つのURL を定義し、1つ以上のダイアログノードからウェブフックを呼び出すことができます。

外部サービスへのプログラマチック呼び出しは、以下の要件を満たす必要があります。

• 呼び出しは POST HTTP 要求であること。
• 要求本体は JSON オブジェクト (Content-Type: application/json) でなければなりません。
• 応答は JSON オブジェクト (Accept: application/json) でなければなりません。
• コールは8秒以内に戻らなければなりません。 ダイアログ・ノード を介して 1 回のメッセージ呼び出しで複数回開始された場合、それらの呼び出しはすべて 8 秒以内に戻る必要があります。

ご利用の外部サービスが GET リクエストのみをサポートしている場合、または実行時に動的に URLを指定する必要がある場合は、実行時の任意の値を含む JSON ペイロードを POST リクエストで受け付ける中間サービスを作成することをご検討ください。 その後、中間サービスは、これらの値を URL パラメーターとして渡してターゲット・サービスに要求を行い、応答をダイアログに返すことができます。

8 秒以内に戻らない可能性があるサービスを呼び出す必要がある場合は、カスタム・クライアント・アプリケーションを介して呼び出しを管理し、別個のステップとして情報をダイアログに渡すことができます。 詳しくは、 クライアント・アクションの要求 を参照してください。

Web フックの詳細を追加するには、以下の手順を実行します。

1. Webhook を追加するダイアログで、 「Webhook」 をクリックします。

2. **「URL」**フィールドに、HTTP POST 要求コールアウトを送信する外部アプリケーションの URL を追加します。

   例えば Language Translatorを呼び出すには、サービスインスタンスURL を指定します。

   https://api.us-south.language-translator.watson.cloud.ibm.com/v3/translate?version=2018-05-01
   

   呼び出した外部アプリケーションが応答を返す場合は、JSON 形式で応答を返せなければなりません。 例えば Language Translatorでは、結果が返されるフォーマットを指定する必要があります。 そのためには、サービスにヘッダーを渡します。

3. 「ヘッダー」セクションで、**「ヘッダーの追加 (Add header)」**をクリックし、サービスに渡すヘッダーを 1 つずつ追加します。

   例えば、このヘッダーは、要求が JSON 形式であることを示します。

   ヘッダーの例

   ヘッダー名	ヘッダー値
   Content-Type	application/json

4. 要求と一緒に基本認証の資格情報を渡す必要がある外部サービスの場合は、資格情報を指定します。 **「許可の追加 (Add authorization)」をクリックして、資格情報を「ユーザー名 (User name)」フィールドと「パスワード」フィールドに追加し、「保存」**をクリックします。

   資格情報を base-64 でエンコードした ASCII 文字列が生成され、ページに追加するヘッダーも自動的に生成されます。

   ヘッダーの例

   ヘッダー名	ヘッダー値
   認証情報	基本 <encoded-credentials>

   ウェブチャットの統合機能を使用し、セキュリティを有効にしている場合、ウェブチャットのセキュリティに使用しているのと同じトークンを Authorization ヘッダーで使用できます。 詳しくは、Web チャット: Web フック認証での JWT の再使用を参照してください。

Web フックの詳細は自動的に保存されます。

ダイアログ・ノードへの Web フック・コールアウトの追加

ダイアログ・ノードから Web フックを使用するには、そのノードで Web フックを有効にしてからコールアウトの詳細を追加する必要があります。

1. コールアウトを追加するダイアログ・ノードを見つけます。 このノードがユーザーとの会話中にトリガーされるたびに、ウェブフックへのコールアウトが発生します。

   例えば、#General_Greetings ノードから Web フックにコールアウトを送信できます。

2. 対象のダイアログ・ノードをクリックして開き、**「カスタマイズ」**をクリックします。

3. Web フック・セクションまでスクロールダウンします。 ウェブフック/アクションへの呼び出しスイッチ をオンに設定します。

4. **「Web フックを呼び出す (Call a webhook)」を選択し、「適用」**をクリックします。

   **「複数の条件付き応答 (Multiple conditioned responses)」スイッチは、まだ有効にしていなければ自動的に「オン」**に設定され、無効にすることはできません。 この設定が有効になるのは、Web フック呼び出しの成功/失敗に応じて異なる応答を追加できるようにするためです。 すでにノードに対して指定されている応答がある場合、それが最初の条件付き応答となります。

5. 外部アプリケーションに渡すデータを、キーと値のペアとして*「パラメーター」*セクションに追加します。

   パラメーターは、要求本体プロパティーとして渡されます。 ダイアログ・ノードで照会パラメーターまたは URL パラメーターを指定することはできません。 これらのパラメータは、ウェブフック定義の一部としてのみ静的値で設定できます。 詳しくは、Web フックの定義を参照してください。

   例えば、Language Translator サービスを呼び出す場合は、以下のパラメーターの値を指定する必要があります。

   パラメーターの例

   キー	値	説明
   model_id	en-es	入力言語と出力言語を指定します。 この例の要求では、英語 (en) のテキストをスペイン語 (es) に変換します。
   テキスト	How are you?	このパラメーターには、サービスで変換するテキスト文字列が入ります。 この値をハードコードすることも、$saved_textなどのコンテキスト変数を渡すことも、あるいはユーザー入力を直接サービスに渡すこともできます。 <? input.text ?> をこの値として指定することで、これらの操作が可能です。

   より複雑なユース・ケースでは、例えば、旅行計画に関するユーザーとの会話中に情報を収集できます。 日付と目的地の情報を収集し、コンテキスト変数に保存し、パラメーターとして外部アプリケーションに渡すことができます。

   旅行パラメーターの例

   キー	値
   depart_date	$departure
   arrive_date	$arrival
   origin	$origin
   destination	$destination

6. コールアウトによってなされた応答はすべて、戻り値変数に保存されます。 **「戻り変数 (Return variable)」**フィールドに自動的に追加されるこの変数は、名前を変更できます。 コールアウトの結果がエラーになった場合、この変数には null が設定されます。

   生成される変数名は、 webhook_result_n という構文を持ちます。 _n という接尾辞は、ウェブフックコールアウトをダイアログノードに追加するたびにインクリメントされます。 この命名規則により、コンテキスト変数名がダイアログ全体で一意であることが保証されます。 変数名を変更する場合は、必ず固有の名前を使用してください。

7. 条件付き応答のセクションには 2 つの応答条件が自動的に追加されます。1 つは Web フックのコールアウトが成功し、戻り変数が返されたときに表示される応答です。 もう 1 つはコールアウトが失敗したときに表示される応答です。 これらの応答を編集することも、条件付き応答をノードに追加することもできます。

   • コールアウトが応答を返す場合は、その JSON 応答の形式がわかっていれば、ダイアログ・ノードの応答を編集して、ユーザーに提示したい応答のセクションのみを含めることができます。

     例えば、Language Translator サービスが次のようなオブジェクトを返すとします。

        {
        "translations":[
           {"translation":"¿Cómo estás?"}
        ],
        "word_count":3,
        "character_count":12
        }
     

     変換されたテキストの値のみを抽出する SpEL 式を使用します。

     条件付き応答の例

     条件	応答
     $webhook_result_1	スペイン語でのあなたの言葉：.
     anything_else	外部アプリケーションへの呼び出しが失敗しました。 しばらくしてからやり直してください。

     推奨される形式で応答した場合に、先に示した翻訳応答が返された場合、アシスタントのユーザーへの応答は次のようになります。 Your words in Spanish: ¿Cómo estás?

   • コールアウトが空の文字列を返した場合に特定の応答を返したい場合、つまり、コールは成功したが、返された値が空の文字列である場合、条件付き応答を追加し、条件として次のような構文を使用することができます

     $webhook_result_1.size() == 0
     

8. 完了したら、「X」をクリックしてノードを閉じます。 変更内容は自動的に保存されます。

Web フックのテスト

ウェブフックのコールアウトを初めて追加する際には、外部アプリケーションからの応答で何が返されるのか、そのデータとフォーマットを正確に確認することが役立つ場合があります。 成功したコールアウトの条件付き応答のテキスト応答として、この式を追加します。 $webhook_result_n ここで、 n はテストするウェブフックの適切な番号です。

この応答は戻り変数の本体全体を返すので、コールアウトから戻された内容を確認してから、ユーザーに提示する内容を決定することができます。 次に 、Expression言語のメソッド で説明されている方法を使用して、レスポンスから必要な情報のみを抽出することができます。

特定のユーザー入力がコールアウトでエラーを生成する可能性があるかどうかをテストし、そのような状態に対処する方法を構築します。 外部アプリケーションによって生成されたエラーは、 output.webhook_error.<result_variable> に保存されます。 そのようなエラーをテスト中にキャプチャーするには、以下のような条件付き応答を使用します。

例えば、要求を認証できない場合 (401) や、外部アプリケーションで既に使用されている名前のパラメーターを渡そうとしている場合などがあります。 Web フックをデプロイする前にテストを行い、このようなタイプのエラーを見つけて解決してください。

Web フックの削除

ダイアログ・ノードから Web フック呼び出しを行わない場合は、ノードの*「カスタマイズ」ページを開き、Web フックを*「Off」**に切り替えます。

「パラメーター」セクションと「戻り変数 (Return variable)」**フィールドが、ダイアログ・ノード・エディターから取り除かれます。 ただし、自動で追加された条件付き応答、または自分で追加した条件付き応答は残ります。

*「複数の条件付き応答 (Multiple conditioned responses)」*セクションが再び編集可能になります。 この機能をオフにすることもできます。 オフにすると、最初の条件付き応答のみがノードの唯一のテキスト応答として保存されます。

ダイアログ・ノードから呼び出す外部サービスを変更するには、**「オプション」**タブの「Web フック」ページで定義した Web フックの詳細を編集します。 新しいサービスに異なるパラメーターを渡す必要がある場合は、必ず、そのサービスを呼び出すすべてのダイアログ・ノードを更新してください。

Webhook による output.generic の更新

Webhook を使用して、output.generic を更新し、動的応答を提供できます。 詳しくは、ブログ記事「 How to Dynamically Add Response Options to Dialog Nodes」を参照してください。