> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
> Use this file to discover all available pages before exploring further.
# API でデータをインポートする
> 大規模なデータインポートに Twenty の API をいつ・どのように使用するか。
## 概要
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 レコード/分 |
**これらの制限を前提にインポート計画を立ててください。**
最大スループットで 100,000 レコードの場合、インポート時間は約 17 分になります。 エラー処理や再試行のための余裕時間を確保してください。
## 始めに
### ステップ 1: API キーを取得する
1. **設定 → 開発者** に移動
2. **+ API キーを作成** をクリック
3. キーにわかりやすい名前を付ける
4. API キーをすぐにコピーします（再表示されません）
5. 安全に保管する
**API キーは秘密にしてください。**
API キーを知っている人は誰でも、あなたのワークスペースのデータにアクセス・変更できます。 コードリポジトリにコミットしたり、公開で共有したりしないでください。
### ステップ 2: API を選択する
Twenty は 2 種類の API をサポートしています：
| API | 最適な用途 | ドキュメント |
| ----------- | ------------------------------ | ----------------------------------------- |
| **GraphQL** | 柔軟なクエリ、関連データの取得、複雑な操作に最適 | [API ドキュメント](/l/ja/developers/extend/api) |
| **REST** | シンプルな CRUD 操作、馴染みのある REST パターン | [API ドキュメント](/l/ja/developers/extend/api) |
両方の API でサポートされる内容:
* レコードの作成、読み取り、更新、削除
* **バッチ操作** — 1 回の呼び出しで最大 60 レコードを作成または更新
**インポートではバッチ操作を使用**し、レート制限内でスループットを最大化してください。
### ステップ 3: インポート順序を計画する
CSV インポートと同様に、リレーションでは**順序が重要**です:
1. **会社**を最初に（依存関係なし）
2. 2 番目に **連絡先**（会社にリンク可能）
3. 3 番目に **商談**（会社および連絡先にリンク可能）
4. **タスク/メモ**（上記のいずれにもリンク可能）
5. **カスタムオブジェクト**（依存関係に従って）
## ベストプラクティス
### リクエストをバッチ化する
* レコードを 1 件ずつ送信しない
* 1 回の API 呼び出しにつき**最大 60 レコード**にまとめる
* これにより、レート制限内でスループットを最大化できます
### レート制限への対応
* リクエスト間に遅延を入れる（継続的なインポートでは最小 600ms）
* 制限に達したら指数バックオフを使用する
* 429（Too Many Requests）応答を監視する
### まずデータを検証する
* インポート前にデータをクリーンアップし、検証する
* 必須フィールドが入力されていることを確認する
* 形式が Twenty の要件に合致していることを確認する（[フィールドマッピング](/l/ja/user-guide/data-migration/capabilities/field-mapping) を参照）
### すべてをログに記録する
* インポートしたすべてのレコード（ID を含む）を記録する
* エラーをコンテキスト情報とともに記録する
* これにより、問題のデバッグと完了確認が容易になります
### まずテストする
* 少量のバッチ（10〜20 レコード）でテストする
* Twenty にデータが正しく表示されることを確認する
* その後、フルインポートを実行する
### 重複を避けるためにアップサートを使用する
GraphQL API は **バッチ アップサート**をサポートしています — レコードが存在する場合は更新、存在しない場合は作成します。 これにより、インポートを再実行しても重複を防止できます。
## オブジェクト名とフィールド名の確認方法
利用可能なオブジェクトとフィールドを確認するには:
1. **設定 → API と Webhook** に移動
2. **Metadata API** を参照
3. すべての標準およびカスタムオブジェクトとそのフィールドを表示
ドキュメントには、すべての標準およびカスタムオブジェクト、そのフィールド、および期待されるデータ型が示されています。
## プロフェッショナルサービス
複雑な API 移行については、パートナーがお手伝いします:
| サービス | 提供内容 |
| ------------ | ------------------- |
| **データモデル設計** | 最適なデータ構造を設計 |
| **移行スクリプト** | インポート用スクリプトの作成と実行 |
| **データ変換** | 複雑なマッピングとクリーンアップに対応 |
| **検証と QA** | 移行が完了していることを検証 |
**最適な用途:**
* 10 万件以上のレコードの移行
* 複雑なデータ変換
* 厳しいスケジュール
* 開発リソースのないチーム
[contact@twenty.com](mailto:contact@twenty.com) までお問い合わせいただくか、[導入支援サービス](/l/ja/user-guide/getting-started/capabilities/implementation-services)をご覧ください。
## FAQ
GraphQL は、1 回のクエリで必要なデータだけを正確に要求でき、複雑な操作に適しています。 REST は標準的な HTTP メソッド（GET、POST、PUT、DELETE）を使用しており、従来の API を扱ったことがある場合は馴染みやすいでしょう。
はい! 更新用ミューテーション（GraphQL）またはレコードの `id` を用いた PUT/PATCH リクエスト（REST）を使用してください。
一意の識別子（メール、ドメイン）を使用して、まず既存のレコードをクエリします。 存在すれば更新、なければ作成します。
はい、削除用ミューテーション（GraphQL）または DELETE リクエスト（REST）を使用します。
現時点ではありませんが、どちらの API もあらゆる言語の任意の HTTP クライアントで利用できます。
## API ドキュメント
実装の詳細、コード例、スキーマリファレンスについては次を参照してください:
* [API ドキュメント](/l/ja/developers/extend/api)