IBM Cloud Pak for Data のメッセージ処理後にサービスを呼び出す - 従来の操作

Webhook 構成

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

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

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

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. 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エラー処理の設定

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. 設定したいアシスタントのアイコン をクリックし、 「設定 」を選択します。

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

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

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

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