API 연동

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

API 연동 화면

영역 번호영역 이름영역 설명
1

새 API 추가

기본으로 제공되는 API 템플릿을 활용하거나, "별도 API 추가하기" 를 통해 사용자 정의 API를 새롭게 추가할 수 있습니다.

2

사용중인 API

워크스페이스에서 사용 중인 API들의 리스트를 이 영역에서 확인할 수 있습니다.

3

API 명칭영역

API의 명칭을 사용자가 직접 수정할 수 있는 영역입니다. 각 API의 고유 ID 값도 이곳에서 확인할 수 있으며, 이 명칭은 시나리오 스튜디오에서 서비스를 추가할 때 사용되는 시스템명으로 활용됩니다.

4

API 모듈

현재 선택한 API에 등록된 모든 API 모듈의 리스트를 표시합니다.

5

새 모듈 추가

"새 모듈 추가" 버튼을 통해 사용자는 선택한 API에 새로운 모듈을 추가할 수 있습니다.

6

API 모듈 상세보기

선택한 모듈에 대한 상세 정보를 이 영역에서 구성할 수 있습니다. 모듈 항목별 설명

7

버튼영역

모듈에 대한 배포, 삭제, 취소, 복제를 할 수 있습니다.

모듈 항목별 설명

항목명설명

Module 명

모듈 이름은 스튜디오에서 서비스를 추가할 때 사용되는 모듈명입니다. 이 이름을 통해 특정 API 모듈을 식별하고 호출합니다.

스튜디오에서 동적으로 값을 받아올 수 있는 키를 지정합니다. 여러 개의 값을 입력할 때는 세미콜론(;)으로 구분합니다 (예: a;b;c).

APIKey

Event Config Key와 유사하나 민감한 성격의 데이터일 경우 미리 정의하여 사용합니다. 스튜디오에서 사용할 때 {=APIKey} 로 불러올 수 있습니다.

Token

Event Config Key와 유사하나 민감한 성격의 데이터일 경우 미리 정의하여 사용합니다. 스튜디오에서 사용할 때 {=Token} 로 불러올 수 있습니다.

ID

Event Config Key와 유사하나 민감한 성격의 데이터일 경우 미리 정의하여 사용합니다. 스튜디오에서 사용할 때 {=ID} 로 불러올 수 있습니다.

URL

호출할 API의 주소를 정의합니다. 이 주소는 API 요청을 보내는 데 사용됩니다.

Header

API 호출 시 사용할 헤더를 정의합니다. 필수 항목이며, 값이 없는 경우 {}로 추가합니다.

HTTP Method

호출 방식 정의 선택 (GET, POST, PUT, PATCH, DELETE)

Request Body

API 호출 시 전달할 요청 본문을 정의합니다. 시나리오에서 전달 받은 데이터는 ParamBlocks를 통해 접근 가능하며, 기본적으로 이중 배열 형태입니다.

Response Body

API 호출 후 시나리오로 전달할 데이터를 정의합니다. 이 데이터는 Result를 통해 접근 가능합니다.

API를 호출하기 전 요청하는 Body의 이중배열 내부 데이터 즉 ParamBlocks를 전처리하는 스크립트를 작성합니다.

API 호출 후 응답받은 데이터 Result를 후처리하는 스크립트를 작성합니다.

Error Message

API 호출 후 오류가 발생할 경우 전달할 데이터를 정의합니다. API 호출이 실패하면 실패 메시지만 반환됩니다.

Event Config Key

Event Config Key는 API 연동 모듈의 동적 데이터 처리를 가능하게 하는 중요한 요소입니다. 이를 통해, 스튜디오에서 설정한 사용자 정의 값들을 API 호출 과정에 직접 적용할 수 있습니다. 설정된 Event Config Key 값을 {= }를 사용하여 모듈 내에서 동적으로 참조하는 방법을 자세히 알아보겠습니다.

설정 예시

Event Config Key 설정은 스튜디오에서 API 모듈을 구성할 때, 필요한 동적 데이터를 지정하는 과정입니다. 사용자는 스튜디오 내에서 모듈 설정 시, 필요한 동적 값을 token;baseId;tableIdOrName;과 같이 세미콜론(;)을 사용하여 구분지어 입력할 수 있습니다. 이렇게 입력된 각 키는 나중에 API 호출 시 서비스에서 설정한 값으로 대체됩니다.

사용 예시

  • URL에 동적 값 적용하기: API의 URL 경로에 사용자 입력 값을 포함시킬 경우, {=Event.keyword}와 같은 방식으로 URL 문자열 내에 직접 삽입할 수 있습니다.

https://api.airtable.com/v0/{=Event.baseId}/{=Event.tableIdOrName}
  • Header, Request Body 값 적용하기: API 요청의 헤더에 동적 값을 포함시키려면, 헤더 정의 부분에 아래와 같이 적용합니다.

{
    "Authorization": "Bearer {=Event.token}"
}

추가정보

  • 문자열로 전달되는 값들은 모두 "" 묶어서 설정해야 합니다. 키 값은 반드시 문자열로 정의합니다.

  • Header, Request Body, Response Body 모두 JSON 형식으로 정의합니다.

  • 보내는 데이터 값은 Request Body에서 필요한 내용을 ParamBlocks로 접근하여 body에 포함시킬 수 있습니다. 보내는 데이터의 전처리가 필요한 경우 스튜디오 서비스에서 ParamBlock 전처리 스크립트에서 ParamBlocks를 커스텀할 수 있습니다.

ParamBlocks 예시
[
  [
    {
      "title": "test",
      "description": "test",
      "bookmark": "1"
    },
    {
      "title": "메모테스트",
      "description": "123",
      "bookmark": "1"
    },
    ...
  ],
  ...
]
보내는 데이터 사용예시
{
	"ALLData" : {=ParamBlocks}, // [ [ { "title": "test", "description": "test", "bookmark": "1" }, { "title": "메모테스트", "description": "123", "bookmark": "1" }, ... ], ... ]
	"Data1" : {=ParamBlocks[0]}, // [ { "title": "test", "description": "test", "bookmark": "1" }, { "title": "메모테스트", "description": "123", "bookmark": "1" }, ... ]
	"Data1_Sector" : {=ParamBlocks[0][0]} // { "title": "test", "description": "test", "bookmark": "1" }
	"Data1_Sector_title" : "{=ParamBlocks[0][0].title}" // "test
}

ParamBlocks Convert Script

Javascript로 API 요청전 사용하는 ParamBlocks의 전처리를 작성할 수 있습니다.

// paramBlocks와 sector의 구조에 맞게 스크립트를 작성합니다.
let sector = paramBlocks[1][0];
sector.role = "user";
delete sector._SUID;

return paramBlocks;

Result Convert Script

Javascript로 API 응답 데이터(Result)에 대한 후처리를 작성할 수 있습니다.

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

API 연동 사용하는 방법

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

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

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

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

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

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

보다 자세한 API 사용방법은 [스튜디오 개발하기]-[개발 모드]-[서비스]-[API 연동]를 참고해주세요

Last updated