데이터 스트림에 연결하고 데이터 소비

다음 단계에 따라 데이터 스트림에 접속하고 데이터를 소비합니다.

1단계: WebSocket URL 작성

생성된 AsyncAPI YAML에서 다음 값을 읽습니다.

servers.<name>.protocol: ws 또는 wss.
servers.<name>.host: 호스트 이름 및 포트(있는 경우)
channels.<name>.address: 데이터 스트림에 대한 전체 WebSocket 경로입니다.

wss://<server-host><channel-address>?begin=<percent-encoded-begin-value>

경로를 하드 코딩하지 마십시오. OCI GoldenGate, 온프레미스 배포, 리버스 프록시가 다양한 라우팅 접두어를 노출할 수 있습니다. 생성된 YAML 또는 REST API에서 반환된 정식 링크에서 호스트 및 채널 주소를 복사합니다.

2단계: 시작 값 선택

다음 표에 제공된 지침에 따라 BEGIN 값을 지정합니다.

값	사용	지침
`now`	새 활동으로 시작	현재 시간 기록으로 변환되어 사용 가능한 추적에 대해 해결되었습니다. 해결된 점 이전의 변경 사항은 전달되지 않습니다.
`earliest`	사용 가능한 트레일에서 초기 백필	시간 기록 0으로 변환되었습니다. 배달은 구성된 추적에서 계속 사용할 수 있는 가장 이른 레코드에서 시작되며 소스 기록의 시작일 필요는 없습니다.
ISO 8601 시간 기록	비즈니스 시간 경계 근처에서 시작	서비스는 시간 기록 기반 조회를 수행합니다. 명시적 시간대(예: `2026-07-13T04:00:00Z`)를 사용합니다.
저장된 `pos`	이전 실행 성공 후 복구	이 서비스는 위치 기반 조회를 수행합니다. 위치를 사용할 수 없는 경우의 결과는 서비스 품질에 따라 달라집니다.

시작 값 퍼센트 인코딩

pos 토큰은 URL에 특별한 의미를 가지는 +, / 및 =와 같은 문자를 포함할 수 있습니다. 질의 문자열에 추가하기 전에 전체 토큰을 퍼센트 인코딩합니다. 응용 프로그램 논리에서 토큰을 수정하거나 디코딩하지 마십시오.

3단계: 인증 및 TLS

인증 방식을 선택합니다. 다음 표를 사용하여 가장 적합한 방법을 결정합니다.

모드	사용 시기	클라이언트 응답
기본 승인	직접 노출된 서비스 또는 역 프록시의 공통	`Authorization: Basic ...` 헤더를 보냅니다. 자격 증명은 URL이나 소스 코드가 아닌 암호 저장소 또는 환경 삽입에 보관합니다.
다이제스트 인증	역 프록시에서 필요한 경우	WebSocket 핸드셰이크 중 HTTP 다이제스트 시도를 구현하는 클라이언트 또는 생성된 템플리트를 사용합니다.
클라이언트 인증서	상호 TLS 또는 인증서 기반 서비스 인증	클라이언트 인증서 및 개인 키를 TLS 컨텍스트로 로드하고 구성된 CA에 대해 서버를 검증합니다.
보안 역 프록시	게이트웨이가 TLS를 종료하거나 전달합니다.	프록시 인증 모드를 따릅니다. 보안 프록시에는 기본/다이제스트 자격 증명과 클라이언트 인증서가 모두 필요할 수 있습니다.

4단계: AsyncAPI에서 클라이언트 생성

Oracle은 AsyncAPI 생성기에 대한 WebSocket 클라이언트 템플리트를 제공합니다. JavaScript, Python, Java, Go 또는 지원되는 모든 클라이언트를 생성할 수 있습니다. 생성기에는 Node.js 18.12 이상 및 npm 8.19 이상이 필요합니다.

npm install -g @asyncapi/generator

git clone https://github.com/oracle-samples/websocket-client-template.git
cd websocket-client-template

ag /path/to/sales-orders.yaml .
  -o output
  -p server=production
  -p language=python
  -p authorization=basic

cd output
python -m pip install -r requirements.txt
export ASYNCAPI_WS_CLIENT_USERNAME="$OGG_USER"
export ASYNCAPI_WS_CLIENT_PASSWORD="$OGG_PASSWORD"
python client.py

이 템플리트는 인증서 변수 ASYNCAPI_WS_CLIENT_CERT, ASYNCAPI_WS_CLIENT_KEY 및 ASYNCAPI_WS_CA_CERT도 지원합니다. 조직의 일반적인 보안 소프트웨어 개발 프로세스에서 생성된 코드 및 종속성 버전을 검토합니다.

5단계: WebSocket 메시지 이해

일반적인 메시지 페이로드는 JSON 배열입니다. 프레임은 하나 이상의 스키마, 메타 데이터, DML 또는 DDL 레코드를 포함할 수 있습니다. 클라이언트는 배열을 반복하고 각 객체를 독립적으로 분류해야 합니다.

백프레스: 서비스가 레코드별 클라이언트 확인 없이 레코드를 푸시합니다. 수신 루프를 가볍게 유지합니다. 느린 비즈니스 처리를 제한된 내부 대기열 또는 내구성이 뛰어난 스테이징 계층 뒤에 두고, 대기열 깊이를 모니터링하고, 메모리가 소진되기 전에 소비자를 중지하거나 확장합니다.

6단계: 소비자 처리 루프

전체 WebSocket 메시지를 수신합니다.
JSON 배열의 구문을 분석합니다. CloudEvents가 사용으로 설정된 경우 data 멤버의 래핑을 해제합니다.
스키마, 스트림 메타데이터, 객체 메타데이터, DML 및 DDL 레코드를 분류합니다.
검증이 필요한 경우 최신 캐시된 스키마에 대해 레코드를 검증합니다.
비즈니스 작업을 적용하거나 영구 다운스트림 시스템에 게시합니다.
작업이 성공하면 선택한 원자 또는 멱등 체크포인트 설계를 사용하여 pos 레코드를 저장합니다.
연결 손실 시 마지막 지속 pos 및 지수 백오프와 다시 연결합니다.