API 연동

API 연동 서비스는 사용자가 자주 사용하는 API를 템플릿으로 등록하고, 이를 통해 손쉽게 해당 서비스를 호출할 수 있도록 지원하는 기능입니다. 이 서비스를 통해 사용자는 반복적인 API 호출 과정을 간소화할 수 있으며, 개발 과정에서의 시간과 노력을 절약할 수 있습니다.

API 연동 화면

영역 번호	영역 이름	영역 설명
1	API 및 모듈 리스트	모든 API 및 모듈을 리스트로 표시합니다. +버튼을 통해 새 API를 추가할 수 있고, 마우스를 올려놓으면 생기는 … 을 클릭하여 모듈추가, API삭제, 모듈 삭제, 모듈 복사를 할 수 있습니다.
2	모듈 모드 전환 패널	모듈 정의 / 모듈 테스트 화면간에 전환을 할 수 있습니다.
3	모듈 명칭 영역	모듈의 명칭을 수정할 수 있는 영역입니다.
4	모듈 상세보기	선택한 모드에 따라 모듈정의 또는 모듈 테스트를 진행할 수 있는 영역입니다. [정의 영역 설명][테스트 영역 설명]
5	버튼영역	모듈에 대한 배포, 변경사항 취소를 할 수 있습니다.

정의 영역 설명

영역 번호	영역 이름	영역 설명
1	Method 및 URL	API 요청의 Method 타입을 설정하고 호출할 URL을 정의하는 영역입니다.
2	자동 URL 인코딩 사용 여부	URL을 자동으로 인코딩하여 API를 호출합니다. 이미 인코딩된 값이 URL에 포함된 경우, 2중 인코딩이 발생할 수 있습니다.
3	모듈 세부 항목 정의	선택한 모듈의 세부 정보를 구성하는 영역입니다. [모듈 항목 탭별 설명]

모듈 항목 탭별 설명

Params

Query Params에 정의된 Key-Value 값이 URL에 추가됩니다.

{= } 구문을 사용하여 값을 동적으로 전달할 수 있습니다.

Header

Header에 설정된 Key-Value 값을 기반으로 헤더가 생성됩니다.

{= } 구문을 사용하여 값을 동적으로 전달할 수 있습니다.

Advanced Key Setting

스튜디오에서 동적으로 값을 받아오거나 민감한 데이터를 미리 정의해 안전하게 처리할 수 있는 키를 설정합니다.

Event Config Key

Event Config Key는 API 연동 모듈에서 동적 데이터 처리를 가능하게 하는 핵심 구성 요소입니다. 이를 통해 사용자 정의 값을 API 호출에 동적으로 적용할 수 있습니다. {= } 구문을 사용하여 Event Config Key 값을 참조합니다.

설정 예시 API 모듈을 구성할 때 필요한 동적 데이터를 정의합니다. 이 정의된 키는 시나리오에서 API 호출 시 설정한 값으로 자동 대체됩니다.

사용 예시 {=Event.keyword}와 같이 {=Event.[정의한 키]} 형식으로 Query, Header의 key-value 정의 영역 및 Body에서 사용할 수 있습니다.

Secret Key

Secret Key는 Event Config Key와 유사하지만, 민감한 데이터를 보호하기 위해 미리 정의하여 사용합니다. {= } 구문을 활용해 안전하게 값을 전달합니다.

사용 예시 {=Token}과 같이 {=[정의한 키]} 형식으로 Query, Header의 key-value 정의 영역 및 Body에서 사용할 수 있습니다.

Body

Request Body

API 호출 시 전달할 요청 본문을 구성하는 영역입니다. 서비스 호출 시 전달된 데이터는 ParamBlocks를 통해 접근할 수 있으며, ParamBlocks는 기본적으로 이중 배열 형태로 제공됩니다. 문자열 형태로 값을 전달해야 할 경우, {= } 구문을 반드시 따옴표("")로 감싸서 작성해야 합니다.

사용 예시

{
	"data": {=ParamBlocks},
	"stringData": "{=ParamBlocks[0][0]}"
}

Response

Response Body API 호출 후 시나리오에 전달할 데이터를 구성하는 부분입니다. 이 데이터는 Result 객체를 통해 접근할 수 있으며, Result 값이 이중 배열이 아닌 경우 자동으로 이중 배열 형태로 변환되어 Result Convert Script에 전달됩니다. 문자열 형태로 값을 전달해야 할 경우, {= } 구문을 따옴표("")로 감싸서 작성해야 합니다.

