AI 상담사 워크스페이스 와 다른 시스템 간의 연동이 예상대로 작동하지 않는 경우 문제를 해결해야 할 수도 있습니다. 이 문서에서는 연동 문제를 파악하기 위해 수행할 수 있는 여러 가지 문제 해결 단계에 대해 설명합니다.
이 문서에서는 다음과 같은 주제를 다룹니다.
- 연동 빌더에서 연동 테스트
- 요청 매개변수가 일치하는지 확인
- 대화 로그에서 세션 매개변수 확인
- 실패 시나리오에서 출력 원시 값
- HTTP 상태 코드 확인
- 대화에서 기술적 오류를 조사합니다.
관련 문서:
연동 빌더에서 연동 테스트
연동 서비스 문제 해결의 첫 번째 단계로 연동 빌더에서 테스트하세요 . 응답을 받고 있고 세션 매개변수에 올바른 데이터가 표시되는지 확인하세요.
요청 매개변수가 일치하는지 확인
URL 쿼리, 본문 또는 헤더 등 연동 빌더에서 사용하는 요청 매개변수는 대화에서 캡처된 것과 정확히 일치해야 합니다.
다음 사항을 확인합니다.
- 오타가 없습니다.
- 대화의 어느 단계에서든 매개변수의 철자나 이름을 업데이트한 경우에는 연동 서비스에서도 업데이트됩니다.
- 대소문자가 정확히 일치합니다. 매개변수는 대소문자를 구분합니다.
팁: 모든 요청 또는 세션 매개변수에 대해 lowCamelCase 또는 snake_case와 같은 일관된 이름 지정 규칙을 채택하는 것이 좋습니다.
대화 로그에서 세션 매개변수 확인
세션 데이터와 같은 자세한 내용은 대화 로그를 확인하세요. 태그를 필터링하여 API를 사용하여 대화를 검색할 수 있습니다. 대화에서 API를 사용하는 경우 검색할 수 있습니다.
대화 로그에서 왼쪽 위에 있는 필터 추가를 클릭합니다.
왼쪽 메뉴에서 레이블로 이동합니다.
여기에서 이름 및 성공, 실패 또는 API 오류가 있었는지 여부와 같은 시나리오별로 연동 서비스를 필터링할 수 있습니다.
연동 빌더에서 구축된 연동 서비스의 경우에는 API가 앞에 붙고, 그 뒤에 연동 서비스 이름이 오고, 그 다음에 시나리오 이름으로 끝납니다.
아래 스크린샷의 예는 API-Chloe 데모입니다. Apple Cart-Success:
- API = 접두어
- Chloe 데모: Apple Cart = 연동 서비스의 이름
- 성공 = 시나리오 이름
연동 여부를 간단히 살펴보기 위해 대화 로그의 태그 기호에 커서를 갖다 대면 대화와 연결된 태그를 볼 수도 있습니다.
API가 있는 대화에 오류가 발생한 이유만 보려면 레이블 검색에서 apiError를 검색합니다.
그런 다음 대화를 선택하여 자세한 정보를 봅니다.
대화에 있을 때 세션 데이터에 무엇이 있는지 확인할 수 있습니다.
오른쪽 위에 있는 세부 정보를 클릭합니다.
이 버튼을 클릭하면 대화 개요가 표시됩니다. 그런 다음 세션 데이터를 클릭합니다.
이제 채팅에서 세션 데이터를 볼 수 있습니다. 여기서 흥미로운 것은 아래쪽에 API 연동에서 오는 세션 매개변수가 있다는 것입니다.
대화 상자에서 세션 매개변수 확인
세션에 대한 세션 매개변수가 있는지 신속하게 확인하려면 대화를 통해 AI 상담사 메시지에 로깅할 수 있습니다. 스테이징 환경에서 대화를 테스트할 때 또는 연동이 실행 중인 경우에는 테스트할 때 대화를 저장하지 않도록 하는 것이 가장 안전합니다.
아래 AI 상담사 메시지에서 세션 매개변수는 테스트 시 표시되도록 로깅됩니다.
원시 값을 실패 시나리오로 출력
`$string(data)` 함수에 'data'를 래핑하여 응답에 있는 모든 데이터의 문자열을 만듭니다. 그런 다음 테스트할 때 실패 시나리오에 로깅하여 리턴되는 내용을 신속하게 확인할 수 있습니다.
HTTP 상태 코드 확인
연동 서비스를 테스트할 때 리턴되는 http 상태 코드를 반드시 확인하세요. 오른쪽 응답에 `statusCode` 키가 있는 것을 볼 수 있습니다.
2xx: 성공
-
200 OK: 요청이 성공했고 서버가 예상 데이터로 응답했습니다.
- 연동 서비스를 테스트할 때 이상적인 응답입니다.
4xx: 클라이언트 오류
이 범위의 오류는 일반적으로 연동 빌더에서 보낸 요청에 문제가 있음을 나타냅니다.
-
400 잘못된 요청: 올바르지 않은 구문이나 누락된 매개변수로 인해 서버에서 요청을 이해할 수 없습니다.
- 요청 페이로드에 오류, 누락된 필드 또는 잘못된 서식이 있는지 확인합니다.
-
401 Unauthorized: 인증이 필요하지만 제공되지 않았거나 올바르지 않습니다.
- API 키, 토큰 또는 기타 인증 자격 증명을 확인합니다. 권한 부여 헤더를 다시 확인하세요.
-
403 Forbidden: 서버가 요청을 이해했지만 권한 부여를 거부합니다.
- IP 주소가 허용 목록에 있는지 확인하거나 API에 대한 권한을 확인하세요.
-
404 찾을 수 없음: 서버에서 요청한 리소스를 찾을 수 없습니다.
- URL 또는 엔드포인트를 확인합니다. 올바른 경로가 사용되고 있고 리소스가 있는지 확인합니다.
5xx: 서버 오류
이 범위의 오류는 일반적으로 백엔드 서버에 문제가 있음을 나타냅니다.
-
500 내부 서버 오류: 백엔드 서버에서 문제가 발생했음을 나타내는 일반 오류입니다.
- 추가 디버깅을 위해 요청의 세부 정보와 함께 백엔드 팀에 문의하세요.
-
502 Bad Gateway: 서버가 업스트림 서버로부터 잘못된 응답을 받았습니다.
- 이는 종종 백엔드의 내부 서비스 또는 종속성에 문제가 있음을 나타냅니다.
-
503 서비스를 사용할 수 없음: 과부하 또는 유지 관리로 인해 서버에서 현재 요청을 처리할 수 없습니다.
- 잠시 후 다시 시도하고 예정된 다운타임이 있는지 확인하세요.
-
504 게이트웨이 시간 제한: 서버가 업스트림 서버로부터 적시에 응답을 받지 못했습니다.
- 백엔드 서비스가 작동하는지 확인하고 지연 시간 문제가 있는지 확인합니다.
대화에서 기술적 오류를 조사합니다.
경우에 따라 기술적 오류가 포함된 메시지가 표시될 수 있습니다. 기술적 오류에는 다음 텍스트가 포함됩니다.
“죄송합니다. 기술적인 문제가 있는 것 같습니다. 곧 정상 상태로 돌아갈 수 있기를 바랍니다.”
이 시나리오에서 문제는 연동 서비스 자체와 관련된 것이 아니라 대화 오류일 가능성이 높습니다. 다음은 몇 가지 팁입니다.
- 대화를 확인하여 플로우가 연동 서비스에 도달하는지 확인합니다. 버퍼 메시지를 사용하여 혼합된 버튼 기능, 끊어진 링크 또는 순환 참조와 같은 문제를 확인하고 확인합니다.
- 필수 매개변수가 있는지 확인합니다. 필수 매개변수가 없으면 연동 서비스가 실행되기 전에 오류가 트리거됩니다.
- 카드 및 회전 슬라이드와 같은 동적 콘텐츠 의 경우 모든 필드가 채워져 있는지 확인합니다. 정의되지 않음, 공백 또는 null 값은 이러한 구성 요소를 손상시켜 오류를 일으킬 수 있습니다.
번역 고지 사항: 본 문서는 콘텐츠에 대한 기본적인 이해를 제공하기 위해 자동 번역 소프트웨어를 사용하여 번역되었습니다. 정확한 번역을 제공하고자 합당한 노력을 기울였으나 Zendesk는 번역의 정확성을 보장하지 않습니다.
번역된 문서에 포함된 정보의 정확성과 관련하여 질문이 있으시면 문서의 공식 버전인 영문 버전을 참조하시기 바랍니다.