クラシック Watson Assistant エクスペリエンスの Documentation が移動しました。最新バージョンについては、ダイアログからのプログラマチック呼び出しの実行を参照してください。

ダイアログからのプログラマチック呼び出しの実行

プログラマチック呼び出しを行うには、プログラムの機能を実行する外部アプリケーションに POST 要求のコールアウトを送信する Web フックを定義します。そして、1 つ以上のダイアログ・ノードからその Web フックを呼び出すことができます。

Web フックとは、プログラム内で行われた処理に応じて外部プログラムを呼び出すためのメカニズムです。 Web フックをダイアログ・スキルで使用すると、Web フックを有効にしたノードがアシスタントで処理されたときに、Web フックがトリガーされます。 Web フックは、指定されたデータや、会話中にユーザーから集めたデータをコンテキスト変数に保存します。そのデータを、HTTP POST 要求の一部として、Web フック定義の中で指定された URL に送信します。 Web フックを受け取る URL はリスナーです。リスナーは、Web フック定義の指定に沿って渡された情報を使用して、事前定義アクションを実行します。オプションで応答を返すこともできます。

Web フックを使用して、以下のようなタイプのことを行えます。

ユーザーから収集した情報を検証する。
外部 Web サービスと対話して情報を取得する。例えば、航空交通サービスから飛行機の到着予定時刻を調べたり、気象サービスから天気予報を入手したりすることもできます。
レストラン予約サイトなどの外部アプリケーションに要求を送信して、ユーザーの代わりに単純な取り引きを行う。
SMS 通知をトリガーする。
IBM Cloud® Functions Web アクションをトリガーします。

トークン・ベースの ID およびアクセス管理 (IAM) 認証を使用する Cloud Functions アクションを Web フックで呼び出すことはできません。ただし、保護された Cloud Functions Web アクションを呼び出すことはできます。詳しくは、IBM Cloud Functions の Web アクションの呼び出しを参照してください。

クライアント・アプリケーションの呼び出し方法については、ダイアログ・ノードからのクライアント・アプリケーションの呼び出しを参照してください。

プラス以上のプランのみプライベート・エンドポイントが使用されている環境では、Webhook がトラフィックをインターネット経由で送信することに注意してください。詳しくは、プライベート・ネットワーク・エンドポイントを参照してください。

Web フックの定義

ダイアログ・スキルとして Web フック URL を 1 つ定義し、その Web フックを 1 つ以上のダイアログ・ノードから呼び出すことができます。

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

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

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

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

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

Web フックを追加するスキルから**「オプション」**タブをクリックします。
**「Web フック」**をクリックします。
**「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 サービスの場合は、結果を返す形式を指定する必要があります。そのためには、サービスにヘッダーを渡します。
「ヘッダー」セクションで、**「ヘッダーの追加 (Add header)」**をクリックし、サービスに渡すヘッダーを 1 つずつ追加します。

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

ヘッダーの例
ヘッダー名	ヘッダー値
コンテンツ・タイプ	application/json

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

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

ヘッダーの例
ヘッダー名	ヘッダー値
許可	基本 ` `

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

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

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

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

**「ダイアログ (Dialog)」**タブをクリックします。
コールアウトを追加するダイアログ・ノードを見つけます。ユーザーとの会話中にこのノードがトリガーされるたびに、Web フックへのコールアウトが実行されます。

例えば、#General_Greetings ノードから Web フックにコールアウトを送信できます。
対象のダイアログ・ノードをクリックして開き、**「カスタマイズ」**をクリックします。
Web フック・セクションまでスクロールダウンします。 **「Web フック/アクション・スキルへのコールアウト (Callout to webhooks/actions skill)」スイッチを「オン」**に設定します。
**「Web フックを呼び出す (Call a webhook)」を選択し、「適用」**をクリックします。

**「複数の条件付き応答 (Multiple conditioned responses)」スイッチは、まだ有効にしていなければ自動的に「オン」**に設定され、無効にすることはできません。この設定が有効になるのは、Web フック呼び出しの成功/失敗に応じて異なる応答を追加できるようにするためです。そのノードに既に応答を指定していた場合は、その応答が最初の条件付き応答になります。
外部アプリケーションに渡すデータを、キーと値のペアとして*「パラメーター」*セクションに追加します。

パラメーターは、要求本体プロパティーとして渡されます。ダイアログ・ノードで照会パラメーターまたは URL パラメーターを指定することはできません。これらのパラメーターは、Webhook 定義の一部として静的値でのみ構成できます。詳しくは、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

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

生成される変数名の構文は webhook_result_n です。末尾に追加される _n は、ダイアログ・ノードに Web フックのコールアウトを追加するたびに増分します。この命名規則により、コンテキスト変数名がダイアログ・スキル全体で固有になります。変数名を変更する場合は、必ず固有の名前を使用してください。
条件付き応答のセクションには 2 つの応答条件が自動的に追加されます。1 つは Web フックのコールアウトが成功し、戻り変数が返されたときに表示される応答です。もう 1 つはコールアウトが失敗したときに表示される応答です。これらの応答を編集することも、条件付き応答をノードに追加することもできます。
- コールアウトが応答を返す場合は、その JSON 応答の形式がわかっていれば、ダイアログ・ノードの応答を編集して、ユーザーに提示したい応答のセクションのみを含めることができます。
  
  例えば、Language Translator サービスが次のようなオブジェクトを返すとします。
