Advanced 시나리오

Advanced 시나리오는 Basic 시나리오를 기반으로 여러 블록들을 활용하여 Skill을 생성하는 확장 시나리오입니다.

안내
다양한 Advanced 시나리오는 지속적으로 업데이트될 예정입니다.

두 개 이상의 REST API 조합

두 개 이상의 REST API들을 조합하는 Advanced 시나리오는 카페 정보와 간식 정보를 가지고 있는 단일 REST API들의 조합으로 Skill을 생성하는 확장 시나리오입니다. Basic 시나리오와 유사한 작업 순서로 진행하지만, 동일한 입력 데이터를 다수의 블록으로 전달하는 SCATTER 블록과 다수 블록들의 출력 데이터를 병합하는 AGGREGATE 블록이 추가됩니다.

그림두 개 이상의 REST API 조합

1. 신규 Skill을 생성합니다.

2. START 블록을 추가합니다.

3. SCATTER 블록을 추가합니다.

   • SCATTER 블록은 동일한 입력 데이터를 다수의 블록으로 전달합니다.

4. REST API CALL 블록을 추가합니다.

5. AGGREGATE 블록을 추가합니다.

   • AGGREGATE는 다수 블록들의 출력 데이터를 병합합니다.

6. BOT RESPONSE 블록을 추가합니다.

7. 생성한 Skill을 배포합니다.

8. 배포 결과를 확인합니다.

안내
블록별 자세한 설명은 Skill Builder 블록 상세 설명 문서를 참고하시기 바랍니다.

신규 Skill 생성하기

Skill Builder에서 신규 Skill을 생성하는 순서는 다음과 같습니다.

1. [Builder 사이트] Skill Builder 메인 화면에서 [+] 버튼을 클릭합니다.

   그림Skill 추가

2. API 생성 팝업창에서 생성할 Skill의 이름과 설명을 입력하고, [생성하기] 버튼을 클릭합니다.

   안내
   생성한 Skill은 메인 화면의 내 스킬 > MY > 편집용 스킬 영역에 추가됩니다.

   그림신규 Skill 생성

   표API 생성 팝업창

   항목	설명
   이름	생성할 Skill(API)의 이름
   설명	생성할 Skill(API)의 간략한 설명

START 블록 추가하기

생성한 Skill의 캔버스에 START 블록을 추가하는 순서는 다음과 같습니다.

1. [Builder 사이트] Skill Builder 메인 화면의 편집용 스킬 영역에서 앞서 추가한 Skill을 클릭합니다.

   안내
   선택된 Skill이 없으면 [저장] 버튼이 비활성화되어 작업을 저장할 수 없습니다.

   그림Skill 선택

2. START(REST) 블록을 캔버스에 드래그 앤 드롭하여 추가합니다.

   그림START 블록 추가

3. 생성한 START 블록을 클릭하고, 프로퍼티 영역의 일반 > 상세 정보에 필요한 내용을 작성합니다.

   그림상세 정보 설정

   표일반 > 상세 정보

   항목	설명
   이름	해당 블록의 이름
   별명	해당 블록의 별명(자동 생성)
   API 요청 방식	생성할 Skill(API)의 요청 방식 챗봇 관리자센터 스펙에 따라 챗봇용 Skill을 생성할 때는 반드시 POST 선택 - POST(기본값): 데이터 생성 - GET: 데이터 조회 - PUT: 데이터 수정 - DELETE: 데이터 삭제
   URI 정보	생성할 Skill(API)의 URI - 사용자가 직접 지정해야 하며, 여기에 입력한 이름이 API의 호출 주소가 됨 ex) URI 정보에 cafeInfo를 입력 시 API 호출 주소: http://{Skill Builder 백엔드 서버 도메인 주소}/api/cafeInfo

   주의
   API 요청 방식에 따라 응답을 확인하는 방법은 달라집니다.

   • GET: 웹으로 응답 확인 가능
   • POST: 웹으로 응답 확인이 어려우며, 다른 툴을 사용하여 응답을 확인해야 함

