Extended JSON extraction을 통한 중첩 구조 전개

Extended JSON extraction을 통한 중첩 구조 전개란

REST API에서 데이터를 가져와 파이프라인에 통합하고 싶은 경우는 ETL 업무에서 매우 흔한 시나리오입니다. 하지만 응답 JSON은 중첩된 객체나 배열을 포함한 복잡한 구조로 되어 있는 경우가 많아, "필요한 필드만 평탄화하여 추출하는" 작업에 상당한 수고가 듭니다.

Xplenty의 Rest API Source 컴포넌트는 HTTP 엔드포인트로부터의 데이터 취득, 인증, 페이지네이션, 그리고 응답 파싱까지를 로우코드로 완결할 수 있는 소스 컴포넌트입니다.

새롭게 추가된 Extended JSON extraction 기능을 사용하면, 중첩된 JSON의 필드를 스키마 상에서 직접 선택·전개할 수 있으며, 후속 컴포넌트에 플랫한 데이터로 전달하는 것이 가능해집니다.

본 문서에서는 Rest API Source의 Extended JSON extraction의 실전적인 사용법을 해설합니다.

Rest API Source 개요

Rest API Source는 REST 웹 서비스 등의 HTTP 엔드포인트에서 데이터를 읽어 들이기 위한 컴포넌트입니다. 패키지 디자이너에서 아래의 요소를 정의하는 것만으로 API 데이터 수집 파이프라인을 구축할 수 있습니다.

• 스텝 1: 인증 방식
  • 인증 없음
  • Basic 인증
  • Connection
    • 네이티브 커넥터에 의한 인증은 Connection에서 해당 네이티브 커넥터를 선택
    • 기타 OAuth 인증은 Connection에서 설정 완료된 Universal OAuth 커넥터를 선택
• 스텝 2: 요청 및 응답 설정
  • 요청 설정 (HTTP 메서드, URL, 헤더, 바디)
  • 페이지네이션 설정
  • 응답 파싱 방식
  • Extended JSON extraction 사용 여부
• 스텝 3: 입력 필드 선택
  • 필드 선택
  • Extended JSON extraction 활성화 시 추가 필드 선택 (탭 형식)
  • 데이터 미리보기

Extended JSON extraction: 중첩된 JSON을 직접 전개

Extended JSON extraction이란

일반적인 JSON 파싱에서는 응답의 1단계 계층 키만이 필드로 인식됩니다. 예를 들어, 다음과 같은 API 응답이 있다고 가정해 봅시다.

{
  "id": 1,
  "name": "Example",
  "address": {
    "city": "Tokyo",
    "zip": "100-0001"
  },
  "tags": [
    { "name": "priority" },
    { "name": "active" }
  ]
}

일반 파싱에서는 id, name, address(객체 그대로), tags(배열 그대로)의 4개 필드만 취득할 수 있습니다. address.city나 tags[*].name과 같은 중첩된 값을 개별적으로 추출하려면 후속 변환 컴포넌트에서 추가 처리가 필요했습니다.

Extended JSON extraction을 true로 설정하면, 이러한 중첩된 프로퍼티나 배열의 요소가 스키마 섹션에 전개 표시되어, 체크박스로 직접 선택할 수 있게 됩니다. 즉, address.city, address.zip, tags[*].name 등을 Rest API Source 단계에서 플랫한 필드로 추출할 수 있습니다.

Multiple output parses를 통한 복수 데이터셋 추출

REST API의 응답이 복잡하여, 서로 다른 경로의 데이터를 별도의 컴포넌트로 전달하고 싶은 경우도 있습니다. 예를 들어, 1회의 API 호출로 주문 데이터와 주문 상세 데이터를 동시에 포함하는 응답이 반환되는 경우, 주문 데이터는 주문 테이블로, 상세 데이터는 상세 테이블로 각각 별도의 흐름으로 처리하고 싶은 시나리오입니다.

컴포넌트 설정 화면의 응답 섹션에서 Extended JSON extraction 옵션을 true로 설정합니다. 설정 후, 스키마 섹션에 중첩 구조가 전개된 상태로 필드가 표시되므로, 필요한 필드에 체크를 넣어 주세요.

