84. API workflow 생성하기 (중급) : 활성화, endpoint 정의, parameter 정의, 자동 감지 설정

이 섹션에서는 API 워크플로를 만들고 설정하는 방법을 다룹니다. API 워크플로우는 백엔드 워크플로우 중의 하나로, 외부에서 연결 가능하도록 설정하는 워크플로우를 말합니다.

 

(1) API 워크플로 시작

API 워크플로의 생성은 html페이지에서의 일반 워크플로 생성과 동일한 방식으로 이루어집니다.

 

*활성화 설정

먼저 Settings > API > Public API endpoints에서 Enable Workflow API and Backend workflows를 체크하여 workflow API를 활성화하고 백엔드 편집기로 이동한 후, 박스의 Click here to add a backend workflow를 클릭하고 New API workflow를 선택합니다.

 

(2) Endpoint 설정

외부에 노출하는 각 API workflow에 대해 앱의 [Worfklow API 루트 URL + 워크플로에 지정한 이름] 으로 구성된 고유의 엔드포인트가 생성됩니다.

루트 URL은 아래 그림과 같이 Workflow API를 활성화하는 즉시 Bubble 편집기에 표시됩니다.

endpoint 주소

1. 워크플로 이름 지정

전체 API 워크플로 endpoint는 루트 URL을 이름과 결합하여 구성됩니다.
결과적으로 API 이름은 URL 친화적인 형식이어야 합니다.
위의 (1)에서 설정 후 백엔드 워크플로우에서 하나의 새로운 API workflow 를 만들 때 아래와 같이 이름을 설정합니다.
이름 설정은 Backend editor 로 넘어가서 상단 박스의 Click here to add a backend workflow  클릭 New API workflow... 클릭하여 API workflow를 추가하여 이름 설정   

• 각 API 워크플로에는 고유한 이름이 있어야 합니다.
• 소문자 사용
• 공백 및 특수 문자 제거 (대시 또는 밑줄로 대체)
• 후행 또는 선행 공백 제거
• 이름을 너무 길게 하지 마세요

: 예를 들어 워크플로 이름을 새 사용자 만들기 대신 create-new-user로 지정합니다.

 

2. Endpoint 구성

Workflow API를 활성화했고 워크플로에 이름을 지정했으므로 이제 완전한 Endpoint를 구성할 수 있습니다.

https://my-bubble-application.bubbleapps.io/version-test/api/1.1/wf/create-new-user

 

(3) 워크플로 에디터 상단 레이블 지정

• 워크플로의 이름은 URL 친화적이어야 하지만 레이블은 사람이 더 읽기 쉬게 자유롭게 만들 수 있습니다.
• API 워크플로 에디터에 이름을 적으면 레이블을 자동으로 상속하여 만들지만 더 쉽게 읽고 검색할 수 있도록 이 레이블을 변경할 수 있습니다.

 

(4) 워크플로를 외부에 노출

Workflow를 만들고 이름을 지정했으면 애플리케이션 외부에 노출되는지 확인해야 합니다.
그렇지 않으면 Endpoint에 연결 시도시에 단순히 오류를 반환합니다.

workflow API 외부 노출

: 자신의 앱 외부에서 접근을 허용하려면 위의 빨간 부분 상자를 체크해야 합니다.

 

• Expose as public API workflow를 선택하여 외부 애플리케이션에 엔드포인트에 대한 액세스 권한을 부여하십시오
• 외부 시스템에서 트리거하려는 API 워크플로만 노출합니다.
• 자신의 앱 내부 프로세스의 일부로만 워크플로를 사용하려는 경우 확인란을 선택하지 않은 상태로 유지합니다.

 

(5) Authentication(인증) 재정의

데이터 API와 마찬가지로 API 워크플로는 워크플로가 트리거 되기 전에 클라이언트가 자신을 인증해야 합니다.

인증 없이 워크플로우 실행 설정

 

