웹훅 구성

웹훅 세부사항을 추가하려면 다음 단계를 완료하십시오.

1. 탐색 패널에서 환경을 클릭하고 웹훅을 구성할 환경을 엽니다.

2. 아이콘을 클릭하여 환경 설정을 여십시오.

3. 사전 메시지 웹훅 스위치를 사용으로 설정하십시오.

4. 동기 이벤트에서 다음 옵션 중 하나를 선택합니다:

   • 오류가 있는 경우 웹훅 업데이트 없이 사용자 입력을 계속 처리합니다.

   • 웹훅 호출이 실패하면 클라이언트에 오류를 반환합니다.

   자세한 내용은 전처리를 위한 웹훅 오류 처리 구성하기를 참조하세요.

5. 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을 지정하십시오.

6. 사전 메시지 웹훅에 대한 인증을 구성하려면 인증 편집을 클릭합니다. 자세한 지침은 메시지 전 및 메시지 후 웹훅에 대한 인증 방법 정의하기를 참조하세요.

7. 시간 초과 필드에서 어시스턴트가 오류를 반환하기 전에 웹훅의 응답을 기다릴 시간(초)을 지정합니다. 제한시간 지속 기간은 1초보다 짧거나 30초보다 길 수 없습니다.

8. 헤더 섹션에서 헤더 추가 +를 클릭하여 서비스에 전달할 헤더를 한 번에 하나씩 추가합니다.

   호출하는 외부 애플리케이션이 응답을 반환하는 경우 다른 형식으로 응답을 보낼 수 있습니다. 웹훅은 응답이 JSON으로 형식화되어야 합니다. 다음 표는 반환할 결과값이 JSON 형식임을 나타내는 헤더를 추가하는 방법을 설명합니다.

   헤더 예제

   헤더 이름	헤더 값
   Content-Type	application/json

9. 헤더 값을 저장한 후에는 문자열이 별표로 바뀌며 다시 볼 수 없습니다.

10. 웹훅 세부사항이 자동으로 저장됩니다.

전처리를 위한 웹훅 오류 처리 구성하기

웹훅 호출이 실패할 경우 전처리 단계에서 오류 반환 여부를 결정할 수 있습니다. 다음과 같은 두 가지 옵션이 존재합니다.

• 오류가 있는 경우 웹훅 업데이트 없이 사용자 입력을 계속 처리합니다: 어시스턴트가 오류를 무시하고 웹훅 결과 없이 메시지를 처리합니다. 전처리가 유용하지만 필수적인 것은 아니라면 이 옵션을 고려하세요.

• 웹훅 호출이 실패하면 클라이언트에 오류를 반환합니다: 어시스턴트가 메시지를 처리하기 전에 전처리가 중요한 경우 이 옵션을 선택합니다.

웹훅 호출이 실패할 경우 클라이언트에 오류 반환을 사용 설정하면 전처리 단계가 성공적으로 완료될 때까지 모든 작업이 중지됩니다.

외부 프로세스를 정기적으로 테스트하여 잠재적인 장애를 파악하세요. 필요한 경우 이 설정을 조정하여 메시지 처리 중단을 방지하세요.

웹훅 테스트

프로덕션 환경에서 사용되는 어시스턴트에 웹훅을 사용 설정하기 전에 웹훅에 대한 광범위한 테스트를 수행하세요.

웹훅은 메시지가 처리할 어시스턴트에게 전송될 때 트리거됩니다.

웹훅 문제점 해결

다음 오류 코드는 발생할 수 있는 문제의 원인을 추적하는 데 도움이 될 수 있습니다. 예를 들어 웹 채팅 연동 서비스를 사용하는 경우 제출하는 모든 테스트 메시지가 There is an error with the message you just sent, but feel free to ask me something else 와 같은 메시지를 반환하면 웹훅에 문제가 있다는 것을 알 수 있습니다. 이 메시지가 표시되면 cURL, 등의 REST API 도구를 사용하여 테스트 /message API 요청을 보내면 오류 코드와 반환되는 전체 메시지를 확인할 수 있습니다.

요청 본문 예

외부 코드에서 처리할 수 있도록 사전 메시지 웹훅의 요청 본문 형식을 아는 것이 유용합니다.

페이로드에는 /message, 상태 저장 또는 상태 비저장, 버전 2 API 요청의 요청 본문이 포함됩니다. 이벤트 이름 message_received 은 사전 메시지 웹훅에 의해 요청이 생성되었음을 나타냅니다. 메시지 요청 본문에 대한 자세한 내용은 API 참조를 참조하세요.

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

보조 처리 건너뛰기

사전 메시지 웹훅 기능이 개선되어 Cloud Pak for Data 에서 메시지 처리를 건너뛰고 웹훅에서 직접 응답을 반환할 수 있습니다. 이 기능은 웹훅의 HTTP 응답에 x-watson-assistant-webhook-return 헤더를 설정하여 활성화할 수 있습니다.

응답 본문

웹훅에서 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

이 예는 Cloud Pak for Data 가 메시지 처리를 건너뛰고 웹훅의 응답을 직접 반환하도록 웹훅 응답을 작성하는 방법을 보여 줍니다.

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;
}

웹훅 제거

웹훅으로 고객 입력을 사전 처리하지 않으려면 다음 단계를 완료하세요:

1. 어시스턴트에서 환경으로 이동하여 웹훅을 제거하려는 환경을 엽니다.

2. 아이콘을 클릭하여 환경 설정을 여십시오.

3. 환경 설정 페이지에서 사전 메시지 웹훅을 클릭합니다.

4. 다음 단계 중 하나를 수행하십시오.

• 수신되는 모든 메시지를 처리하기 위해 웹훅 호출을 중지하려면 메시지 전 웹훅 스위치를 사용 안 함으로 설정하세요.

• 호출하려는 웹훅을 변경하려면 웹훅 삭제를 클릭합니다.