사용 예시

사용 예시// API 호출 결과를 그대로 사용할 때
{=Result}

// API 호출 결과를 원하는 형태로 변환하여 사용할 때
[[{ "data": "{=Result.data}", "testSample": "{=Result.testData}" }]]

Custom Error Msg API 호출이 성공했더라도 특정 값이 반환될 경우 이를 오류로 처리할 수 있는 기능입니다. 오류 메시지는 시나리오에서 팝업으로 표시됩니다.

사용 예시

// Result에 'errMsg' 항목이 포함된 경우 오류로 처리하여 팝업 표시
{=Result.errMsg}

Script

ParamBlocks Convert Script

이 스크립트는 API 호출 전에 ParamBlocks 데이터를 전처리하는 데 사용됩니다. 이중 배열 형식의 데이터를 가공하여 원하는 형태로 반환합니다.

사용 예시

// 섹터의 SUID를 제거하고 호출하는 예시
for (let i = 0; i < ParamBlocks[0].length; i++) {
    let sector = ParamBlocks[0][i];
    delete sector._SUID;
}
return ParamBlocks;

Result Convert Script API 호출 후 응답받은 데이터를 후처리하는 스크립트입니다. 응답 데이터는 Result에 이중 배열 형식으로 전달되며, 직접 수정하여 필요한 형태로 가공할 수 있습니다. 반환값 없이 Result를 수정합니다.

사용 예시

// resultBlocks와 sector의 구조에 맞게 스크립트를 작성합니다
for (let i = 0; i < resultBlocks[0].length; i++) {
    let sector = resultBlocks[0][i];
    sector.content = sector.content[0].text.value;
}

테스트 영역 설명

Test Value 영역

테스트 호출 시, 모듈 정의 영역에서 설정된 Event Config Key에 해당하는 항목들의 값을 여기에 입력합니다. 각각의 키에 대한 값을 정확히 설정하여 원하는 테스트 결과를 얻을 수 있습니다.

Test Param Blocks

테스트 호출에 사용할 ParamBlocks를 정의합니다. ParamBlocks는 반드시 이중 배열 형식의 JSON이어야 합니다. 올바른 형식이 아닐 경우, 호출이 실패할 수 있으므로 주의가 필요합니다.

사용 예시

[
   [
      { "value": "sampleValue1", "name": "sampleName1" },
      { "value": "sampleValue2", "name": "sampleName2" }
   ]
]

Test Result

작성 중인 API를 테스트 호출한 후 반환된 데이터를 확인할 수 있는 영역입니다. API 호출이 완료되면, 반환된 데이터 및 관련 정보가 이곳에 표시되어 API가 기대한 대로 작동하는지 검증할 수 있습니다. 호출 과정에서 오류가 발생하면, 해당 탭에 빨간 점이 표시되며 오류 메시지가 제공되어 문제를 빠르게 식별할 수 있습니다.

• API URL: 최종적으로 API 호출에 사용된 URL입니다.

• Request Headers: API 호출 시 함께 전송된 HTTP 요청 헤더입니다.

• Request Body: ParamBlocks Convert Script를 거친 후, 최종적으로 API 호출에 사용된 본문 데이터입니다.

• ResultBlocks: API 호출 후 받아온 데이터입니다. 응답 데이터가 이중 배열 형식이 아닐 경우, 자동으로 이중 배열 형식으로 변환되어 반환됩니다.

• afterScript ResultBlocks: 후처리 스크립트(Result Convert Script)를 통해 변환된 최종 데이터입니다. 이 스크립트에서 데이터 변환 및 추가 처리가 완료된 결과를 확인할 수 있습니다.

API 연동 사용하는 방법

API연동에서 정의한 API를 사용하기위해서는 다음과 같습니다.

1. API 연동을 위해 정의한 API 모듈을 배포합니다.

2. 시나리오 스튜디오에서 사용할 API 모듈을 이벤트로 등록합니다.

3. 동적 데이터 처리를 위한 Event Config Key를 설정합니다. 이는 API 호출 시 동적으로 변경되는 데이터를 관리하는 데 사용됩니다.

4. ParamBlock 전처리 스크립트를 통해 API 요청 전에 데이터를 준비하고, ResultBlock 후처리 스크립트를 통해 API 응답 데이터를 가공합니다.

5. 생성한 서비스를 이벤트에 연결합니다.

보다 자세한 API 사용방법은 API 호출을 참고해주세요