---
title: API でデータをインポートする
description: 大規模なデータインポートに Twenty の API をいつ・どのように使用するか。
---

## 概要

Twenty は、プログラムによるデータインポートのために **GraphQL** と **REST API** の両方を提供しています。 CSV インポートがデータ量の観点で現実的でない場合、または自動化された定期的なインポートが必要な場合は、API を使用してください。

## API インポートを使うべきタイミング

| シナリオ          | 推奨アプローチ           |
| ------------- | ----------------- |
| 1 万件未満        | CSVインポート          |
| 1 万〜5 万件      | CSVインポート（ファイルに分割） |
| **5 万件以上**    | **API インポート**     |
| 一度きりの移行       | どちらでも可（データ量に応じて）  |
| **定期的なインポート** | **API インポート**     |
| **リアルタイム同期**  | **API インポート**     |
| **他システムとの統合** | **API インポート**     |

<Note>数十万件規模のデータセットでは、複数回の CSV インポートよりも API の方が大幅に高速で信頼性があります。</Note>

## API レートリミット

Twenty では、システムの安定性を確保するためにレート制限を設けています：

| 制限                   | 値             |
| -------------------- | ------------- |
| **1 分あたりのリクエスト数**    | 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 は 2 種類の API をサポートしています：

| API         | 最適な用途                          | ドキュメント                                             |
| ----------- | ------------------------------ | -------------------------------------------------- |
| **GraphQL** | 柔軟なクエリ、関連データの取得、複雑な操作に最適       | [API ドキュメント](/l/ja/developers/api) |
| **REST**    | シンプルな CRUD 操作、馴染みのある REST パターン | [API ドキュメント](/l/ja/developers/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

<AccordionGroup>
  <Accordion title="GraphQL と REST の違いは何ですか？">
    GraphQL は、1 回のクエリで必要なデータだけを正確に要求でき、複雑な操作に適しています。 REST は標準的な HTTP メソッド（GET、POST、PUT、DELETE）を使用しており、従来の API を扱ったことがある場合は馴染みやすいでしょう。
  </Accordion>

  <Accordion title="API で既存のレコードを更新できますか？">
    はい! 更新用ミューテーション（GraphQL）またはレコードの `id` を用いた 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/ja/developers/api)
