​

HTTP API에서 이벤트 수집하기

목표: 제품의 HTTP API Polling Connector로 이벤트를 수집해 일반 Stream/Route를 통해 Destination으로 전송합니다.

​

실행 순서와 완료 기준

1. 필수 정보 준비: Vendor 공식 API/연동 가이드에서 Endpoint, 인증 방식, 최소 권한, Pagination/Checkpoint, 응답 샘플을 확인합니다. 테스트용 비식별 이벤트와 실제 Destination 접속 정보를 준비합니다.
2. 모르는 항목은 ChatGPT로 정리: 공개 API 문서와 비식별 샘플을 제공하고 Connector 필수 필드, 요청 예시, Event Root, Timestamp/ID, Cursor, 미확인 사항을 표로 요청합니다. Token·비밀번호는 입력하지 않습니다. ChatGPT 답변은 Vendor 문서와 Run Test로 검증합니다.
3. Connector 생성: Connectors → Create Connector에서 이 페이지의 해당 Source Type을 선택하고 실제 접속·인증 정보를 입력합니다. 저장하고 연결 테스트를 확인합니다.
4. Destination 생성: Destinations → Create에서 실제 수신기 유형(SYSLOG_UDP/TCP/TLS 또는 WEBHOOK_POST)을 선택하고 Host/Port/URL, TLS/인증을 입력합니다.
5. Stream 생성: Streams → Create → Connect에서 Connector를 선택하고 Source 요청/수집 조건을 지정합니다.
6. 샘플과 스키마: Sample & Record Selection → Run Test에서 실제 레코드가 추출되는지 확인합니다. Record Root, Union Schema, Pagination 및 Checkpoint를 확정합니다.
7. 데이터 처리: Destinations에서 Route를 연결하고 Route Processing에서 Mapping, Timestamp, Enrichment, Masking/Drop/Quarantine을 설정합니다. Tokenization은 실제 제품에서 지원되는 경우에만 사용합니다. Route Effective Status와 최종 출력값을 확인합니다.
8. 배포와 검증: Deploy의 경고를 해결하고 Stream을 실행합니다. Run ID, Route Logs와 실제 Destination 수신 기록을 비교합니다. 이 세 가지가 일치해야 완료입니다.
9. 장애 대응: 연결/인증 오류는 API 권한·TLS·Network·429를, 레코드 0건은 Record Root·Pagination을, 전송 실패는 Delivery Incident를, 필드 변경은 Schema Drift를 확인합니다.

​

ChatGPT 질문 예시

DataRelay Control에서 이 제품의 로그를 수집하려고 합니다. 아래 공개 API 가이드와 비식별 JSON 샘플을 기준으로 Connector 연결·인증 필수값, API Request/Pagination, Event Root, Timestamp/ID/Checkpoint, Mapping·민감 필드 보호, 장애 시 확인 항목을 표로 작성해 주세요. 문서에 없는 정보는 임의로 생성하지 말고 ‘확인 필요’로 표시하세요.

​

API 소유자에게 먼저 확보할 정보

실제로 접근 가능한 Base URL, 요청 경로/Method, 인증 방식, 개인정보가 제거된 응답 샘플, Pagination, 이벤트 순서 및 Cursor/Checkpoint 정의가 필요합니다. 아래 주소는 실제로 동작하는 API가 아닌 설명용입니다.

​

1. Connector 만들기

1. Connectors → Create Connector로 이동하여 HTTP API Polling을 선택합니다.
2. Connector Name, 실제 Host / Base URL을 입력합니다.
3. Vendor가 지원하는 인증 방식을 선택하고 Credential을 구성합니다. Secret을 공개 YAML이나 샘플 JSON에 넣지 않습니다.
4. Connector를 저장한 뒤 연결 테스트 기능이 제공되면 실제 응답/TLS/권한을 검증합니다.

​

2. 수집 방법 지정

