> ## Documentation Index
> Fetch the complete documentation index at: https://docs.get-clara.tech/llms.txt
> Use this file to discover all available pages before exploring further.
# API로 데이터 가져오기
> 대규모 데이터 가져오기에 Twenty의 API를 언제, 어떻게 사용할지 안내합니다.
## 개요
Twenty는 프로그램 방식의 데이터 가져오기를 위해 **GraphQL** 및 **REST API**를 모두 제공합니다. 데이터 규모상 CSV 가져오기가 실용적이지 않거나 자동화된 반복 가져오기가 필요한 경우 API를 사용하세요.
## API 가져오기 사용 시기
| 시나리오 | 권장 방법 |
| -------------------- | ---------------- |
| 10,000개 미만의 레코드 | CSV 가져오기 |
| 10,000 - 50,000개 레코드 | CSV 가져오기(파일로 분할) |
| **50,000개 이상의 레코드** | **API 가져오기** |
| 1회성 마이그레이션 | 둘 다 가능(규모에 따라) |
| **반복 가져오기** | **API 가져오기** |
| **실시간 동기화** | **API 가져오기** |
| **다른 시스템과의 통합** | **API 가져오기** |
수십만 건 규모의 데이터셋의 경우, API가 여러 번의 CSV 가져오기보다 훨씬 빠르고 더 신뢰할 수 있습니다.
## API 속도 제한
시스템 안정성을 보장하기 위해 Twenty는 속도 제한을 적용합니다:
| 제한 | 값 |
| ---------------- | ------------- |
| **분당 요청 수** | 100 |
| **배치 호출당 레코드 수** | 60 |
| **최대 처리량** | \~6,000 레코드/분 |
**이 한도를 기준으로 가져오기 계획을 수립하세요.**
최대 처리량 기준으로 100,000개 레코드를 가져오는 데 약 17분이 소요됩니다. 오류 처리와 재시도를 위한 여유 시간을 추가하세요.
## 시작하기
### 1단계: API 키 받기
1. **설정 → 개발자**로 이동하세요.
2. **+ API 키 생성**을 클릭하세요.
3. 키에 설명적인 이름을 지정하세요.
4. API 키를 즉시 복사하세요(다시 표시되지 않습니다).
5. 안전하게 보관하세요.
**API 키를 비공개로 유지하세요.**
API 키를 가진 누구나 워크스페이스 데이터에 접근하고 수정할 수 있습니다. 코드 저장소에 커밋하거나 공개적으로 공유하지 마세요.
### 2단계: 사용할 API 선택
Twenty는 두 가지 유형의 API를 지원합니다:
| API | 적합한 용도 | 문서 |
| ----------- | ----------------------------- | ------------------------------ |
| **GraphQL** | 유연한 쿼리, 연관 데이터 조회, 복잡한 작업에 적합 | [API 문서](/l/ko/developers/api) |
| **REST** | 단순한 CRUD 작업, 익숙한 REST 패턴 | [API 문서](/l/ko/developers/api) |
두 API 모두 다음을 지원합니다:
* 레코드 생성, 조회, 업데이트 및 삭제
* **배치 작업** — 호출당 최대 60개 레코드를 생성하거나 업데이트
**가져오기에서는 배치 작업을 사용**하여 한도 내에서 처리량을 극대화하세요.
### 3단계: 가져오기 순서 계획
CSV 가져오기와 마찬가지로, 관계형 데이터에서는 **순서가 중요**합니다:
1. **회사** 먼저(종속성 없음)
2. 그다음 **사람**(회사에 연결 가능)
3. 세 번째로 **기회**(회사 및 사람에 연결 가능)
4. **작업/노트**(위 항목 중 어느 것에도 연결 가능)
5. **사용자 지정 객체**(종속성을 따름)
## 모범 사례
### 요청 일괄 처리
* 레코드를 한 번에 하나씩 보내지 마세요
* API 호출당 최대 **60개 레코드**로 묶으세요
* 이렇게 하면 한도 내에서 처리량을 극대화할 수 있습니다
### 속도 제한 처리
* 요청 사이에 지연을 구현하세요(지속적인 가져오기의 경우 최소 600ms)
* 한도에 도달하면 지수 백오프를 사용하세요
* 429(Too Many Requests) 응답을 모니터링하세요
### 먼저 데이터 검증
* 가져오기 전에 데이터를 정리하고 검증하세요
* 필수 필드가 채워졌는지 확인하세요
* 형식이 Twenty의 요구 사항과 일치하는지 확인하세요([필드 매핑](/l/ko/user-guide/data-migration/capabilities/field-mapping) 참조)
### 모든 항목 로깅
* 가져온 모든 레코드를 로깅하세요(ID 포함)
* 전체 컨텍스트와 함께 오류를 로깅하세요
* 이는 문제를 디버깅하고 완료 여부를 확인하는 데 도움이 됩니다
### 먼저 테스트
* 소량 배치(10-20개 레코드)로 테스트하세요
* 데이터가 Twenty에 올바르게 표시되는지 확인하세요
* 그런 다음 전체 가져오기를 실행하세요
### 중복 방지를 위한 업서트
GraphQL API는 **배치 업서트**를 지원합니다 — 레코드가 있으면 업데이트하고, 없으면 생성합니다. 이렇게 하면 가져오기를 다시 실행할 때 중복을 방지할 수 있습니다.
## 객체 및 필드 이름 찾기
사용 가능한 객체와 필드를 확인하려면:
1. **설정 → API 및 웹훅**으로 이동하세요
2. **Metadata API**를 살펴보세요
3. 모든 표준 및 사용자 지정 객체와 해당 필드를 확인하세요
문서에는 모든 표준 및 사용자 지정 객체, 해당 필드, 예상 데이터 유형이 표시됩니다.
## 전문 서비스
복잡한 API 마이그레이션의 경우, 파트너가 도와드립니다:
| 서비스 | 포함 내용 |
| --------------- | ------------------ |
| **데이터 모델 설계** | 최적의 데이터 구조를 설계 |
| **마이그레이션 스크립트** | 가져오기 스크립트를 작성하고 실행 |
| **데이터 변환** | 복잡한 매핑과 정리를 수행 |
| **검증 및 QA** | 마이그레이션이 완료되었는지 확인 |
**적합한 용도:**
* 100,000개 이상의 레코드 마이그레이션
* 복잡한 데이터 변환
* 빠듯한 일정
* 개발 리소스가 없는 팀
[contact@twenty.com](mailto:contact@twenty.com)으로 문의하시거나 당사의 [구현 서비스](/l/ko/user-guide/getting-started/capabilities/implementation-services)를 확인하세요.
## FAQ
GraphQL은 단일 쿼리로 필요한 데이터만 정확히 요청할 수 있으며, 복잡한 작업에 더 적합합니다. REST는 표준 HTTP 메서드(GET, POST, PUT, DELETE)를 사용하며, 기존 API로 작업해 본 경험이 있다면 더 익숙할 수 있습니다.
예! 레코드의 `id`와 함께 업데이트 뮤테이션(GraphQL) 또는 PUT/PATCH 요청(REST)을 사용하세요.
고유 식별자(이메일, 도메인)를 사용해 먼저 기존 레코드를 조회하세요. 존재하면 업데이트하고, 없으면 생성하세요.
예, 삭제 뮤테이션(GraphQL) 또는 DELETE 요청(REST)을 사용하세요.
현재는 없습니다. 하지만 두 API는 어떤 언어의 HTTP 클라이언트와도 작동합니다.
## API 문서
전체 구현 세부정보, 코드 예제, 스키마 참조는 다음을 확인하세요:
* [API 문서](/l/ko/developers/api)