• 누구나 액세스할 수 있도록 API 워크플로를 설정하려면 This workflow can be run without authentication(인증 없이 이 워크플로를 실행할 수 있음) 확인란을 선택합니다.
• 개인 정보 보호 규칙은 여전히 API 워크플로의 기능을 제한할 수 있습니다.
• 위의 선택을 활성화하면, 인증 없이 액세스 할 수 있도록 API 워크플로를 열 때는 누구나 언제든지 워크플로를 트리거할 수 있으므로 주의하십시오

 

(6) HTTP 메서드 정의

*위의 사진에서 Trigger workflow with 부분

HTTP 메서드는 클라이언트가 서버에 수행하도록 지시하는 작업의 종류를 결정합니다. 기본적으로 API 워크플로는 POST HTTP 메서드를 사용하지만 일부 외부 시스템에서는 웹훅에 GET 메서드를 사용할 수 있어야 합니다.

 

• GET request로 API 워크플로를 트리거하도록 선택하면 매개변수 정의가 Manual definition(정의)로 기본 설정되고 필드가 숨겨집니다. 이러한 방식도 key-value 쌍을 정의할 수 있습니다.
• Bubble의 내장 App Connector를 통해 API 워크플로를 사용하는 경우 이러한 워크플로는 드롭다운에 정의된 적절한 HTTP 요청에 의해 자동으로 트리거 됩니다.
• GET과 POST 사이를 전환하면, 미리 정의한 정의와 매개변수가 유지됩니다. Parameter Definition의 다른 옵션 간에 전환하기로 결정한 경우 Detect request data의 내용이 저장됩니다.
• Bubble의 에러 검사기는 데이터 형식이 올바른지 확인합니다.

 

(7) 매개변수(Parameter) 정의

대부분의 경우 API 워크플로를 실행하려면 매개변수가 필요합니다.

 

예를 들어 앱에서 새 사용자를 생성하도록 워크플로가 설정되어 있고 이메일과 같은 주요 정보와 성과 이름을 포함해야 한다고 가정해 보겠습니다. 매개변수를 사용하여 이 정보를 Bubble 외부에서 워크플로로 보낼 수 있습니다.

 

: 다음 두 가지 방법으로 매개변수를 정의할 수 있습니다.

1. 구조를 직접 정의(Manual definition) - 사용자가 정의하는 API 워크플로와 request 방법을 제어할 때(예: 예약된 워크플로를 사용하거나 사용자 지정 클라이언트를 빌드할 때)에 더 적합
2. 수신된 데이터의 구조를 자동으로 감지(Detect request data) - API 워크플로의 엔드포인트를  webhook에 대한 응답으로 할 때

 

1. 수동 정의(Manual definition) 

매개변수 추가는 세 단계를 거칩니다.

1. 매개변수 이름 지정
2. 수신할 데이터 유형 선택(type, array/list)
3. 매개변수가 선택적인지(optional) 여부를 지정

데이터 유형(type, array/list)과 선택 사항(optioanl)은 모두 중요한 설정입니다.

요청이 있을 때 Bubble은 데이터의 유효성을 검사하고 매개 변수가 잘못된 형식으로 전송되거나 선택 사항이(optional) 아닌 매개 변수가 누락된 경우 Bubble이 오류를 반환합니다.

 

매개변수 정의

위의 예시에서는 사용자를 생성하기 위해 텍스트 유형의 네 가지 매개변수를 포함했습니다.

• 이메일, 이름, 성(필수)
• 닉네임(선택사항 : optional)

 

2. 자동 감지(Detect request data) 

Bubble은 외부 서비스(webhook)에서 전송한 매개변수를 자동으로 감지할 수도 있습니다.

• 들어오는 request를 "감지하고" Call에서 전송된 매개 변수를 확인하여 이를 수행합니다.
• 이렇게 하면 각 매개 변수를 식별하고 어떤 종류의 데이터 유형인지 확인하려고 시도할 수 있습니다.
• 아래의 설명과 같이 엔드포인트 URL을 약간 수정하여 Bubble이 이것이 초기화 호출임을 알도록 해야 합니다.