4. 만약 다음 블록에 전달할 데이터를 추가해야 할 경우, 프로퍼티 영역의 입력 탭에서 [사용자 입력] 버튼을 클릭합니다.

   안내
   Input 설정은 START 블록에서 다음 블록에 전달할 파라미터를 설정하는 작업으로, 챗봇 관리자센터에 연동하는 챗봇용 Skill을 생성하기 위해서는 Input 설정을 반드시 진행해야 합니다.

   • Skill을 호출할 때 전달받는 Request 파라미터를 Input 설정 팝업창에서 추가해야 다음 블록에서 해당 파라미터 값을 사용할 수 있습니다.

   그림사용자 입력

5. Input 설정 팝업창에서 입력 데이터를 추가합니다.

   • 직접 추가: 데이터 설정 영역에서 데이터 명을 입력합니다.
   • 데이터 템플릿에서 추가: 데이터 템플릿 영역의 항목을 입력 데이터에 드래그 앤 드롭합니다.

   그림Input 설정

   표Input 설정 화면

   항목	설명
   데이터 템플릿	기존에 미리 설정해 놓은 데이터 형식 - 데이터 템플릿 추가, 수정, 삭제는 데이터 템플릿 설정하기 문서 참고
   입력 데이터	직접 입력하거나 데이터 템플릿에서 가져온 데이터로 실제 적용되는 데이터
   데이터 설정	입력 데이터를 직접 입력하거나, 입력 데이터 우측 상단 아이콘을 클릭하여 입력 데이터를 JSON 파일 업로드로 설정 가능
   설정하기	자주 사용하는 값을 데이터 템플릿으로 등록 - 데이터 템플릿 설정하기 문서 참고
   적용하기	클릭 시 입력 데이터에 설정된 데이터들이 해당 블록의 입력에 적용

6. 적용하기를 클릭해 Input 설정을 완료합니다.

   그림Input 설정 적용

데이터 템플릿 설정하기

데이터 템플릿 설정은 데이터 템플릿을 추가, 수정, 삭제하는 작업입니다.

1. Input 설정 또는 Out 설정 팝업창에서 설정하기 버튼을 클릭합니다.

   그림Input 설정

2. 데이터 템플릿 설정 팝업창에서 템플릿으로 설정할 데이터를 입력하고 적용을 클릭합니다.

   • JSON 파일로 등록을 클릭하면, JSON 파일을 업로드하여 데이터를 설정할 수 있습니다.

   그림데이터 템플릿 설정

3. Input 설정 또는 Out 설정 팝업창에서 데이터 템플릿 영역에 추가된 데이터 템플릿이 표시되는지 확인합니다.

   그림데이터 템플릿 확인

SCATTER 블록 추가하기

캔버스에 START 블록으로부터 전달받은 입력 데이터를 다수의 블록으로 전달하는 SCATTER 블록을 추가하는 순서는 다음과 같습니다.

1. Control 목록의 SCATTER 블록을 캔버스에 드래그 앤 드롭하여 추가합니다.

   그림SCATTER 블록 추가

2. START 블록을 클릭하고, [화살표] 아이콘을 통해 SCATTER 블록과 연결합니다.

   그림SCATTER 블록 연결

3. 생성한 SCATTER 블록을 클릭하고, 프로퍼티 영역의 일반 > 옵션에서 필요한 작업을 수행합니다.

   그림옵션 설정

   표일반 > 옵션

   항목	설명
   타임아웃	타임아웃 옵션을 설정
   오류 발생 시 진행 중단	토글 버튼을 스위치하여 오류 발생 시 진행 중단 가능
   병렬 처리	토글 버튼을 스위치하여 병렬 처리 가능

안내
SCATTER 블록에 대한 자세한 설명은 Skill Builder 블록 상세 설명 문서를 참고하시기 바랍니다.

REST API CALL 블록 추가하기

캔버스에 기존에 개발된 REST API를 호출하는 복수의 REST API CALL 블록을 추가하는 순서는 다음과 같습니다.

1. Component 목록의 REST API CALL 블록을 필요한 개수만큼 캔버스에 드래그 앤 드롭하여 추가합니다.

   그림REST API CALL 블록 추가

2. SCATTER 블록을 클릭하고, [화살표] 아이콘을 통해 각각의 REST API CALL 블록과 연결합니다.

   그림REST API CALL 블록 연결

