Félix Malfait
882e9fd231
## Summary - Restructures the developer Extend documentation: moves API and Webhooks to top-level pages, creates dedicated Apps section with Getting Started, Building, and Publishing pages - Updates navigation structure (`docs.json`, `base-structure.json`, `navigation.template.json`) - Updates translated docs for all locales and LLMS.md references across app packages ## Test plan - [ ] Run `mintlify dev` locally and verify navigation structure - [ ] Check that all links in the Extend section work correctly - [ ] Verify translated pages render properly Made with [Cursor](https://cursor.com) --------- Co-authored-by: github-actions <github-actions@twenty.com>
177 lines
7.5 KiB
Plaintext
177 lines
7.5 KiB
Plaintext
---
|
|
title: API로 데이터 가져오기
|
|
description: 대규모 데이터 가져오기에 Twenty의 API를 언제, 어떻게 사용할지 안내합니다.
|
|
---
|
|
|
|
## 개요
|
|
|
|
Twenty는 프로그램 방식의 데이터 가져오기를 위해 **GraphQL** 및 **REST API**를 모두 제공합니다. 데이터 규모상 CSV 가져오기가 실용적이지 않거나 자동화된 반복 가져오기가 필요한 경우 API를 사용하세요.
|
|
|
|
## API 가져오기 사용 시기
|
|
|
|
| 시나리오 | 권장 방법 |
|
|
| -------------------- | ---------------- |
|
|
| 10,000개 미만의 레코드 | CSV 가져오기 |
|
|
| 10,000 - 50,000개 레코드 | CSV 가져오기(파일로 분할) |
|
|
| **50,000개 이상의 레코드** | **API 가져오기** |
|
|
| 1회성 마이그레이션 | 둘 다 가능(규모에 따라) |
|
|
| **반복 가져오기** | **API 가져오기** |
|
|
| **실시간 동기화** | **API 가져오기** |
|
|
| **다른 시스템과의 통합** | **API 가져오기** |
|
|
|
|
<Note>수십만 건 규모의 데이터셋의 경우, API가 여러 번의 CSV 가져오기보다 훨씬 빠르고 더 신뢰할 수 있습니다.</Note>
|
|
|
|
## API 속도 제한
|
|
|
|
시스템 안정성을 보장하기 위해 Twenty는 속도 제한을 적용합니다:
|
|
|
|
| 제한 | 값 |
|
|
| ---------------- | ------------ |
|
|
| **분당 요청 수** | 100 |
|
|
| **배치 호출당 레코드 수** | 60 |
|
|
| **최대 처리량** | ~6,000 레코드/분 |
|
|
|
|
<Warning>
|
|
**이 한도를 기준으로 가져오기 계획을 수립하세요.**
|
|
|
|
최대 처리량 기준으로 100,000개 레코드를 가져오는 데 약 17분이 소요됩니다. 오류 처리와 재시도를 위한 여유 시간을 추가하세요.
|
|
</Warning>
|
|
|
|
## 시작하기
|
|
|
|
### 1단계: API 키 받기
|
|
|
|
1. **설정 → 개발자**로 이동하세요.
|
|
2. **+ API 키 생성**을 클릭하세요.
|
|
3. 키에 설명적인 이름을 지정하세요.
|
|
4. API 키를 즉시 복사하세요(다시 표시되지 않습니다).
|
|
5. 안전하게 보관하세요.
|
|
|
|
<Warning>
|
|
**API 키를 비공개로 유지하세요.**
|
|
|
|
API 키를 가진 누구나 워크스페이스 데이터에 접근하고 수정할 수 있습니다. 코드 저장소에 커밋하거나 공개적으로 공유하지 마세요.
|
|
</Warning>
|
|
|
|
### 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
|
|
|
|
<AccordionGroup>
|
|
<Accordion title="GraphQL과 REST의 차이는 무엇인가요?">
|
|
GraphQL은 단일 쿼리로 필요한 데이터만 정확히 요청할 수 있으며, 복잡한 작업에 더 적합합니다. REST는 표준 HTTP 메서드(GET, POST, PUT, DELETE)를 사용하며, 기존 API로 작업해 본 경험이 있다면 더 익숙할 수 있습니다.
|
|
</Accordion>
|
|
|
|
<Accordion title="API를 통해 기존 레코드를 업데이트할 수 있나요?">
|
|
예! 레코드의 `id`와 함께 업데이트 뮤테이션(GraphQL) 또는 PUT/PATCH 요청(REST)을 사용하세요.
|
|
</Accordion>
|
|
|
|
<Accordion title="중복은 어떻게 처리하나요?">
|
|
고유 식별자(이메일, 도메인)를 사용해 먼저 기존 레코드를 조회하세요. 존재하면 업데이트하고, 없으면 생성하세요.
|
|
</Accordion>
|
|
|
|
<Accordion title="API를 통해 레코드를 삭제할 수 있나요?">
|
|
예, 삭제 뮤테이션(GraphQL) 또는 DELETE 요청(REST)을 사용하세요.
|
|
</Accordion>
|
|
|
|
<Accordion title="Python 또는 Node.js SDK가 있나요?">
|
|
현재는 없습니다. 하지만 두 API는 어떤 언어의 HTTP 클라이언트와도 작동합니다.
|
|
</Accordion>
|
|
</AccordionGroup>
|
|
|
|
## API 문서
|
|
|
|
전체 구현 세부정보, 코드 예제, 스키마 참조는 다음을 확인하세요:
|
|
|
|
* [API 문서](/l/ko/developers/api)
|