메인 콘텐츠로 건너뛰기

API 응답에 새 필드가 추가됐을 때

목표: 기존 데이터에 없던 필드를 감지하고, 일반 필드와 민감 필드에 서로 다른 처리 정책을 명시적으로 적용합니다.
화면 버전: 표시된 이미지는 과거 Control UI 테스트 캡처입니다. 현재 제품의 기본 5단계 순서(Connect → Sample & Record Selection → Destinations → Route Processing → Deploy)를 우선하세요. 번호별 화면 가이드에서 차이를 설명합니다.

적용 순서

이 사례는 이미 구성된 Connector·Destination·Stream을 전제로 합니다. 아직 생성하지 않았다면 커넥터별 수집 가이드에서 먼저 수집 Source를 설정하세요. 이후 이 페이지의 구체적인 단계를 수행하고 실제 Logs와 Destination/격리 기록을 검증합니다. 화면 캡처는 기존 테스트 증빙으로, 실제 결과를 대신하지 않습니다.

1. 기존 데이터로 Baseline 확인

첫 Webhook 전송 또는 API 수집 실습을 완료합니다. 다음과 같은 가상 이벤트 여러 건을 입력합니다.
Sample & Record Selection → Record Selection에서 Event Root를 확정하고 Union Schema를 확인합니다. Union Schema는 선택한 이벤트 집합의 필드를 종합한 것이며, 한 개의 샘플 JSON만을 의미하지 않습니다. record-selection — numbered Control historical UI capture 그림 1. 레코드 경로와 Checkpoint 선택. ① 추천 Record Path를 검토하고 ② JSON Tree에서 실제 이벤트 필드를 확인한 다음 ③ Checkpoint Field를 지정합니다. 이 화면은 미확정 상태이므로 경고가 표시되어 있습니다.

2. 변경된 이벤트 추가

같은 Source로 아래 이벤트를 전송합니다.
샘플 재수집 또는 지원되는 런타임/Schema 화면에서 새 필드 경로와 출현 빈도를 확인합니다. 한 번 새 필드가 나왔다고 곧바로 Confirmed Drift로 판단하지 않습니다. Observed와 Confirmed 상태를 구분합니다.

3. 처리 정책 선택

  1. Stream Edit → Route Processing → Protection / Schema Drift Policy(또는 해당 Route Edit)로 이동합니다.
  2. 일반 Unknown Field의 기본 동작 Pass Through를 확인합니다. 필요할 때만 Require Review 또는 Quarantine을 선택합니다.
  3. 이메일, API Key처럼 민감할 수 있는 필드는 탐지 제안을 검토하고 명시적으로 보호/검토 동작을 선택합니다. 제안은 자동 정책 적용이 아닙니다.
  4. Stream의 Union Schema Baseline을 모든 Route가 공유하도록 유지하고, 목적지별 차이가 필요할 때만 Route Override를 사용합니다.
  5. 저장 후 Effective 설정과 정책 경고를 확인합니다.

4. 실제 결과 확인

새 ID를 가진 변경 이벤트를 다시 전송하여 Logs, Stream/Route 상세, Governance 기록, 수신 파일(또는 격리 기록)을 비교합니다. 완료 조건: 새 필드가 관측되며, 설정한 정책에 따라 필드 유지·보호·Review·Quarantine 중 실제 동작이 확인됩니다.

실패 시

  • 새 필드가 없음: 이벤트 수집 여부, Record Root, 다수 Sample 분석 여부 확인
  • 민감도 제안이 없음: 실제 Field Path와 탐지 설정 확인. 제안이 항상 나오는 것은 아닙니다.
  • 이벤트가 사라진 것처럼 보임: Quarantine, Policy, Logs를 확인합니다.
  • 정책과 달리 Pass Through: Draft 상태인지 Effective Route에 저장되었는지 확인합니다.
관련: Route별 보호, Quarantine·Replay.
마지막 수정일 2026년 10월 18일