3. 생성한 각각의 REST API CALL 블록을 클릭하고, 프로퍼티 영역의 일반 > 상세 정보에 필요한 내용을 작성합니다.

   그림상세 정보 설정

   표일반 > 상세 정보

   항목	설명
   이름	해당 블록의 이름
   별명	해당 블록의 별명(자동 생성)
   API 요청 방식	기존 REST API의 요청 방식 - POST(기본값): 데이터 생성 - GET: 데이터 조회 - PUT: 데이터 수정 - DELETE: 데이터 삭제
   프록시	Spring Framework의 프록시 기능 사용 가능
   URI 정보	기존 REST API의 URI 정보 ex) GET: http://apibuilder-server.devel.kakao.com/skill/cafe

4. 헤더/바디 데이터 탭에서 테스트 요청을 위해 [요청하기] 버튼을 클릭합니다.

   그림테스트 요청

5. 요청 결과에서 테스트 요청 결과를 확인합니다.

   그림요청 결과

6. 입력/출력 탭에서 테스트 요청 결과를 바탕으로 출력 데이터가 자동으로 설정되었는지 확인합니다.

   그림입력/출력 탭

7. 만약 다음 블록에 전달할 데이터를 추가해야 할 경우, [사용자 입력] 버튼을 클릭합니다.

   그림사용자 입력

8. Out 설정 팝업창에서 반환 데이터를 추가합니다.

   • 직접 추가: 데이터 설정 영역에서 데이터 명을 입력합니다.
   • 데이터 템플릿에서 추가: 데이터 템플릿 영역의 항목을 반환 데이터에 드래그 앤 드롭합니다.

   그림Out 설정

   표Out 설정

   항목	설명
   데이터 템플릿	기존에 미리 설정해 놓은 데이터 형식 - 데이터 템플릿 추가, 수정, 삭제는 데이터 템플릿 설정하기 문서 참고
   반환 데이터	직접 입력하거나 데이터 템플릿에서 가져온 데이터로 실제 적용되는 데이터
   데이터 설정	반환 데이터를 직접 입력하거나, 반환 데이터 우측 상단 아이콘을 클릭하여 반환 데이터를 JSON 파일로 업로드하여 설정
   설정하기	자주 사용하는 값을 데이터 템플릿으로 등록 - 데이터 템플릿 설정하기 문서 참고
   적용하기	클릭 시 반환 데이터에 설정된 데이터들이 해당 블록의 입력에 적용

9. 적용하기 버튼을 클릭하여 Out 설정을 완료합니다.

   그림Out 설정 적용

AGGREGATE 블록 추가하기

캔버스에 다수 REST API CALL 블록의 출력 데이터를 병합하는 AGGREGATE 블록을 추가하는 순서는 다음과 같습니다.

1. control 목록의 AGGREGATE 블록을 캔버스에 드래그 앤 드롭하여 추가합니다.

   그림AGGREGATE 블록 추가

2. 각각의 REST API CALL 블록을 클릭하고, [화살표] 아이콘을 통해 AGGREGATE 블록과 연결합니다.

   그림AGGREGATE 블록 연결

3. 생성한 AGGREGATE 블록을 클릭하고, 프로퍼티 영역의 입력/출력 탭에서 입력 및 출력 데이터가 자동으로 생성되었는지 확인합니다.

   그림입력/출력 탭

안내
AGGREGATE 블록에 대한 자세한 설명은 Skill Builder 블록 상세 설명 문서를 참고하시기 바랍니다.

BOT RESPONSE 블록 추가하기

캔버스에 챗봇 전용 응답 말풍선을 작성하는 BOT RESPONSE 블록을 추가하는 순서는 다음과 같습니다.

1. Component 목록의 BOT RESPONSE 블록을 캔버스에 드래그 앤 드롭하여 추가합니다.

   그림BOT RESPONSE 블록 추가

2. AGGREGATE 블록을 클릭하고, [화살표] 아이콘을 통해 BOT RESPONSE 블록과 연결합니다.

   그림BOT RESPONSE 블록 연결

