Přehled
Twenty poskytuje pro programový import dat jak GraphQL, tak REST API. API použijte, když import CSV není vzhledem k objemu vašich dat praktický, nebo když potřebujete automatizované, opakované importy.Kdy použít import přes API
| Scénář | Doporučená metoda |
|---|---|
| Méně než 10 000 záznamů | Import CSV |
| 10 000–50 000 záznamů | Import CSV (rozdělený do souborů) |
| 50 000+ záznamů | Import přes API |
| Jednorázová migrace | Obojí (dle objemu) |
| Pravidelné importy | Import přes API |
| Synchronizace v reálném čase | Import přes API |
| Integrace s jinými systémy | Import přes API |
Pro datové sady o stovkách tisíc záznamů je API výrazně rychlejší a spolehlivější než více importů CSV.
Limity rychlosti API
Twenty uplatňuje limity rychlosti, aby zajistilo stabilitu systému:| Limit | Hodnota |
|---|---|
| Požadavků za minutu | 100 |
| Záznamů na jedno dávkové volání | 60 |
| Maximální propustnost | ~6 000 záznamů za minutu |
Začínáme
Krok 1: Získejte svůj klíč API
- Přejděte do Nastavení → Vývojáři
- Klikněte na + Vytvořit klíč API
- Dejte svému klíči API výstižný název
- Klíč API si ihned zkopírujte (znovu se již nezobrazí)
- Uložte ho bezpečně
Krok 2: Vyberte si API
Twenty podporuje dva typy API:| API | Vhodné pro | Dokumentace |
|---|---|---|
| GraphQL | Flexibilní dotazy, získávání souvisejících dat, komplexní operace | Dokumentace API |
| REST | Jednoduché CRUD operace, známé postupy REST | Dokumentace API |
- Vytváření, čtení, aktualizace a mazání záznamů
- Dávkové operace — vytvoření nebo aktualizace až 60 záznamů na jedno volání
Krok 3: Naplánujte pořadí importu
Stejně jako u importů CSV na pořadí záleží kvůli vazbám:- Společnosti jako první (bez závislostí)
- Lidé jako druzí (mohou se propojit se společnostmi)
- Příležitosti jako třetí (mohou se propojit se společnostmi a lidmi)
- Úkoly/Poznámky (mohou se propojit s kteroukoli z výše uvedených entit)
- Vlastní objekty (podle jejich závislostí)
Osvědčené postupy
Dávkujte své požadavky
- Neposílejte záznamy po jednom
- Seskupte až 60 záznamů na jedno volání API
- Tím maximalizujete propustnost v rámci limitů rychlosti
Práce s limity rychlosti
- Zaveďte prodlevy mezi požadavky (minimálně 600 ms pro dlouhodobé importy)
- Při dosažení limitů použijte exponenciální backoff
- Sledujte odpovědi 429 (Too Many Requests)
Nejprve ověřte data
- Před importem data vyčistěte a ověřte
- Zkontrolujte, že jsou vyplněna povinná pole
- Ověřte, že formáty odpovídají požadavkům Twenty (viz Mapování polí)
Zaznamenávejte vše
- Zaznamenávejte každý importovaný záznam (včetně ID)
- Zaznamenávejte chyby s plným kontextem
- To pomáhá při ladění problémů a ověření dokončení
Nejprve testujte
- Testujte s malou dávkou (10–20 záznamů)
- Ověřte, že se data v Twenty zobrazují správně
- Poté spusťte celý import
Upsert pro zamezení duplicit
GraphQL API podporuje dávkový upsert — pokud záznam existuje, aktualizuje; pokud ne, vytvoří. To zabrání duplicitám při opakovaném spouštění importů.Hledání názvů objektů a polí
Chcete-li zobrazit dostupné objekty a pole:- Přejděte do Nastavení → API a webhooky
- Procházejte Metadata API
- Zobrazte všechny standardní i vlastní objekty s jejich poli
Profesionální služby
S náročnými migracemi přes API mohou pomoci naši partneři:| Služba | Co je součástí |
|---|---|
| Návrh datového modelu | navrhnout optimální datovou strukturu |
| Migrační skripty | napsat a spustit importní skripty |
| Transformace dat | zpracovat složité mapování a čištění |
| Validace a QA | ověřit, že je migrace dokončená |
- Migrace 100 000+ záznamů
- Složité transformace dat
- Napjaté časové plány
- Týmy bez vývojářských kapacit
Časté dotazy
Jaký je rozdíl mezi GraphQL a REST?
Jaký je rozdíl mezi GraphQL a REST?
GraphQL vám umožní vyžádat si v jediném dotazu přesně ta data, která potřebujete, a je vhodnější pro složité operace. REST používá standardní metody HTTP (GET, POST, PUT, DELETE) a může vám být bližší, pokud jste pracovali s tradičními API.
Mohu aktualizovat existující záznamy přes API?
Mohu aktualizovat existující záznamy přes API?
Ano! Použijte aktualizační mutace (GraphQL) nebo požadavky PUT/PATCH (REST) s
id záznamu.Jak mám řešit duplicity?
Jak mám řešit duplicity?
Nejprve vyhledejte existující záznamy pomocí jedinečných identifikátorů (e-mail, doména). Pokud existuje, aktualizujte; pokud ne, vytvořte.
Mohu mazat záznamy přes API?
Mohu mazat záznamy přes API?
Ano, použijte mutace pro smazání (GraphQL) nebo požadavky DELETE (REST).
Existuje SDK pro Python nebo Node.js?
Existuje SDK pro Python nebo Node.js?
V současnosti ne, ale obě API fungují s jakýmkoli klientem HTTP v libovolném jazyce.