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
8.5 KiB
Plaintext
177 lines
8.5 KiB
Plaintext
---
|
||
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)
|