```
   {
   "translations":[
      {"translation":"¿Cómo estás?"}
   ],
   "word_count":3,
   "character_count":12
   }
```
  変換されたテキストの値のみを抽出する SpEL 式を使用します。

条件付き応答の例
条件	応答
$webhook_result_1	スペイン語で < と言いますか? $webhook_result_1.translations[0].translation ?>。
anything_else	外部アプリケーションへの呼び出しが失敗しました。しばらくしてからやり直してください。

  この形式案を応答に使用した場合に上記の変換応答が返されると、ユーザーに対するアシスタントの応答は「`Your words in Spanish: ¿Cómo estás?`」になります。

コールアウトが空の文字列を返した場合、つまり呼び出しは成功したものの、返された値が空の文字列であった場合に、特定の応答を提供するには、次のような構文の条件付き応答を追加します。
```
$webhook_result_1.size() == 0
```

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

Web フックのテスト

Web フックのコールアウトを初めて追加するときには、実際に外部アプリケーションからの応答で何が返されたのか、データとデータ形式を確認すると役に立ちます。これを行うには、コールアウト成功の条件付き応答のテキスト応答として、$webhook_result_n という式を追加します。n は、テストする Web フックに該当する番号です。

この応答は戻り変数の本体全体を返すので、コールアウトから戻された内容を確認してから、ユーザーに提示する内容を決定することができます。その後、式言語メソッドに記載しているメソッドを使用して、応答から大事な情報のみを抽出できます。

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

条件	応答
output.webhook_error	コールアウトが次のエラーを生成しました。

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

Web フックの削除

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

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

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

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

IBM Cloud Functions の Web アクションの呼び出し

通常、Web アクションは、呼び出し元による認証が最初に行われなくても実行できます。ただし、要求と一緒に ID を渡すことをすべての呼び出し元に求める Web アクションを保護することができます。 Web アクションを保護する方法について詳しくは、 Web アクションの保護を参照してください。

以下のヒントはダイアログから Cloud Functions Web アクションを呼び出す際に役立ちます。

スキルの**「オプション」ページを開き、「Web フック」**をクリックします。
**「URL」**フィールドに、HTTP POST 要求コールアウトを送信する外部アプリケーションの URL を追加します。

例えば、Cloud Functions Web アクションを呼び出すには、公開されている Web アクションの URL を指定します。以下に例を示します。
```
https://us-south.functions.cloud.ibm.com/api/v1/web/my_org_dev/default/Hello%20World.json
```
呼び出した外部アプリケーションが応答を返す場合は、JSON 形式で応答を返せなければなりません。

この例の要求 URL が .json で終わっていることに注意してください。この拡張子を指定することで、Web アクションの機能を利用して、希望する応答のコンテンツ・タイプを指定できます。この拡張子タイプを指定すれば、Web アクションが複数の形式で応答を返せる場合に JSON 形式の応答が確実に返されます。詳しくは、追加機能を参照してください。
Web アクションが保護されている場合は、Web アクションを呼び出すために必要なヘッダー (X-Require-Whisk-Auth など) を指定します。

ヘッダーの例
ヘッダー名	ヘッダー値
「X-Require-Whisk-Auth」	`{my-secret}`

**「ダイアログ (Dialog)」**タブをクリックします。
Web アクションを呼び出すダイアログ・ノードをクリックして開き、**「カスタマイズ」**をクリックします。
Web フック・セクションまでスクロールダウンします。 **「Web フックへのコールアウト (Callout to webhooks)」スイッチを「オン」に設定し、「適用」**をクリックします。
外部アプリケーションに渡すデータを、キーと値のペアとして*「パラメーター」*セクションに追加します。

例えば、Hello World Cloud Functions Web アクションを呼び出す場合は、以下の情報を追加して、そのアプリケーションで受け入れられるメッセージ・パラメーターを渡します。

パラメーターの例
キー	値
メッセージ	"hello"

Cloud Functions Web アクションを呼び出す場合は、その Web アクションの一部として定義されているパラメーターと同じキーのパラメーターを渡すことはできません。詳しくは、保護されたパラメーターを参照してください。

ダイアログ・ノードの応答を編集して、ユーザーに表示したい応答のセクションのみを含めることができます。

Hello World Cloud Functions Web アクションの応答には、メッセージの名前と値のペアが他の情報とともに含まれています。メッセージの内容のみを表示するには、<return-variable>.message 構文を使用して、応答オブジェクトからのみメッセージ・セクションを抽出できます。

条件付き応答の例
条件	応答
$webhook_result_1	アプリケーションは "$webhook_result_1.message" を返しました。
anything_else	外部アプリケーションへの呼び出しが失敗しました。しばらくしてからやり直してください。

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

Webhook による output.generic の更新

Webhook を使用して、output.generic を更新し、動的応答を提供できます。その方法については、ブログ記事「Watson Assistant でダイアログ・ノードに応答オプションを動的に追加する方法」を参照してください。