3. 프로퍼티 영역의 일반 탭에서 챗봇 응답 말풍선을 편집합니다.

   • 응답에 AGGREGATE 블록에서 받은 입력값을 사용하려면 중괄호({ })안에 해당 키 값을 입력합니다.
   • { 문자 입력 시 이전 블록(AGGREGATE)에서 넘겨받은 데이터에 대한 자동완성(Auto Complete)을 지원합니다.

   그림챗봇 응답 말풍선 편집

   그림자동완성(Auto Complete)

4. [저장] 버튼을 클릭해 현재까지의 작업 내용을 저장합니다.

   안내
   [저장] 버튼 옆의 펼치기 버튼 클릭 시, Skill 저장 옵션을 선택할 수 있습니다.

   그림Skill 저장

배포하기

블록 추가를 모두 완료한 이후 Skill을 배포하는 순서는 다음과 같습니다.

1. [배포] 버튼을 클릭합니다.

   그림Skill 배포

2. Phase 선택 팝업창에서 [+] 버튼을 클릭해 배포할 Phase를 선택하고, [배포하기] 버튼을 클릭합니다.

   안내
   배포 Phase는 다중 선택이 가능합니다.

   그림Phase 선택

배포 상태 확인하기

배포된 Skill의 상태를 확인하는 순서는 다음과 같습니다.

1. 편집용 스킬의 [펼치기] 아이콘을 클릭하고, Phase를 선택합니다.

   그림Phase 이동

2. 프로퍼티 영역의 히스토리 탭에서 생성한 Skill의 배포 상태를 확인합니다.

   • 신규 생성한 Skill(API)의 최종 URL 경로는 http://{Skill Builder 백엔드 서버 도메인 주소}/api/{START 블록 URI 명} 이며, 이때 {START 블록 URI 명}은 START 블록 추가 시 입력한 URI 명입니다.

   안내
   내부 시연용 백엔드 주소는 http://apibuilder-server.devel.kakao.com/api/{START 블록 URI 명}입니다.

   그림API 히스토리

안내
Skill Builder는 다수의 Skill을 한 번에 배포하는 멀티 배포 기능도 지원합니다. 자세한 설명은 멀티 배포 문서를 참고하시기 바랍니다.

결과 확인하기

Skill Builder에서 생성한 Skill은 REST API이므로, 다양한 플랫폼을 통해 Skill 생성 결과를 확인할 수 있습니다.

REST API 테스트 툴에서 확인하기

1. REST API 테스트 툴을 설치합니다.

   • 해당 가이드에서는 Postman을 기준으로 한 테스트 순서를 설명합니다.

2. START 블록에서 정의한 REST 메서드를 선택하고 URL을 호출합니다.

3. JSON 데이터 결괏값을 확인합니다.

   그림Postman에서 응답 결과 확인

챗봇 관리자센터에서 확인하기(챗봇 생성 시)

Skill 생성 시 마지막 단계에 BOT RESPONSE 블록을 사용했을 경우, 챗봇 관리자센터에서 블록(Intent)의 Skill을 설정하여 실제 카카오톡 채널에서 말풍선 응답 결과를 확인할 수 있습니다.

1. [Builder 사이트] 챗봇 관리자센터에서 스킬 메뉴를 클릭합니다.

   그림스킬 메뉴

2. [생성] 버튼을 클릭해 스킬 생성으로 이동합니다.

   그림Skill 생성

3. 스킬명과 기본 정보를 입력하고, [저장] 버튼을 클릭하여 Skill 생성을 완료합니다.

   • URL에는 START 블록에서 정의했던 URL{Skill이 구동중인 서버 http 연결 주소}/api/{START블록 URI}을 입력합니다.

   그림스킬명과 기본 정보 입력

4. 시나리오 메뉴에서 Skill을 적용할 블록을 클릭하고, 파라미터 설정에서 등록한 Skill을 선택합니다.

   그림블록 프로퍼티 수정

5. 봇 응답에서 스킬 데이터를 선택하고, [저장] 버튼을 클릭합니다.

   그림봇 응답에서 스킬데이터 선택

6. 배포 메뉴에서 [배포] 버튼을 클릭하면, 카카오톡 채널에서 발화 입력 시 말풍선으로 결과를 확인할 수 있습니다.

   그림채팅창에서 결과 확인

안내
블록별 자세한 설명은 [카카오 i 기술문서] Skill Builder 화면 구성 문서를 참고하시기 바랍니다.