---
title: 동기화 API
description: 소스 동기화를 시작하고, 이벤트 스트림을 추적하고, 안전하게 다시 연결하며, 수락된 작업과 최종 상태를 구분합니다.
species: reference
---
# 동기화 API

동기화를 시작하려면 `apps:manage`가 필요합니다. 진행 상황 스트림을 읽으려면 `data:read`가 필요합니다.

## 동기화 시작

```endpoint
POST /sources/{id}/sync
```

소스의 동기화 요청을 수락하고 비동기 리소스를 반환합니다. 수락은 요청이 기록되었다는 뜻이며 테이블 커밋이 완료되었다는 뜻은 아닙니다.

일시 중지되었거나 삭제된 소스는 거부합니다. 소스에 이미 진행 중인 작업이 있으면 중복 실행을 시작하지 않고 충돌을 보고합니다.

응답 유실 후 재시도할 때는 `Idempotency-Key`를 사용하세요. 키를 하나의 소스와 요청 본문에 연결하세요.

## 진행 상황 스트리밍

```endpoint
GET /sources/{id}/sync/stream
```

Server-Sent Events 스트림은 진행 상황과 영구 저장된 동기화 결과를 보고합니다. 연결이 닫히면 `Last-Event-ID`를 사용하여 다시 연결하세요. 재연결 후에는 소스 리소스의 최신 동기화를 최종 기준으로 삼으세요.

이벤트에는 테이블 이름, 단계, 완료 및 전체 개수, 최종 결과가 포함될 수 있습니다. 클라이언트는 추가되는 이벤트 필드를 무시해야 합니다.

## 완료 후

성공한 최종 이벤트는 실행의 테이블 커밋이 완료되었다는 뜻입니다. 관련 테이블은 서로 다른 시점에 완료될 수 있으므로 최신성에 민감한 자동화는 최종 상태 이후 커밋된 `_synced_at` 값이나 카탈로그를 확인해야 합니다.

실행이 실패하면 [소스 오류 로그](/docs/api/logs)를 확인하세요. 병합과 삭제의 의미는 [동기화](/docs/concepts/syncing)를 참고하세요.