概要
Twenty は、プログラムによるデータインポートのために GraphQL と REST API の両方を提供しています。 CSV インポートがデータ量の観点で現実的でない場合、または自動化された定期的なインポートが必要な場合は、API を使用してください。API インポートを使うべきタイミング
| シナリオ | 推奨アプローチ |
|---|---|
| 1 万件未満 | CSVインポート |
| 1 万〜5 万件 | CSVインポート（ファイルに分割） |
| 5 万件以上 | API インポート |
| 一度きりの移行 | どちらでも可（データ量に応じて） |
| 定期的なインポート | API インポート |
| リアルタイム同期 | API インポート |
| 他システムとの統合 | API インポート |
数十万件規模のデータセットでは、複数回の CSV インポートよりも API の方が大幅に高速で信頼性があります。
API レートリミット
Twenty では、システムの安定性を確保するためにレート制限を設けています：| 制限 | 値 |
|---|---|
| 1 分あたりのリクエスト数 | 100 |
| バッチ呼び出しあたりのレコード数 | 60 |
| 最大スループット | ~6,000 レコード/分 |
始めに
ステップ 1: API キーを取得する
- 設定 → 開発者 に移動
- + API キーを作成 をクリック
- キーにわかりやすい名前を付ける
- API キーをすぐにコピーします（再表示されません）
- 安全に保管する
ステップ 2: API を選択する
Twenty は 2 種類の API をサポートしています：| API | 最適な用途 | ドキュメント |
|---|---|---|
| GraphQL | 柔軟なクエリ、関連データの取得、複雑な操作に最適 | API ドキュメント |
| REST | シンプルな CRUD 操作、馴染みのある REST パターン | API ドキュメント |
- レコードの作成、読み取り、更新、削除
- バッチ操作 — 1 回の呼び出しで最大 60 レコードを作成または更新
ステップ 3: インポート順序を計画する
CSV インポートと同様に、リレーションでは順序が重要です:- 会社を最初に（依存関係なし）
- 2 番目に 連絡先（会社にリンク可能）
- 3 番目に 商談（会社および連絡先にリンク可能）
- タスク/メモ（上記のいずれにもリンク可能）
- カスタムオブジェクト（依存関係に従って）
ベストプラクティス
リクエストをバッチ化する
- レコードを 1 件ずつ送信しない
- 1 回の API 呼び出しにつき最大 60 レコードにまとめる
- これにより、レート制限内でスループットを最大化できます
レート制限への対応
- リクエスト間に遅延を入れる（継続的なインポートでは最小 600ms）
- 制限に達したら指数バックオフを使用する
- 429（Too Many Requests）応答を監視する
まずデータを検証する
- インポート前にデータをクリーンアップし、検証する
- 必須フィールドが入力されていることを確認する
- 形式が Twenty の要件に合致していることを確認する（フィールドマッピング を参照）
すべてをログに記録する
- インポートしたすべてのレコード（ID を含む）を記録する
- エラーをコンテキスト情報とともに記録する
- これにより、問題のデバッグと完了確認が容易になります
まずテストする
- 少量のバッチ（10〜20 レコード）でテストする
- Twenty にデータが正しく表示されることを確認する
- その後、フルインポートを実行する
重複を避けるためにアップサートを使用する
GraphQL API は バッチ アップサートをサポートしています — レコードが存在する場合は更新、存在しない場合は作成します。 これにより、インポートを再実行しても重複を防止できます。オブジェクト名とフィールド名の確認方法
利用可能なオブジェクトとフィールドを確認するには:- 設定 → API と Webhook に移動
- Metadata API を参照
- すべての標準およびカスタムオブジェクトとそのフィールドを表示
プロフェッショナルサービス
複雑な API 移行については、パートナーがお手伝いします:| サービス | 提供内容 |
|---|---|
| データモデル設計 | 最適なデータ構造を設計 |
| 移行スクリプト | インポート用スクリプトの作成と実行 |
| データ変換 | 複雑なマッピングとクリーンアップに対応 |
| 検証と QA | 移行が完了していることを検証 |
- 10 万件以上のレコードの移行
- 複雑なデータ変換
- 厳しいスケジュール
- 開発リソースのないチーム
FAQ
GraphQL と REST の違いは何ですか？
GraphQL と REST の違いは何ですか？
GraphQL は、1 回のクエリで必要なデータだけを正確に要求でき、複雑な操作に適しています。 REST は標準的な HTTP メソッド（GET、POST、PUT、DELETE）を使用しており、従来の API を扱ったことがある場合は馴染みやすいでしょう。
API で既存のレコードを更新できますか？
API で既存のレコードを更新できますか？
はい! 更新用ミューテーション（GraphQL）またはレコードの
id を用いた PUT/PATCH リクエスト（REST）を使用してください。重複にはどう対処すればよいですか？
重複にはどう対処すればよいですか？
一意の識別子（メール、ドメイン）を使用して、まず既存のレコードをクエリします。 存在すれば更新、なければ作成します。
API でレコードを削除できますか？
API でレコードを削除できますか？
はい、削除用ミューテーション（GraphQL）または DELETE リクエスト（REST）を使用します。
Python や Node.js の SDK はありますか？
Python や Node.js の SDK はありますか？
現時点ではありませんが、どちらの API もあらゆる言語の任意の HTTP クライアントで利用できます。