매개변수 자동감지

위의 사진과 같이 Bubble은 데이터 감지기능을 사용하여 Call에서 매개변수를 자동으로 감지할 수 있습니다.

 

데이터를 자동으로 감지하려면 다음을 설정하십시오

1. 창에서 Parameter definition을 Detect request data로 설정
2. 하단에 나타난 Detect data(데이터 감지)를 클릭합니다.
3. Bubble은 아래와 같이 팝업으로 초기화 URL을 표시
4. 외부 시스템에서 request 보내기

초기화 url 표시

3. 초기화 URL

위의 사진과 같이 Bubble이 초기화 URL을 표시하여 보여주지만, 개발자가 직접 구성할 수도 있습니다.

• 형식은 다음과 같습니다.

https://appname.bubbleapps.io/version-test/api/1.1/wf/endpoint이름/initialize

또는

https://yourdomain.com/version-test/api/1.1/wf/endpoint이름/initialize

• 현재 수정 중인 버전이므로 위의 주소처럼 앱의 테스트 버전에 대해 요청해야 합니다.
• 매개 변수에 대한 모든 변경 사항을 배포하므로 라이브 버전에 초기화를 보낼 필요가 없습니다.

 

(8) Timezone(시간대) 재정의

백엔드에서 시간대를 재정의하려면 앱의 다음 위치에서를 활성화해야 합니다.

Settings > General > Advenced options > Enable timezone override controrls

 

• API 워크플로우를 사용하면 정적 또는 동적 선택으로 대체 시간대를 설정하여 request의 시간대를 재정의할 수 있습니다.
• 이렇게 하면 앱이 데이터 구문을 parse(구문분석 변환)하고 저장하는 방식을 표준화하는 데 도움이 됩니다.

 

예를 들어:

• 동부 표준시에서 2000년 1월 1일을 구문 분석 하고 기본 설정을 유지하면 Bubble은 해당 날짜를 2000년 1월 1일 오전 12:00 동부 표준시로 저장합니다.
• 대신 클라이언트 시간대를 태평양 표준시로 재정의하는 경우 1/1/2000을 선택하면 1/1/2000 12:00 AM 태평양 표준시가 저장됩니다.

 

이러한 유형의 timezone(시간대) 표준화는 다양한 시나리오에서 유용합니다.

• 외부 API 요청에 타임스탬프가 포함되지만 timezone(시간대)는 포함되지 않는 경우:해당 Call이 수신되면 적절하게 구문 분석되도록 정적 또는 동적 timezone(시간대)를 설정할 수 있습니다.
• 예약된 약속의 timezone(시간대)이 일정하게 유지되어야 하는 일정을 처리하는 앱: 예를 들어 사용자가 도쿄에서 런던에서 회의를 예약하는 경우 앱은 사용된 timezone(시간대)이 실제로 도쿄가 아닌 런던임을 확인할 수 있습니다.

(9) API 워크플로에서 데이터 반환

경우에 따라 워크플로가 트리거 된 후 앱에서 데이터를 반환하기를 원할 수 있습니다.

 

다음의 경우에 데이터베이스의 데이터로 응답하려면 데이터 API를 사용하고 싶을 것입니다.

• 워크플로가 성공적으로 완료되었는지 확인
• 워크플로에 따라 달라지는 데이터 반환
• 여러 데이터 유형의 데이터/필드 결합

아래와 같이 데이터를 반환하려면 Return data from API라는 Action을 사용할 수 있습니다.

데이터 반환 예시

• 위의 예시에는 점수를 저장하는 데이터베이스 레코드가 있습니다.
• 데이터베이스에 있는 모든 레코드의 평균 점수를 반환하고 싶다고 상상해 봅시다.
• Return data from API라는 Action을 사용하여 검색을 수행하고 계산된 평균을 반환할 수 있습니다.