IBM Cloud Pak for Data 向けのメッセージ処理後にサービスを呼び出す

Webhook 構成

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

1. ナビゲーション・パネルから Environmentsをクリックし、Webhookを設定する環境を開きます。

2. アイコン をクリックして環境設定を開きます。

3. ポストメッセージ Webhook スイッチを 有効に設定します。

4. Synchronous event（同期イベント ）で、以下のオプションから1つを選択する：

   • エラーが発生した場合は、Webhookを更新せずにユーザー入力の処理を続行します。

   • Webhookの呼び出しに失敗した場合、クライアントにエラーを返します。

詳細については、 後処理のためのウェブフック・エラー処理の設定を参照してください。

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

例えば、アシスタントの応答を別のコンテンツ管理システムに保管するとします。 アシスタントが入力を理解すると、処理されたアクションは、CMS 内の応答に対応する固有 ID を返します。 特定の固有 ID について CMS から応答を取得するサービスを呼び出すには、サービス・インスタンスの URL を指定します。 例えば、https://example.com/get_answer などです。

SSL プロトコルを使用する URL を指定する必要があります。したがって、https で始まる URL を指定してください。

1. メッセージ送信後 Webhook の認証を設定するには、 認証の編集をクリックします。 詳細な手順については、 プレメッセージとポストメッセージのウェブフックの認証方法を定義するを参照してください。

2. Timeout フィールドで、アシスタントがエラーを返す前にWebhookからの応答を待つ時間を秒単位で指定します。 タイムアウト期間は、1 秒未満に短くすることも、30 秒超に長くすることもできません。

3. ヘッダーセクションで、 ヘッダーの追加をクリックし、サービスに渡したいヘッダーを1つずつ追加します。

あなたが呼び出した外部アプリケーションが応答を返す場合、そのアプリケーションは異なるフォーマットで応答を送信できるかもしれない。 Webhook では、応答が JSON でフォーマットされている必要があります。 次の表は、結果の値をJSON形式で返したいことを示すヘッダーを追加する方法を示している。

1. ヘッダー値を保存した後、文字列はアスタリスクに置き換えられ、再び表示することはできません。

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

後処理のためのWebhookエラー処理の設定

Webhook 呼び出しが失敗した場合、後処理ステップでエラーを返すかどうかを決定できます。 次の 2 つのオプションがあります。

• エラーがある場合、Webhook を更新せずにユーザー入力の処理を続行します。アシスタントはエラーを無視し、Webhook の結果なしでメッセージを処理します。 後処理が便利だが必須ではない場合は、このオプションを検討してほしい。

• Webhook呼び出しが失敗した場合、クライアントにエラーを返します ：アシスタントがレスポンスを送信した後の後処理が重要な場合、このオプションを選択します。

重要：「Webhook呼び出しが失敗した場合、クライアントにエラーを返す」を有効にすると、後処理ステップが正常に完了するまで、すべての処理が停止します。

定期的に外部プロセスをテストし、潜在的な障害を特定する。 必要に応じてこの設定を調整し、応答処理の中断を防ぐ。

Webhook のテスト

重要：本番環境で使用されるアシスタントに対してWebhookを有効化する前に、十分なテストを行ってください。

Webhookは、アシスタントがメッセージを処理し、チャネルにレスポンスを返す準備ができたときにのみトリガーされます。

Webhook のトラブルシューティング

以下のエラー・コードは、発生する可能性がある問題の原因を追跡するのに役立ちます。 たとえば、ウェブチャットとの統合がある場合、送信したテストメッセージがすべて There is an error with the message you just sent, but feel free to ask me something else のようなメッセージを返すと、ウェブフックに問題があることがわかります。 このメッセージが表示された場合は、 cURL, などの REST API ツールを使用してテスト用の /message API リクエストを送信し、エラー・コードと返されるメッセージの全文を確認してください。

要求本文の例

リクエスト・ポストメッセージのウェブフック・ボディのフォーマットを知っておくと、外部コードがそれを処理できるので便利です。

ペイロードには、アシスタントがバージョン2 /message、ステートフル、ステートレスAPIコールに対して返すレスポンスボディが含まれます。 イベント名 message_processed は、ポストメッセージWebhookがリクエストを生成することを示す。 メッセージのリクエスト本文に関する詳細については、 APIリファレンスを参照してください。

次のサンプルは、単純なリクエストボディがどのようにフォーマットされるかを示しています：