1. /streams/new를 열고 Connect에서 앞의 Connector를 선택합니다.
2. 실제 Endpoint, HTTP Method, Query Parameter를 설정합니다.
3. Vendor 문서에 따라 Page/Offset/Cursor 방식의 Pagination을 설정합니다. 제품마다 방식이 다르므로 임의로 추정하지 않습니다.
4. Sample & Record Selection → Run Test에서 API 호출을 수행하고 HTTP Status와 응답 JSON을 확인합니다.
5. Record Selection에서 실제 이벤트 배열을 지정합니다. {"events":[...]} 구조가 확인될 때만 $.events를 선택하고 추출 건수를 검증합니다.
6. Union Schema에서 필수/드문 필드와 민감 필드 제안을 검토합니다. 자동 제안한 Record Path와 Checkpoint는 사용자 확인 후 사용합니다.
7. 이벤트 진행 상태에 사용할 Checkpoint Mode와 Field를 구성합니다. 안정적인 Cursor가 없는 API라면 잘못된 증분 수집을 강행하지 않습니다.

그림 1. 기존 Connector를 선택하는 화면. ① Saved Connector 목록에서 미리 만든 Connector를 선택합니다(캡처의 Generic REST는 예시). ② 다음 Sample 단계로 이동합니다. 상단 Connector 탭은 이미 선택된 상태입니다. 그림 2. 실제 수집 테스트와 레코드 수 확인. ① Run Test 실행 → ② HTTP 상태와 추출 레코드 수 확인 → ③ 성공하면 Record Selection으로 이동합니다. API 호출 성공만으로 Destination 전송이 증명되지는 않습니다. 그림 3. 레코드 경로와 Checkpoint 선택. ① 추천 Record Path를 검토하고 ② JSON Tree에서 실제 이벤트 필드를 확인한 다음 ③ Checkpoint Field를 지정합니다. 이 화면은 미확정 상태이므로 경고가 표시되어 있습니다.

​

3. Destination 연결 및 배포

1. Destinations에서 기존 목적지를 선택합니다. 독립 검증이 필요하면 테스트 수신기를 사용합니다.
2. Route Processing에서 Transform, 필요한 Data Protection, Preview를 확인합니다.
3. Deploy의 차단 경고를 해결한 후 배포하고, 필요 시 Stream을 시작합니다.
4. 실제 수집 Run을 수행하여 Logs의 Route 결과와 Destination 수신 기록을 모두 확인합니다.

그림 4. 원본 이벤트를 대상 필드로 매핑. ① Sample Event의 원본값 확인 → ② Field Mapping에서 대상 필드 매핑 → ③ Final Event Preview의 출력값 비교. Preview는 실제 전송 증빙이 아닙니다. 그림 5. Stream 생성 후 실행 및 로그 확인. ① Stream 생성 결과 확인 → ② 실제 Runtime이 정상일 때 Start Stream → ③ View logs에서 Run과 Route 결과 확인. 캡처에는 Runtime API unavailable이 표시되므로 실제 전송 성공 증거는 아닙니다.

​

4. 증분 수집의 정확도 확인

• Run ID, 수집 이벤트 ID/시간 범위, 실행 전 Checkpoint를 기록합니다.
• 새 이벤트가 없는 상태에서 다음 주기를 실행하고 예상치 못한 중복이 없는지 확인합니다.
• 테스트 가능한 Vendor API라면 새 가상 이벤트를 추가하고 수집·전송·Checkpoint 갱신을 검증합니다.
• 필요한 Destination 전달이 성공하기 전에는 Checkpoint가 전진하지 않아야 합니다.
• Timestamp 중복/순서 변경이 있는 API라면 커서 전략을 수정해야 합니다.

​

문제 해결

완료 조건: 신규 이벤트가 독립 Destination에 저장되고, 그 이벤트의 Route 전송 로그와 Checkpoint 동작이 일치합니다. 관련: Schema 변경, 전송 장애. 그림 6. Source API가 HTTP 503을 반환한 경우. ① HTTP 503 응답과 오류 메시지 확인 → ② Source/API 문제를 고친 뒤 Retry → ③ 다음 단계가 차단된 상태에서는 진행하지 않습니다. 이 화면은 Destination 장애가 아닌 Source API Test 실패입니다.