콘텐츠 연동

숙소, 객실, 패키지 정보를 연동하는 방법을 안내합니다.

콘텐츠 연동#

ONDA의 숙박 콘텐츠(숙소/객실 정보)를 효율적으로 동기화하고 최신 상태를 유지하는 전략을 안내합니다.

콘텐츠 연동 개요#

콘텐츠 연동은 다음 세 가지 레벨로 구성됩니다:

숙소 (Property)
  └─ 객실 타입 (Room Type)
      └─ 패키지/요금제 (Rate Plan)

데이터 구조#

레벨	설명	예시
Property	호텔, 리조트, 펜션 등 숙박 시설	서울 센트럴 호텔
Room Type	객실 유형 및 구성	디럭스 더블룸, 스위트룸
Rate Plan	요금제 및 정책 (조식 포함, 환불 가능 등)	조식 포함 프로모션

콘텐츠 정보(숙소/객실 설명, 이미지, 편의시설 등)는 자주 변경되지 않으므로 S3 벌크 다운로드 방식을 사용합니다. 가격/재고 정보는 실시간 API로만 조회 가능합니다.

S3 벌크 다운로드 전략#

왜 S3 벌크 다운로드인가?#

콘텐츠 데이터(Property → RoomType → RatePlan)는 다음 특징을 가집니다:

변경 빈도가 낮음: 숙소 설명, 이미지, 편의시설 등은 하루에 수십 번 조회되지만 주 1-2회 정도만 변경됨
데이터 크기가 큼: 전체 숙소 정보를 API로 조회하면 수천 건의 요청 필요
일관성 보장: 특정 시점의 스냅샷을 받아 데이터 정합성 유지

다운로드 프로세스#

S3 다운로드 URL 발급

ONDA API를 통해 최신 콘텐츠 스냅샷의 S3 Presigned URL을 받습니다.

JSON 파일 다운로드

압축된 JSON 파일(gzip)을 다운로드하고 압축 해제합니다.

로컬 DB 동기화

전체 콘텐츠를 파싱하여 로컬 데이터베이스에 저장합니다.

증분 업데이트

웹훅을 통해 변경 사항이 발생하면 해당 항목만 API로 재조회합니다.

다운로드 주기#

시나리오	권장 주기	이유
초기 동기화	시스템 구축 시 1회	전체 데이터 로드
정기 갱신	하루 1회 (새벽 시간대)	변경 누락 방지
웹훅 기반 갱신	실시간	특정 숙소/객실만 업데이트

권장 전략: 하루 1회 S3 벌크 다운로드 + 웹훅 기반 실시간 증분 업데이트를 병행하면 최신 상태 유지와 API 호출 절감을 동시에 달성할 수 있습니다.

콘텐츠 계층 이해하기#

Property (숙소)#

기본 정보: 이름, 주소, 성급, 숙박 시설 유형
위치 정보: 위도/경도, 주변 랜드마크
편의시설: Wi-Fi, 주차장, 수영장, 레스토랑 등
정책: 체크인/체크아웃 시간, 반려동물 정책, 어린이 정책
이미지: 외관, 로비, 부대시설 사진

Room Type (객실 타입)#

객실 정보: 객실명, 크기(㎡), 최대 수용 인원
침대 구성: 더블 베드 1개, 싱글 베드 2개 등
객실 편의시설: TV, 미니바, 금고, 커피머신 등
전망: 도시 전망, 바다 전망, 산 전망 등
이미지: 객실 내부, 욕실, 전망 사진

Rate Plan (요금제)#

패키지 정보: 패키지명, 설명
포함 사항: 조식 포함 여부, 조식 인원수
취소 정책: flexible, moderate, strict, non_refundable
결제 정책: 선결제, 현장 결제
예약 제한: 최소/최대 숙박일, 사전 예약 기간

이미지 CDN 활용#

ONDA는 모든 이미지를 CDN을 통해 제공하며, URL 쿼리 파라미터로 크기 조정이 가능합니다.

이미지 최적화 전략#

원본: https://cdn.onda.me/properties/prop_123456/main.jpg

썸네일: ?w=300&h=200&fit=crop&q=80
갤러리: ?w=1200&q=85
상세: ?w=1920&q=90

용도	권장 크기	품질
목록 썸네일	300x200px	80%
갤러리/슬라이드	1200px	85%
상세 페이지	1920px	90%

이미지 URL에 쿼리 파라미터를 추가하면 CDN이 자동으로 리사이징을 처리합니다. 원본을 다운로드하지 말고 필요한 크기만 요청하세요.

다국어 지원#

ONDA API는 5개 언어를 지원합니다:

한국어 (ko): 기본 언어
영어 (en)
일본어 (ja)
중국어 간체 (zh-CN)
중국어 번체 (zh-TW)

언어 지정 방법#

Accept-Language 헤더에 원하는 언어 코드를 지정하면 해당 언어로 된 콘텐츠를 받습니다. 번역이 없는 경우 기본 언어(한국어)로 응답됩니다.

웹훅 기반 증분 업데이트#

콘텐츠 변경 시 웹훅으로 알림을 받아 해당 항목만 재조회하면 효율적입니다.

주요 이벤트#

이벤트	발생 시점	권장 조치
`property.created`	새 숙소 등록	해당 숙소 정보 조회 후 DB 추가
`property.updated`	숙소 정보 변경	해당 숙소 정보 재조회 후 DB 업데이트
`property.deleted`	숙소 운영 중단	DB에서 비활성화 처리
`roomtype.updated`	객실 정보 변경	해당 객실 타입 재조회
`rateplan.updated`	패키지 정책 변경	해당 패키지 재조회

웹훅 설정 방법은 웹훅 가이드를 참고하세요.

동기화 아키텍처 예시#

권장 동기화 전략#

초기 로드: S3 벌크 다운로드로 전체 콘텐츠 로드
일일 갱신: 매일 새벽 S3 다운로드로 전체 동기화 (변경 누락 방지)
실시간 갱신: 웹훅 이벤트 수신 시 해당 항목만 API 재조회
캐시 관리: 콘텐츠는 24시간 캐싱 가능 (가격/재고는 캐싱 금지)

다음 단계#

실시간 검색 - 재고 및 가격 검색 아키텍처
예약 관리 - 예약 프로세스 개념
웹훅 - 실시간 이벤트 알림
API 레퍼런스 - 전체 API 명세