개요
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 레코드/분 |
시작하기
1단계: API 키 받기
- 설정 → 개발자로 이동하세요.
- + API 키 생성을 클릭하세요.
- 키에 설명적인 이름을 지정하세요.
- API 키를 즉시 복사하세요(다시 표시되지 않습니다).
- 안전하게 보관하세요.
2단계: 사용할 API 선택
Twenty는 두 가지 유형의 API를 지원합니다: 두 API 모두 다음을 지원합니다:- 레코드 생성, 조회, 업데이트 및 삭제
- 배치 작업 — 호출당 최대 60개 레코드를 생성하거나 업데이트
3단계: 가져오기 순서 계획
CSV 가져오기와 마찬가지로, 관계형 데이터에서는 순서가 중요합니다:- 회사 먼저(종속성 없음)
- 그다음 사람(회사에 연결 가능)
- 세 번째로 기회(회사 및 사람에 연결 가능)
- 작업/노트(위 항목 중 어느 것에도 연결 가능)
- 사용자 지정 객체(종속성을 따름)
모범 사례
요청 일괄 처리
- 레코드를 한 번에 하나씩 보내지 마세요
- API 호출당 최대 60개 레코드로 묶으세요
- 이렇게 하면 한도 내에서 처리량을 극대화할 수 있습니다
속도 제한 처리
- 요청 사이에 지연을 구현하세요(지속적인 가져오기의 경우 최소 600ms)
- 한도에 도달하면 지수 백오프를 사용하세요
- 429(Too Many Requests) 응답을 모니터링하세요
먼저 데이터 검증
- 가져오기 전에 데이터를 정리하고 검증하세요
- 필수 필드가 채워졌는지 확인하세요
- 형식이 Twenty의 요구 사항과 일치하는지 확인하세요(필드 매핑 참조)
모든 항목 로깅
- 가져온 모든 레코드를 로깅하세요(ID 포함)
- 전체 컨텍스트와 함께 오류를 로깅하세요
- 이는 문제를 디버깅하고 완료 여부를 확인하는 데 도움이 됩니다
먼저 테스트
- 소량 배치(10-20개 레코드)로 테스트하세요
- 데이터가 Twenty에 올바르게 표시되는지 확인하세요
- 그런 다음 전체 가져오기를 실행하세요
중복 방지를 위한 업서트
GraphQL API는 배치 업서트를 지원합니다 — 레코드가 있으면 업데이트하고, 없으면 생성합니다. 이렇게 하면 가져오기를 다시 실행할 때 중복을 방지할 수 있습니다.객체 및 필드 이름 찾기
사용 가능한 객체와 필드를 확인하려면:- 설정 → API 및 웹훅으로 이동하세요
- Metadata API를 살펴보세요
- 모든 표준 및 사용자 지정 객체와 해당 필드를 확인하세요
전문 서비스
복잡한 API 마이그레이션의 경우, 파트너가 도와드립니다:| 서비스 | 포함 내용 |
|---|---|
| 데이터 모델 설계 | 최적의 데이터 구조를 설계 |
| 마이그레이션 스크립트 | 가져오기 스크립트를 작성하고 실행 |
| 데이터 변환 | 복잡한 매핑과 정리를 수행 |
| 검증 및 QA | 마이그레이션이 완료되었는지 확인 |
- 100,000개 이상의 레코드 마이그레이션
- 복잡한 데이터 변환
- 빠듯한 일정
- 개발 리소스가 없는 팀
FAQ
GraphQL과 REST의 차이는 무엇인가요?
GraphQL과 REST의 차이는 무엇인가요?
GraphQL은 단일 쿼리로 필요한 데이터만 정확히 요청할 수 있으며, 복잡한 작업에 더 적합합니다. REST는 표준 HTTP 메서드(GET, POST, PUT, DELETE)를 사용하며, 기존 API로 작업해 본 경험이 있다면 더 익숙할 수 있습니다.
API를 통해 기존 레코드를 업데이트할 수 있나요?
API를 통해 기존 레코드를 업데이트할 수 있나요?
예! 레코드의
id와 함께 업데이트 뮤테이션(GraphQL) 또는 PUT/PATCH 요청(REST)을 사용하세요.중복은 어떻게 처리하나요?
중복은 어떻게 처리하나요?
고유 식별자(이메일, 도메인)를 사용해 먼저 기존 레코드를 조회하세요. 존재하면 업데이트하고, 없으면 생성하세요.
API를 통해 레코드를 삭제할 수 있나요?
API를 통해 레코드를 삭제할 수 있나요?
예, 삭제 뮤테이션(GraphQL) 또는 DELETE 요청(REST)을 사용하세요.
Python 또는 Node.js SDK가 있나요?
Python 또는 Node.js SDK가 있나요?
현재는 없습니다. 하지만 두 API는 어떤 언어의 HTTP 클라이언트와도 작동합니다.