148 lines
6.4 KiB
Plaintext
148 lines
6.4 KiB
Plaintext
---
|
||
title: API
|
||
description: REST または GraphQL を使用して、プログラムから CRM データをクエリおよび変更します。
|
||
---
|
||
|
||
import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';
|
||
|
||
Twentyは開発者に優しい設計で、強力なAPIを提供し、カスタムデータモデルに適応します。 異なる統合ニーズに対応する4つの異なるAPIタイプを提供します。 異なる統合ニーズに対応する4つの異なるAPIタイプを提供します。 異なる統合ニーズに対応する4つの異なるAPIタイプを提供します。
|
||
|
||
## 開発者優先アプローチ
|
||
|
||
Twenty は、お使いのデータモデルに特化した API を生成します:
|
||
|
||
* **長いIDが不要**：オブジェクトとフィールド名をエンドポイントに直接使用
|
||
* **標準とカスタムオブジェクトを同等に扱う**：カスタムオブジェクトも組み込みのものと同じAPI処理を受ける
|
||
* **専用エンドポイント**：各オブジェクトとフィールドに固有のAPIエンドポイントが設けられる
|
||
* **カスタムドキュメント**：ワークスペースのデータモデルに特化して生成
|
||
|
||
<Note>
|
||
API キー作成後、**Settings → API & Webhooks** でパーソナライズされた API ドキュメントを利用できます。 Twenty はカスタムデータモデルに合致する API を生成するため、ドキュメントはお使いのワークスペース専用です。
|
||
</Note>
|
||
|
||
## 2 つの API タイプ
|
||
|
||
### コアAPI
|
||
|
||
`/rest/` または `/graphql/` でアクセスできます。
|
||
|
||
実際の **レコード**（データ）を扱います:
|
||
|
||
* People、Companies、Opportunities などを作成・読み取り・更新・削除。
|
||
* データのクエリとフィルター
|
||
* レコードの関係管理
|
||
|
||
### メタデータAPI
|
||
|
||
`/rest/metadata/` または `/metadata/` でアクセスできます。
|
||
|
||
**ワークスペースとデータモデル**を管理:
|
||
|
||
* オブジェクトやフィールドの作成、変更、削除
|
||
* ワークスペース設定の構成
|
||
* オブジェクト間のリレーションシップを定義
|
||
|
||
## REST と GraphQL の比較
|
||
|
||
Core と Metadata の両 API は、REST と GraphQL の形式で利用可能です:
|
||
|
||
| 形式 | 利用可能な操作 |
|
||
| ----------- | ---------------------------------------- |
|
||
| **REST** | CRUD、バッチ操作、アップサート |
|
||
| **GraphQL** | 同様に、**バッチアップサート**、1 回の呼び出しでのリレーションシップクエリ |
|
||
|
||
ニーズに合わせて選択してください—どちらの形式でも同じデータにアクセスできます。
|
||
|
||
## APIエンドポイント
|
||
|
||
| 環境 | ベース URL |
|
||
| ---------- | ------------------------- |
|
||
| **クラウド** | `https://api.twenty.com/` |
|
||
| **セルフホスト** | `https://{your-domain}/` |
|
||
|
||
## 認証
|
||
|
||
すべての API リクエストにはヘッダーに API キーが必要です:
|
||
|
||
```
|
||
Authorization: Bearer YOUR_API_KEY
|
||
```
|
||
|
||
### APIキーを作成
|
||
|
||
1. **Settings → APIs & Webhooks**に移動
|
||
2. **+ Create key** をクリック
|
||
3. 設定:
|
||
* **Name**: キーのわかりやすい名前
|
||
* **Expiration Date**: キーの有効期限
|
||
4. **保存**をクリック
|
||
5. **すぐにコピー** — キーは一度しか表示されません
|
||
|
||
<VimeoEmbed videoId="928786722" title="API キーの作成" />
|
||
|
||
<Warning>
|
||
API キーは機密データへのアクセスを許可します。 信頼できないサービスと共有しないでください。 漏洩した場合は、直ちに無効化して新しいものを生成してください。
|
||
</Warning>
|
||
|
||
### API キーにロールを割り当てる
|
||
|
||
セキュリティを高めるため、アクセスを制限する特定のロールを割り当ててください:
|
||
|
||
1. **設定 → 役割** に移動
|
||
2. 割り当てるロールをクリック
|
||
3. **割り当て** タブを開く
|
||
4. **API Keys** の下で、**+ Assign to API key** をクリック
|
||
5. API キーを選択
|
||
|
||
キーはそのロールの権限を継承します。 詳細は[権限](/l/ja/user-guide/permissions-access/capabilities/permissions)を参照してください。
|
||
|
||
### APIキーの管理
|
||
|
||
**Regenerate**: Settings → APIs & Webhooks → キーをクリック → **Regenerate**
|
||
|
||
**Delete**: Settings → APIs & Webhooks → キーをクリック → **Delete**
|
||
|
||
## API プレイグラウンド
|
||
|
||
組み込みのプレイグラウンドでブラウザから直接 API をテストできます—**REST** と **GraphQL** の両方で利用可能です。
|
||
|
||
### プレイグラウンドにアクセス
|
||
|
||
1. **Settings → APIs & Webhooks**に移動
|
||
2. API キーを作成（必須）
|
||
3. プレイグラウンドを開くには **REST API** または **GraphQL API** をクリック
|
||
|
||
### 提供内容
|
||
|
||
* **インタラクティブなドキュメント**: お使いの特定のデータモデル向けに生成
|
||
* **ライブテスト**: ワークスペースに対して実際の API 呼び出しを実行
|
||
* **スキーマエクスプローラー**: 利用可能なオブジェクト、フィールド、リレーションシップを閲覧
|
||
* **リクエストビルダー**: オートコンプリートでクエリを構築
|
||
|
||
プレイグラウンドはカスタムのオブジェクトとフィールドを反映するため、ドキュメントは常にお使いのワークスペースに対して正確です。
|
||
|
||
## バッチ操作
|
||
|
||
REST と GraphQL の両方がバッチ操作をサポートしています:
|
||
|
||
* **バッチサイズ**：リクエストあたり最大60記録
|
||
* **操作**: 複数のレコードの作成、更新、削除
|
||
|
||
**GraphQL のみの機能:**
|
||
|
||
* **バッチアップサート**: 1 回の呼び出しで作成または更新
|
||
* 複数形のオブジェクト名を使用（例：`CreateCompany` ではなく `CreateCompanies`）
|
||
|
||
## API レートリミット
|
||
|
||
プラットフォームの安定性を確保するため、API リクエストはレート制限されています:
|
||
|
||
| 制限 | 値 |
|
||
| ---------- | ------------------- |
|
||
| **リクエスト** | 1 分あたり 100 回の呼び出し |
|
||
| **バッチサイズ** | 1 回の呼び出しあたり 60 レコード |
|
||
|
||
<Tip>
|
||
バッチ操作を使用してスループットを最大化しましょう—個別のリクエストではなく、1 回の API 呼び出しで最大 60 レコードを処理できます。
|
||
</Tip>
|