지금까지 Kore.ai 가상 비서 플랫폼에서 경고 작업을 설정하는 방법을 여기에서 확인했습니다. 이 섹션에서는, REST 서비스의 API 요청을 구성하는 방법을 살펴봅니다.
다음 그림은 일반 탭에서 연결 유형이 웹 서비스로 지정되고 연결 모드가 REST로 설정된 경고 작업을 위한 경고 편집 – <작업 이름> 페이지에서 API 요청 탭의 예입니다.
연결 유형이 웹 서비스로 지정되고 연결 모드가 REST로 설정된 작업의 경우 다음을 정의해야 합니다.
- 콘텐츠 유형 – Kore.ai 및 웹 애플리케이션 간에 교환되는 데이터 유형입니다. 자세한 내용은 아래를 참조하세요.
- 인증 – 경고 작업에 필요한 경우, 기본 인증, OAuth 또는 API 키를 사용하여 API에 액세스하기 위해 인증을 정의해야 합니다. 자세한 내용은 여기를 참조하세요.
- 매개변수 – API 요청을 처리하는 데 사용되는 매개변수를 하나 이상 정의합니다. 예: 사용자 프롬프트의 입력, 선택 항목에서 최종 사용자가 선택한 항목, URL 등. 자세한 내용은 아래를 참조하세요.
- 이니셜라이저 – 웹 서비스가 코드를 실행할 때 또는 세션 변수가 설정될 때, API 요청이 실행되기 전에 사용자 컨텍스트 세부 정보를 수정할 때, 작업 인스턴스를 생성하기 전에 실행할 사용자 정의 JavaScript를 지정하거나 세션 변수를 설정합니다. 자세한 내용은 아래를 참조하세요.
- 요청 – 봇에 대한 URL과 경로를 사용하여 웹 서비스에 API 호출을 수행하여 작업을 시작하고 웹 서비스에서 봇 플랫폼으로 데이터 페이로드 전달을 시작하는 데 사용되는 요청 체인을 정의합니다. 요청 체인은 전처리기, API 요청, 후처리기로 구성됩니다. 자세한 내용은 아래를 참조하세요.
- 응답 샘플 – 작업 페이로드에서 수신할 것으로 예상되는 키/ 값 쌍을 정의합니다. 입력한 키는 최종 사용자에게 표시할 데이터를 처리하기 위해 드롭다운 선택 항목으로 사용할 수 있습니다. 자세한 내용은 아래를 참조하세요.
- 게시물의 웹 사이트 링크 콘텐츠 미리 보기 – 작업 알림 메시지에 표시되는 웹 사이트 미리 보기 콘텐츠입니다. 자세한 내용은 아래를 참조하세요.
저장을 클릭하여 API 요청 설정을 저장합니다.
콘텐츠 유형 정의하기
콘텐츠 유형은 Kore.ai 및 봇 웹 사이트 또는 애플리케이션 간에 교환되는 데이터 유형 및 작업 페이로드 응답에서 예상되는 키-값 쌍을 설명합니다. API 요청(REST)을 위한 콘텐츠 유형을 정의하려면 콘텐츠 유형 탭을 확장하고 다음 옵션 중 하나를 선택합니다.
- JSON – JavaScript Object Notation은 사람이 읽을 수 있는 텍스트를 사용하여 데이터 개체를 속성-값 쌍으로 전송하는 개방형 표준 포맷입니다. JSON을 사용하여 Kore.ai 서버와 봇 웹 애플리케이션 간에 데이터를 전송할 수 있습니다.
- RSS – Rich Site Summary 또는 Really Simple Syndication은 블로그 항목, 뉴스 헤드라인, 오디오 및 동영상과 같이 자주 업데이트되는 정보를 게시하는 데 사용되는 표준화된 형식 집합입니다.
- XML – Extensible Markup Language는 사람이 읽을 수 있고 기계가 읽을 수 있는 형식으로 문서를 인코딩하기 위한 규칙 집합을 정의한 마크업 언어입니다. 웹 서비스는 종종 XML 스키마를 사용하여 XML 데이터를 처리합니다.
- URL 인코딩된 JSON – 예약된 문자에 대해 JSON 인코딩을 사용한 URL입니다.
- CSV – 쉼표로 구분된 값 목록입니다.
- 텍스트 – 텍스트 기반 키-값 쌍입니다.
- Twitter 인코딩된 JSON – 예약된 문자에 대해 JSON 인코딩을 사용한 Twitter의 URL입니다.
- Multipart/Form-data – 사용자가 양식에서 파일을 업로드할 수 있도록 하는 경우 HTTP POST 요청 메소드를 통해 파일을 전송하는 인코딩 유형입니다.
- Multipart/Related – 같은 정보를 다른 본문 파트에 다른 형태로 표시할 때 사용됩니다. 본문 파트는 복잡도가 높은 순으로 정렬됩니다.
- Oracle ADF – Oracle Application Development Framework용 입니다.
매개 변수 정의하기
API 요청(REST) 매개 변수를 정의하려면 다음 단계를 따르세요.
- 매개변수 섹션을 클릭한 다음 추가를 클릭합니다. 작업 매개변수 설정 대화 상자가 열립니다.
- 선택에 따라, 다음 표에 설명된 대로 관련 필드 값을 입력합니다.
필드 이름 설명 작업 매개 변수 유형 다음 중 하나를 지정합니다.
- 페이로드 매개변수 – 이 필드 유형을 사용하여 POST, PUT, GET, DELETE 등 HTTP 메소드의 페이로드 데이터를 나타냅니다. 예:
{ "taskId":"{payloadfield2}", "message":"{payloadfield1}" }
- 쿼리 매개변수 – 이 필드는 URL 경로 또는 URL 내의 쿼리의 일부로 사용됩니다. 예:
http://app.asana.com/api/workspaces/{queryfield1}/project/{queryfield2}?userId={queryfield3}
매개 변수 이름 사용자에게 표시되는 작업 입력 필드의 제목입니다. 예: <i>계정 선택</i> 프롬프트 메시지 매개변수 이름 아래에 표시되는 도움말 설명입니다. 예: 어떤 계정에 액세스하시겠습니까? 매개 변수 키 수집하려는 최종 사용자 입력값을 나타내는 키입니다. 예: accountType. 매개 변수 유형 키 값에 할당할 요청 개체의 사용자 입력 수집을 위해 최종 사용자 인터페이스에 표시되는 작업 입력 필드의 유형을 지정합니다. 기본 설정은 텍스트 상자이지만 다음 중 하나에 맞게 사용자 정의할 수 있습니다.
- 날짜 – 작업을 계정에 설정할 때 최종 사용자가 정의할 날짜 형식 구문을 선택할 수 있는 형식 필드를 표시합니다. 날짜 형식 선택 드롭다운 목록에서, 다음 중 하나를 선택합니다.
- dd-MM-YYYY – 예: 16-05-1999
- MM-dd-YYYY – 예: 05-16-1999
- dd-MM-YY – 예: 16-05-99
- YYYY-MM-dd – 예: 1999-05-16
- URL – 올바른 URL 구문을 위한 필드 유효성 검사를 포함하여 최종 사용자가 URL을 입력할 수 있는 텍스트 상자를 표시합니다. 플레이스 홀더 필드에, 텍스트 상자에 표시되는 도움말 힌트를 입력합니다. 예: 여기에 웹 사이트의 URL 입력.
- 텍스트 상자 – 최종 사용자가 작업 입력 필드로 텍스트를 입력하기 위한 텍스트 상자를 표시합니다. 일반적으로 몇 단어입니다. 플레이스 홀더 필드에서, 텍스트 필드에 표시되는 도움말 힌트를 입력합니다. 예: 꾸미려는 이름을 입력합니다.
- 정적 드롭다운 – 최종 사용자에 대한 드롭다운 선택 목록을 표시합니다. 옵션 추가를 클릭하여 다음 매개변수를 사용하여 최종 사용자에게 표시할 항목 목록을 추가합니다.
- 옵션 이름 – 최종 사용자에게 표시되는 옵션의 이름입니다.
- 옵션값 – 애플리케이션에 반환된 옵션 이름을 나타내는 값입니다.
- 기본값 – 하나 이상의 옵션이 정의된 경우 옵션의 기본값을 선택합니다.
- 검색 가능 – 최종 사용자가 이 필드에 텍스트를 입력할 때 동적 검색 및 표시를 사용함으로 설정하거나 일치 항목이 없는 경우 자유 양식 입력을 허용하려면 선택합니다.
저장을 클릭합니다. 추가 항목을 추가하려면, 옵션 추가를 다시 클릭합니다. 옵션의 조치 열에서 옵션을 편집하거나 삭제합니다.
- 동적 드롭다운 – 봇의 URL 응답에 따라 실행 시 동적으로 채워진 드롭다운 목록을 표시합니다. 예: JIRA 작업 알림용 프로젝트 목록. 동적으로 채워진 드롭다운에 대해 다음 속성을 정의합니다.
- 엔드포인트 URL – 봇 엔드포인트 URL입니다. 예: https://app.asana.com/api/1.0/workspaces.
- 엔드포인트 콘텐츠 유형 – 지정된 엔드포인트 URL에서 예상되는 콘텐츠 유형입니다. 다음 중 하나입니다. JSON, RSS, XML, URL Encoded JSON, CCV, Text 또는 Twitter 인코딩된 JSON.
- 엔드포인트 메소드 – 다음 중 하나입니다.
- GET – 작업 필드의 HTTP 요청 GET 메소드를 지정합니다.
- POST – 작업 필드의 HTTP 요청 POST 메소드를 지정합니다.
- 응답 경로 – 원하는 드롭다운 목록 값이 포함된 응답의 경로입니다. 예: data.
- 라벨 키 – 드롭다운 옵션의 라벨 키입니다. 예: name.
- 옵션값 키 – 드롭다운 옵션 값의 키입니다. 예: id.
- 페이로드 필드 추가 – 동적 드롭다운에 대한 옵션으로 응답 페이로드에서 하나 이상의 필드를 추가하려면 클릭합니다. 각 페이로드 필드에서, 페이로드 필드 키 및 페이로드 필드 값을 입력한 다음 저장을 클릭합니다. 조치 열에서 페이로드 필드를 편집하거나 삭제합니다.
- 검색 가능 – 최종 사용자가 이 필드에 텍스트를 입력할 때 동적 검색 및 표시를 사용함으로 설정하거나 일치 항목이 없는 경우 자유 양식 입력을 허용하려면 선택합니다.
- 텍스트 영역 – 최종 사용자가 작업 입력 텍스트를 입력하기 위한 텍스트 영역을 표시합니다. 일반적으로 몇 문장입니다. 플레이스 홀더 필드에서, 텍스트 영역 내부에 표시되는 도움말 힌트를 입력합니다.
- 타입 어헤드 – 작업에 정의된 URL 응답에 따라 사용자가 검색 결과와 일치하는 3개 이상의 문자를 입력할 때 실행 시 동적으로 채워진 드롭다운 선택 목록을 최종 사용자에게 표시합니다. 예: JIRA 작업 알림 메시지의 프로젝트 목록. 동적으로 채워진 드롭다운에 대해 다음 속성을 정의합니다.
- 엔드포인트 URL – 봇 엔드포인트 URL입니다. 예: https://app.asana.com/api/1.0/workspaces.
- 엔드포인트 콘텐츠 유형 – 지정된 엔드포인트 URL에서 예상되는 콘텐츠 유형입니다. 다음 중 하나입니다. JSON, RSS, XML, URL Encoded JSON, CCV, Text, Twitter Encoded JSON, Multipart/Form-data 또는 Multipart/Related.
- 엔드포인트 메소드 – 다음 중 하나입니다.
- GET – 작업 필드의 HTTP 요청 GET 메소드를 지정합니다.
- POST – 작업 필드의 HTTP 요청 POST 메소드를 지정합니다.
- 응답 경로 – 원하는 드롭다운 목록 값이 포함된 응답의 경로입니다. 예: data.
- 라벨 키 – 드롭다운 옵션의 라벨 키입니다. 예: name.
- 옵션값 키 – 드롭다운 옵션 값의 키입니다. 예: id.
- 페이로드 필드 추가 – 타입 어헤드 필드에 대한 옵션으로 응답 페이로드에서 하나 이상의 필드를 추가하려면 클릭합니다. 각 타입 어헤드 필드 옵션에서, 페이로드 필드 키 및 페이로드 필드 값을 입력한 다음 저장을 클릭합니다. 조치 열에서 페이로드 필드를 편집하거나 삭제합니다.
- 편집 가능 – 타입 어헤드 검색 결과가 일치하지 않을 때 사용자가 필드에서 텍스트를 자유롭게 입력할 수 있습니다.
- 이메일 – 최종 사용자가 이메일 주소를 입력할 수 있는 텍스트 상자를 표시합니다. 플레이스 홀더 필드에서, 텍스트 상자 내부에 최종 사용자에게 표시되는 유용한 힌트를 입력합니다.
- 날짜 및 시간 – 최종 사용자가 시간과 함께 날짜를 입력할 수 있는 텍스트 상자를 표시합니다. 형식 필드에서, 날짜 텍스트 상자에 최종 사용자에게 표시할 예상되는 날짜 또는 시간 형식을 입력합니다. 날짜 형식 선택 드롭다운 목록에서, 시간 형식의 날짜를 선택합니다.
- 시간대 – 운영 체제 설정에 따른 시간대 드롭다운 목록을 표시합니다.
- 위치 – 최종 사용자가 지리적 위치를 입력할 수 있는 텍스트 상자를 표시합니다. 예: Orlando, FL 또는 32801.
- 중첩된 양식 – 상위 입력 필드 아래에 중첩된 형식으로 최종 사용자 입력 필드를 표시합니다. 중첩된 양식 입력 필드에 대해 다음 필드를 지정합니다.
- 배열 요소 유형 – 상위 입력 양식 요소의 데이터 유형을 선택합니다.
- 중첩 양식 필드 추가 – 하나 이상의 중첩된 양식 필드를 추가하려면 클릭합니다.
- 파일 업로드 – 검색할 최종 사용자 컨트롤을 표시하고 업로드할 파일을 선택합니다. 클릭되면, 파일 업로드 페이로드 키를 입력합니다. 파일 업로드 페이로드 키가 정의된 경우, 파일 업로드 페이로드 필드 값 드롭다운 목록에서 다음 유형 중 하나를 선택합니다.
- 파일 이름
- 파일 크기
- 파일 콘텐츠 유형
데이터 유형 다음 사용자 입력 유형 중 하나를 선택합니다.
- 문자열 – 사용자는 연속된 숫자, 문자 또는 특수 문자를 입력할 수 있습니다.
- 숫자 – 사용자는 숫자를 입력할 수 있습니다. 특수 문자는 허용되지 않습니다.
- 불리언 – 사용자는 true 또는 false의 부울 값을 입력할 수 있습니다.
- 이메일 – 사용자는 유효한 이메일 주소를 입력할 수 있습니다.
- 개체 – 봇의 데이터는 JSON 개체로 수신할 수 있습니다. 예: 다음과 같이 정의된 위치 세부정보 “location” : { “lat” : 17.4374614, “lng” : 78.4482878 } 요청 체인 또는 작업 요청에서 속성을 location.lat 및 location.lng로 참조할 수 있습니다.
- Array – 사용자는 쉼표로 구분된 값 목록을 봇에 전달할 수 있습니다. 예: 구글 캘린더에서 데이터가 있는 여러 참석자는 다음과 같이 전달할 수 있습니다. “attendees”: [“user1”, “user2”, “user3”] 선택되면 사용자 입력 배열의 유형을 다음 중 하나로 지정합니다.
- 페이로드 매개변수 – 이 필드 유형을 사용하여 POST, PUT, GET, DELETE 등 HTTP 메소드의 페이로드 데이터를 나타냅니다. 예:
- 문자열
- 숫자
- 불리언
- 이메일
- 배열
- 날짜
- 날짜 – 사용자는 전체 날짜를 입력하거나 날짜 선택기에서 날짜를 선택할 수 있습니다.
Is Multi Select를 사용하여 사용자는 하나 이상의 항목을 선택할 수 있습니다. 이 필드는 선택한 필드 유형에 따라 표시됩니다.
- 고급 설정 탭을 클릭하여 작업 필드의 추가 옵션 설정을 정의합니다.
필드 이름 설명 가시성 작업 입력 필드를 최종 사용자에게 표시할지 숨길지 여부를 지정합니다. 가시성 필드는 사용자 정의로 설정할 수도 있으며 데이터는 사용자로부터 캡처되지만 쿼리 매개 변수 또는 페이로드 필드로 사용되지 않습니다. 예: JIRA 봇을 사용하는 경우 아래와 같이 @mention 태그를 사용하여 티켓에 의견을 게시합니다. “@Mike, 이 문제를 살펴보세요” ‘의견 게시’를 위한 JIRA API는 다음과 같이 하나의 쿼리 필드와 하나의 페이로드 필드가 필요합니다.
- 발급 ID
- 의견
가시성 필드를 사용자 정의로 설정하면 페이로드 필드 또는 쿼리 필드로 사용하지 않고
comment
필드 값에 추가할 데이터를 가져오기 위해 JIRA API를 사용하여@Mike
로 언급된 사용자의 사용자 정보를 캡처할 수 있습니다. 기본 가시성 필드 설정은 Visible입니다.필수 최종 사용자가 이 설정을 정의하여 작업 설정 구성을 저장하려는 경우 선택합니다. 키 전치 해제 Kore.ai의 키 전치를 비활성화하려면 선택하세요. 기본적으로 Kore.ai는 키/값 쌍을 전치합니다. 예: Kore.ai는 “parameter”:”value”를 “parameter:{value:”actualValue”}로 전치합니다. 선택되면 키는 전치되지 않습니다. 세션에서 가져오기 이 필드의 사용자 입력값을 세션 변수로 저장하려면 선택합니다. 선택되면, 세션의 필드 값 필드가 표시됩니다. 기본 변수를 선택하거나 새 세션 변수 추가를 선택하여 새 변수를 정의합니다. 새 세션 변수를 생성하려면, 변수의 범위를 선택하고 변수를 저장할 키를 정의해야 합니다. 범위 필드에서 다음 중 하나를 선택합니다.
- EnterpriseContext – 엔터프라이즈 모든 사용자가 사용할 수 있는 키/값 쌍을 정의합니다.
- BotContext – 봇의 모든 사용자가 사용할 수 있는 키/값 쌍을 정의합니다.
- UserSession – 엔터프라이즈 내 모든 봇 사용자를 위한 키/값 쌍을 정의합니다.
- BotUserSession – 사용자 입력을 기반으로 봇이 사용 가능한 키/값 쌍을 정의합니다.
- 추가 및 계속을 클릭하여 작업 요청의 매개변수를 저장하고 다른 매개변수를 추가하거나, 추가 및 종료를 클릭하여 작업 요청의 매개변수를 저장하고 대화 상자를 닫습니다. 봇 사용자가 입력을 제공해야 하는 순서대로 여러 매개변수를 구성해야 합니다. 매개변수를 이동하려면 및 아이콘을 사용합니다.
이니셜라이저 정의하기
작업을 실행하려면, Kore.ai 세션별 변수를 사용하여 작업을 실행하기 전에 세션에 값을 입력하거나 가져와야 할 수 있습니다. 자세한 내용은, 작업에서 세션 변수 및 컨텍스트 변수 사용하기를 참조하세요. 일부 웹 서비스는 API 요청을 실행하기 전에 실행된 코드, 세션 변수 또는 사용자 컨텍스트 세부 정보 수정이 필요합니다. 예: 웹 서비스는 2단계 사용자 권한 부여가 필요할 수 있습니다. 첫 번째 단계는 사용자 인증이며 두 번째 단계는 파트너 인증입니다. 이 두 단계를 모두 검증한 후, 액세스 토큰이 부여되며 해당 웹 서비스에 대한 후속 API 호출 헤더에 사용됩니다. 이니셜라이저를 사용하여, 파트너 권한 부여를 완료하고 사용자 인증에서 액세스 토큰을 검색할 수 있습니다. 액세스 토큰은 사용자 정의 세션 변수로 저장할 수 있고 후속 API 호출을 위한 헤더로 설정할 수 있습니다.
작업 이니셜라이저 정의
작업 이니셜라이저를 설정하려면, 이니셜라이저 탭을 클릭하세요. 필요한 코드를 작성할 수 있는 JavaScript 편집기가 열립니다. JavaScript 편집기에서, 다음과 같이 키 및 범위를 정의합니다.
- EnterpriseContext – 엔터프라이즈 내 모든 봇과 사용자가 사용할 수 있는 키-값 쌍입니다. 예: GitHub 봇의 경우 사용자는 하나 이상의 엔터프라이즈 저장소에 액세스해야 합니다. 이니셜라이저에서, 다음 JavaScript 코드를 사용하여 저장소 데이터를 Gitrepository(엔터프라이즈 컨텍스트)로 유지할 수 있습니다.
var userRepository = { "title": _labels_[repository], "value": repository }; EnterpriseContext.put('Gitrepository', userRepository, 200000);
- BotContext – 특정 봇의 모든 사용자가 사용할 수 있는 키-값 쌍입니다. 예: 사용자의 위치에 따라 세션에서 금융 거래를 위한 기본 통화를 설정할 수 있습니다. 이니셜라이저에서 다음 JavaScript 코드를 사용하여 기본 통화 데이터를 currency(봇 컨텍스트)로 유지할 수 있습니다.
var defaultCurrency = { TODO Custom JavaScript for location-based currency } BotContext.put('currency', defaultCurrency, 200000);
- UserContext – 사용자의 모든 봇이 사용할 수 있는 키-값 쌍입니다. 이 키는 읽기 전용이며 시스템에서 다음과 같은 사용자 데이터로 제공됩니다.
- _id – Kore.ai userId입니다.
- emailId – userId에 연결된 이메일 주소입니다.
- lastName – 사용자의 성입니다.
- firstName – 사용자의 이름입니다.
- profImage – 사용자의 이미지 또는 아바타 파일 이름입니다.
- profColour – 사용자의 계정 색상입니다.
- activationStatus – 사용자의 계정 상태입니다.
- 직함 – 정의된 경우 사용자의 직함입니다.
- orgId – 정의된 경우 사용자 계정의 조직 ID입니다.
- UserSession – 엔터프라이즈 내 모든 봇의 특정 사용자가 사용할 수 있는 키-값 쌍을 정의합니다. 예: 상거래, 운송 및 가정 배달 서비스를 위한 사용자 집 주소와 같이 사용자 위치를 저장하여 모든 봇이 사용할 수 있도록 해야 합니다. 이니셜라이저에서, 다음 JavaScript 코드를 사용하여 기본 위치 데이터를 HomeLocation (사용자 세션)으로 유지할 수 있습니다.
var location = { "title": labels[location], "value": { "latitude": location.latitude, "longitude": request.location.longitude } }; UserSession.put('HomeLocation', location, '20000');
- BotUserSession – 같은 특정 사용자의 입력을 기반으로 특정 봇이 사용 가능한 키-값 쌍을 정의합니다. 예: 하나 이상의 봇 작업에 대해 사용자 위치를 유지해야 합니다. 여행 봇의 경우 같은 집 주소와 목적지 주소를 기준으로 항공편과 호텔을 예약할 수 있습니다. 이니셜라이저에서 다음 JavaScript 코드를 사용하여 기본 집 및 목적지 데이터를 HomeLocation (봇 사용자 세션) 및 DestinationLocation (봇 사용자 세션)으로 유지할 수 있습니다.
var homelocation = { "title": labels[request.sourceLocation], "value": { "latitude": request.sourceLocation.latitude, "longitude": request.sourceLocation.longitude } }; BotUserSession.put('HomeLocation', homelocation, '20000'); var destlocation = { "title": labels[request.destLocation], "value": { "latitude": request.destLocation.latitude, "longitude": request.destLocation.longitude } }; BotUserSession.put('DestinationLocation', destlocation, '20000’);
GET 및 PUT 구문
다음 코드 예시에서는 각 컨텍스트 유형에 따라 키-값 쌍을 GET 또는 PUT하는 구문을 보여줍니다.
"EnterpriseContext" : { "get" : function(key){...},//get the specified key "put" : function(key, value, ttl){...} //put the value at the key for the specified ttl, ttl is in minutes }, "BotContext" : { "get" : function(key){...},//get the specified key "put" : function(key, value, ttl){...} //put the value at the key for the specified ttl, ttl is in minutes }, "UserContext" : { "get" : function(key){...},//get the specified key }, "UserSession" : { "get" : function(key){...},//get the specified key "put" : function(key, value, ttl){...} //put the value at the key for the specified ttl, ttl is in minutes }, "BotUserSession" : { "get" : function(key){...},//get the specified key "put" : function(key, value, ttl){...} //put the value at the key for the specified ttl, ttl is in minutes }
예:
BotContext.put("topicSessionVariable","music",2000); UserSession.put("firstName","Mary",20000); UserContext.get("firstName");
예외 구문
인증 실패와 같은 작업 설정 전에 오류를 캡처하도록 사용자 정의 오류 메시지를 정의할 수도 있습니다. 예외가 캡처된 경우 작업 설정이 중지됩니다. 다음 구문을 사용하여 예외를 발생시킵니다.
{ "exceptions": { "message": " Error Message" } }
예,
var ex ={}; var exceptions={}; exceptions.message ='You can not proceed further with out valid permissions'; ex.exceptions = exceptions; print(JSON.stringify(ex)); //print is mandatory.
이니셜라이저 섹션에서는, 세션 키 또는 기타 세션 값을 설정할 수 있지만, 값을 설정하거나 액세스할 수는 없습니다. 예:
var name = UserContext.get("firstName")+UserContext.get("lastName"); UserSession.put("fullName") = name;
앞의 코드 예시에서는, 작업의 고급 설정 섹션에서 세션에서 가져오기 필드로 정의된 작업 매개변수를 사용하여 세션에 값을 입력합니다. 키는 사용자 정의된 UserSession
컨텍스트 변수에 대해 fullName
으로 정의됩니다.
작업 이니셜라이저 예시
다음 코드는 API 요청에서 변수를 미리 채우는 사용자 ID 및 이메일 데이터를 얻기 위한 작업 이니셜라이저의 예입니다.
var x = UserContext.get("identities"); var isEmailFound = false; for (var i = 0; i < x.length; i++) { if (x[i].type === "mapped") { var identity = x[i].val var arr = identity.split("/"); var pattern = /^cs/i; var result = arr[0].match(pattern); if (result) { isEmailFound = true; UserSession.put("rtmEmail", arr[1], '20000'); } } } if (!isEmailFound) { for (var j = 0; j < x.length; j++) { if (x[j].type === "email") { UserSession.put("rtmEmail", x[j].val, '20000'); } } }
요청 체인 정의하기
API 요청 탭의 요청 섹션에서, 전처리기, API 요청, 후처리기로 구성된 API 요청 체인을 정의할 수 있습니다. 처리기는 선택이지만, API 요청은 하나 이상 필요합니다.
API 요청
모든 작업에 대해 작업을 시작하려면 웹 서비스 호출을 위한 API 요청을 정의해야 합니다. 각 작업을 위해 최소한 하나의 API 요청은 필요합니다. 각 API 요청에 대해 웹 서비스에서 데이터 페이로드 전달을 시작하려면 하나 이상의 요청 URL 및 경로를 추가해야 합니다.
API 요청 설정하기
- API 요청 탭에서, 요청 탭을 확장한 다음 API 추가를 클릭합니다.
- 다음 절차에 설명된 대로 API 추가 대화 상자에 필드 값을 지정합니다.
- 이름 필드에서, API 요청의 이름을 입력합니다. 예: 내 API 요청.
- 메소드 드롭다운 목록에서, 작업에 사용되는 HTTP 메소드를 입력합니다. 다음 중 하나입니다.
- POST– HTML 양식을 사용하여 고객 정보, 파일 업로드 등 서버에 데이터를 전송하는 데 사용됩니다.
- PUT– 대상 리소스의 내용을 전송된 내용으로 대체합니다.
- PATCH – 기존 대상 리소스의 내용에 전송된 내용을 추가합니다.
- DELETE – 기존 대상 리소스의 내용을 삭제합니다.
- GET – 기존 대상 리소스의 내용을 반환합니다.
- URL 필드에서 프로세스에 대한 봇 작업 응답의 URL을 지정합니다. 예: http://koremessenger.com/postURL. 다음 예시와 같이 URL에서 세션 변수를 사용할 수도 있습니다.
https://mySite.crm.ondemand.com/sap/c4c/odata/v1/c4codata/ServiceRequestCollection?$filter=ID eq '{id}' and ReporterEmail eq '{userEmail}'&$expand=ServiceRequestHistoricalVersion,ServiceRequestDescription
참고 사항: 일부 URL에서는 종료 및 시작 매개변수에 독자적인 Kore.ai 매개변수 값을 사용해야 합니다. Kore.ai 매개변수 값에 대한 자세한 내용은, 봇 추가하기에서 봇별 문서를 참조하세요. - 커넥터를 사용한 액세스 필드에서, Kore.ai 커넥터 에이전트를 사용하여 Kore.ai 봇의 액세스를 활성화하려면 예를 선택합니다. 이 옵션은 Kore.ai 커넥터 에이전트가 엔터프라이즈 온프레미스 네트워크에서 설정되어 사용함으로 설정한 경우에만 표시됩니다. 자세한 내용은, Kore.ai 커넥터 사용하기를 참조하세요.
- 헤더 탭의 콘텐츠 유형 필드에서, 샘플 응답 데이터에 대해 지원되는 다음 데이터 유형 중 하나를 선택합니다.
- JSON – JavaScript Object Notation은 사람이 읽을 수 있는 텍스트를 사용하여 데이터 개체를 속성-값 쌍으로 전송하는 개방형 표준 포맷입니다. JSON을 사용하여 Kore.ai 서버와 봇 웹 애플리케이션 간에 데이터를 전송할 수 있습니다.
- RSS – Rich Site Summary 또는 Really Simple Syndication은 블로그 항목, 뉴스 헤드라인, 오디오 및 동영상과 같이 자주 업데이트되는 정보를 게시하는 데 사용되는 표준화된 형식 집합입니다.
- XML – Extensible Markup Language는 사람이 읽을 수 있고 기계가 읽을 수 있는 형식으로 문서를 인코딩하기 위한 규칙 집합을 정의한 마크업 언어입니다. 웹 서비스는 종종 XML 스키마를 사용하여 XML 데이터를 처리합니다.
- URL 인코딩된 JSON – 예약된 문자에 대해 JSON 인코딩을 사용한 URL입니다.
- CSV – 쉼표로 구분된 값 목록입니다.
- 텍스트 – 텍스트 기반 키-값 쌍입니다.
- Twitter 인코딩된 JSON – 예약된 문자에 대해 JSON 인코딩을 사용한 Twitter의 URL입니다.
- Multipart/Form-data – 사용자가 양식에서 파일을 업로드할 수 있도록 하는 경우 HTTP POST 요청 메소드를 통해 파일을 전송하는 인코딩 유형입니다.
- Multipart/Related – 같은 정보를 다른 본문 파트에 다른 형태로 표시할 때 사용됩니다. 본문 파트는 복잡도가 높은 순으로 정렬됩니다.
- Oracle ADF – Oracle Application Development Framework용 입니다.
- 권한 부여 헤더 섹션에서 키를 선택하거나 선택 취소하여 다음 그림과 같이 헤더의 키를 사용하거나 비활성화합니다.
- 다음 그림과 같이 매개변수 탭에서 헤더에 포함할 권한 부여 매개변수 또는 매개변수를 선택하거나 선택 취소합니다.
- 저장을 클릭하여 저장하고 API 요청 설정을 닫습니다.
처리기
처리기를 사용하고 자바스크립트를 사용하여 웹 서비스에 API 요청 전, 요청 중, 요청 후에 사용자 세션에서 수집된 데이터를 수정할 수 있습니다. 처리기가 정의되고 API 요청 전 순차적으로 배치된 경우 이 처리기는 전처리기입니다. 전처리기를 사용하면 API 요청이 수행되기 전 세션 변수에서 입력 매개변수와 값을 관리할 수 있습니다. 처리기가 API 요청 후 순차적으로 배치된 경우 이 처리기는 후처리기입니다. 후처리기를 사용하여 API 요청에서 페이로드 응답 키에 액세스할 수 있습니다. 키에 액세스하려면, 다음 후처리기 유형 중 하나를 사용하세요.
- 해결: 두 번째 요청에 대한 입력으로 하나의 페이로드 응답의 결과를 사용합니다.
- 확장 – 페이로드에서 데이터 배열을 분리합니다.
- 추출 – 여러 개체가 있는 페이로드의 특정 개체의 경로를 지정합니다.
- 할당 – 페이로드 응답의 변수 이름을 지정합니다.
전처리기
세션 변수 및 매개 변수를 사용하여 API 요청을 실행하기 전에 전처리기를 사용해 요청 매개 변수를 관리할 수 있습니다. 전처리기를 정의할 때, 처리 유형을 사용자 정의로 설정한 다음 표시되는 JavaScript 편집기에 코드를 입력해야 합니다. 전처리기는 사용자 정의 유형만 될 수 있습니다.
전처리기 추가하기
- API 요청 페이지에서, 요청 탭을 확장한 다음 처리기 추가를 클릭합니다.
- 이름 필드에 처리기의 이름을 입력합니다.
- 처리 유형 드롭다운 목록에서, 전처리기에 대해 사용자 정의를 선택합니다.
- 다음 구문을 사용하여 필요에 따라 요청 매개 변수를 수정하기 위한 코드를 추가합니다.
{ "fields": { "payloadFields": { // to set value to a payload field "key1": "value1", // Payload fields are not applicable for Alert tasks. "key2": "value2".... }, "headerFields": { // to set value to a header field "key1": "value1", "key2": "value2".... }, "pathFields": { // to set value to a path field or query field. "key1": "value1", "key2": "value2".... } } }
예: 다음 코드 조각을 사용하여 API 개체의 경로 필드 또는 쿼리 필드를 설정할 수 있습니다.
var fields= {}; var pathFields = {}; pathFields.fullName = UserContext.get("firstName")+UserContext.get("lastName") fields.pathFields = pathFields; var finalObject = {}; finalObject.fields = fields; print(JSON.stringify(finalObject));
이전 코드에서,
firstName
및lastName
이 세션 변수로John
및Smith
로 각각 저장된 경우 전처리기의 JSON 응답 페이로드는 다음과 같습니다.{ fields: { "pathFields": { "key": "fullName", "value": "John Smith" } } }
다음 전처리기 예시에서는, 실제 API 요청 호출 전에 변수를 세션 변수로 설정합니다.
var fields = {}; var pathFields = {}; var UserEmailID = UserSession.get("rtmEmail"); pathFields.userEmail = UserEmailID; fields.pathFields = pathFields; var finalObject = {}; finalObject.fields = fields; print(JSON.stringify(finalObject));
- 저장을 클릭하여 저장하고 처리기 추가 대화 상자를 닫습니다.
후처리기 추가하기
Kore.ai 후처리기를 사용하여 웹 서비스에서 원하는 데이터 페이로드를 가져오려면 하나 이상의 API 요청이 필요합니다.
사용자 정의 후처리기 정의
사용자 정의 후처리기를 생성하려는 경우, 다음 구문을 사용하여 이전 API 요청의 응답 키에 액세스할 수 있습니다”
payload[0].{ key }
JSON 구문
{ "payload": { "key1" : "value1", "key2" : "value2" } }
예
var final = {}; var data = payload[0]; //Accessing the response of the previous API object data.title[0] = 'New value for key here'; final.payload = data; // Updating the response of the API object print(JSON.stringify(final)); // This step is mandatory
사용자 정의 처리기의 경우, 이전 코드와 같이 최종 응답을 출력해야 합니다. 그렇지 않으면 빈 응답이 반환됩니다. 다음 구문을 사용합니다.
print(JSON.stringify( <<object>> ));
표준 후처리기 설정
표준 후처리기를 추가하려면 다음 단계를 따릅니다.
- API 요청 탭에서 요청 탭을 확장한 다음 처리기 추가를 클릭합니다.
- 또한 Kore.ai는 후처리기를 위한 사용자 정의 코드를 생성하는 대신 사용할 수 있는 일련의 표준 후처리기를 제공합니다. 처리 유형 필드에서, 다음 네 가지 표준 처리기 유형 중 하나를 선택합니다.
- 해결: 두 번째 요청에 대한 입력으로 하나의 페이로드 응답의 결과를 사용합니다. 예: 처리기 추가를 클릭하고 처리기의 이름을 입력하고 처리 유형을 resolve로 설정하고 키를 변수의 이름으로 설정한 다음 첫 번째 API 요청의 변수를 사용하여 Post URL을 정의합니다. 예: https://app.asana.com/api/1.0/projects/{project_id}는 페이로드 응답에서 다음과 같이 id 필드를 반환합니다.
... "id":80468818418144, <br/> "created_at":"2016-01-14T05:34:35.848Z", "modified_at":"2016-01-20T04:29:52.505Z", "owner":{ "id":73114591129714, "name":"jaganmohan.evuri" }, ...
그 이후 다음과 같이 변수 입력으로 사용됩니다 Post URL: https://app.asana.com/api/1.0/projects/{id}/tasks?opt_fields=completed,modified_at 페이로드 응답에서 예상되는 HTML 콘텐츠 유형 및 HTML 요청 메소드를 지정해야 합니다. 자세한 내용은, 작업에서 세션 변수 및 컨텍스트 변수 사용하기를 참조하세요.
- 확장: 분리해야 하는 데이터 배열이 포함된 페이로드입니다. 예: 처리기 추가를 클릭하고 처리기의 이름을 입력하고 키 필드를 데이터로 설정하고 처리 유형을 spread로 설정하여 다음 코드 예제에서
data
요소의 내용을 캡처하여 배열의 각 항목을 추출합니다.{ "attribution": null, "tags": [], "type": "image", "location": null, "comments": { "count": 51, "data": [{ "created_time": "1453900980", "text": "43rd", "from": { "username": "kore_hyd", "profile_picture": "https://scontent.cdninstagram.com/t51.2885-19/11906329_960233084022564_1448528159_a.jpg", "id": "2056218675", "full_name": "Kore.ai Hyd" }, "id": "1171728804843572377" }, { "created_time": "1453901222", "text": "44th", "from": { "username": "kore_hyd", "profile_picture": "https://scontent.cdninstagram.com/t51.2885-19/11906329_960233084022564_1448528159_a.jpg", "id": "2056218675", "full_name": "Kore.ai Hyd" }, "id": "1171730841379491107" }, { "created_time": "1453901997", "text": "45th", "from": { "username": "kore_hyd", "profile_picture": "https://scontent.cdninstagram.com/t51.2885-19/11906329_960233084022564_1448528159_a.jpg", "id": "2056218675", "full_name": "Kore.ai Hyd" }, "id": "1171737339782450909" }, { "created_time": "1453902304", "text": "46th and 47th", "from": { "username": "kore_hyd", "profile_picture": "https://scontent.cdninstagram.com/t51.2885-19/11906329_960233084022564_1448528159_a.jpg", "id": "2056218675", "full_name": "Kore.ai Hyd" }, "id": "1171739915923967873" }, { "created_time": "1453902638", "text": "48th", "from": { "username": "kore_hyd", "profile_picture": "https://scontent.cdninstagram.com/t51.2885-19/11906329_960233084022564_1448528159_a.jpg", "id": "2056218675", "full_name": "Kore.ai Hyd" }, "id": "1171742713994497101" }, { "created_time": "1453964684", "text": "49th", "from": { "username": "venkataphani.ailavarapu", "profile_picture": "https://scontent.cdninstagram.com/t51.2885-19/11906329_960233084022564_1448528159_a.jpg", "id": "2679234818", "full_name": "Phani" }, "id": "1172263199715314941" }, { "created_time": "1453964710", "text": "50th", "from": { "username": "kore_hyd", "profile_picture": "https://scontent.cdninstagram.com/t51.2885-19/11906329_960233084022564_1448528159_a.jpg", "id": "2056218675", "full_name": "Kore.ai Hyd" }, "id": "1172263415747136776" }, { "created_time": "1453964717", "text": "51st", "from": { "username": "kore_hyd", "profile_picture": "https://scontent.cdninstagram.com/t51.2885-19/11906329_960233084022564_1448528159_a.jpg", "id": "2056218675", "full_name": "Kore.ai Hyd" }, "id": "1172263474056350986" }] ...
- 추출: 여러 개체가 포함된 페이로드의 경우, 특정 개체에 대한 경로를 지정할 수 있습니다. 예: 처리기 추가를 클릭하고, 처리기의 이름을 입력하고, 키 필드를
data
로 설정한 다음, 처리 유형을 extract로 설정하여 다음 페이로드 응답에서 개체 데이터를 사용합니다.{ "user": { "full_name": "Kore.ai Hyd", "id": "2056218675", "profile_picture": "https://instagramimages-a.akamaihd.net/profiles/anonymousUser.jpg", "username": "kore_hyd" }, ... }, "likes": { "data": [{ "full_name": "kstream002", "id": "2100724876", "profile_picture": "https://instagramimages-a.akamaihd.net/profiles/anonymousUser.jpg", "username": "kstream002" } }, ... }
- 할당: 할당 처리기를 사용하여, 필요한 경우 페이로드 응답의 변수 이름을 지정할 수 있습니다. 예: 페이로드에 페이로드 응답 데이터의 키가 포함되지 않은 경우. 예: 처리 유형을 assign으로 설정한 다음, 출력 변수 필드에서 세 개의 개체 배열로 구성된 다음 페이로드의 출력 변수를 정의할 수 있습니다.
[ { "Cost": "$0.00", "Desc1": "$150 bonus after $500 of purchases in the first 3 months from account opening. ", "Desc2": "Earn unlimited cash back Earn unlimited 1.5% cash back on every purchase – it's automatic. Redeem for cash back – any amount, any time. ", "Keywords": "weekend dining,online,groceries,fuel,rewards,rebate,365,allaround", "OfferName": "Freedom Unlimited", "OfferType": "CreditCard", "Status": "1", "imageURL": "http://www.psdgraphics.com/file/credit-card.jpg", "id": "5b5195e264bbd800" }, { "Cost": "$95.00", "Desc1": "Pay 0 balance transfer fee when you transfer a balance during the first 60 days.", "Desc2": "Jumpstart your financial fitness Get an introductory fee for balance transfers, save on interest†, and get your free monthly credit score.", "Keywords": "privileges,rebate,health,wellness,great eastern,insurance,policy,installments,split,cashflo", "OfferName": "Premium Plus", "OfferType": "CreditCard", "Status": "1", "imageURL": "http://i.imgur.com/rMOXYql.jpg", "id": "5caf2155873f89c8" }, { "Cost": "$10.00", "Desc1": "Pay 0 balance transfer fee when you transfer a balance during the first 60 days.", "Desc2": "Jumpstart your financial fitness Get an introductory fee for balance transfers, save on interest†, and get your free monthly credit score.", "Keywords": "privileges,rebate,health,wellness,great eastern,insurance,policy,installments,split,cashflo", "OfferName": "Frequent Flyer", "OfferType": "CreditCard", "Status": "1", "imageURL": "http://www.moneychoice.org/wp-content/uploads/2016/01/credit-card-calculator-image.png.jpeg", "id": "c0b05bc3062658ee" } ]
출력 변수 필드에서, 배열을 나타낼 변수를
offers
다음으로 지정합니다. UX 미리 보기 기능을 사용한 경우, Kore.ai의 응답은 다음과 같습니다.{ "response": { "offers": [ { "Cost": "$0.00", "Desc1": "$150 bonus after $500 of purchases in the first 3 months from account opening. ", "Desc2": "Earn unlimited cash back Earn unlimited 1.5% cash back on every purchase – it's automatic. Redeem for cash back – any amount, any time. ", "Keywords": "weekend dining,online,groceries,fuel,rewards,rebate,365,allaround", "OfferName": "Freedom Unlimited", "OfferType": "CreditCard", "Status": "1", "imageURL": "http://www.psdgraphics.com/file/credit-card.jpg", "id": "5b5195e264bbd800" }, { "Cost": "$95.00", "Desc1": "Pay 0 balance transfer fee when you transfer a balance during the first 60 days.", "Desc2": "Jumpstart your financial fitness Get an introductory fee for balance transfers, save on interest†, and get your free monthly credit score.", "Keywords": "privileges,rebate,health,wellness,great eastern,insurance,policy,installments,split,cashflo", "OfferName": "Premium Plus", "OfferType": "CreditCard", "Status": "1", "imageURL": "http://vignette3.wikia.nocookie.net/objectmayhem/images/5/52/Credit_card.png/revision/latest?cb=20130629150408", "id": "5caf2155873f89c8" } ] } }
출력 변수를
offers
로 설정하면, 봇 빌더에서 변수를 다음과 같은 작업 응답 개체에서response.offers
로 사용할 수 있습니다.print(JSON.stringify(response)); var data = response.offers for (i = 0; i < data.length; i++) { print('<a href="' + data[i].imageURL + '" target="_blank">' + data[i].OfferName + '</a><br>'); print(data[i].Desc1) print('<br>'); print('<br>'); print('Cost: ' + data[i].Cost) print('<br>'); if (i < data.length - 1) { print('<br>'); print('<br>'); } }
- 해결: 두 번째 요청에 대한 입력으로 하나의 페이로드 응답의 결과를 사용합니다. 예: 처리기 추가를 클릭하고 처리기의 이름을 입력하고 처리 유형을 resolve로 설정하고 키를 변수의 이름으로 설정한 다음 첫 번째 API 요청의 변수를 사용하여 Post URL을 정의합니다. 예: https://app.asana.com/api/1.0/projects/{project_id}는 페이로드 응답에서 다음과 같이 id 필드를 반환합니다.
- 추가를 클릭하여 API 요청을 저장한 다음 다른 요청을 생성하거나, 추가 및 종료를 클릭하여 API 요청을 저장하고 대화 상자를 닫습니다.
여러 API 요청의 경우, 전체 데이터 응답을 얻는 데 필요한 요청을 순차적으로 순서를 정렬해야 합니다. 예: 작업 영역 목록, 프로젝트 목록, 마지막으로 사용자 목록을 요청해야 합니다. 위로 이동 및 아래로 이동 아이콘을 사용하여 API 요청을 재정렬합니다.
참고 사항: API 요청을 삭제할 때 확인 대화 상자가 표시되지 않습니다. 계속 또는 저장을 클릭한 경우 삭제 조치는 영구적이므로 취소할 수 없습니다.
응답 샘플 추가하기
응답 샘플 섹션에서, 작업 페이로드에서 수신할 것으로 예상되는 키-값 쌍의 예를 입력하거나 붙여넣을 수 있습니다. 응답 샘플을 정의할 때, 응답 샘플 섹션에 정의된 키는 출력 데이터를 처리하기 위한 드롭다운 선택 항목으로 사용할 수 있습니다.
샘플 응답 추가하기
웹 사이트 링크 콘텐츠 미리 보기
일부 웹 서비스는 페이로드 응답의 일부로 미디어를 미리 볼 수 있는 링크를 보냅니다. 이 섹션에서는, 미리 보기 링크를 활성화 또는 비활성화하고 페이로드에 링크 경로를 정의할 수 있습니다. 기본적으로, 웹 사이트 미리 보기 링크는 비활성화되어 있습니다. 다음 그림은 예를 선택할 때 게시물의 웹 사이트 링크 콘텐츠 미리 보기 섹션의 예입니다. 활성화된 경우에 페이로드에서 미리 보기 링크에 대한 경로를 정의합니다. 경로가 페이로드의 루트에 없다면 링크에 대한 경로(toPreview) 필드에서 정의합니다. 예: RSS 페이로드의 다음 코드 예시에서 미리 보기의 경로는 다음과 같습니다
... "item": [ { "title": "U.S. to Boost Refugee Intake by 30,000 by 2017", "guid": { "-isPermaLink": "false", "#text": "SB12418904751422433479504581245034032986752" }, "link": "http://www.wsj.com/articles/john-kerry-says-u-s-to-admit-30-000-more-refugees-in-next-2-years-1442768498?mod=fox_australian", ...
게시물에서 웹 사이트 링크 콘텐츠 미리 보기를 사용하도록 설정된 경우 다음과 같은 미리 보기 개체를 선택합니다.
- 미리 보기 제목 – 웹 사이트 콘텐츠의 제목을 표시합니다.
- 미리 보기 설명 – 웹 사이트 설명을 표시합니다.
- 미디어(동영상) 미리 보기 – 웹 사이트 콘텐츠에서 동영상 링크 표시를 사용합니다.
- 미디어(이미지) 미리 보기 – 웹 사이트 콘텐츠에서 이미지 링크 표시를 사용합니다.