Skip to main content

​
개요

Twenty는 프로그램 방식의 데이터 가져오기를 위해 GraphQL 및 REST API를 모두 제공합니다. 데이터 규모상 CSV 가져오기가 실용적이지 않거나 자동화된 반복 가져오기가 필요한 경우 API를 사용하세요.

​
API 가져오기 사용 시기

수십만 건 규모의 데이터셋의 경우, API가 여러 번의 CSV 가져오기보다 훨씬 빠르고 더 신뢰할 수 있습니다.

​
API 속도 제한

시스템 안정성을 보장하기 위해 Twenty는 속도 제한을 적용합니다:
이 한도를 기준으로 가져오기 계획을 수립하세요.최대 처리량 기준으로 100,000개 레코드를 가져오는 데 약 17분이 소요됩니다. 오류 처리와 재시도를 위한 여유 시간을 추가하세요.

​
시작하기

​
1단계: API 키 받기

  1. 설정 → 개발자로 이동하세요.
  2. + API 키 생성을 클릭하세요.
  3. 키에 설명적인 이름을 지정하세요.
  4. API 키를 즉시 복사하세요(다시 표시되지 않습니다).
  5. 안전하게 보관하세요.
API 키를 비공개로 유지하세요.API 키를 가진 누구나 워크스페이스 데이터에 접근하고 수정할 수 있습니다. 코드 저장소에 커밋하거나 공개적으로 공유하지 마세요.

​
2단계: 사용할 API 선택

Twenty는 두 가지 유형의 API를 지원합니다: 두 API 모두 다음을 지원합니다:
  • 레코드 생성, 조회, 업데이트 및 삭제
  • 배치 작업 — 호출당 최대 60개 레코드를 생성하거나 업데이트
가져오기에서는 배치 작업을 사용하여 한도 내에서 처리량을 극대화하세요.

​
3단계: 가져오기 순서 계획

CSV 가져오기와 마찬가지로, 관계형 데이터에서는 순서가 중요합니다:
  1. 회사 먼저(종속성 없음)
  2. 그다음 사람(회사에 연결 가능)
  3. 세 번째로 기회(회사 및 사람에 연결 가능)
  4. 작업/노트(위 항목 중 어느 것에도 연결 가능)
  5. 사용자 지정 객체(종속성을 따름)

​
모범 사례

​
요청 일괄 처리

  • 레코드를 한 번에 하나씩 보내지 마세요
  • API 호출당 최대 60개 레코드로 묶으세요
  • 이렇게 하면 한도 내에서 처리량을 극대화할 수 있습니다

​
속도 제한 처리

  • 요청 사이에 지연을 구현하세요(지속적인 가져오기의 경우 최소 600ms)
  • 한도에 도달하면 지수 백오프를 사용하세요
  • 429(Too Many Requests) 응답을 모니터링하세요

​
먼저 데이터 검증

  • 가져오기 전에 데이터를 정리하고 검증하세요
  • 필수 필드가 채워졌는지 확인하세요
  • 형식이 Twenty의 요구 사항과 일치하는지 확인하세요(필드 매핑 참조)

​
모든 항목 로깅

  • 가져온 모든 레코드를 로깅하세요(ID 포함)
  • 전체 컨텍스트와 함께 오류를 로깅하세요
  • 이는 문제를 디버깅하고 완료 여부를 확인하는 데 도움이 됩니다

​
먼저 테스트

  • 소량 배치(10-20개 레코드)로 테스트하세요
  • 데이터가 Twenty에 올바르게 표시되는지 확인하세요
  • 그런 다음 전체 가져오기를 실행하세요

​
중복 방지를 위한 업서트

GraphQL API는 배치 업서트를 지원합니다 — 레코드가 있으면 업데이트하고, 없으면 생성합니다. 이렇게 하면 가져오기를 다시 실행할 때 중복을 방지할 수 있습니다.

​
객체 및 필드 이름 찾기

사용 가능한 객체와 필드를 확인하려면:
  1. 설정 → API 및 웹훅으로 이동하세요
  2. Metadata API를 살펴보세요
  3. 모든 표준 및 사용자 지정 객체와 해당 필드를 확인하세요
문서에는 모든 표준 및 사용자 지정 객체, 해당 필드, 예상 데이터 유형이 표시됩니다.

​
전문 서비스

복잡한 API 마이그레이션의 경우, 파트너가 도와드립니다: 적합한 용도:
  • 100,000개 이상의 레코드 마이그레이션
  • 복잡한 데이터 변환
  • 빠듯한 일정
  • 개발 리소스가 없는 팀
contact@twenty.com으로 문의하시거나 당사의 구현 서비스를 확인하세요.

​
FAQ

GraphQL은 단일 쿼리로 필요한 데이터만 정확히 요청할 수 있으며, 복잡한 작업에 더 적합합니다. REST는 표준 HTTP 메서드(GET, POST, PUT, DELETE)를 사용하며, 기존 API로 작업해 본 경험이 있다면 더 익숙할 수 있습니다.
예! 레코드의 id와 함께 업데이트 뮤테이션(GraphQL) 또는 PUT/PATCH 요청(REST)을 사용하세요.
고유 식별자(이메일, 도메인)를 사용해 먼저 기존 레코드를 조회하세요. 존재하면 업데이트하고, 없으면 생성하세요.
예, 삭제 뮤테이션(GraphQL) 또는 DELETE 요청(REST)을 사용하세요.
현재는 없습니다. 하지만 두 API는 어떤 언어의 HTTP 클라이언트와도 작동합니다.

​
API 문서

전체 구현 세부정보, 코드 예제, 스키마 참조는 다음을 확인하세요: