메시지를 처리하기 전에 호출 작성
사전 메시지 웹훅은 고객이 입력을 제출할 때마다 외부 서비스나 애플리케이션을 호출합니다. 어시스턴트가 메시지를 처리하기 전에 외부 서비스에서 메시지를 처리할 수 있습니다.
어시스턴트가 수신 메시지를 처리하기 전에 웹훅이 트리거되도록 하려면 어시스턴트에 사전 메시지 웹훅을 추가하세요.
사용자 지정 채널을 사용하는 경우, 사전 메시지 웹훅은 v2 /message
API(상태 비저장 및 상태 저장)에서만 작동합니다. 자세한 정보는 API 참조를 참조하십시오. 모든 기본 제공 채널 통합은 이 API를 사용합니다.
다음과 같은 사용 사례에 사전 메시지 웹훅을 사용할 수 있습니다:
-
고객의 입력을 어시스턴트가 사용하는 언어로 번역합니다.
-
고객이 제출할 수 있는 이메일 주소 또는 주민등록번호와 같은 개인 식별 정보를 확인하고 제거하십시오.
이 웹훅을 메시지 후 웹훅과 함께 사용할 수 있습니다. 예를 들어 메시지 후 웹훅은 응답을 고객의 언어로 다시 번역하거나 개인정보 보호를 위해 삭제된 정보를 다시 추가하는 등의 작업을 수행할 수 있습니다. 자세한 정보는 메시지를 처리한 후 호출 작성의 내용을 참조하십시오.
개인 엔드포인트가 사용 중인 환경의 경우 웹훅이 인터넷을 통해 트래픽을 전송함을 기억하십시오.
대화 중에 필요할 때 일회성 작업을 수행해야 하는 경우 대화 웹훅을 사용하세요. 예를 들어 어시스턴트가 계정 번호, 사용자 ID, 계정 비밀번호 등 필요한 모든 세부 정보를 수집하면 조건이 충족됩니다. 자세한 정보는 대화 노드에서 프로그래밍 방식 호출 작성을 참조하십시오.
웹훅 정의
모든 수신 메시지를 사전 처리하는 데 사용할 하나의 웹훅 URL을 정의할 수 있습니다.
시작하기 전에
외부 서비스에 대한 프로그래밍 방식의 호출은 다음 요구 사항을 충족해야 합니다:
- 어시스턴트가 배치되어 고객과 상호작용하는 프로덕션 환경에서 웹훅을 설정하고 테스트하지 마십시오.
- 호출은 POST HTTP 요청이어야 합니다.
- 요청 본문은 JSON 오브젝트(
Content-Type: application/json
)여야 합니다. - 호출은 30초 이내에 답해야 합니다.
외부 서비스가 GET 요청만 지원하거나 런타임에 URL 매개변수를 동적으로 지정해야 하는 경우 런타임 값이 포함된 JSON 페이로드가 포함된 POST 요청을 수락하는 중간 서비스를 만드는 것을 고려해 보세요. 그러면 중간 서비스가 대상 서비스에 대한 요청을 작성하고 이 값을 URL 매개변수로 전달한 다음 대화 상자에 응답을 리턴할 수 있습니다.
각 배포 유형에 대해 사전 메시지 웹훅을 설정하는 절차
watsonx Assistant 의 배포 유형을 선택하여 사전 메시지 웹훅 구성 단계를 확인합니다:
사용 중인 배포 유형을 확인하려면 관리 메뉴 클릭합니다. 클래식 환경으로 전환이 표시되면 새 환경을 사용하고 있는 것입니다. 새 환경으로 전환이 표시되면 클래식 환경을 사용하고 있는 것입니다.
이 섹션에서는 다음에 대한 사전 메시지 웹훅을 정의, 테스트 및 제거하는 절차에 대해 설명합니다 IBM Cloud Pak for Data:
이 섹션에서는 IBM Cloud Pak for Data- 클래식 경험에 대한 사전 메시지 웹훅을 정의, 테스트 및 제거하는 절차에 대해 설명합니다:
- 웹훅 구성
- 비밀 추가하기
- 웹훅 보안
- 전처리를 위한 웹훅 오류 처리 구성하기
- 웹훅 테스트
- 웹훅 문제 해결하기
- 요청 본문 예시
- 보조 처리 건너뛰기
- 응답 본문
- 예제 1
- 예 2
- 예제 3
- 웹훅 제거하기
이 섹션에서는 다음에 대한 사전 메시지 웹훅을 정의, 테스트 및 제거하는 절차에 대해 설명합니다 watsonx Assistant:
이 섹션에서는 watsonx Assistant- 클래식 경험에 대한 사전 메시지 웹훅을 정의, 테스트 및 제거하는 절차에 대해 설명합니다:
- 웹훅 구성
- 비밀 추가하기
- 웹훅 보안
- 전처리를 위한 웹훅 오류 처리 구성하기
- 웹훅 테스트
- 웹훅 문제 해결하기
- 요청 본문 예시
- 보조 처리 건너뛰기
- 응답 본문
- 예제 1
- 예 2
- 예제 3
- 웹훅 제거하기
절차 IBM Cloud Pak for Data
웹훅 세부사항을 추가하려면 다음 단계를 완료하십시오.
-
탐색 패널에서 환경을 클릭하고 웹훅을 구성할 환경을 엽니다.
-
아이콘을 클릭하여 환경 설정을 여십시오.
-
사전 메시지 웹훅 스위치를 사용으로 설정하십시오.
-
동기 이벤트에서 다음 옵션 중 하나를 선택합니다:
-
오류가 있는 경우 웹훅 업데이트 없이 사용자 입력을 계속 처리합니다.
-
웹훅 호출이 실패하면 클라이언트에 오류를 반환합니다.
자세한 내용은 전처리를 위한 웹훅 오류 처리 구성하기를 참조하세요.
-
-
URL 필드에서 HTTP POST 요청 콜아웃을 전송할 외부 애플리케이션의 URL을 추가하십시오.
예를 들어, 메시지가 영어 이외의 언어로 되어 있는지 확인하는 Cloud Functions 웹 작업을 작성하여 Language Translator 서비스로 전송하여 영어로 변환할 수 있습니다. 다음 예제와 같이 웹 조치에 대한 URL을 지정하십시오.
https://us-south.functions.cloud.ibm.com/api/v1/web/my_org_dev/default/translateToEnglish.json
SSL 프로토콜을 사용하는 URL을 지정해야 하므로
https
시작 URL을 지정하십시오. -
사전 메시지 웹훅에 대한 인증을 구성하려면 인증 편집을 클릭합니다. 자세한 지침은 메시지 전 및 메시지 후 웹훅에 대한 인증 방법 정의하기를 참조하세요.
-
시간 제한 필드에서 어시스턴트가 오류를 반환하기 전에 웹훅의 응답을 기다릴 시간(초)을 지정합니다. 제한시간 지속 기간은 1초보다 짧거나 30초보다 길 수 없습니다.
-
헤더 섹션에서 헤더 추가 +를 클릭하여 서비스에 전달할 헤더를 한 번에 하나씩 추가합니다.
호출하는 외부 애플리케이션이 응답을 반환하는 경우 다른 형식으로 응답을 보낼 수 있습니다. 웹훅은 응답이 JSON으로 형식화되어야 합니다. 다음 표는 반환할 결과값이 JSON 형식임을 나타내는 헤더를 추가하는 방법을 설명합니다.
헤더 예제 헤더 이름 헤더 값 Content-Type
application/json
-
헤더 값을 저장하면 문자열이 별표로 대체되어 다시 볼 수 없습니다.
-
웹훅 세부사항이 자동으로 저장됩니다.
전처리를 위한 웹훅 오류 처리 구성하기
웹훅 호출이 실패할 경우 전처리 단계에서 오류 반환 여부를 결정할 수 있습니다. 다음과 같은 두 가지 옵션이 존재합니다.
-
오류가 있는 경우 웹훅 업데이트 없이 사용자 입력을 계속 처리합니다: 어시스턴트가 오류를 무시하고 웹훅 결과 없이 메시지를 처리합니다. 전처리가 유용하지만 필수적인 것은 아니라면 이 옵션을 고려하세요.
-
웹훅 호출이 실패하면 클라이언트에 오류를 반환합니다: 어시스턴트가 메시지를 처리하기 전에 전처리가 중요한 경우 이 옵션을 선택합니다.
웹훅 호출이 실패할 경우 클라이언트에 오류 반환을 사용 설정하면 전처리 단계가 성공적으로 완료될 때까지 모든 작업이 중지됩니다.
외부 프로세스를 정기적으로 테스트하여 잠재적인 장애를 파악하세요. 필요한 경우 이 설정을 조정하여 메시지 처리 중단을 방지하세요.
웹훅 테스트
프로덕션 환경에서 사용되는 어시스턴트에 웹훅을 사용 설정하기 전에 웹훅에 대한 광범위한 테스트를 수행하세요.
웹훅은 메시지가 처리할 어시스턴트에게 전송될 때 트리거됩니다.
웹훅 문제점 해결
다음 오류 코드는 발생할 수 있는 문제의 원인을 추적하는 데 도움이 될 수 있습니다. 예를 들어, 웹 대화 통합이 있는 경우 제출하는 모든 테스트 메시지가 There is an error with the message you just sent, but feel free to ask me something else
와 같은 메시지를 리턴하면 웹훅에 문제가 있음을 알 수 있습니다. 이 메시지가 표시되면 cURL,
같은 REST API 도구를 사용하여 테스트 ' /message
API 요청을 보내면 오류 코드와 반환되는 전체 메시지를 확인할 수 있습니다.
오류 코드 및 메시지 | 설명 |
---|---|
422 웹훅이 올바르지 않은 JSON 본문과 함께 응답 | 웹훅의 HTTP 응답 본문을 JSON으로 구문 분석할 수 없습니다. |
422 웹훅 응답 유효성 검증 오류 | 웹훅의 HTTP 응답 본문이 올바른 /message 본문이 아닙니다. |
422 웹 훅이 [500] 상태 코드와 함께 응답 |
호출한 외부 서비스에 문제가 있습니다. 코드가 실패했거나 외부 서버가 요청을 거부했습니다. |
500 프로세서 예외: [connections to all backends failing] |
웹훅 마이크로서비스에서 오류가 발생했습니다. 백엔드 서비스에 연결할 수 없습니다. |
요청 본문 예
외부 코드에서 처리할 수 있도록 사전 메시지 웹훅의 요청 본문 형식을 아는 것이 유용합니다.
페이로드는 /message
(Stateful 또는 Stateless) v2 API 요청의 요청 본문을 포함합니다. 이벤트 이름 message_received
은 사전 메시지 웹훅에 의해 요청이 생성되었음을 나타냅니다. 메시지 요청 본문에 대한 자세한 정보는 API 참조를 참조하십시오.
{
"payload" : { Copy of request body sent to /message }
"event": {
"name": "message_received"
}
}
보조 처리 건너뛰기
사전 메시지 웹훅 기능이 개선되어 IBM Cloud Pak for Data 를 사용하여 메시지 처리를 건너뛰고 웹훅에서 직접 응답을 반환할 수 있습니다. 이 기능은 웹훅의 HTTP 응답에 x-watson-assistant-webhook-return
헤더를 설정하여 활성화할 수 있습니다.
시작하기 전에
다음 단계를 완료하십시오.
- 웹훅의 HTTP 응답에
x-watson-assistant-webhook-return
헤더를 임의의 값으로 포함하세요. - 웹훅 응답에 유효한 메시지 응답이 포함되어 있는지 확인하십시오. 이 메시지 응답은 watsonx Assistant 요구 사항에 따라 포맷됩니다.
이 기능을 사용하면 웹훅이 대화 흐름을 동적으로 제어할 수 있으므로 필요할 때 즉각적인 응답이 가능합니다.
응답 본문
웹훅에서 POST 요청을 수신하는 서비스는 JSON 오브젝트(Accept: application/json
)를 리턴해야 합니다.
응답 본문의 구조는 다음과 같아야 합니다.
{
"payload": {
...
}
}
응답 payload
에는 요청 본문의 payload
이 포함되어야 합니다. 코드에서 속성 값을 수정하거나 컨텍스트 변수를 수정할 수 있지만 반환된 메시지 페이로드는 message
메서드 스키마를 따라야 합니다. 자세한 내용은 API 참조를 참조하세요.
예제 1
이 예는 입력 텍스트의 언어를 확인하고 입력 텍스트 문자열에 언어 정보를 추가하는 방법을 보여 줍니다.
사전 메시지 웹훅 구성 페이지에서 다음 값이 지정됩니다:
- URL:
https://us-south.functions.appdomain.cloud/api/v1/web/e97d2516-5ce4-4fd9-9d05-acc3dd8ennn/default/check_language
- 헤더 이름: 컨텐츠 유형
- 헤더 값: application/json
사전 메시지 웹훅은 IBM Cloud Functions 웹 액션 이름 check_language
을 호출합니다.
check_language
웹 조치의 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
}
};
웹훅을 테스트하려면 미리 보기를 클릭하십시오. Buenos días
텍스트를 제출하십시오. 어시스턴트는 입력을 이해할 수 없을 수도 있으며, Anything else 노드의 응답을 반환합니다. 하지만 어시스턴트의 분석 페이지로 이동하여 대화를 열면 제출된 내용을 볼 수 있습니다. 가장 최근의 사용자 대화를 확인하십시오. 로그는
사용자 입력이 Buenos días (in es)
임을 표시합니다. 괄호 안의 es
은 스페인어의 언어 코드를 나타내므로 웹훅이 작동하여 제출된 텍스트가 스페인어 구문임을 인식했습니다.
예제 2
이 예는 수신 메시지의 언어를 확인하고 영어가 아닌 경우 어시스턴트에게 제출하기 전에 영어로 번역하는 방법을 보여 줍니다.
IBM Cloud Functions에서 웹 조치 시퀀스를 정의하십시오. 시퀀스의 첫 번째 조치는 수신 텍스트의 언어를 검사합니다. 시퀀스의 두 번째 조치는 텍스트를 원래 언어에서 영어로 변환합니다.
사전 메시지 웹훅 구성 페이지에서 다음 값이 지정됩니다:
- URL:
https://us-south.functions.appdomain.cloud/api/v1/web/e97d2516-5ce4-4fd9-9d05-acc3dd8ennn/default/translation_sequence
- 헤더 이름: 컨텐츠 유형
- 헤더 값: application/json
시퀀스의 첫 번째 웹 조치에 대한 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
}
};
시퀀스의 두 번째 웹 조치는 텍스트를 Watson Language Translator 서비스로 전송하여 이전 웹 조치에서 식별된 언어의 입력 텍스트를 영어로 변환합니다. 그러면 변환된 문자열이 원래 텍스트 대신 어시스턴트에 전송됩니다.
시퀀스의 두 번째 조치에 대한 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
}
};
미리보기 패널에서 웹훅을 테스트할 때 Buenos días
제출이 가능하며 사용자가 영어로 Good morning
이용 시와 같이 어시스턴트가 응답합니다. 실제로 어시스턴트의 분석 페이지를 확인하고 대화를 열면 로그에 사용자 입력이 Good morning
로 표시됩니다.
메시지 후 웹훅을 추가하여 메시지가 표시되기 전에 메시지의 응답을 고객의 언어로 다시 번역할 수 있습니다. 자세한 내용은 예제 2를 참조하세요.
예제 3
이 예는 웹훅 응답을 작성하여 메시지 처리를 건너뛰고 IBM Cloud Pak for Data 가 메시지 처리를 건너뛰고 웹후크의 응답을 직접 반환하도록 하는 방법을 보여줍니다.
웹훅 구성
메시지 전 웹훅 구성 페이지에서 다음 값을 지정합니다
- URL: https://your-webhook-url/webhook_skip
- 헤더 이름: 컨텐츠 유형
- 헤더 값: application/json
웹훅_스킵 웹 액션의 node.js 코드는 다음과 같습니다.
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;
}
웹훅 제거
웹훅으로 고객 입력을 사전 처리하지 않기로 결정했다면 다음 단계를 완료하세요:
-
어시스턴트에서 환경 으로 이동하여 웹훅을 제거할 환경을 여십시오.
-
아이콘을 클릭하여 환경 설정을 여십시오.
-
환경 설정 페이지에서 사전 메시지 웹훅을 클릭합니다.
-
다음 단계 중 하나를 수행하십시오.
-
수신되는 모든 메시지를 처리하기 위해 웹훅 호출을 중지하려면 메시지 전 웹훅 스위치를 사용 안 함으로 설정하세요.
-
호출하려는 웹훅을 변경하려면 웹훅 삭제를 클릭합니다.
절차 IBM Cloud Pak for Data- 클래식 경험
웹훅 세부사항을 추가하려면 다음 단계를 완료하십시오.
-
구성하려는 어시스턴트에 대해
아이콘을 클릭한 다음 설정을 선택합니다.
-
웹훅 > 사전 메시지 웹훅을 클릭합니다.
-
사전 메시지 웹훅 스위치를 사용으로 설정하십시오.
-
동기 이벤트에서 다음 옵션 중 하나를 선택합니다:
-
오류가 있는 경우 웹훅 업데이트 없이 사용자 입력을 계속 처리합니다.
-
웹훅 호출이 실패하면 클라이언트에 오류를 반환합니다.
자세한 내용은 전처리를 위한 웹훅 오류 처리 구성하기를 참조하세요.
-
-
URL 필드에서 HTTP POST 요청 콜아웃을 전송할 외부 애플리케이션의 URL을 추가하십시오.
예를 들어, 메시지가 영어 이외의 언어로 되어 있는지 확인하는 Cloud Functions 웹 작업을 작성하여 Language Translator 서비스로 전송하여 영어로 변환할 수 있습니다. 다음 예제와 같이 웹 조치에 대한 URL을 지정하십시오.
https://us-south.functions.cloud.ibm.com/api/v1/web/my_org_dev/default/translateToEnglish.json
SSL 프로토콜을 사용하는 URL을 지정해야 하므로
https
시작 URL을 지정하십시오. -
비밀 필드를 입력합니다. 자세한 내용은 비밀 번호 추가하기를 참조하세요.
-
시간 제한 필드에서 어시스턴트가 오류를 반환하기 전에 웹훅의 응답을 기다릴 시간(초)을 지정합니다. 제한시간 지속 기간은 1초보다 짧거나 30초보다 길 수 없습니다.
-
헤더 섹션에서 헤더 추가 +를 클릭하여 서비스에 전달할 헤더를 한 번에 하나씩 추가합니다.
호출하는 외부 애플리케이션이 응답을 반환하는 경우 다른 형식으로 응답을 보낼 수 있습니다. 웹훅은 응답이 JSON으로 형식화되어야 합니다. 다음 표는 반환할 결과값이 JSON 형식임을 나타내는 헤더를 추가하는 방법을 설명합니다.
헤더 예제 헤더 이름 헤더 값 Content-Type
application/json
-
헤더 값을 저장하면 문자열이 별표로 대체되어 다시 볼 수 없습니다.
-
웹훅 세부사항이 자동으로 저장됩니다.
비밀 추가하기
외부 서비스 인증 요청과 함께 전달할 개인 키를 비밀 필드에 추가합니다:
-
purple unicorn
과 같이 텍스트 문자열로 키를 입력합니다. -
최대 1,024자까지 입력할 수 있습니다.
-
컨텍스트 변수를 사용하지 마세요.
외부 서비스는 비밀을 확인하고 확인할 책임이 있습니다. 토큰이 필요하지 않은 경우 아무 문자열이나 지정합니다. 이 필드는 비워 둘 수 없습니다.
비밀번호를 입력할 때 비밀번호를 확인하려면 입력하기 전에 비밀번호 표시 아이콘 클릭합니다. 비밀번호를 저장한 후에는 별표가 문자열을 대체하며 다시 볼 수 없습니다.
이 필드를 사용하는 방법에 대한 자세한 정보는 웹훅 보안의 내용을 참조하십시오.
웹훅 보안
요청과 함께 전송된 JSON 웹 토큰(JWT)을 확인하여 웹훅 요청을 인증합니다. 웹훅 마이크로서비스는 자동으로 JWT를 생성하여 각 웹훅 호출과 함께 Authorization
헤더로 전송합니다:
-
인증 수정을 통해 업데이트된 새 웹훅 또는 웹훅의 경우 인증 헤더가 무시됩니다.
-
인증 헤더가 저장된 기존 웹훅의 경우 인증 편집 옵션이 비활성화됩니다.
-
새 인증 구성을 사용하도록 기존 웹훅을 업데이트하면 동작이 변경됩니다.
JWT 확인을 테스트해야 하는 경우 외부 서비스에 코드를 추가할 수 있습니다. 예를 들어 비밀 필드에 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
}
전처리를 위한 웹훅 오류 처리 구성하기
웹훅 호출이 실패할 경우 전처리 단계에서 오류 반환 여부를 결정할 수 있습니다. 다음과 같은 두 가지 옵션이 존재합니다.
-
오류가 있는 경우 웹훅 업데이트 없이 사용자 입력을 계속 처리합니다: 어시스턴트가 오류를 무시하고 웹훅 결과 없이 메시지를 처리합니다. 전처리가 유용하지만 필수적인 것은 아니라면 이 옵션을 고려하세요.
-
웹훅 호출이 실패하면 클라이언트에 오류를 반환합니다: 어시스턴트가 메시지를 처리하기 전에 전처리가 중요한 경우 이 옵션을 선택합니다.
웹훅 호출이 실패할 경우 클라이언트에 오류 반환을 사용 설정하면 전처리 단계가 성공적으로 완료될 때까지 모든 작업이 중지됩니다.
외부 프로세스를 정기적으로 테스트하여 잠재적인 장애를 파악하세요. 필요한 경우 이 설정을 조정하여 메시지 처리 중단을 방지하세요.
웹훅 테스트
프로덕션 환경에서 사용되는 어시스턴트에 웹훅을 사용 설정하기 전에 웹훅에 대한 광범위한 테스트를 수행하세요.
웹훅은 메시지가 처리할 어시스턴트에게 전송될 때 트리거됩니다.
웹훅 문제점 해결
다음 오류 코드는 발생할 수 있는 문제의 원인을 추적하는 데 도움이 될 수 있습니다. 예를 들어, 웹 대화 통합이 있는 경우 제출하는 모든 테스트 메시지가 There is an error with the message you just sent, but feel free to ask me something else
와 같은 메시지를 리턴하면 웹훅에 문제가 있음을 알 수 있습니다. 이 메시지가 표시되면 cURL,
같은 REST API 도구를 사용하여 테스트 ' /message
API 요청을 보내면 오류 코드와 반환되는 전체 메시지를 확인할 수 있습니다.
오류 코드 및 메시지 | 설명 |
---|---|
422 웹훅이 올바르지 않은 JSON 본문과 함께 응답 | 웹훅의 HTTP 응답 본문을 JSON으로 구문 분석할 수 없습니다. |
422 웹훅 응답 유효성 검증 오류 | 웹훅의 HTTP 응답 본문이 올바른 /message 본문이 아닙니다. |
422 웹 훅이 [500] 상태 코드와 함께 응답 |
호출한 외부 서비스에 문제가 있습니다. 코드가 실패했거나 외부 서버가 요청을 거부했습니다. |
500 프로세서 예외: [connections to all backends failing] |
웹훅 마이크로서비스에서 오류가 발생했습니다. 백엔드 서비스에 연결할 수 없습니다. |
요청 본문 예
외부 코드에서 처리할 수 있도록 사전 메시지 웹훅의 요청 본문 형식을 아는 것이 유용합니다.
페이로드는 /message
(Stateful 또는 Stateless) v2 API 요청의 요청 본문을 포함합니다. 이벤트 이름 message_received
은 사전 메시지 웹훅에 의해 요청이 생성되었음을 나타냅니다. 메시지 요청 본문에 대한 자세한 정보는 API 참조를 참조하십시오.
{
"payload" : { Copy of request body sent to /message }
"event": {
"name": "message_received"
}
}
보조 처리 건너뛰기
사전 메시지 웹후크 기능이 개선되어 IBM Cloud Pak for Data- 클래식 환경에서 메시지 처리를 건너뛰고 웹훅의 응답을 바로 반환할 수 있습니다. 이 기능은 웹훅의 HTTP 응답에 x-watson-assistant-webhook-return
헤더를 설정하여 활성화할 수 있습니다.
시작하기 전에
다음 단계를 완료하십시오.
- 웹훅의 HTTP 응답에
x-watson-assistant-webhook-return
헤더를 임의의 값으로 포함하세요. - 웹훅 응답에 유효한 메시지 응답이 포함되어 있는지 확인하십시오. 이 메시지 응답은 watsonx Assistant 요구 사항에 따라 포맷됩니다.
이 기능을 사용하면 웹훅이 대화 흐름을 동적으로 제어할 수 있으므로 필요할 때 즉각적인 응답이 가능합니다.
응답 본문
웹훅에서 POST 요청을 수신하는 서비스는 JSON 오브젝트(Accept: application/json
)를 리턴해야 합니다.
응답 본문의 구조는 다음과 같아야 합니다.
{
"payload": {
...
}
}
응답 payload
에는 요청 본문의 payload
이 포함되어야 합니다. 코드에서 속성 값을 수정하거나 컨텍스트 변수를 수정할 수 있지만 반환된 메시지 페이로드는 message
메서드 스키마를 따라야 합니다. 자세한 내용은 API 참조를 참조하세요.
예제 1
이 예는 입력 텍스트의 언어를 확인하고 입력 텍스트 문자열에 언어 정보를 추가하는 방법을 보여 줍니다.
사전 메시지 웹훅 구성 페이지에서 다음 값이 지정됩니다:
- URL:
https://us-south.functions.appdomain.cloud/api/v1/web/e97d2516-5ce4-4fd9-9d05-acc3dd8ennn/default/check_language
- 시크릿: 없음
- 헤더 이름: 컨텐츠 유형
- 헤더 값: application/json
사전 메시지 웹훅은 IBM Cloud Functions 웹 액션 이름 check_language
을 호출합니다.
check_language
웹 조치의 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
}
};
웹훅을 테스트하려면 미리 보기를 클릭하십시오. Buenos días
텍스트를 제출하십시오. 어시스턴트는 입력을 이해할 수 없을 수도 있으며, Anything else 노드의 응답을 반환합니다. 하지만 어시스턴트의 분석 페이지로 이동하여 대화를 열면 제출된 내용을 볼 수 있습니다. 가장 최근의 사용자 대화를 확인하십시오. 로그는
사용자 입력이 Buenos días (in es)
임을 표시합니다. 괄호 안의 es
은 스페인어의 언어 코드를 나타내므로 웹훅이 작동하여 제출된 텍스트가 스페인어 구문임을 인식했습니다.
예제 2
이 예는 수신 메시지의 언어를 확인하고 영어가 아닌 경우 어시스턴트에게 제출하기 전에 영어로 번역하는 방법을 보여 줍니다.
IBM Cloud Functions에서 웹 조치 시퀀스를 정의하십시오. 시퀀스의 첫 번째 조치는 수신 텍스트의 언어를 검사합니다. 시퀀스의 두 번째 조치는 텍스트를 원래 언어에서 영어로 변환합니다.
사전 메시지 웹훅 구성 페이지에서 다음 값이 지정됩니다:
- URL:
https://us-south.functions.appdomain.cloud/api/v1/web/e97d2516-5ce4-4fd9-9d05-acc3dd8ennn/default/translation_sequence
- 시크릿: 없음
- 헤더 이름: 컨텐츠 유형
- 헤더 값: application/json
시퀀스의 첫 번째 웹 조치에 대한 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
}
};
시퀀스의 두 번째 웹 조치는 텍스트를 Watson Language Translator 서비스로 전송하여 이전 웹 조치에서 식별된 언어의 입력 텍스트를 영어로 변환합니다. 그러면 변환된 문자열이 원래 텍스트 대신 어시스턴트에 전송됩니다.
시퀀스의 두 번째 조치에 대한 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
}
};
미리보기 패널에서 웹훅을 테스트할 때 Buenos días
제출이 가능하며 사용자가 영어로 Good morning
이용 시와 같이 어시스턴트가 응답합니다. 실제로 어시스턴트의 분석 페이지를 확인하고 대화를 열면 로그에 사용자 입력이 Good morning
로 표시됩니다.
메시지 후 웹훅을 추가하여 메시지가 표시되기 전에 메시지의 응답을 고객의 언어로 다시 번역할 수 있습니다. 자세한 내용은 예제 2를 참조하세요.
예제 3
이 예는 웹후크 응답을 작성하여 클래식 경험에서 IBM Cloud Pak for Data- 클래식 경험에서 메시지 처리를 건너뛰고 웹후크의 응답을 직접 반환하도록 하는 방법을 보여줍니다.
웹훅 구성
메시지 전 웹훅 구성 페이지에서 다음 값을 지정합니다
- URL: https://your-webhook-url/webhook_skip
- 시크릿: 없음
- 헤더 이름: 컨텐츠 유형
- 헤더 값: application/json
웹훅_스킵 웹 액션의 node.js 코드는 다음과 같습니다.
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;
}
웹훅 제거
-
구성하려는 어시스턴트에 대해
아이콘을 클릭한 다음 설정을 선택합니다.
-
웹훅 > 사전 메시지 웹훅을 클릭합니다.
-
다음 단계 중 하나를 수행하십시오.
-
수신되는 모든 메시지를 처리하기 위해 웹훅 호출을 중지하려면 메시지 전 웹훅 스위치를 사용 안 함으로 설정하세요.
-
호출하려는 웹훅을 변경하려면 웹훅 삭제를 클릭합니다.
절차 {site.data.keyword.conversationshort}
웹훅 세부사항을 추가하려면 다음 단계를 완료하십시오.
-
탐색 패널에서 환경을 클릭하고 웹훅을 구성할 환경을 엽니다.
-
아이콘을 클릭하여 환경 설정을 여십시오.
-
사전 메시지 웹훅 스위치를 사용으로 설정하십시오.
-
동기 이벤트에서 다음 옵션 중 하나를 선택합니다:
-
오류가 있는 경우 웹훅 업데이트 없이 사용자 입력을 계속 처리합니다.
-
웹훅 호출이 실패하면 클라이언트에 오류를 반환합니다.
자세한 내용은 전처리를 위한 웹훅 오류 처리 구성하기를 참조하세요.
-
-
URL 필드에서 HTTP POST 요청 콜아웃을 전송할 외부 애플리케이션의 URL을 추가하십시오.
예를 들어, 메시지가 영어 이외의 언어로 되어 있는지 확인하는 Cloud Functions 웹 작업을 작성하여 Language Translator 서비스로 전송하여 영어로 변환할 수 있습니다. 다음 예제와 같이 웹 조치에 대한 URL을 지정하십시오.
https://us-south.functions.cloud.ibm.com/api/v1/web/my_org_dev/default/translateToEnglish.json
SSL 프로토콜을 사용하는 URL을 지정해야 하므로
https
시작 URL을 지정하십시오. -
사전 메시지 웹훅에 대한 인증을 구성하려면 인증 편집을 클릭합니다. 자세한 지침은 메시지 전 및 메시지 후 웹훅에 대한 인증 방법 정의하기를 참조하세요.
-
시간 제한 필드에서 어시스턴트가 오류를 반환하기 전에 웹훅의 응답을 기다릴 시간(초)을 지정합니다. 제한시간 지속 기간은 1초보다 짧거나 30초보다 길 수 없습니다.
-
헤더 섹션에서 헤더 추가 +를 클릭하여 서비스에 전달할 헤더를 한 번에 하나씩 추가합니다.
호출하는 외부 애플리케이션이 응답을 반환하는 경우 다른 형식으로 응답을 보낼 수 있습니다. 웹훅은 응답이 JSON으로 형식화되어야 합니다. 다음 표는 반환할 결과값이 JSON 형식임을 나타내는 헤더를 추가하는 방법을 설명합니다.
헤더 예제 헤더 이름 헤더 값 Content-Type
application/json
-
헤더 값을 저장하면 문자열이 별표로 대체되어 다시 볼 수 없습니다.
-
웹훅 세부사항이 자동으로 저장됩니다.
전처리를 위한 웹훅 오류 처리 구성하기
웹훅 호출이 실패할 경우 전처리 단계에서 오류 반환 여부를 결정할 수 있습니다. 다음과 같은 두 가지 옵션이 존재합니다.
-
오류가 있는 경우 웹훅 업데이트 없이 사용자 입력을 계속 처리합니다: 어시스턴트가 오류를 무시하고 웹훅 결과 없이 메시지를 처리합니다. 전처리가 유용하지만 필수적인 것은 아니라면 이 옵션을 고려하세요.
-
웹훅 호출이 실패하면 클라이언트에 오류를 반환합니다: 어시스턴트가 메시지를 처리하기 전에 전처리가 중요한 경우 이 옵션을 선택합니다.
웹훅 호출이 실패할 경우 클라이언트에 오류 반환을 사용 설정하면 전처리 단계가 성공적으로 완료될 때까지 모든 작업이 중지됩니다.
외부 프로세스를 정기적으로 테스트하여 잠재적인 장애를 파악하세요. 필요한 경우 이 설정을 조정하여 메시지 처리 중단을 방지하세요.
웹훅 테스트
프로덕션 환경에서 사용되는 어시스턴트에 웹훅을 사용 설정하기 전에 웹훅에 대한 광범위한 테스트를 수행하세요.
웹훅은 메시지가 처리할 어시스턴트에게 전송될 때 트리거됩니다.
웹훅 문제점 해결
다음 오류 코드는 발생할 수 있는 문제의 원인을 추적하는 데 도움이 될 수 있습니다. 예를 들어, 웹 대화 통합이 있는 경우 제출하는 모든 테스트 메시지가 There is an error with the message you just sent, but feel free to ask me something else
와 같은 메시지를 리턴하면 웹훅에 문제가 있음을 알 수 있습니다. 이 메시지가 표시되면 cURL,
같은 REST API 도구를 사용하여 테스트 ' /message
API 요청을 보내면 오류 코드와 반환되는 전체 메시지를 확인할 수 있습니다.
오류 코드 및 메시지 | 설명 |
---|---|
422 웹훅이 올바르지 않은 JSON 본문과 함께 응답 | 웹훅의 HTTP 응답 본문을 JSON으로 구문 분석할 수 없습니다. |
422 웹훅 응답 유효성 검증 오류 | 웹훅의 HTTP 응답 본문이 올바른 /message 본문이 아닙니다. |
422 웹 훅이 [500] 상태 코드와 함께 응답 |
호출한 외부 서비스에 문제가 있습니다. 코드가 실패했거나 외부 서버가 요청을 거부했습니다. |
500 프로세서 예외: [connections to all backends failing] |
웹훅 마이크로서비스에서 오류가 발생했습니다. 백엔드 서비스에 연결할 수 없습니다. |
요청 본문 예
외부 코드에서 처리할 수 있도록 사전 메시지 웹훅의 요청 본문 형식을 아는 것이 유용합니다.
페이로드는 /message
(Stateful 또는 Stateless) v2 API 요청의 요청 본문을 포함합니다. 이벤트 이름 message_received
은 사전 메시지 웹훅에 의해 요청이 생성되었음을 나타냅니다. 메시지 요청 본문에 대한 자세한 정보는 API 참조를 참조하십시오.
{
"payload" : { Copy of request body sent to /message }
"event": {
"name": "message_received"
}
}
보조 처리 건너뛰기
사전 메시지 웹훅 기능이 개선되어 watsonx Assistant 에서 메시지 처리를 건너뛰고 웹훅에서 직접 응답을 반환할 수 있습니다. 이 기능은 웹훅의 HTTP 응답에 x-watson-assistant-webhook-return
헤더를 설정하여 활성화할 수 있습니다.
시작하기 전에
다음 단계를 완료하십시오.
- 웹훅의 HTTP 응답에
x-watson-assistant-webhook-return
헤더를 임의의 값으로 포함하세요. - 웹훅 응답에 유효한 메시지 응답이 포함되어 있는지 확인하십시오. 이 메시지 응답은 watsonx Assistant 요구 사항에 따라 포맷됩니다.
이 기능을 사용하면 웹훅이 대화 흐름을 동적으로 제어할 수 있으므로 필요할 때 즉각적인 응답이 가능합니다.
응답 본문
웹훅에서 POST 요청을 수신하는 서비스는 JSON 오브젝트(Accept: application/json
)를 리턴해야 합니다.
응답 본문의 구조는 다음과 같아야 합니다.
{
"payload": {
...
}
}
응답 payload
에는 요청 본문의 payload
이 포함되어야 합니다. 코드에서 속성 값을 수정하거나 컨텍스트 변수를 수정할 수 있지만 반환된 메시지 페이로드는 message
메서드 스키마를 따라야 합니다. 자세한 내용은 API 참조를 참조하세요.
예제 1
이 예는 입력 텍스트의 언어를 확인하고 입력 텍스트 문자열에 언어 정보를 추가하는 방법을 보여 줍니다.
사전 메시지 웹훅 구성 페이지에서 다음 값이 지정됩니다:
- URL:
https://us-south.functions.appdomain.cloud/api/v1/web/e97d2516-5ce4-4fd9-9d05-acc3dd8ennn/default/check_language
- 헤더 이름: 컨텐츠 유형
- 헤더 값: application/json
사전 메시지 웹훅은 IBM Cloud Functions 웹 액션 이름 check_language
을 호출합니다.
check_language
웹 조치의 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
}
};
웹훅을 테스트하려면 미리 보기를 클릭하십시오. Buenos días
텍스트를 제출하십시오. 어시스턴트는 입력을 이해할 수 없을 수도 있으며, Anything else 노드의 응답을 반환합니다. 하지만 어시스턴트의 분석 페이지로 이동하여 대화를 열면 제출된 내용을 볼 수 있습니다. 가장 최근의 사용자 대화를 확인하십시오. 로그는
사용자 입력이 Buenos días (in es)
임을 표시합니다. 괄호 안의 es
은 스페인어의 언어 코드를 나타내므로 웹훅이 작동하여 제출된 텍스트가 스페인어 구문임을 인식했습니다.
예제 2
이 예는 수신 메시지의 언어를 확인하고 영어가 아닌 경우 어시스턴트에게 제출하기 전에 영어로 번역하는 방법을 보여 줍니다.
IBM Cloud Functions에서 웹 조치 시퀀스를 정의하십시오. 시퀀스의 첫 번째 조치는 수신 텍스트의 언어를 검사합니다. 시퀀스의 두 번째 조치는 텍스트를 원래 언어에서 영어로 변환합니다.
사전 메시지 웹훅 구성 페이지에서 다음 값이 지정됩니다:
- URL:
https://us-south.functions.appdomain.cloud/api/v1/web/e97d2516-5ce4-4fd9-9d05-acc3dd8ennn/default/translation_sequence
- 헤더 이름: 컨텐츠 유형
- 헤더 값: application/json
시퀀스의 첫 번째 웹 조치에 대한 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
}
};
시퀀스의 두 번째 웹 조치는 텍스트를 Watson Language Translator 서비스로 전송하여 이전 웹 조치에서 식별된 언어의 입력 텍스트를 영어로 변환합니다. 그러면 변환된 문자열이 원래 텍스트 대신 어시스턴트에 전송됩니다.
시퀀스의 두 번째 조치에 대한 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
}
};
미리보기 패널에서 웹훅을 테스트할 때 Buenos días
제출이 가능하며 사용자가 영어로 Good morning
이용 시와 같이 어시스턴트가 응답합니다. 실제로 어시스턴트의 분석 페이지를 확인하고 대화를 열면 로그에 사용자 입력이 Good morning
로 표시됩니다.
메시지 후 웹훅을 추가하여 메시지가 표시되기 전에 메시지의 응답을 고객의 언어로 다시 번역할 수 있습니다. 자세한 내용은 예제 2를 참조하세요.
예제 3
이 예는 watsonx Assistant 가 메시지 처리를 건너뛰고 웹훅의 응답을 직접 반환하도록 웹훅 응답을 작성하는 방법을 보여 줍니다.
웹훅 구성
메시지 전 웹훅 구성 페이지에서 다음 값을 지정합니다
- URL: https://your-webhook-url/webhook_skip
- 헤더 이름: 컨텐츠 유형
- 헤더 값: application/json
웹훅_스킵 웹 액션의 node.js 코드는 다음과 같습니다.
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;
}
웹훅 제거
웹훅으로 고객 입력을 사전 처리하지 않기로 결정했다면 다음 단계를 완료하세요:
-
어시스턴트에서 환경 으로 이동하여 웹훅을 제거할 환경을 여십시오.
-
아이콘을 클릭하여 환경 설정을 여십시오.
-
환경 설정 페이지에서 사전 메시지 웹훅을 클릭합니다.
-
다음 단계 중 하나를 수행하십시오.
-
수신되는 모든 메시지를 처리하기 위해 웹훅 호출을 중지하려면 메시지 전 웹훅 스위치를 사용 안 함으로 설정하세요.
-
호출하려는 웹훅을 변경하려면 웹훅 삭제를 클릭합니다.
{site.data.keyword.conversationshort} 절차 - 클래식 경험
웹훅 세부사항을 추가하려면 다음 단계를 완료하십시오.
웹훅 세부사항을 추가하려면 다음 단계를 완료하십시오.
-
구성하려는 어시스턴트에 대해
아이콘을 클릭한 다음 설정을 선택합니다.
-
웹훅 > 사전 메시지 웹훅을 클릭합니다.
-
사전 메시지 웹훅 스위치를 사용으로 설정하십시오.
-
동기 이벤트에서 다음 옵션 중 하나를 선택합니다:
-
오류가 있는 경우 웹훅 업데이트 없이 사용자 입력을 계속 처리합니다.
-
웹훅 호출이 실패하면 클라이언트에 오류를 반환합니다.
자세한 내용은 전처리를 위한 웹훅 오류 처리 구성하기를 참조하세요.
-
-
URL 필드에서 HTTP POST 요청 콜아웃을 전송할 외부 애플리케이션의 URL을 추가하십시오.
예를 들어, 메시지가 영어 이외의 언어로 되어 있는지 확인하는 Cloud Functions 웹 작업을 작성하여 Language Translator 서비스로 전송하여 영어로 변환할 수 있습니다. 다음 예제와 같이 웹 조치에 대한 URL을 지정하십시오.
https://us-south.functions.cloud.ibm.com/api/v1/web/my_org_dev/default/translateToEnglish.json
SSL 프로토콜을 사용하는 URL을 지정해야 하므로
https
시작 URL을 지정하십시오. -
비밀 필드를 입력합니다. 자세한 내용은 비밀 번호 추가하기를 참조하세요.
-
시간 제한 필드에서 어시스턴트가 오류를 반환하기 전에 웹훅의 응답을 기다릴 시간(초)을 지정합니다. 제한시간 지속 기간은 1초보다 짧거나 30초보다 길 수 없습니다.
-
헤더 섹션에서 헤더 추가 +를 클릭하여 서비스에 전달할 헤더를 한 번에 하나씩 추가합니다.
호출하는 외부 애플리케이션이 응답을 반환하는 경우 다른 형식으로 응답을 보낼 수 있습니다. 웹훅은 응답이 JSON으로 형식화되어야 합니다. 다음 표는 반환할 결과값이 JSON 형식임을 나타내는 헤더를 추가하는 방법을 설명합니다.
헤더 예제 헤더 이름 헤더 값 Content-Type
application/json
-
헤더 값을 저장하면 문자열이 별표로 대체되어 다시 볼 수 없습니다.
-
웹훅 세부사항이 자동으로 저장됩니다.
비밀 추가하기
외부 서비스 인증 요청과 함께 전달할 개인 키를 비밀 필드에 추가합니다:
-
purple unicorn
과 같이 텍스트 문자열로 키를 입력합니다. -
최대 1,024자까지 입력할 수 있습니다.
-
컨텍스트 변수를 사용하지 마세요.
외부 서비스는 비밀을 확인하고 확인할 책임이 있습니다. 토큰이 필요하지 않은 경우 아무 문자열이나 지정합니다. 이 필드는 비워 둘 수 없습니다.
비밀번호를 입력할 때 비밀번호를 확인하려면 입력하기 전에 비밀번호 표시 아이콘 클릭합니다. 비밀번호를 저장한 후에는 별표가 문자열을 대체하며 다시 볼 수 없습니다.
이 필드를 사용하는 방법에 대한 자세한 정보는 웹훅 보안의 내용을 참조하십시오.
웹훅 보안
요청과 함께 전송된 JSON 웹 토큰(JWT)을 확인하여 웹훅 요청을 인증합니다. 웹훅 마이크로서비스는 자동으로 JWT를 생성하여 각 웹훅 호출과 함께 Authorization
헤더로 전송합니다:
-
인증 수정을 통해 업데이트된 새 웹훅 또는 웹훅의 경우 인증 헤더가 무시됩니다.
-
인증 헤더가 저장된 기존 웹훅의 경우 인증 편집 옵션이 비활성화됩니다.
-
새 인증 구성을 사용하도록 기존 웹훅을 업데이트하면 동작이 변경됩니다.
JWT 확인을 테스트해야 하는 경우 외부 서비스에 코드를 추가할 수 있습니다. 예를 들어 비밀 필드에 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
}
전처리를 위한 웹훅 오류 처리 구성하기
웹훅 호출이 실패할 경우 전처리 단계에서 오류 반환 여부를 결정할 수 있습니다. 다음과 같은 두 가지 옵션이 존재합니다.
-
오류가 있는 경우 웹훅 업데이트 없이 사용자 입력을 계속 처리합니다: 어시스턴트가 오류를 무시하고 웹훅 결과 없이 메시지를 처리합니다. 전처리가 유용하지만 필수적인 것은 아니라면 이 옵션을 고려하세요.
-
웹훅 호출이 실패하면 클라이언트에 오류를 반환합니다: 어시스턴트가 메시지를 처리하기 전에 전처리가 중요한 경우 이 옵션을 선택합니다.
웹훅 호출이 실패할 경우 클라이언트에 오류 반환을 사용 설정하면 전처리 단계가 성공적으로 완료될 때까지 모든 작업이 중지됩니다.
외부 프로세스를 정기적으로 테스트하여 잠재적인 장애를 파악하세요. 필요한 경우 이 설정을 조정하여 메시지 처리 중단을 방지하세요.
웹훅 테스트
프로덕션 환경에서 사용되는 어시스턴트에 웹훅을 사용 설정하기 전에 웹훅에 대한 광범위한 테스트를 수행하세요.
웹훅은 메시지가 처리할 어시스턴트에게 전송될 때 트리거됩니다.
웹훅 문제점 해결
다음 오류 코드는 발생할 수 있는 문제의 원인을 추적하는 데 도움이 될 수 있습니다. 예를 들어, 웹 대화 통합이 있는 경우 제출하는 모든 테스트 메시지가 There is an error with the message you just sent, but feel free to ask me something else
와 같은 메시지를 리턴하면 웹훅에 문제가 있음을 알 수 있습니다. 이 메시지가 표시되면 cURL,
같은 REST API 도구를 사용하여 테스트 ' /message
API 요청을 보내면 오류 코드와 반환되는 전체 메시지를 확인할 수 있습니다.
오류 코드 및 메시지 | 설명 |
---|---|
422 웹훅이 올바르지 않은 JSON 본문과 함께 응답 | 웹훅의 HTTP 응답 본문을 JSON으로 구문 분석할 수 없습니다. |
422 웹훅 응답 유효성 검증 오류 | 웹훅의 HTTP 응답 본문이 올바른 /message 본문이 아닙니다. |
422 웹 훅이 [500] 상태 코드와 함께 응답 |
호출한 외부 서비스에 문제가 있습니다. 코드가 실패했거나 외부 서버가 요청을 거부했습니다. |
500 프로세서 예외: [connections to all backends failing] |
웹훅 마이크로서비스에서 오류가 발생했습니다. 백엔드 서비스에 연결할 수 없습니다. |
요청 본문 예
외부 코드에서 처리할 수 있도록 사전 메시지 웹훅의 요청 본문 형식을 아는 것이 유용합니다.
페이로드는 /message
(Stateful 또는 Stateless) v2 API 요청의 요청 본문을 포함합니다. 이벤트 이름 message_received
은 사전 메시지 웹훅에 의해 요청이 생성되었음을 나타냅니다. 메시지 요청 본문에 대한 자세한 정보는 API 참조를 참조하십시오.
{
"payload" : { Copy of request body sent to /message }
"event": {
"name": "message_received"
}
}
보조 처리 건너뛰기
사전 메시지 웹후크가 개선되어 {site.data.keyword.conversationshort}- 클래식 환경에서는 메시지 처리를 건너뛰고 웹후크에서 바로 응답을 반환할 수 있습니다. 이 기능은 웹훅의 HTTP 응답에 x-watson-assistant-webhook-return
헤더를 설정하여 활성화할 수 있습니다.
시작하기 전에
다음 단계를 완료하십시오.
- 웹훅의 HTTP 응답에
x-watson-assistant-webhook-return
헤더를 임의의 값으로 포함하세요. - 웹훅 응답에 유효한 메시지 응답이 포함되어 있는지 확인하십시오. 이 메시지 응답은 watsonx Assistant 요구 사항에 따라 포맷됩니다.
이 기능을 사용하면 웹훅이 대화 흐름을 동적으로 제어할 수 있으므로 필요할 때 즉각적인 응답이 가능합니다.
응답 본문
웹훅에서 POST 요청을 수신하는 서비스는 JSON 오브젝트(Accept: application/json
)를 리턴해야 합니다.
응답 본문의 구조는 다음과 같아야 합니다.
{
"payload": {
...
}
}
응답 payload
에는 요청 본문의 payload
이 포함되어야 합니다. 코드에서 속성 값을 수정하거나 컨텍스트 변수를 수정할 수 있지만 반환된 메시지 페이로드는 message
메서드 스키마를 따라야 합니다. 자세한 내용은 API 참조를 참조하세요.
예제 1
이 예는 입력 텍스트의 언어를 확인하고 입력 텍스트 문자열에 언어 정보를 추가하는 방법을 보여 줍니다.
사전 메시지 웹훅 구성 페이지에서 다음 값이 지정됩니다:
- URL:
https://us-south.functions.appdomain.cloud/api/v1/web/e97d2516-5ce4-4fd9-9d05-acc3dd8ennn/default/check_language
- 시크릿: 없음
- 헤더 이름: 컨텐츠 유형
- 헤더 값: application/json
사전 메시지 웹훅은 IBM Cloud Functions 웹 액션 이름 check_language
을 호출합니다.
check_language
웹 조치의 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
}
};
웹훅을 테스트하려면 미리 보기를 클릭하십시오. Buenos días
텍스트를 제출하십시오. 어시스턴트는 입력을 이해할 수 없을 수도 있으며, Anything else 노드의 응답을 반환합니다. 하지만 어시스턴트의 분석 페이지로 이동하여 대화를 열면 제출된 내용을 볼 수 있습니다. 가장 최근의 사용자 대화를 확인하십시오. 로그는
사용자 입력이 Buenos días (in es)
임을 표시합니다. 괄호 안의 es
은 스페인어의 언어 코드를 나타내므로 웹훅이 작동하여 제출된 텍스트가 스페인어 구문임을 인식했습니다.
예제 2
이 예는 수신 메시지의 언어를 확인하고 영어가 아닌 경우 어시스턴트에게 제출하기 전에 영어로 번역하는 방법을 보여 줍니다.
IBM Cloud Functions에서 웹 조치 시퀀스를 정의하십시오. 시퀀스의 첫 번째 조치는 수신 텍스트의 언어를 검사합니다. 시퀀스의 두 번째 조치는 텍스트를 원래 언어에서 영어로 변환합니다.
사전 메시지 웹훅 구성 페이지에서 다음 값이 지정됩니다:
- URL:
https://us-south.functions.appdomain.cloud/api/v1/web/e97d2516-5ce4-4fd9-9d05-acc3dd8ennn/default/translation_sequence
- 시크릿: 없음
- 헤더 이름: 컨텐츠 유형
- 헤더 값: application/json
시퀀스의 첫 번째 웹 조치에 대한 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
}
};
시퀀스의 두 번째 웹 조치는 텍스트를 Watson Language Translator 서비스로 전송하여 이전 웹 조치에서 식별된 언어의 입력 텍스트를 영어로 변환합니다. 그러면 변환된 문자열이 원래 텍스트 대신 어시스턴트에 전송됩니다.
시퀀스의 두 번째 조치에 대한 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
}
};
미리보기 패널에서 웹훅을 테스트할 때 Buenos días
제출이 가능하며 사용자가 영어로 Good morning
이용 시와 같이 어시스턴트가 응답합니다. 실제로 어시스턴트의 분석 페이지를 확인하고 대화를 열면 로그에 사용자 입력이 Good morning
로 표시됩니다.
메시지 후 웹훅을 추가하여 메시지가 표시되기 전에 메시지의 응답을 고객의 언어로 다시 번역할 수 있습니다. 자세한 내용은 예제 2를 참조하세요.
예제 3
이 예는 watsonx Assistant- 클래식 경험에서 메시지 처리를 건너뛰고 웹후크의 응답을 직접 반환하도록 웹후크 응답을 작성하는 방법을 보여 줍니다.
웹훅 구성
메시지 전 웹훅 구성 페이지에서 다음 값을 지정합니다
- URL: https://your-webhook-url/webhook_skip
- 시크릿: 없음
- 헤더 이름: 컨텐츠 유형
- 헤더 값: application/json
웹훅_스킵 웹 액션의 node.js 코드는 다음과 같습니다.
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;
}
웹훅 제거
-
구성하려는 어시스턴트에 대해
아이콘을 클릭한 다음 설정을 선택합니다.
-
웹훅 > 사전 메시지 웹훅을 클릭합니다.
-
다음 단계 중 하나를 수행하십시오.
-
수신되는 모든 메시지를 처리하기 위해 웹훅 호출을 중지하려면 메시지 전 웹훅 스위치를 사용 안 함으로 설정하세요.
-
호출하려는 웹훅을 변경하려면 웹훅 삭제를 클릭합니다.