{
 "event": {
    "name": "message_processed"
},
"options": {},
"payload": {
    "output": {
        "intents": [
            {
                "intent": "General_Greetings",
                "confidence": 1
            }
        ],
        "entities": [],
        "generic": [
            {
                "response_type": "text",
                "text": "Hello. Good evening"
            }
        ]
    },
    "user_id": "test user",
    "context": {
        "global": {
            "system": {
                "user_id": "test user",
                "turn_count": 11
            },
            "session_id": "sxxx"
        },
        "skills": {
            "actions skill": {
                "user_defined": {
                    "var": "anthony"
                },
                "system": {
                    "state": "nnn"
                }
            }
        }
    }
}

例 1

この例では、アシスタントからの各レスポンスの最後に y'all を追加する方法を示しています。

ポストメッセージWebhook設定ページでは、以下の値を指定します：

• URL: https://your-webhook-url/

• ヘッダー名: Content-Type

• ヘッダー値: application/json

ポストメッセージ Webhook は IBM Cloud Functions Web アクション名 add_southern_charm を呼び出します。

add_southern_charm Web アクションの node.js コードは、以下のようになります。

function main(params) {
  console.log(JSON.stringify(params))
  if (params.payload.output.generic[0].text !== '') {
      //Get the length of the input text
        var length = params.payload.output.generic[0].text.length;
        //create a substring that removes the last character from the input string, which is typically punctuation.
        var revision = params.payload.output.generic[0].text.substring(0,length-1);
        const response = {
            body : {
                payload : {
                    output : {
                        generic : [
                              {
                                  //Replace the input text with your shortened revision and append y'all to it.
                                "response_type": "text",
                                "text": revision + ', ' + 'y\'all.'
                              }
                        ],
                    },
                },
            },
        };
        return response;
  }
  else {
    return { 
        body : params
    }
  }
}

例 2

この例では、メッセージ応答を顧客の言語に翻訳する方法を示します。 これは、 例2のステップを実行し、オリジナルのメッセージを英語に翻訳するプレメッセージWebhookを定義した場合にのみ機能します。

IBM Cloud Functions で Web アクションのシーケンスを定義します。 この変数は、プレメッセージのウェブフック・コードの original_input というコンテキスト変数に格納されています。 シーケンス内の 2 番目のアクションは、ダイアログ応答テキストを英語から顧客が使用した元の言語に変換します。

ポストメッセージWebhook設定ページでは、以下の値を指定します：

• URL: https://your-webhook-url/

• ヘッダー名: Content-Type

• ヘッダー値: application/json

シーケンス内の最初の Web アクションの node.js コードは、以下のようになります。

let rp = require("request-promise");

function main(params) {
console.log(JSON.stringify(params))

if (params.payload.output.generic[0].text !== '') {
const options = { method: 'POST',
  url: 'https://api.us-south.language-translator.watson.cloud.ibm.com/instances/572b37be-09f4-4704-b693-3bc63869nnnn/v3/identify?version=2018-05-01',
  auth: {
           'username': 'apikey',
           'password': 'nnnn'
       },
  headers: {
    "Content-Type":"text/plain"
},
  body: [
          params.payload.context.skills['actions skill'].user_defined.original_input
  ],
  json: true,
};
     return rp(options)
    .then(res => {
      //Set the language property of the incoming message to the language that was identified by Watson Language Translator. 
        params.payload.context.skills['actions skill'].user_defined['language'] = res.languages[0].language;
        console.log(JSON.stringify(params))
        return params;
})
}
else {
    params.payload.context.skills['actions skill'].user_defined['language'] = 'none';
    return param
}
};

シーケンス内の 2 番目の Web アクションは、以下のようになります。

let rp = require("request-promise");

function main(params) {
  console.log(JSON.stringify(params))
    if ((params.payload.context.skills["actions skill"].user_defined.language !== 'en') && (params.payload.context.skills["actions skill"].user_defined.language !== 'none')) {
    const options = { method: 'POST',
    url: 'https://api.us-south.language-translator.watson.cloud.ibm.com/instances/572b37be-09f4-4704-b693-3bc63869nnnn/v3/translate?version=2018-05-01',
    auth: {
            'username': 'apikey',
            'password': 'nnn'
        },
    body: { 
        text: [ 
            params.payload.output.generic[0].text
            ],
            target: params.payload.context.skills["actions skill"].user_defined.language
    },
    json: true 
    };
      return rp(options)
      .then(res => {
          params.payload.context.skills["actions skill"].user_defined["original_output"] = params.payload.output.generic[0].text;
          params.payload.output.generic[0].text = res.translations[0].translation;
          return {
            body : params
          }
  })
  }
  return { 
    body : params
  }
};

Webhook の削除

Webhook を使ってメッセージ・レスポンスを処理したくない場合は、以下の手順を実行してください：

1. アシスタントの Environmentsで、Webhookを削除したい環境を開いてください。

2. アイコン をクリックして環境設定を開きます。

3. 環境設定ページで、 ポストメッセージWebhookをクリックします。

4. 以下のいずれかの手順を実行します。

   • 受信メッセージを処理するために Webhook を呼び出すのを止めるには、 Post-message webhook スイッチを Disabled に設定します。

   • 呼び出す Webhook を変更するには、 Delete webhook をクリックします。