IBM Cloud Pak for Data （クラシック版）でメッセージを処理する前にサービスを呼び出す

Webhook 構成

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

1. 設定したいアシスタントのアイコン をクリックし、「 設定 」を選択します。

2. Webhooks > Pre-message webhook をクリックします。

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

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

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

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

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

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

例えば、メッセージが英語以外の言語で書かれているかどうかをチェックし、それを英語に変換するために Language Translator サービスに送信する Cloud Functions ウェブ・アクションを書くことができる。 以下の例にあるように、Web アクションの URL を指定します。

    https://us-south.functions.cloud.ibm.com/api/v1/web/my_org_dev/default/translateToEnglish.json

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

1. Secretフィールドを埋める。 詳細については、 秘密の追加を参照してください。

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

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

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

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

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

秘密を追加する

Secret フィールドにクライアントシークレットを追加し、外部サービスとの認証リクエストに渡します：

• purple unicorn のように、テキスト文字列としてキーを入力する。

• 最大1,024文字まで。

• コンテキスト変数は使用しないでください。

外部サービスは秘密のチェックと検証に責任を負う。 トークンが不要な場合は、任意の文字列を指定する。 このフィールドを空欄にすることはできない。

このフィールドの使用方法について詳しくは、Webhook セキュリティーを参照してください。

Webhook セキュリティー

リクエストと共に送信される JSON Web Token (JWT) を検証することで、Webhook リクエストを認証します。 ウェブフック・マイクロサービスは自動的にJWTを生成し、各ウェブフック・コールで Authorization ヘッダーにそれを送信する：

• 新しい Webhook または Edit 認証で更新された Webhook の場合、authorization ヘッダーは無視されます。

• 保存された認証ヘッダーを持つ既存の Webhook の場合、 認証の編集オプションは無効になります。

• 新しい認証設定を使用するように既存のWebhookを更新すると、その動作が変更されます。

JWT検証をテストする必要がある場合は、外部サービスにコードを追加できます。 例えば、 Secret フィールドに purple unicorn ：

const jwt = require('jsonwebtoken');
...
const token = request.headers.authentication; // grab the "Authentication" header
try {
  const decoded = jwt.verify(token, 'purple unicorn');
} catch(err) {
  // error thrown if token is invalid
}

前処理のための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 リクエストを送信し、エラー・コードと返されるメッセージの全文を確認してください。

要求本文の例

外部コードが処理できるように、プレメッセージWebhookのリクエストボディのフォーマットを知っておくと便利です。

ペイロードは、 /message、ステートフルまたはステートレス、APIリクエストのバージョン2のリクエストボディを含む。 イベント名 message_received は、リクエストがプレメッセージウェブフックによって生成されたことを示す。 メッセージのリクエスト本文に関する詳細については、 APIリファレンスを参照してください。

{
  "payload" : { Copy of request body sent to /message }
  "event": {
      "name": "message_received"
   }
}

アシスタント処理をスキップする

メッセージ送信前のWebhookの機能強化により、「 IBM Cloud Pak for Data - classic exerience」では、メッセージ処理をスキップして、Webhookから直接レスポンスを返すことができるようになりました。 この機能は、Webhookの HTTP レスポンスで x-watson-assistant-webhook-return ヘッダーを設定することで有効になります。

応答本体

Webhook から POST 要求を受け取るサービスは、JSON オブジェクト (Accept: application/json) を返す必要があります。

応答本体には、以下の構造が必要です。

{
  "payload": {
    ...
  }
}

レスポンス payload 、リクエストボディの payload 。 あなたのコードは、プロパティ値を変更したり、コンテキスト変数を変更したりできますが、返されるメッセージのペイロードは、 message メソッドのスキーマに従わなければなりません。 詳細については、 APIリファレンスを参照してください。

例 1

この例では、入力テキストの言語をチェックし、その言語情報を入力テキスト文字列に追加する方法を示します。

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

• URL: https://us-south.functions.appdomain.cloud/api/v1/web/e97d2516-5ce4-4fd9-9d05-acc3dd8ennn/default/check_language

• シークレット: なし

• ヘッダー名: Content-Type

• ヘッダー値: application/json

プレメッセージ Webhook は IBM Cloud Functions Web アクション名 check_language を呼び出します。

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

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

