> ## Documentation Index
> Fetch the complete documentation index at: https://control.datarelay.run/llms.txt
> Use this file to discover all available pages before exploring further.

# HTTP API 데이터 수집

> 실제 Vendor API 연결부터 샘플 선택·페이지 처리·Checkpoint·전송 검증까지 안내합니다.

# HTTP API에서 이벤트 수집하기

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

> [!NOTE]
>
> **화면 버전:** 표시된 이미지는 과거 Control UI 테스트 캡처입니다. 현재 제품의 기본 5단계 순서(Connect → Sample & Record Selection → Destinations → Route Processing → Deploy)를 우선하세요. [번호별 화면 가이드](https://control.datarelay.run/ko/use-cases/screen-walkthrough.md)에서 차이를 설명합니다.

## 실행 순서와 완료 기준

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](https://control.datarelay.run/ko/use-cases/delivery-incident.md)를, 필드 변경은 [Schema Drift](https://control.datarelay.run/ko/use-cases/schema-change.md)를 확인합니다.

### ChatGPT 질문 예시

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

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

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

| 항목 | 예시 | 설정 위치 |
| - | - | - |
| Base URL | `https://vendor.example.invalid` | Connector의 **Host / Base URL** |
| API 경로 | `/v1/audit/events` | Connect/Run Test의 Request Path |
| 인증 | Vendor 문서상의 API Key 또는 Bearer | Credential/Auth |
| 이벤트 배열 | `$.events` | 실제 응답에서 해당 경로가 존재하는 경우 Record Selection |
| 커서 | `event_time` | 해당 필드가 안정적·단조증가하는 경우만 Checkpoint |

## 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라면 잘못된 증분 수집을 강행하지 않습니다.

![select-connector — numbered Control historical UI capture](https://mintcdn.com/datarelay-control/Tl9_UibGAprPlCr8/images/screenshots/annotated/select-connector.webp?fit=max\&auto=format\&n=Tl9_UibGAprPlCr8\&q=85\&s=595bbed2cfdba81a0a246ed84116cc33)

*그림 1. **기존 Connector를 선택하는 화면.** ① Saved Connector 목록에서 미리 만든 Connector를 선택합니다(캡처의 Generic REST는 예시). ② 다음 Sample 단계로 이동합니다. 상단 Connector 탭은 이미 선택된 상태입니다.*

![run-test — numbered Control historical UI capture](https://mintcdn.com/datarelay-control/Tl9_UibGAprPlCr8/images/screenshots/annotated/run-test.webp?fit=max\&auto=format\&n=Tl9_UibGAprPlCr8\&q=85\&s=b608f03405b24c6b130a215599571177)

*그림 2. **실제 수집 테스트와 레코드 수 확인.** ① Run Test 실행 → ② HTTP 상태와 추출 레코드 수 확인 → ③ 성공하면 Record Selection으로 이동합니다. API 호출 성공만으로 Destination 전송이 증명되지는 않습니다.*

![record-selection — numbered Control historical UI capture](https://mintcdn.com/datarelay-control/Tl9_UibGAprPlCr8/images/screenshots/annotated/record-selection.webp?fit=max\&auto=format\&n=Tl9_UibGAprPlCr8\&q=85\&s=196de1ecaf541296095434008afc05ad)

*그림 3. **레코드 경로와 Checkpoint 선택.** ① 추천 Record Path를 검토하고 ② JSON Tree에서 실제 이벤트 필드를 확인한 다음 ③ Checkpoint Field를 지정합니다. 이 화면은 미확정 상태이므로 경고가 표시되어 있습니다.*

## 3. Destination 연결 및 배포

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

![field-mapping — numbered Control historical UI capture](https://mintcdn.com/datarelay-control/Tl9_UibGAprPlCr8/images/screenshots/annotated/field-mapping.webp?fit=max\&auto=format\&n=Tl9_UibGAprPlCr8\&q=85\&s=15ae79d8a5249262f236f997f253d286)

*그림 4. **원본 이벤트를 대상 필드로 매핑.** ① Sample Event의 원본값 확인 → ② Field Mapping에서 대상 필드 매핑 → ③ Final Event Preview의 출력값 비교. Preview는 실제 전송 증빙이 아닙니다.*

![stream-actions — numbered Control historical UI capture](https://mintcdn.com/datarelay-control/Tl9_UibGAprPlCr8/images/screenshots/annotated/stream-actions.webp?fit=max\&auto=format\&n=Tl9_UibGAprPlCr8\&q=85\&s=f5462ebde85e05d0c95ab32096a1a24e)

*그림 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라면 커서 전략을 수정해야 합니다.

## 문제 해결

| 증상 | 확인할 항목 |
| - | - |
| 401/403 | Credential, Token 만료, Vendor 권한 |
| 429/Timeout | 호출 제한, Backoff, Connector/API Health |
| API 응답은 오지만 레코드가 0건 | JSON Envelope, Event Root, 요청 필터 |
| 동일 이벤트 반복 수집 | Cursor/Checkpoint, 정렬 기준 |
| 수집은 됐으나 전송 실패 | Route, Destination, Policy/Protection, Logs |

**완료 조건:** 신규 이벤트가 독립 Destination에 저장되고, 그 이벤트의 Route 전송 로그와 Checkpoint 동작이 일치합니다.

**관련:** [Schema 변경](https://control.datarelay.run/ko/use-cases/schema-change.md), [전송 장애](https://control.datarelay.run/ko/use-cases/delivery-incident.md).

![source-api-error — numbered Control historical UI capture](https://mintcdn.com/datarelay-control/Tl9_UibGAprPlCr8/images/screenshots/annotated/source-api-error.webp?fit=max\&auto=format\&n=Tl9_UibGAprPlCr8\&q=85\&s=c66a05ef28da079c34e48a36ed217113)

*그림 6. **Source API가 HTTP 503을 반환한 경우.** ① HTTP 503 응답과 오류 메시지 확인 → ② Source/API 문제를 고친 뒤 Retry → ③ 다음 단계가 차단된 상태에서는 진행하지 않습니다. 이 화면은 Destination 장애가 아닌 Source API Test 실패입니다.*


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.