Extended JSON extraction에서는 + Add output parse 버튼을 사용하여 복수의 출력 파싱을 추가할 수 있습니다. 추가된 각 파싱은 각각 독립된 스키마 섹션을 가지며, 서로 다른 에지(edge) 이름을 부여할 수 있습니다. 이를 통해 하나의 API 응답에서 여러 관점으로 데이터를 추출하고, 각각을 서로 다른 후속 컴포넌트(변환이나 데스티네이션)에 연결할 수 있습니다.

• Bag 데이터 추출
• Map 데이터 추출
• 복합 데이터 추출

Extended JSON extraction을 사용하는 상황

• 응답에 중첩된 객체나 배열이 포함되어 있고, 그 안의 필드를 개별적으로 추출하고 싶은 경우
• 중첩 구조의 전개 처리를 소스 컴포넌트 단계에서 완결시켜, 하류의 변환 처리를 심플하게 유지하고 싶은 경우
• 하나의 응답에서 복수의 출력 파싱을 생성하여, 서로 다른 데스티네이션에 분배하고 싶은 경우
• 샘플 데이터에 나타나지 않는 필드를 Key 수동 편집으로 명시적으로 정의하고 싶은 경우

Key 수동 편집: 스키마에 표시되지 않는 필드에 대한 대응

Extended JSON extraction을 활성화해도, API 응답의 샘플 데이터 상태에 따라서는 일부 중첩 필드가 스키마의 필드 목록에 표시되지 않을 수 있습니다. 이는 샘플로 취득된 레코드에서 해당 필드가 비어 있는 경우(null이나 빈 배열)에 발생합니다.

예를 들어, tags가 배열 필드임에도 불구하고 첫 번째 레코드의 tags가 빈 배열 []이었다면, tags[*].test_field는 필드 목록에 자동으로 나타나지 않습니다.

이러한 경우에는 스키마의 Key를 수동으로 편집하여 대응할 수 있습니다. 스키마 섹션에서 해당 필드의 Key 값을 직접 tags[*].test_field와 같이 수정하면, 파이프라인 실행 시 해당 필드가 이용 가능한 레코드에서는 값이 취득되고, 이용할 수 없는 레코드에서는 null이 설정됩니다.

이 수동 편집 기능은 응답의 구조는 파악하고 있지만, 샘플 데이터에 모든 패턴이 포함되어 있지 않은 경우에 매우 유용합니다.

제한 사항

Rest API Source를 사용할 때 알아두어야 할 제한 사항이 있습니다.

• $ 기호의 이스케이프: API 호출 내에서 $ 기호를 사용하는 경우, 백슬래시 \로 이스케이프해야 합니다(\$). 참고로 런타임에서는 정상적으로 실행되지만, API 소스 컴포넌트의 미리보기나 플로우 내의 컴포넌트 미리보기에서는 에러가 발생합니다.
• BAG 필드 전개 제한: 하나의 파싱당 전개(flatten)할 수 있는 BAG 필드는 1개까지입니다. 다른 BAG 필드도 전개하고 싶은 경우에는, 새로운 파싱을 추가하여 대응해 주세요.

정리

Rest API Source는 외부 API로부터의 데이터 수집을 인증·요청·페이지네이션·파싱까지 일관되게 로우코드로 구축할 수 있는 컴포넌트입니다.

특히 Extended JSON extraction 기능은 기존에는 후속 변환 컴포넌트에서 수행하던 중첩 구조의 전개 처리를 소스 단계에서 완결시킬 수 있어, 파이프라인 전체의 설계를 심플하게 유지할 수 있습니다. Key의 수동 편집에 의한 스키마 정의나 Multiple output parses를 통한 복수 출력 생성 등, 실무에서 빈번하게 요구되는 시나리오에도 유연하게 대응할 수 있습니다.

먼저 대상 API의 인증 방식과 응답 구조를 확인하고, Extended JSON extraction의 활성화를 검토해 보세요. 중첩이 깊은 API 응답일수록, 이 기능의 혜택을 강하게 실감할 수 있을 것입니다.