function main(params) {
console.log(JSON.stringify(params))
if (params.payload.input.text !== '') {
  // Send a request to the Watson Language Translator service to check the language of the input 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': 'nnn'
       },
headers: {
    "Content-Type":"text/plain"
},
  body: [
          params.payload.input.text
  ],
  json: true,
};
     return rp(options)
    .then(res => {
        params.payload.context.skills["actions skill"].user_defined["language"] = res.languages[0].language;
        console.log(JSON.stringify(params))
        //Append "in" plus "the language code" to the input text, surrounded by parentheses.
        const response = {
            body : {
                payload : {
                    input : {
                        text : params.payload.input.text + ' ' + '(in ' + res.languages[0].language + ')'
                    },
                },
            },
        };
        return response;
})
}
return { 
    body : params
}
};

Webhook をテストするには、プレビューをクリックします。 Buenos días を送信してください。 アシスタントはおそらく入力を理解できず、 Anything else ノードからの応答を返します。 しかし、アシスタントの「分析」ページで 「会話」を開くと、投稿された内容を見ることができます。 最新のユーザー会話を確認します。 ログによると、ユーザー入力は Buenos días (in es)。 括弧内の es はスペイン語の言語コードを表しているため、ウェブフックは機能し、送信されたテキストがスペイン語のフレーズであることを認識した。

例 2

この例では、受信メッセージの言語をチェックし、英語でなければアシスタントに送信する前に英語に翻訳する方法を示しています。

IBM Cloud Functions で Web アクションのシーケンスを定義します。 シーケンス内の最初のアクションは、着信テキストの言語を検査します。 シーケンス内の 2 番目のアクションは、テキストを元の言語から英語に変換します。

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

• URL: https://us-south.functions.appdomain.cloud/api/v1/web/e97d2516-5ce4-4fd9-9d05-acc3dd8ennn/default/translation_sequence

• シークレット: なし

• ヘッダー名: Content-Type

• ヘッダー値: application/json

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

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

function main(params) {
console.log(JSON.stringify(params))
if (params.payload.input.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': 'nnn'
       },
headers: {
    "Content-Type":"text/plain"
},
  body: [
          params.payload.input.text
  ],
  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 params
}
};

シーケンス内の 2 番目の Web アクションは、テキストを Watson Language Translator サービスに送信して、前の Web アクションで識別された言語からの入力テキストを英語に変換します。 翻訳されたストリングは、元のテキストではなく、アシスタントに送信されます。

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

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

function main(params) {
console.log(JSON.stringify(params))
//If the the incoming message is not null and is not English, translate it.
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'
       },
  headers: {
    "Content-Type":"application/json"
  },
       //The body includes the parameters that are required by the Language Translator service, the text to translate and the target language to translate it into.
  body: { 
      text: [ 
          params.payload.input.text
          ],
          target: 'en' 
  },
  json: true 
};
     return rp(options)
    .then(res => {
        params.payload.context.skills["actions skill"].user_defined["original_input"] = params.payload.input.text;
        const response = {
            body : {
                payload : {
                    "context" : params.payload.context,
                    "input" : {
                        "text" : res.translations[0].translation,
                        "options" : {
                            "export" : true
                            }
                    },
                },
            },
        };
    return response
})
}
return { 
    body : params
    }
};

プレビュー・パネルで Webhook をテストすると、Buenos días を実行依頼できます。アシスタントは、Good morning と英語で応答した場合と同様に応答します。 実際、アシスタントの分析ページをチェックし、 会話を開くと、ログにはユーザーの入力が Good morning。

あなたは、メッセージの応答が表示される前に顧客の言語に翻訳し直すために、メッセージ後のWebhookを追加することができます。 詳しくは例2を参照。

例 3

この例では、 IBM Cloud Pak for Data （クラシック版）がメッセージの処理をスキップし、Webhookのレスポンスを直接返すように設定する方法を示します。

function main(params) {
  // Your custom logic to determine the response
  let responseText = "This response is directly from the pre-message webhook.";

  const response = {
    headers: {
      "X-Watson-Assistant-Webhook-Return": "true"
    },
    body: {
      output: {
        generic: [
          {
            response_type: "text",
            text: responseText
          }
        ]
      }
    }
  };

  return response;
}

Webhook の削除

1. 設定したいアシスタントのアイコン をクリックし、「 設定 」を選択します。

2. Webhooks > Pre-message webhook をクリックします。

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

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

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