LinkMerce

E-commerce API 통합 관리 플랫폼

---

목차

• LinkMerce
  • 목차
  • 소개
  • 설치 및 사용법
    • PyPI 패키지
  • 구성
    • ETL 모듈 및 구조
      • 요청 작업별 ETL 구조 (core/)
  • 확장 모듈
  • Airflow 워크플로우

소개

LinkMerce는 다양한 이커머스 API를 통합 관리할 수 있는 Python 기반 플랫폼입니다. API 연동, 데이터 적재, ETL, 스케줄링을 지원하며, PyPI 패키지와 Airflow 워크플로우로 구성되어 있습니다.

---

설치 및 사용법

PyPI 패키지

1. Python 환경 준비 (>=3.10)
2. 패키지 설치:
   pip install linkmerce
3. 환경설정 파일(src/env/) 및 예제 참고

---

구성

ETL 모듈 및 구조

• Extract (추출)

  • extract.py의 Extractor 클래스는 외부 API, DB, 파일 등 다양한 소스에서 데이터를 동기/비동기로 추출하는 기능을 제공합니다.
  • 세션 관리, 요청 파라미터, 변수 관리, 파싱 로직을 포함하며, 실제 데이터 추출은 extract 또는 extract_async 메서드를 통해 구현됩니다.
  • 예시: REST API에서 상품 정보를 받아오는 커스텀 Extractor 구현 가능

• Transform (변환)

  • transform.py의 Transformer 및 하위 클래스(JsonTransformer, DBTransformer 등)는 추출된 데이터를 원하는 형태로 변환합니다.
  • JSON, DB 결과 등 다양한 입력을 받아 파싱, 필터링, 타입 변환, 구조 변경 등 데이터 가공을 담당합니다.
  • 예시: API 응답 JSON을 표준 데이터셋으로 변환, DB 결과를 DataFrame 등으로 가공

• Load (적재)

  • load.py의 Connection 및 관련 함수/클래스는 변환된 데이터를 DB, 파일, 외부 시스템에 적재하는 기능을 제공합니다.
  • DuckDB, BigQuery 등 다양한 데이터 웨어하우스 연동을 지원하며, SQL 실행, 파일 저장(csv/json/parquet), 커넥션 관리 등 포함
  • 예시: 변환된 데이터를 DuckDB에 저장, BigQuery로 업로드, CSV/JSON 파일로 내보내기

각 모듈은 추상 클래스와 메서드로 구성되어 있어, 실제 사용 환경에 맞게 커스텀 구현이 가능합니다.

요청 작업별 ETL 구조 (core/)

• 각 비즈니스/데이터 작업 단위별로 core/ 디렉토리 내에 아래와 같은 파일 구조를 갖습니다:

  • extract.py: 해당 작업에 필요한 데이터 추출 로직(예: API 호출, DB 조회 등)을 정의합니다.
  • transform.py: 추출된 데이터를 가공/정제/필터링하는 변환 로직을 정의합니다.
  • models.sql: 데이터 적재 및 조회에 필요한 SQL 모델(테이블/뷰/쿼리 등)을 정의합니다.

• 이들 파일은 서로 다음과 같이 연결되어 동작합니다:

  1. extract.py에서 원천 데이터를 수집
  2. transform.py에서 수집된 데이터를 비즈니스 목적에 맞게 변환
  3. models.sql에 정의된 스키마/쿼리를 활용해 데이터를 저장하거나 추가 가공

• API 통합 사용 방식

  • api/ 모듈에서는 각 작업별로 core/의 extract, transform, models를 불러와 하나의 파이프라인으로 통합합니다.
  • 예를 들어, 특정 상품의 랭킹 정보를 가져오는 API는 core/rank_shop/extract.py로 데이터 추출, transform.py로 변환, models.sql로 적재 및 조회를 수행합니다.
  • 이를 통해 코드의 재사용성과 유지보수성을 높이고, 각 작업별 ETL 로직을 명확하게 분리할 수 있습니다.

이 구조는 확장성과 모듈화에 최적화되어 있어, 새로운 데이터 작업 추가 시에도 일관된 방식으로 ETL 파이프라인을 설계할 수 있습니다.

---

확장 모듈

• BigQuery 연동: 확장 모듈(extensions/bigquery.py)을 통해 Google BigQuery에 데이터를 적재하거나 조회할 수 있습니다.
• Google Sheets 연동: 확장 모듈(extensions/sheets.py)을 통해 Google Sheets API를 활용한 데이터 연동이 가능합니다.
• 기타 외부 시스템 연동도 확장 모듈 구조로 손쉽게 추가할 수 있습니다.
• 확장 모듈에 대한 의존성은 명시되어 있지 않습니다.

---

Airflow 워크플로우

• 이커머스 데이터 ETL 및 스케줄링을 위한 Airflow DAG 및 관련 스크립트/설정
• 주요 구성:
  • DAGs: airflow/dags/ (예: naver_brand_price, naver_brand_sales_first, naver_product_catalog 등)
  • 설정: airflow/config/airflow.cfg, docker-compose.yaml
  • 실행 스크립트: exec.sh, init.sh
• 주요 기능:
  • 네이버 스마트스토어/검색광고/랭킹/브랜드 데이터 ETL
  • BigQuery, DuckDB 등 데이터 웨어하우스 연동
  • 스케줄링 및 트리거 기반 데이터 파이프라인
• 실행 예시:

  cd airflow
  docker compose up airflow-init && docker compose up -d

• DAG 예시:
  • 매일 자정 브랜드 가격 데이터 적재: naver_brand_price
  • 매일 오전 브랜드 매출 데이터 적재: naver_brand_sales_first
  • 시간별 광고/비광고 순위 데이터 적재: naver_rank_ad, naver_rank_shop