i18n - docs translations (#17434)
Created by Github action Co-authored-by: github-actions <github-actions@twenty.com>
This commit is contained in:
github-actions[bot]
committed by
GitHub
GitHub
parent
2353bc62cc
commit
e0d4492013
@@ -1,147 +1,147 @@
|
||||
---
|
||||
title: APIs
|
||||
description: Query and modify your CRM data programmatically using REST or GraphQL.
|
||||
title: API
|
||||
description: REST または GraphQL を使用して、プログラムから CRM データをクエリおよび変更します。
|
||||
---
|
||||
|
||||
import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';
|
||||
|
||||
Twenty was built to be developer-friendly, offering powerful APIs that adapt to your custom data model. We provide four distinct API types to meet different integration needs.
|
||||
Twentyは開発者に優しい設計で、強力なAPIを提供し、カスタムデータモデルに適応します。 異なる統合ニーズに対応する4つの異なるAPIタイプを提供します。 異なる統合ニーズに対応する4つの異なるAPIタイプを提供します。 異なる統合ニーズに対応する4つの異なるAPIタイプを提供します。
|
||||
|
||||
## Developer-First Approach
|
||||
## 開発者優先アプローチ
|
||||
|
||||
Twenty generates APIs specifically for your data model:
|
||||
Twenty は、お使いのデータモデルに特化した API を生成します:
|
||||
|
||||
* **No long IDs required**: Use your object and field names directly in endpoints
|
||||
* **Standard and custom objects treated equally**: Your custom objects get the same API treatment as built-in ones
|
||||
* **Dedicated endpoints**: Each object and field gets its own API endpoint
|
||||
* **Custom documentation**: Generated specifically for your workspace's data model
|
||||
* **長いIDが不要**：オブジェクトとフィールド名をエンドポイントに直接使用
|
||||
* **標準とカスタムオブジェクトを同等に扱う**：カスタムオブジェクトも組み込みのものと同じAPI処理を受ける
|
||||
* **専用エンドポイント**：各オブジェクトとフィールドに固有のAPIエンドポイントが設けられる
|
||||
* **カスタムドキュメント**：ワークスペースのデータモデルに特化して生成
|
||||
|
||||
<Note>
|
||||
Your personalized API documentation is available under **Settings → API & Webhooks** after creating an API key. Since Twenty generates APIs that match your custom data model, the documentation is unique to your workspace.
|
||||
API キー作成後、**Settings → API & Webhooks** でパーソナライズされた API ドキュメントを利用できます。 Twenty はカスタムデータモデルに合致する API を生成するため、ドキュメントはお使いのワークスペース専用です。
|
||||
</Note>
|
||||
|
||||
## The Two API Types
|
||||
## 2 つの API タイプ
|
||||
|
||||
### Core API
|
||||
### コアAPI
|
||||
|
||||
Accessed on `/rest/` or `/graphql/`
|
||||
`/rest/` または `/graphql/` でアクセスできます。
|
||||
|
||||
Work with your actual **records** (the data):
|
||||
実際の **レコード**（データ）を扱います:
|
||||
|
||||
* Create, read, update, delete People, Companies, Opportunities, etc.
|
||||
* Query and filter data
|
||||
* Manage record relationships
|
||||
* People、Companies、Opportunities などを作成・読み取り・更新・削除。
|
||||
* データのクエリとフィルター
|
||||
* レコードの関係管理
|
||||
|
||||
### Metadata API
|
||||
### メタデータAPI
|
||||
|
||||
Accessed on `/rest/metadata/` or `/metadata/`
|
||||
`/rest/metadata/` または `/metadata/` でアクセスできます。
|
||||
|
||||
Manage your **workspace and data model**:
|
||||
**ワークスペースとデータモデル**を管理:
|
||||
|
||||
* Create, modify, or delete objects and fields
|
||||
* Configure workspace settings
|
||||
* Define relationships between objects
|
||||
* オブジェクトやフィールドの作成、変更、削除
|
||||
* ワークスペース設定の構成
|
||||
* オブジェクト間のリレーションシップを定義
|
||||
|
||||
## REST vs GraphQL
|
||||
## REST と GraphQL の比較
|
||||
|
||||
Both Core and Metadata APIs are available in REST and GraphQL formats:
|
||||
Core と Metadata の両 API は、REST と GraphQL の形式で利用可能です:
|
||||
|
||||
| Format | Available Operations |
|
||||
| ----------- | ---------------------------------------------------------- |
|
||||
| **REST** | CRUD, batch operations, upserts |
|
||||
| **GraphQL** | Same + **batch upserts**, relationship queries in one call |
|
||||
| 形式 | 利用可能な操作 |
|
||||
| ----------- | ---------------------------------------- |
|
||||
| **REST** | CRUD、バッチ操作、アップサート |
|
||||
| **GraphQL** | 同様に、**バッチアップサート**、1 回の呼び出しでのリレーションシップクエリ |
|
||||
|
||||
Choose based on your needs — both formats access the same data.
|
||||
ニーズに合わせて選択してください—どちらの形式でも同じデータにアクセスできます。
|
||||
|
||||
## API Endpoints
|
||||
## APIエンドポイント
|
||||
|
||||
| Environment | Base URL |
|
||||
| --------------- | ------------------------- |
|
||||
| **Cloud** | `https://api.twenty.com/` |
|
||||
| **Self-Hosted** | `https://{your-domain}/` |
|
||||
| 環境 | ベース URL |
|
||||
| ---------- | ------------------------- |
|
||||
| **クラウド** | `https://api.twenty.com/` |
|
||||
| **セルフホスト** | `https://{your-domain}/` |
|
||||
|
||||
## Authentication
|
||||
## 認証
|
||||
|
||||
Every API request requires an API key in the header:
|
||||
すべての API リクエストにはヘッダーに API キーが必要です:
|
||||
|
||||
```
|
||||
Authorization: Bearer YOUR_API_KEY
|
||||
```
|
||||
|
||||
### Create an API Key
|
||||
### APIキーを作成
|
||||
|
||||
1. Go to **Settings → APIs & Webhooks**
|
||||
2. Click **+ Create key**
|
||||
3. Configure:
|
||||
* **Name**: Descriptive name for the key
|
||||
* **Expiration Date**: When the key expires
|
||||
4. Click **Save**
|
||||
5. **Copy immediately** — the key is only shown once
|
||||
1. **Settings → APIs & Webhooks**に移動
|
||||
2. **+ Create key** をクリック
|
||||
3. 設定:
|
||||
* **Name**: キーのわかりやすい名前
|
||||
* **Expiration Date**: キーの有効期限
|
||||
4. **保存**をクリック
|
||||
5. **すぐにコピー** — キーは一度しか表示されません
|
||||
|
||||
<VimeoEmbed videoId="928786722" title="Creating API key" />
|
||||
<VimeoEmbed videoId="928786722" title="API キーの作成" />
|
||||
|
||||
<Warning>
|
||||
Your API key grants access to sensitive data. Don't share it with untrusted services. If compromised, disable it immediately and generate a new one.
|
||||
API キーは機密データへのアクセスを許可します。 信頼できないサービスと共有しないでください。 漏洩した場合は、直ちに無効化して新しいものを生成してください。
|
||||
</Warning>
|
||||
|
||||
### Assign a Role to an API Key
|
||||
### API キーにロールを割り当てる
|
||||
|
||||
For better security, assign a specific role to limit access:
|
||||
セキュリティを高めるため、アクセスを制限する特定のロールを割り当ててください:
|
||||
|
||||
1. Go to **Settings → Roles**
|
||||
2. Click on the role to assign
|
||||
3. Open the **Assignment** tab
|
||||
4. Under **API Keys**, click **+ Assign to API key**
|
||||
5. Select the API key
|
||||
1. **設定 → 役割** に移動
|
||||
2. 割り当てるロールをクリック
|
||||
3. **割り当て** タブを開く
|
||||
4. **API Keys** の下で、**+ Assign to API key** をクリック
|
||||
5. API キーを選択
|
||||
|
||||
The key will inherit that role's permissions. See [Permissions](/l/ja/user-guide/permissions-access/capabilities/permissions) for details.
|
||||
キーはそのロールの権限を継承します。 詳細は[権限](/l/ja/user-guide/permissions-access/capabilities/permissions)を参照してください。
|
||||
|
||||
### Manage API Keys
|
||||
### APIキーの管理
|
||||
|
||||
**Regenerate**: Settings → APIs & Webhooks → Click key → **Regenerate**
|
||||
**Regenerate**: Settings → APIs & Webhooks → キーをクリック → **Regenerate**
|
||||
|
||||
**Delete**: Settings → APIs & Webhooks → Click key → **Delete**
|
||||
**Delete**: Settings → APIs & Webhooks → キーをクリック → **Delete**
|
||||
|
||||
## API Playground
|
||||
## API プレイグラウンド
|
||||
|
||||
Test your APIs directly in the browser with our built-in playground — available for both **REST** and **GraphQL**.
|
||||
組み込みのプレイグラウンドでブラウザから直接 API をテストできます—**REST** と **GraphQL** の両方で利用可能です。
|
||||
|
||||
### Access the Playground
|
||||
### プレイグラウンドにアクセス
|
||||
|
||||
1. Go to **Settings → APIs & Webhooks**
|
||||
2. Create an API key (required)
|
||||
3. Click on **REST API** or **GraphQL API** to open the playground
|
||||
1. **Settings → APIs & Webhooks**に移動
|
||||
2. API キーを作成（必須）
|
||||
3. プレイグラウンドを開くには **REST API** または **GraphQL API** をクリック
|
||||
|
||||
### What You Get
|
||||
### 提供内容
|
||||
|
||||
* **Interactive documentation**: Generated for your specific data model
|
||||
* **Live testing**: Execute real API calls against your workspace
|
||||
* **Schema explorer**: Browse available objects, fields, and relationships
|
||||
* **Request builder**: Construct queries with autocomplete
|
||||
* **インタラクティブなドキュメント**: お使いの特定のデータモデル向けに生成
|
||||
* **ライブテスト**: ワークスペースに対して実際の API 呼び出しを実行
|
||||
* **スキーマエクスプローラー**: 利用可能なオブジェクト、フィールド、リレーションシップを閲覧
|
||||
* **リクエストビルダー**: オートコンプリートでクエリを構築
|
||||
|
||||
The playground reflects your custom objects and fields, so documentation is always accurate for your workspace.
|
||||
プレイグラウンドはカスタムのオブジェクトとフィールドを反映するため、ドキュメントは常にお使いのワークスペースに対して正確です。
|
||||
|
||||
## Batch Operations
|
||||
## バッチ操作
|
||||
|
||||
Both REST and GraphQL support batch operations:
|
||||
REST と GraphQL の両方がバッチ操作をサポートしています:
|
||||
|
||||
* **Batch size**: Up to 60 records per request
|
||||
* **Operations**: Create, update, delete multiple records
|
||||
* **バッチサイズ**：リクエストあたり最大60記録
|
||||
* **操作**: 複数のレコードの作成、更新、削除
|
||||
|
||||
**GraphQL-only features:**
|
||||
**GraphQL のみの機能:**
|
||||
|
||||
* **Batch Upsert**: Create or update in one call
|
||||
* Use plural object names (e.g., `CreateCompanies` instead of `CreateCompany`)
|
||||
* **バッチアップサート**: 1 回の呼び出しで作成または更新
|
||||
* 複数形のオブジェクト名を使用（例：`CreateCompany` ではなく `CreateCompanies`）
|
||||
|
||||
## Rate Limits
|
||||
## API レートリミット
|
||||
|
||||
API requests are throttled to ensure platform stability:
|
||||
プラットフォームの安定性を確保するため、API リクエストはレート制限されています:
|
||||
|
||||
| Limit | Value |
|
||||
| -------------- | -------------------- |
|
||||
| **Requests** | 100 calls per minute |
|
||||
| **Batch size** | 60 records per call |
|
||||
| 制限 | 値 |
|
||||
| ---------- | ------------------- |
|
||||
| **リクエスト** | 1 分あたり 100 回の呼び出し |
|
||||
| **バッチサイズ** | 1 回の呼び出しあたり 60 レコード |
|
||||
|
||||
<Tip>
|
||||
Use batch operations to maximize throughput — process up to 60 records in a single API call instead of making individual requests.
|
||||
バッチ操作を使用してスループットを最大化しましょう—個別のリクエストではなく、1 回の API 呼び出しで最大 60 レコードを処理できます。
|
||||
</Tip>
|
||||
|
||||
@@ -1,81 +1,88 @@
|
||||
---
|
||||
title: Twenty Apps
|
||||
description: Build and manage Twenty customizations as code.
|
||||
title: Twenty アプリ
|
||||
description: Twenty のカスタマイズをコードとして構築・管理します。
|
||||
---
|
||||
|
||||
<Warning>
|
||||
Apps are currently in alpha testing. The feature is functional but still evolving.
|
||||
アプリは現在アルファテスト中です。 この機能は動作しますが、まだ進化の途上です。
|
||||
</Warning>
|
||||
|
||||
## What Are Apps?
|
||||
## Apps とは？
|
||||
|
||||
Apps let you build and manage Twenty customizations **as code**. Instead of configuring everything through the UI, you define your data model and serverless functions in code — making it faster to build, maintain, and roll out to multiple workspaces.
|
||||
Apps を使うと、Twenty のカスタマイズを**コードとして**構築・管理できます。 すべてを UI から設定する代わりに、データモデルやサーバーレス関数をコードで定義できます。これにより、構築と保守が高速になり、複数のワークスペースへの展開も容易になります。
|
||||
|
||||
**What you can do today:**
|
||||
**現在できること:**
|
||||
|
||||
* Define custom objects and fields as code (managed data model)
|
||||
* Build serverless functions with custom triggers
|
||||
* Deploy the same app across multiple workspaces
|
||||
* カスタムオブジェクトとフィールドをコードとして定義（管理されたデータモデル）
|
||||
* カスタムトリガー付きのサーバーレス関数を作成
|
||||
* 同じアプリを複数のワークスペースにデプロイ
|
||||
|
||||
**Coming soon:**
|
||||
**近日公開:**
|
||||
|
||||
* Custom UI layouts and components
|
||||
* カスタム UI レイアウトとコンポーネント
|
||||
|
||||
## Prerequisites
|
||||
## 前提条件
|
||||
|
||||
* Node.js 24+ and Yarn 4
|
||||
* A Twenty workspace and an API key (create one at https://app.twenty.com/settings/api-webhooks)
|
||||
* Node.js 24+ と Yarn 4
|
||||
* Twenty のワークスペースと API キー（https://app.twenty.com/settings/api-webhooks で作成）
|
||||
|
||||
## Getting Started
|
||||
## 始めに
|
||||
|
||||
Create a new app using the official scaffolder, then authenticate and start developing:
|
||||
公式スキャフォルダーで新しいアプリを作成し、認証して開発を開始します：
|
||||
|
||||
```bash filename="Terminal"
|
||||
# Scaffold a new app
|
||||
# 新しいアプリのひな型を作成
|
||||
npx create-twenty-app@latest my-twenty-app
|
||||
cd my-twenty-app
|
||||
|
||||
# Authenticate using your API key (you'll be prompted)
|
||||
yarn auth
|
||||
# yarn@4 を使用していない場合
|
||||
corepack enable
|
||||
yarn install
|
||||
|
||||
# Start dev mode: automatically syncs local changes to your workspace
|
||||
yarn dev
|
||||
# API キーで認証（プロンプトが表示されます）
|
||||
yarn auth:login
|
||||
|
||||
# 開発モードを開始：ローカルの変更がワークスペースに自動同期されます
|
||||
yarn app:dev
|
||||
```
|
||||
|
||||
From here you can:
|
||||
そこで次のことができます：
|
||||
|
||||
```bash filename="Terminal"
|
||||
# Add a new entity to your application (guided)
|
||||
yarn create-entity
|
||||
# アプリケーションに新しいエンティティを追加（ガイド付き）
|
||||
yarn app:create-entity
|
||||
|
||||
# Generate a typed Twenty client and workspace entity types
|
||||
yarn generate
|
||||
# 型付きの Twenty クライアントとワークスペースのエンティティ型を生成
|
||||
yarn app:generate
|
||||
|
||||
# Run a one‑time sync (instead of watch mode)
|
||||
yarn sync
|
||||
# 1回限りの同期を実行（ウォッチモードの代わり）
|
||||
yarn app:sync
|
||||
|
||||
# Watch your application's functions logs
|
||||
yarn logs
|
||||
# アプリケーションの関数のログを監視
|
||||
yarn function:logs
|
||||
|
||||
# Uninstall the application from the current workspace
|
||||
yarn uninstall
|
||||
# 名前で関数を実行
|
||||
yarn function:execute -n my-function -p '{\"name\": \"test\"}'
|
||||
|
||||
# Display commands' help
|
||||
yarn help
|
||||
# 現在のワークスペースからアプリケーションをアンインストール
|
||||
yarn app:uninstall
|
||||
|
||||
# コマンドのヘルプを表示
|
||||
yarn app:help
|
||||
```
|
||||
|
||||
See also: the CLI reference pages for [create-twenty-app](https://www.npmjs.com/package/create-twenty-app) and [twenty-sdk CLI](https://www.npmjs.com/package/twenty-sdk).
|
||||
参考: [create-twenty-app](https://www.npmjs.com/package/create-twenty-app) および [twenty-sdk CLI](https://www.npmjs.com/package/twenty-sdk) の CLI リファレンスページをご覧ください。
|
||||
|
||||
## Project structure (scaffolded)
|
||||
## プロジェクト構成（スキャフォルド作成）
|
||||
|
||||
When you run `npx create-twenty-app@latest my-twenty-app`, the scaffolder:
|
||||
`npx create-twenty-app@latest my-twenty-app` を実行すると、スキャフォルダーは次を行います：
|
||||
|
||||
* Copies a minimal base application into `my-twenty-app/`
|
||||
* Adds a local `twenty-sdk` dependency and Yarn 4 configuration
|
||||
* Creates config files and scripts wired to the `twenty` CLI
|
||||
* Generates a default application config and a default function role
|
||||
* 最小限のベースアプリケーションを `my-twenty-app/` にコピーします
|
||||
* ローカルの `twenty-sdk` 依存関係と Yarn 4 の設定を追加します
|
||||
* `twenty` CLI と連携する設定ファイルとスクリプトを作成します
|
||||
* デフォルトのアプリケーション設定とデフォルトの関数ロールを生成します
|
||||
|
||||
A freshly scaffolded app looks like this:
|
||||
スキャフォルド直後のアプリは次のようになります：
|
||||
|
||||
```text filename="my-twenty-app/"
|
||||
my-twenty-app/
|
||||
@@ -85,79 +92,144 @@ my-twenty-app/
|
||||
.nvmrc
|
||||
.yarnrc.yml
|
||||
.yarn/
|
||||
releases/
|
||||
yarn-4.9.2.cjs
|
||||
install-state.gz
|
||||
eslint.config.mjs
|
||||
tsconfig.json
|
||||
README.md
|
||||
src/
|
||||
application.config.ts
|
||||
role.config.ts
|
||||
// your entities, actions, and other app files
|
||||
app/
|
||||
application.config.ts # Required - main application configuration
|
||||
default-function.role.ts # Default role for serverless functions
|
||||
// your entities (*.object.ts, *.function.ts, *.role.ts)
|
||||
utils/ # Optional - handler implementations & utilities
|
||||
```
|
||||
|
||||
At a high level:
|
||||
### コンベンション優先
|
||||
|
||||
* **package.json**: Declares the app name, version, engines (Node 24+, Yarn 4), and adds `twenty-sdk` plus scripts like `dev`, `sync`, `generate`, `create-entity`, `logs`, `uninstall`, and `auth` that delegate to the local `twenty` CLI.
|
||||
* **.gitignore**: Ignores common artifacts such as `node_modules`, `.yarn`, `generated/` (typed client), `dist/`, `build/`, coverage folders, log files, and `.env*` files.
|
||||
* **yarn.lock**, **.yarnrc.yml**, **.yarn/**: Lock and configure the Yarn 4 toolchain used by the project.
|
||||
* **.nvmrc**: Pins the Node.js version expected by the project.
|
||||
* **eslint.config.mjs** and **tsconfig.json**: Provide linting and TypeScript configuration for your app’s TypeScript sources.
|
||||
* **README.md**: A short README in the app root with basic instructions.
|
||||
* **src/**: The main place where you define your application-as-code:
|
||||
* `application.config.ts`: Global configuration for your app (metadata and runtime wiring). See “Application config” below.
|
||||
* `role.config.ts`: Default function role used by your serverless functions. See “Default function role” below.
|
||||
* Future entities, actions/functions, and any supporting code you add.
|
||||
アプリケーションは **コンベンション優先（設定より規約）** のアプローチを採用し、エンティティはファイルのサフィックスで検出されます。 これにより、`src/app/` フォルダー内を柔軟に構成できます：
|
||||
|
||||
Later commands will add more files and folders:
|
||||
| ファイルサフィックス | エンティティタイプ |
|
||||
| --------------- | ------------- |
|
||||
| `*.object.ts` | カスタムオブジェクトの定義 |
|
||||
| `*.function.ts` | サーバーレス関数の定義 |
|
||||
| `*.role.ts` | ロールの定義 |
|
||||
|
||||
* `yarn generate` will create a `generated/` folder (typed Twenty client + workspace types).
|
||||
* `yarn create-entity` will add entity definition files under `src/` for your custom objects.
|
||||
### サポートされるフォルダー構成
|
||||
|
||||
## Authentication
|
||||
エンティティは次のいずれのパターンでも構成できます：
|
||||
|
||||
The first time you run `yarn auth`, you'll be prompted for:
|
||||
**従来型（タイプ別）:**
|
||||
|
||||
* API URL (defaults to http://localhost:3000 or your current workspace profile)
|
||||
* API key
|
||||
```text
|
||||
src/app/
|
||||
├── application.config.ts
|
||||
├── objects/
|
||||
│ └── postCard.object.ts
|
||||
├── functions/
|
||||
│ └── createPostCard.function.ts
|
||||
└── roles/
|
||||
└── admin.role.ts
|
||||
```
|
||||
|
||||
Your credentials are stored per-user in `~/.twenty/config.json`. You can maintain multiple profiles and switch using `--workspace <name>`.
|
||||
**機能単位:**
|
||||
|
||||
Examples:
|
||||
```text
|
||||
src/app/
|
||||
├── application.config.ts
|
||||
└── post-card/
|
||||
├── postCard.object.ts
|
||||
├── createPostCard.function.ts
|
||||
└── postCardAdmin.role.ts
|
||||
```
|
||||
|
||||
**フラット:**
|
||||
|
||||
```text
|
||||
src/app/
|
||||
├── application.config.ts
|
||||
├── postCard.object.ts
|
||||
├── createPostCard.function.ts
|
||||
└── admin.role.ts
|
||||
```
|
||||
|
||||
概要：
|
||||
|
||||
* **package.json**: アプリ名、バージョン、エンジン（Node 24+、Yarn 4）を宣言し、`twenty-sdk` と、`dev`、`sync`、`generate`、`create-entity`、`logs`、`uninstall`、`auth` などのスクリプトを追加します。これらはローカルの `twenty` CLI に委譲されます。
|
||||
* **.gitignore**: `node_modules`、`.yarn`、`generated/`（型付きクライアント）、`dist/`、`build/`、カバレッジ用フォルダー、ログファイル、`.env*` ファイルなどの一般的な生成物を無視します。
|
||||
* **yarn.lock**、**.yarnrc.yml**、**.yarn/**: プロジェクトで使用する Yarn 4 ツールチェーンをロックおよび構成します。
|
||||
* **.nvmrc**: プロジェクトで想定する Node.js バージョンを固定します。
|
||||
* **eslint.config.mjs** と **tsconfig.json**: アプリの TypeScript ソース向けの Lint と TypeScript 設定を提供します。
|
||||
* **README.md**: アプリのルートにある、基本的な手順を記した短い README。
|
||||
* **src/app/**: アプリケーションをコードとして定義する主な場所：
|
||||
* `application.config.ts`: アプリのグローバル設定（メタデータとランタイムの接続）。 「アプリケーション設定」を参照してください。
|
||||
* `*.role.ts`: サーバーレス関数で使用するロール定義。 「デフォルトの関数ロール」を参照してください。
|
||||
* `*.object.ts`: カスタムオブジェクトの定義。
|
||||
* `*.function.ts`: サーバーレス関数の定義。
|
||||
* **src/utils/**: ハンドラーの実装やユーティリティ用の任意フォルダー。
|
||||
|
||||
後続のコマンドにより、さらにファイルやフォルダーが追加されます：
|
||||
|
||||
* `yarn app:generate` は `generated/` フォルダー（型付きの Twenty クライアント + ワークスペースの型）を作成します。
|
||||
* `yarn app:create-entity` は、カスタムオブジェクト、関数、ロール用のエンティティ定義ファイルを `src/app/` 配下に追加します。
|
||||
l
|
||||
|
||||
## 認証
|
||||
|
||||
初めて `yarn auth:login` を実行すると、次が求められます：
|
||||
|
||||
* API URL（デフォルトは http://localhost:3000 または現在のワークスペースプロファイル）
|
||||
* API キー
|
||||
|
||||
認証情報はユーザーごとに `~/.twenty/config.json` に保存されます。 複数のプロファイルを管理し、相互に切り替えることができます。
|
||||
|
||||
### ワークスペースの管理
|
||||
|
||||
```bash filename="Terminal"
|
||||
# Login interactively (recommended)
|
||||
yarn auth
|
||||
# 対話的にログイン（推奨）
|
||||
yarn auth:login
|
||||
|
||||
# Use a specific workspace profile
|
||||
yarn auth --workspace my-custom-workspace
|
||||
# 特定のワークスペースプロファイルにログイン
|
||||
yarn auth:login --workspace my-custom-workspace
|
||||
|
||||
# 設定済みのワークスペースをすべて一覧表示
|
||||
yarn auth:list
|
||||
|
||||
# デフォルトのワークスペースを切り替え（対話的）
|
||||
yarn auth:switch
|
||||
|
||||
# 特定のワークスペースに切り替え
|
||||
yarn auth:switch production
|
||||
|
||||
# 現在の認証状態を確認
|
||||
yarn auth:status
|
||||
```
|
||||
|
||||
## Use the SDK resources (types & config)
|
||||
一度 `auth:switch` でワークスペースを切り替えると、その後のすべてのコマンドはデフォルトでそのワークスペースを使用します。 一時的に `--workspace <name>` で上書きできます。
|
||||
|
||||
The twenty-sdk provides typed building blocks you use inside your app. Below are the key pieces you'll touch most often.
|
||||
## SDK リソース（型と設定）を使う
|
||||
|
||||
### Defining objects
|
||||
twenty-sdk は、アプリ内で使用する型付きのビルディングブロックとヘルパー関数を提供します。 以下は、最も頻繁に扱う主要な構成要素です。
|
||||
|
||||
Custom objects are regular TypeScript classes annotated with decorators from `twenty-sdk`. They live under `src/objects/` in your app and describe both schema and behavior for records in your workspace.
|
||||
### ヘルパー関数
|
||||
|
||||
Here is an example `postCard` object from the Hello World app:
|
||||
この SDK は、アプリのエンティティを定義するための組み込み検証付きヘルパー関数を 4 つ提供します：
|
||||
|
||||
| 関数 | 目的 |
|
||||
| ------------------ | --------------------- |
|
||||
| `defineApp()` | アプリケーションのメタデータを構成 |
|
||||
| `defineObject()` | フィールド付きのカスタムオブジェクトを定義 |
|
||||
| `defineFunction()` | ハンドラー付きのサーバーレス関数を定義 |
|
||||
| `defineRole()` | ロールの権限とオブジェクトアクセスを構成 |
|
||||
|
||||
これらの関数は実行時に設定を検証し、IDE の補完と型安全性を向上させます。
|
||||
|
||||
### オブジェクトの定義
|
||||
|
||||
カスタムオブジェクトは、ワークスペース内のレコードのスキーマと挙動の両方を表します。 組み込み検証付きでオブジェクトを定義するには `defineObject()` を使用します：
|
||||
|
||||
```typescript
|
||||
import { type Note } from '../../generated';
|
||||
|
||||
import {
|
||||
type AddressField,
|
||||
Field,
|
||||
FieldType,
|
||||
type FullNameField,
|
||||
Object,
|
||||
OnDeleteAction,
|
||||
Relation,
|
||||
RelationType,
|
||||
STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
|
||||
} from 'twenty-sdk';
|
||||
// src/app/postCard.object.ts
|
||||
import { defineObject, FieldType } from 'twenty-sdk';
|
||||
|
||||
enum PostCardStatus {
|
||||
DRAFT = 'DRAFT',
|
||||
@@ -166,176 +238,186 @@ enum PostCardStatus {
|
||||
RETURNED = 'RETURNED',
|
||||
}
|
||||
|
||||
@Object({
|
||||
export default defineObject({
|
||||
universalIdentifier: '54b589ca-eeed-4950-a176-358418b85c05',
|
||||
nameSingular: 'postCard',
|
||||
namePlural: 'postCards',
|
||||
labelSingular: 'Post card',
|
||||
labelPlural: 'Post cards',
|
||||
description: ' A post card object',
|
||||
labelSingular: 'Post Card',
|
||||
labelPlural: 'Post Cards',
|
||||
description: 'A post card object',
|
||||
icon: 'IconMail',
|
||||
})
|
||||
export class PostCard {
|
||||
@Field({
|
||||
universalIdentifier: '58a0a314-d7ea-4865-9850-7fb84e72f30b',
|
||||
type: FieldType.TEXT,
|
||||
label: 'Content',
|
||||
description: "Postcard's content",
|
||||
icon: 'IconAbc',
|
||||
})
|
||||
content: string;
|
||||
|
||||
@Field({
|
||||
universalIdentifier: 'c6aa31f3-da76-4ac6-889f-475e226009ac',
|
||||
type: FieldType.FULL_NAME,
|
||||
label: 'Recipient name',
|
||||
icon: 'IconUser',
|
||||
})
|
||||
recipientName: FullNameField;
|
||||
|
||||
@Field({
|
||||
universalIdentifier: '95045777-a0ad-49ec-98f9-22f9fc0c8266',
|
||||
type: FieldType.ADDRESS,
|
||||
label: 'Recipient address',
|
||||
icon: 'IconHome',
|
||||
})
|
||||
recipientAddress: AddressField;
|
||||
|
||||
@Field({
|
||||
universalIdentifier: '87b675b8-dd8c-4448-b4ca-20e5a2234a1e',
|
||||
type: FieldType.SELECT,
|
||||
label: 'Status',
|
||||
icon: 'IconSend',
|
||||
defaultValue: `'${PostCardStatus.DRAFT}'`,
|
||||
options: [
|
||||
{ value: PostCardStatus.DRAFT, label: 'Draft', position: 0, color: 'gray' },
|
||||
{ value: PostCardStatus.SENT, label: 'Sent', position: 1, color: 'orange' },
|
||||
{ value: PostCardStatus.DELIVERED, label: 'Delivered', position: 2, color: 'green' },
|
||||
{ value: PostCardStatus.RETURNED, label: 'Returned', position: 3, color: 'orange' },
|
||||
],
|
||||
})
|
||||
status: PostCardStatus;
|
||||
|
||||
@Relation({
|
||||
universalIdentifier: 'c9e2b4f4-b9ad-4427-9b42-9971b785edfe',
|
||||
type: RelationType.ONE_TO_MANY,
|
||||
label: 'Notes',
|
||||
icon: 'IconComment',
|
||||
inverseSideTargetUniversalIdentifier: STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.note,
|
||||
onDelete: OnDeleteAction.CASCADE,
|
||||
})
|
||||
notes: Note[];
|
||||
|
||||
@Field({
|
||||
universalIdentifier: 'e06abe72-5b44-4e7f-93be-afc185a3c433',
|
||||
type: FieldType.DATE_TIME,
|
||||
label: 'Delivered at',
|
||||
icon: 'IconCheck',
|
||||
isNullable: true,
|
||||
defaultValue: null,
|
||||
})
|
||||
deliveredAt?: Date;
|
||||
}
|
||||
fields: [
|
||||
{
|
||||
universalIdentifier: '58a0a314-d7ea-4865-9850-7fb84e72f30b',
|
||||
name: 'content',
|
||||
type: FieldType.TEXT,
|
||||
label: 'Content',
|
||||
description: "Postcard's content",
|
||||
icon: 'IconAbc',
|
||||
},
|
||||
{
|
||||
universalIdentifier: 'c6aa31f3-da76-4ac6-889f-475e226009ac',
|
||||
name: 'recipientName',
|
||||
type: FieldType.FULL_NAME,
|
||||
label: 'Recipient name',
|
||||
icon: 'IconUser',
|
||||
},
|
||||
{
|
||||
universalIdentifier: '95045777-a0ad-49ec-98f9-22f9fc0c8266',
|
||||
name: 'recipientAddress',
|
||||
type: FieldType.ADDRESS,
|
||||
label: 'Recipient address',
|
||||
icon: 'IconHome',
|
||||
},
|
||||
{
|
||||
universalIdentifier: '87b675b8-dd8c-4448-b4ca-20e5a2234a1e',
|
||||
name: 'status',
|
||||
type: FieldType.SELECT,
|
||||
label: 'Status',
|
||||
icon: 'IconSend',
|
||||
defaultValue: `'${PostCardStatus.DRAFT}'`,
|
||||
options: [
|
||||
{ value: PostCardStatus.DRAFT, label: 'Draft', position: 0, color: 'gray' },
|
||||
{ value: PostCardStatus.SENT, label: 'Sent', position: 1, color: 'orange' },
|
||||
{ value: PostCardStatus.DELIVERED, label: 'Delivered', position: 2, color: 'green' },
|
||||
{ value: PostCardStatus.RETURNED, label: 'Returned', position: 3, color: 'orange' },
|
||||
],
|
||||
},
|
||||
{
|
||||
universalIdentifier: 'e06abe72-5b44-4e7f-93be-afc185a3c433',
|
||||
name: 'deliveredAt',
|
||||
type: FieldType.DATE_TIME,
|
||||
label: 'Delivered at',
|
||||
icon: 'IconCheck',
|
||||
isNullable: true,
|
||||
defaultValue: null,
|
||||
},
|
||||
],
|
||||
});
|
||||
```
|
||||
|
||||
Key points:
|
||||
主要ポイント：
|
||||
|
||||
* The `@Object` decorator defines the object identity and labels used across the workspace; its `universalIdentifier` must be unique and stable across deployments.
|
||||
* Each `@Field` decorator defines a field on the object with a type, label, and its own stable `universalIdentifier`.
|
||||
* `@Relation` wires this object to other objects (standard or custom) and controls cascade behavior with `onDelete`.
|
||||
* You can scaffold new objects using `yarn create-entity`, which guides you through naming, fields, and relationships, then generates object files similar to the `postCard` example.
|
||||
* 組み込み検証と優れた IDE サポートのために `defineObject()` を使用します。
|
||||
* `universalIdentifier` は、デプロイをまたいで一意かつ安定している必要があります。
|
||||
* 各フィールドには、`name`、`type`、`label`、および自身の安定した `universalIdentifier` が必要です。
|
||||
* `fields` 配列は任意です。カスタムフィールドなしでオブジェクトを定義できます。
|
||||
* `yarn app:create-entity` を使用すれば、新しいオブジェクトをスキャフォルドできます。名前、フィールド、リレーションシップの設定がガイドされます。
|
||||
|
||||
### Application config (application.config.ts)
|
||||
<Note>
|
||||
**ベースフィールドは自動作成されます。** カスタムオブジェクトを定義すると、Twenty は `name`、`createdAt`、`updatedAt`、`createdBy`、`position`、`deletedAt` などの標準フィールドを自動的に追加します。 これらを `fields` 配列で定義する必要はありません。カスタムフィールドのみを追加してください。
|
||||
</Note>
|
||||
|
||||
Every app has a single `application.config.ts` file that describes:
|
||||
<Accordion title="代替: デコレーター ベースの構文">
|
||||
TypeScript のデコレーターを使ってオブジェクトを定義することもできます。 この方法では、`@Object`、`@Field`、`@Relation` デコレーターを用いたクラスベースの構文を使用します：
|
||||
|
||||
* **Who the app is**: identifiers, display name, and description.
|
||||
* **How its functions run**: which role they use for permissions.
|
||||
* **(Optional) variables**: key–value pairs exposed to your functions as environment variables.
|
||||
```typescript
|
||||
import {
|
||||
type AddressField,
|
||||
Field,
|
||||
FieldType,
|
||||
type FullNameField,
|
||||
Object,
|
||||
OnDeleteAction,
|
||||
Relation,
|
||||
RelationType,
|
||||
STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
|
||||
} from 'twenty-sdk';
|
||||
import { type Note } from '../../generated';
|
||||
|
||||
When you scaffold a new app, you start with a minimal config:
|
||||
@Object({
|
||||
universalIdentifier: '54b589ca-eeed-4950-a176-358418b85c05',
|
||||
nameSingular: 'postCard',
|
||||
namePlural: 'postCards',
|
||||
labelSingular: 'Post card',
|
||||
labelPlural: 'Post cards',
|
||||
description: 'A post card object',
|
||||
icon: 'IconMail',
|
||||
})
|
||||
export class PostCard {
|
||||
@Field({
|
||||
universalIdentifier: '58a0a314-d7ea-4865-9850-7fb84e72f30b',
|
||||
type: FieldType.TEXT,
|
||||
label: 'Content',
|
||||
description: "Postcard's content",
|
||||
icon: 'IconAbc',
|
||||
})
|
||||
content: string;
|
||||
|
||||
@Relation({
|
||||
universalIdentifier: 'c9e2b4f4-b9ad-4427-9b42-9971b785edfe',
|
||||
type: RelationType.ONE_TO_MANY,
|
||||
label: 'Notes',
|
||||
icon: 'IconComment',
|
||||
inverseSideTargetUniversalIdentifier: STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.note,
|
||||
onDelete: OnDeleteAction.CASCADE,
|
||||
})
|
||||
notes: Note[];
|
||||
}
|
||||
```
|
||||
|
||||
注記: デコレーター方式では、TypeScript 設定で `experimentalDecorators` が必要です。
|
||||
</Accordion>
|
||||
|
||||
### アプリケーション設定（application.config.ts）
|
||||
|
||||
すべてのアプリには、次の内容を記述する単一の `application.config.ts` ファイルがあります：
|
||||
|
||||
* **アプリの概要**: 識別子、表示名、説明。
|
||||
* **関数の実行方法**: 権限に使用するロール。
|
||||
* **（任意）変数**: 関数に環境変数として公開されるキーと値のペア。
|
||||
|
||||
アプリケーション設定を定義するには `defineApp()` を使用します：
|
||||
|
||||
```typescript
|
||||
import { type ApplicationConfig } from 'twenty-sdk';
|
||||
// src/app/application.config.ts
|
||||
import { defineApp } from 'twenty-sdk';
|
||||
import { DEFAULT_FUNCTION_ROLE_UNIVERSAL_IDENTIFIER } from './default-function.role';
|
||||
|
||||
const config: ApplicationConfig = {
|
||||
universalIdentifier: '<generated-app-uuid>',
|
||||
export default defineApp({
|
||||
universalIdentifier: '4ec0391d-18d5-411c-b2f3-266ddc1c3ef7',
|
||||
displayName: 'My Twenty App',
|
||||
description: 'My first Twenty app',
|
||||
functionRoleUniversalIdentifier: '<generated-role-uuid>',
|
||||
};
|
||||
|
||||
export default config;
|
||||
```
|
||||
|
||||
You can gradually extend this file as your app grows. For example, you can add an icon and application-scoped variables:
|
||||
|
||||
```typescript
|
||||
import { type ApplicationConfig } from 'twenty-sdk';
|
||||
|
||||
const config: ApplicationConfig = {
|
||||
universalIdentifier: '<your-app-uuid>',
|
||||
displayName: 'My App',
|
||||
description: 'What your app does',
|
||||
icon: 'IconWorld', // Choose an icon by name
|
||||
icon: 'IconWorld',
|
||||
applicationVariables: {
|
||||
DEFAULT_RECIPIENT_NAME: {
|
||||
universalIdentifier: '<uuid>',
|
||||
description: 'Default recipient used by functions',
|
||||
universalIdentifier: '19e94e59-d4fe-4251-8981-b96d0a9f74de',
|
||||
description: 'Default recipient name for postcards',
|
||||
value: 'Jane Doe',
|
||||
isSecret: false,
|
||||
},
|
||||
},
|
||||
functionRoleUniversalIdentifier: '<your-role-uuid>',
|
||||
};
|
||||
|
||||
export default config;
|
||||
functionRoleUniversalIdentifier: DEFAULT_FUNCTION_ROLE_UNIVERSAL_IDENTIFIER,
|
||||
});
|
||||
```
|
||||
|
||||
Notes:
|
||||
注記：
|
||||
|
||||
* `universalIdentifier` fields are deterministic IDs you own; generate them once and keep them stable across syncs.
|
||||
* `applicationVariables` become environment variables for your functions (for example, `DEFAULT_RECIPIENT_NAME` is available as `process.env.DEFAULT_RECIPIENT_NAME`).
|
||||
* `functionRoleUniversalIdentifier` must match the role you define in `role.config.ts` (see below).
|
||||
* `universalIdentifier` フィールドは、あなたが管理する決定的な ID です。一度生成し、同期をまたいで安定したままにしてください。
|
||||
* `applicationVariables` は関数の環境変数になります（例：`DEFAULT_RECIPIENT_NAME` は `process.env.DEFAULT_RECIPIENT_NAME` として利用可能）。
|
||||
* `functionRoleUniversalIdentifier` は、`*.role.ts` ファイルで定義するロールと一致している必要があります（下記参照）。
|
||||
|
||||
#### Roles and permissions
|
||||
#### ロールと権限
|
||||
|
||||
Applications can define roles that encapsulate permissions on your workspace’s objects and actions. The field `functionRoleUniversalIdentifier` in `application.config.ts` designates the default role used by your app’s serverless functions.
|
||||
アプリケーションは、ワークスペース内のオブジェクトやアクションに対する権限をカプセル化するロールを定義できます。 `application.config.ts` の `functionRoleUniversalIdentifier` フィールドは、アプリのサーバーレス関数で使用されるデフォルトのロールを指定します。
|
||||
|
||||
* The runtime API key injected as `TWENTY_API_KEY` is derived from this default function role.
|
||||
* The typed client will be restricted to the permissions granted to that role.
|
||||
* Follow least‑privilege: create a dedicated role with only the permissions your functions need, then reference its universal identifier.
|
||||
* `TWENTY_API_KEY` として注入される実行時の API キーは、このデフォルトの関数ロールから派生します。
|
||||
* 型付きクライアントの権限は、そのロールに付与された権限に制限されます。
|
||||
* 最小権限の原則に従い、関数に必要な権限のみに限定した専用ロールを作成し、そのユニバーサル識別子を参照してください。
|
||||
|
||||
##### Default function role (role.config.ts)
|
||||
##### デフォルトの関数ロール（\*.role.ts）
|
||||
|
||||
When you scaffold a new app, the CLI also creates `src/role.config.ts`. This file exports the default role your serverless functions will use at runtime:
|
||||
新しいアプリをスキャフォルドすると、CLI はデフォルトのロールファイルも作成します。 組み込み検証付きでロールを定義するには `defineRole()` を使用します：
|
||||
|
||||
```typescript
|
||||
import { PermissionFlag, type RoleConfig } from 'twenty-sdk';
|
||||
// src/app/default-function.role.ts
|
||||
import { defineRole, PermissionFlag } from 'twenty-sdk';
|
||||
|
||||
export const functionRole: RoleConfig = {
|
||||
universalIdentifier: '<generated-role-uuid>',
|
||||
label: 'My Twenty App default function role',
|
||||
description: 'My Twenty App default function role',
|
||||
canReadAllObjectRecords: true,
|
||||
canUpdateAllObjectRecords: true,
|
||||
canSoftDeleteAllObjectRecords: true,
|
||||
canDestroyAllObjectRecords: false,
|
||||
};
|
||||
```
|
||||
export const DEFAULT_FUNCTION_ROLE_UNIVERSAL_IDENTIFIER =
|
||||
'b648f87b-1d26-4961-b974-0908fd991061';
|
||||
|
||||
The `universalIdentifier` of this role is automatically wired into `application.config.ts` as `functionRoleUniversalIdentifier`. In other words:
|
||||
|
||||
* **role.config.ts** defines what the default function role can do.
|
||||
* **application.config.ts** points to that role so your functions inherit its permissions.
|
||||
|
||||
As you move beyond the initial scaffold, you should tighten this role and make it explicit about what it can access. A more production-ready role might look closer to:
|
||||
|
||||
```typescript
|
||||
import { PermissionFlag, type RoleConfig } from 'twenty-sdk';
|
||||
|
||||
export const functionRole: RoleConfig = {
|
||||
universalIdentifier: '<your-role-uuid>',
|
||||
export default defineRole({
|
||||
universalIdentifier: DEFAULT_FUNCTION_ROLE_UNIVERSAL_IDENTIFIER,
|
||||
label: 'Default function role',
|
||||
description: 'Default role for function Twenty client',
|
||||
canReadAllObjectRecords: false,
|
||||
@@ -363,41 +445,41 @@ export const functionRole: RoleConfig = {
|
||||
canUpdateFieldValue: false,
|
||||
},
|
||||
],
|
||||
permissionFlags: ['APPLICATIONS'],
|
||||
};
|
||||
permissionFlags: [PermissionFlag.APPLICATIONS],
|
||||
});
|
||||
```
|
||||
|
||||
Notes:
|
||||
このロールの `universalIdentifier` は、`application.config.ts` で `functionRoleUniversalIdentifier` として参照されます。 言い換えると：
|
||||
|
||||
* Start from the scaffolded role, then progressively restrict it following least‑privilege.
|
||||
* Replace the `objectPermissions` and `fieldPermissions` with the objects/fields your functions need.
|
||||
* `permissionFlags` control access to platform-level capabilities. Keep them minimal; add only what you need.
|
||||
* See a working example in the Hello World app: [`packages/twenty-apps/hello-world/src/roles/function-role.ts`](https://github.com/twentyhq/twenty/blob/main/packages/twenty-apps/hello-world/src/roles/function-role.ts).
|
||||
* **\*.role.ts** は、デフォルトの関数ロールで可能な操作を定義します。
|
||||
* **application.config.ts** でそのロールを指定することで、関数はその権限を継承します。
|
||||
|
||||
### Serverless function config and entrypoint
|
||||
注記：
|
||||
|
||||
Each function exports a main handler and a config describing its triggers. You can mix multiple trigger types.
|
||||
* スキャフォルドされたロールから開始し、最小権限の原則に従って段階的に制限してください。
|
||||
* `objectPermissions` と `fieldPermissions` を、関数に必要なオブジェクト／フィールドに置き換えてください。
|
||||
* `permissionFlags` はプラットフォームレベルの機能へのアクセスを制御します。 最小限に保ち、必要なものだけを追加してください。
|
||||
* 動作例は Hello World アプリにあります: [packages/twenty-apps/hello-world/src/roles/function-role.ts](https://github.com/twentyhq/twenty/blob/main/packages/twenty-apps/hello-world/src/roles/function-role.ts)。
|
||||
|
||||
### サーバーレス関数の設定とエントリポイント
|
||||
|
||||
各関数ファイルは、ハンドラーと任意のトリガーを含む設定を `defineFunction()` でエクスポートします。 自動検出のために `*.function.ts` のファイルサフィックスを使用します。
|
||||
|
||||
```typescript
|
||||
// src/actions/create-new-post-card.ts
|
||||
import type {
|
||||
FunctionConfig,
|
||||
DatabaseEventPayload,
|
||||
ObjectRecordCreateEvent,
|
||||
CronPayload,
|
||||
} from 'twenty-sdk';
|
||||
import Twenty, { type Person } from '../generated';
|
||||
// src/app/createPostCard.function.ts
|
||||
import { defineFunction } from 'twenty-sdk';
|
||||
import type { DatabaseEventPayload, ObjectRecordCreateEvent, CronPayload, RoutePayload } from 'twenty-sdk';
|
||||
import Twenty, { type Person } from '../../generated';
|
||||
|
||||
// main handler can accept parameters from route, cron, or database events
|
||||
export const main = async (
|
||||
const handler = async (
|
||||
params:
|
||||
| { name?: string }
|
||||
| RoutePayload
|
||||
| DatabaseEventPayload<ObjectRecordCreateEvent<Person>>
|
||||
| CronPayload,
|
||||
) => {
|
||||
const client = new Twenty(); // generated typed client
|
||||
const name = 'name' in params
|
||||
? params.name ?? process.env.DEFAULT_RECIPIENT_NAME ?? 'Hello world'
|
||||
const name = 'name' in params.queryStringParameters
|
||||
? params.queryStringParameters.name ?? process.env.DEFAULT_RECIPIENT_NAME ?? 'Hello world'
|
||||
: 'Hello world';
|
||||
|
||||
const result = await client.mutation({
|
||||
@@ -410,14 +492,15 @@ export const main = async (
|
||||
return result;
|
||||
};
|
||||
|
||||
export const config: FunctionConfig = {
|
||||
universalIdentifier: '<function-uuid>',
|
||||
export default defineFunction({
|
||||
universalIdentifier: 'e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf',
|
||||
name: 'create-new-post-card',
|
||||
timeoutSeconds: 2,
|
||||
handler,
|
||||
triggers: [
|
||||
// Public HTTP route trigger '/s/post-card/create'
|
||||
{
|
||||
universalIdentifier: '<route-trigger-uuid>',
|
||||
universalIdentifier: 'c9f84c8d-b26d-40d1-95dd-4f834ae5a2c6',
|
||||
type: 'route',
|
||||
path: '/post-card/create',
|
||||
httpMethod: 'GET',
|
||||
@@ -425,39 +508,137 @@ export const config: FunctionConfig = {
|
||||
},
|
||||
// Cron trigger (CRON pattern)
|
||||
{
|
||||
universalIdentifier: '<cron-trigger-uuid>',
|
||||
universalIdentifier: 'dd802808-0695-49e1-98c9-d5c9e2704ce2',
|
||||
type: 'cron',
|
||||
pattern: '0 0 1 1 *',
|
||||
},
|
||||
// Database event trigger
|
||||
{
|
||||
universalIdentifier: '<db-trigger-uuid>',
|
||||
universalIdentifier: '203f1df3-4a82-4d06-a001-b8cf22a31156',
|
||||
type: 'databaseEvent',
|
||||
eventName: 'person.created',
|
||||
eventName: 'person.updated',
|
||||
updatedFields: ['name'],
|
||||
},
|
||||
],
|
||||
});
|
||||
```
|
||||
|
||||
一般的なトリガーの種類：
|
||||
|
||||
* **route**: `/s/` エンドポイント配下で、HTTP パスとメソッドで関数を公開します：
|
||||
|
||||
> 例: `path: '/post-card/create',` -> `<APP_URL>/s/post-card/create` で呼び出し
|
||||
|
||||
* **cron**: CRON 式を使用してスケジュールで関数を実行します。
|
||||
* **databaseEvent**: ワークスペースのオブジェクトのライフサイクルイベントで実行されます。 イベント操作が `updated` の場合、監視する特定のフィールドを `updatedFields` 配列で指定できます。 未定義または空のままにすると、任意の更新でも関数がトリガーされます。
|
||||
|
||||
> 例: `person.updated`
|
||||
|
||||
注記：
|
||||
|
||||
* `triggers` 配列は任意です。 トリガーのない関数は、他の関数から呼び出されるユーティリティ関数として使用できます。
|
||||
* 1 つの関数で複数のトリガータイプを組み合わせることができます。
|
||||
|
||||
### ルートトリガーのペイロード
|
||||
|
||||
<Warning>
|
||||
**破壊的変更（v1.16、2026年1月）：** ルートトリガーのペイロード形式が変更されました。 v1.16 以前は、クエリパラメーター、パスパラメーター、および body がペイロードとして直接送信されていました。 v1.16 以降は、それらは構造化された `RoutePayload` オブジェクト内にネストされます。
|
||||
|
||||
**v1.16 以前:**
|
||||
|
||||
```typescript
|
||||
const handler = async (params) => {
|
||||
const { param1, param2 } = params; // Direct access
|
||||
};
|
||||
```
|
||||
|
||||
**v1.16 以降:**
|
||||
|
||||
```typescript
|
||||
const handler = async (event: RoutePayload) => {
|
||||
const { param1, param2 } = event.body; // Access via .body
|
||||
const { queryParam } = event.queryStringParameters;
|
||||
const { id } = event.pathParameters;
|
||||
};
|
||||
```
|
||||
|
||||
**既存の関数を移行するには：** ハンドラーで、params オブジェクトから直接ではなく、`event.body`、`event.queryStringParameters`、または `event.pathParameters` から分割代入するように更新してください。
|
||||
</Warning>
|
||||
|
||||
ルートトリガーが関数を呼び出すと、AWS HTTP API v2 形式に準拠した `RoutePayload` オブジェクトを受け取ります。 型を `twenty-sdk` からインポートします:
|
||||
|
||||
```typescript
|
||||
import { defineFunction, type RoutePayload } from 'twenty-sdk';
|
||||
|
||||
const handler = async (event: RoutePayload) => {
|
||||
// Access request data
|
||||
const { headers, queryStringParameters, pathParameters, body } = event;
|
||||
|
||||
// HTTP method and path are available in requestContext
|
||||
const { method, path } = event.requestContext.http;
|
||||
|
||||
return { message: 'Success' };
|
||||
};
|
||||
```
|
||||
|
||||
Common trigger types:
|
||||
`RoutePayload` 型は次の構造になっています:
|
||||
|
||||
* route: Exposes your function on an HTTP path and method **under the `/s/` endpoint**:
|
||||
| プロパティ | タイプ | 説明 |
|
||||
| ---------------------------- | ------------------------------------- | ---------------------------------------------------------- |
|
||||
| `headers` | `Record<string, string \| undefined>` | HTTP ヘッダー (`forwardedRequestHeaders` に列挙されたもののみ) |
|
||||
| `queryStringParameters` | `Record<string, string \| undefined>` | クエリ文字列パラメーター (複数の値はカンマで連結) |
|
||||
| `pathParameters` | `Record<string, string \| undefined>` | ルートパターンから抽出されたパスパラメーター (例: `/users/:id` → `{ id: '123' }`) |
|
||||
| `本文` | `object \| null` | 解析済みのリクエストボディ (JSON) |
|
||||
| `isBase64Encoded` | `ブール型` | body が base64 エンコードされているかどうか |
|
||||
| `requestContext.http.method` | `string` | HTTP メソッド (GET, POST, PUT, PATCH, DELETE) |
|
||||
| `requestContext.http.path` | `string` | 生のリクエストパス |
|
||||
|
||||
> e.g. `path: '/post-card/create',` -> call on `<APP_URL>/s/post-card/create`
|
||||
### HTTP ヘッダーの転送
|
||||
|
||||
* cron: Runs your function on a schedule using a CRON expression.
|
||||
* databaseEvent: Runs on workspace object lifecycle events
|
||||
デフォルトでは、セキュリティ上の理由から、受信リクエストの HTTP ヘッダーはサーバーレス関数に**渡されません**。 特定のヘッダーにアクセスするには、`forwardedRequestHeaders` 配列に明示的に列挙してください:
|
||||
|
||||
> e.g. `person.created`
|
||||
```typescript
|
||||
export default defineFunction({
|
||||
universalIdentifier: 'e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf',
|
||||
name: 'webhook-handler',
|
||||
handler,
|
||||
triggers: [
|
||||
{
|
||||
universalIdentifier: 'c9f84c8d-b26d-40d1-95dd-4f834ae5a2c6',
|
||||
type: 'route',
|
||||
path: '/webhook',
|
||||
httpMethod: 'POST',
|
||||
isAuthRequired: false,
|
||||
forwardedRequestHeaders: ['x-webhook-signature', 'content-type'],
|
||||
},
|
||||
],
|
||||
});
|
||||
```
|
||||
|
||||
You can create new functions in two ways:
|
||||
ハンドラー内で、これらのヘッダーにアクセスできます:
|
||||
|
||||
* **Scaffolded**: Run `yarn create-entity --path <custom-path>` and choose the option to add a new function. This generates a starter file under `<custom-path>` with a `main` handler and a `config` block similar to the example above.
|
||||
* **Manual**: Create a new file and export `main` and `config` yourself, following the same pattern.
|
||||
```typescript
|
||||
const handler = async (event: RoutePayload) => {
|
||||
const signature = event.headers['x-webhook-signature'];
|
||||
const contentType = event.headers['content-type'];
|
||||
|
||||
### Generated typed client
|
||||
// Validate webhook signature...
|
||||
return { received: true };
|
||||
};
|
||||
```
|
||||
|
||||
Run yarn generate to create a local typed client in generated/ based on your workspace schema. Use it in your functions:
|
||||
<Note>
|
||||
ヘッダー名は小文字に正規化されます。 小文字のキーを使用してアクセスしてください (例: `event.headers['content-type']`)。
|
||||
</Note>
|
||||
|
||||
新しい関数は次の 2 通りで作成できます：
|
||||
|
||||
* **スキャフォルド**: `yarn app:create-entity` を実行し、新しい関数を追加するオプションを選択します。 これにより、ハンドラーと設定を備えたスターターファイルが生成されます。
|
||||
* **手動**: 新しい `*.function.ts` ファイルを作成し、同じパターンで `defineFunction()` を使用します。
|
||||
|
||||
### 生成された型付きクライアント
|
||||
|
||||
ワークスペースのスキーマに基づき、generated/ にローカルの型付きクライアントを作成するには yarn app:generate を実行します。 関数内で使用します：
|
||||
|
||||
```typescript
|
||||
import Twenty from './generated';
|
||||
@@ -466,34 +647,34 @@ const client = new Twenty();
|
||||
const { me } = await client.query({ me: { id: true, displayName: true } });
|
||||
```
|
||||
|
||||
The client is re-generated by `yarn generate`. Re-run after changing your objects and `yarn sync` or when onboarding to a new workspace.
|
||||
このクライアントは `yarn app:generate` によって再生成されます。 オブジェクトを変更して `yarn app:sync` した後、または新しいワークスペースにオンボードする際には再実行してください。
|
||||
|
||||
#### Runtime credentials in serverless functions
|
||||
#### サーバーレス関数における実行時認証情報
|
||||
|
||||
When your function runs on Twenty, the platform injects credentials as environment variables before your code executes:
|
||||
関数が Twenty 上で実行されると、コードが実行される前に、プラットフォームが認証情報を環境変数として注入します：
|
||||
|
||||
* `TWENTY_API_URL`: Base URL of the Twenty API your app targets.
|
||||
* `TWENTY_API_KEY`: Short‑lived key scoped to your application’s default function role.
|
||||
* `TWENTY_API_URL`: アプリが対象とする Twenty API のベース URL。
|
||||
* `TWENTY_API_KEY`: アプリケーションのデフォルト関数ロールにスコープされた短命のキー。
|
||||
|
||||
Notes:
|
||||
ノート:
|
||||
|
||||
* You do not need to pass URL or API key to the generated client. It reads `TWENTY_API_URL` and `TWENTY_API_KEY` from process.env at runtime.
|
||||
* The API key’s permissions are determined by the role referenced in your `application.config.ts` via `functionRoleUniversalIdentifier`. This is the default role used by serverless functions of your application.
|
||||
* Applications can define roles to follow least‑privilege. Grant only the permissions your functions need, then point `functionRoleUniversalIdentifier` to that role’s universal identifier.
|
||||
* 生成されたクライアントに URL や API キーを渡す必要はありません。 実行時に process.env から `TWENTY_API_URL` と `TWENTY_API_KEY` を読み取ります。
|
||||
* API キーの権限は、`application.config.ts` で `functionRoleUniversalIdentifier` によって参照されるロールによって決まります。 これは、アプリケーションのサーバーレス関数で使用されるデフォルトのロールです。
|
||||
* アプリケーションは、最小権限の原則に従うロールを定義できます。 関数に必要な権限のみを付与し、`functionRoleUniversalIdentifier` をそのロールのユニバーサル識別子に指定してください。
|
||||
|
||||
### Hello World example
|
||||
### Hello World の例
|
||||
|
||||
Explore a minimal, end-to-end example that demonstrates objects, functions, and multiple triggers [here](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/hello-world):
|
||||
オブジェクト、関数、複数のトリガーを示す最小のエンドツーエンド例は[こちら](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/hello-world)をご覧ください。
|
||||
|
||||
## Manual setup (without the scaffolder)
|
||||
## 手動セットアップ（スキャフォルダーなし）
|
||||
|
||||
While we recommend using `create-twenty-app` for the best getting-started experience, you can also set up a project manually. Do not install the CLI globally. Instead, add `twenty-sdk` as a local dependency and wire scripts in your package.json:
|
||||
最適な導入体験のために `create-twenty-app` の使用を推奨しますが、手動でプロジェクトをセットアップすることもできます。 CLI をグローバルにインストールしないでください。 代わりに、`twenty-sdk` をローカル依存関係として追加し、package.json にスクリプトを設定します：
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn add -D twenty-sdk
|
||||
```
|
||||
|
||||
Then add scripts like these:
|
||||
次のようなスクリプトを追加します：
|
||||
|
||||
```json filename="package.json"
|
||||
{
|
||||
@@ -510,13 +691,13 @@ Then add scripts like these:
|
||||
}
|
||||
```
|
||||
|
||||
Now you can run the same commands via Yarn, e.g. `yarn dev`, `yarn sync`, etc.
|
||||
これで Yarn 経由で同じコマンド（例：`yarn app:dev`、`yarn app:sync` など）を実行できます。
|
||||
|
||||
## Troubleshooting
|
||||
## トラブルシューティング
|
||||
|
||||
* Authentication errors: run `yarn auth` and ensure your API key has the required permissions.
|
||||
* Cannot connect to server: verify the API URL and that the Twenty server is reachable.
|
||||
* Types or client missing/outdated: run `yarn generate` and then `yarn dev`.
|
||||
* Dev mode not syncing: ensure `yarn dev` is running and that changes are not ignored by your environment.
|
||||
* 認証エラー: `yarn auth:login` を実行し、API キーに必要な権限があることを確認してください。
|
||||
* サーバーに接続できません: API URL と、Twenty サーバーに到達可能であることを確認してください。
|
||||
* 型やクライアントがない／古い: `yarn app:generate` を実行してから `yarn app:dev` を実行してください。
|
||||
* 開発モードで同期されない: `yarn app:dev` が実行中であり、環境によって変更が無視されていないことを確認してください。
|
||||
|
||||
Discord Help Channel: https://discord.com/channels/1130383047699738754/1130386664812982322
|
||||
Discord ヘルプチャンネル: https://discord.com/channels/1130383047699738754/1130386664812982322
|
||||
|
||||
@@ -1,44 +1,44 @@
|
||||
---
|
||||
title: Webhooks
|
||||
description: Receive real-time notifications when events occur in your CRM.
|
||||
description: CRM でイベントが発生したときにリアルタイム通知を受信します。
|
||||
---
|
||||
|
||||
import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';
|
||||
|
||||
Webhooks push data to your systems in real-time when events occur in Twenty — no polling required. Use them to keep external systems in sync, trigger automations, or send alerts.
|
||||
ウェブフックは、Twenty でイベントが発生したときに、ポーリング不要でリアルタイムにお使いのシステムへデータをプッシュします。 外部システムとの同期を保ち、オートメーションをトリガーしたり、アラートを送信したりするために使用できます。
|
||||
|
||||
## Create a Webhook
|
||||
## Webhookを作成
|
||||
|
||||
1. Go to **Settings → APIs & Webhooks → Webhooks**
|
||||
2. Click **+ Create webhook**
|
||||
3. Enter your webhook URL (must be publicly accessible)
|
||||
4. Click **Save**
|
||||
1. **Settings → APIs & Webhooks → Webhooks**に移動
|
||||
2. **+ Webhookを作成**をクリック
|
||||
3. ウェブフックの URL を入力（外部からアクセス可能である必要があります）
|
||||
4. **保存**をクリック
|
||||
|
||||
The webhook activates immediately and starts sending notifications.
|
||||
ウェブフックは直ちに有効化され、通知の送信を開始します。
|
||||
|
||||
<VimeoEmbed videoId="928786708" title="Creating a webhook" />
|
||||
<VimeoEmbed videoId="928786708" title="ウェブフックの作成" />
|
||||
|
||||
### Manage Webhooks
|
||||
### Webhookを管理
|
||||
|
||||
**Edit**: Click the webhook → Update URL → **Save**
|
||||
**編集**: ウェブフックをクリック → URL を更新 → **保存**
|
||||
|
||||
**Delete**: Click the webhook → **Delete** → Confirm
|
||||
**削除**: ウェブフックをクリック → **削除** → 確認
|
||||
|
||||
## Events
|
||||
## イベント
|
||||
|
||||
Twenty sends webhooks for these event types:
|
||||
Twenty は次のイベントタイプに対してウェブフックを送信します。
|
||||
|
||||
| Event | Example |
|
||||
| ------------------ | ---------------------------------------------------------- |
|
||||
| **Record Created** | `person.created`, `company.created`, `note.created` |
|
||||
| **Record Updated** | `person.updated`, `company.updated`, `opportunity.updated` |
|
||||
| **Record Deleted** | `person.deleted`, `company.deleted` |
|
||||
| イベント | 例 |
|
||||
| ----------- | ---------------------------------------------------------- |
|
||||
| **レコードの作成** | `person.created`, `company.created`, `note.created` |
|
||||
| **レコードの更新** | `person.updated`, `company.updated`, `opportunity.updated` |
|
||||
| **レコードの削除** | `person.deleted`, `company.deleted` |
|
||||
|
||||
All event types are sent to your webhook URL. Event filtering may be added in future releases.
|
||||
すべてのイベントタイプはウェブフックの URL に送信されます。 イベントのフィルタリングは将来のリリースで追加される可能性があります。
|
||||
|
||||
## Payload Format
|
||||
## ペイロード形式
|
||||
|
||||
Each webhook sends an HTTP POST with a JSON body:
|
||||
各ウェブフックは JSON ボディを含む HTTP POST を送信します。
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -55,35 +55,35 @@ Each webhook sends an HTTP POST with a JSON body:
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Description |
|
||||
| ----------- | ------------------------------------------------ |
|
||||
| `event` | What happened (e.g., `person.created`) |
|
||||
| `data` | The full record that was created/updated/deleted |
|
||||
| `timestamp` | When the event occurred (UTC) |
|
||||
| フィールド | 説明 |
|
||||
| --------- | --------------------------- |
|
||||
| `イベント` | 何が起きたか（例: `person.created`） |
|
||||
| `データ` | 作成／更新／削除された完全なレコード |
|
||||
| `タイムスタンプ` | イベントが発生した時刻（UTC） |
|
||||
|
||||
<Note>
|
||||
Respond with a **2xx HTTP status** (200-299) to acknowledge receipt. Non-2xx responses are logged as delivery failures.
|
||||
受信を確認するために、**2xx HTTP ステータス**（200～299）で応答してください。 2xx 以外の応答は配信失敗として記録されます。
|
||||
</Note>
|
||||
|
||||
## Webhook Validation
|
||||
## ウェブフックの検証
|
||||
|
||||
Twenty signs each webhook request for security. Validate signatures to ensure requests are authentic.
|
||||
Twenty はセキュリティのために各ウェブフックリクエストに署名します。 リクエストが正当であることを確認するために署名を検証してください。
|
||||
|
||||
### Headers
|
||||
### ヘッダー
|
||||
|
||||
| Header | Description |
|
||||
| ---------------------------- | --------------------- |
|
||||
| `X-Twenty-Webhook-Signature` | HMAC SHA256 signature |
|
||||
| `X-Twenty-Webhook-Timestamp` | Request timestamp |
|
||||
| ヘッダー | 説明 |
|
||||
| ---------------------------- | -------------- |
|
||||
| `X-Twenty-Webhook-Signature` | HMAC SHA256 署名 |
|
||||
| `X-Twenty-Webhook-Timestamp` | リクエストのタイムスタンプ |
|
||||
|
||||
### Validation Steps
|
||||
### 検証手順
|
||||
|
||||
1. Get the timestamp from `X-Twenty-Webhook-Timestamp`
|
||||
2. Create the string: `{timestamp}:{JSON payload}`
|
||||
3. Compute HMAC SHA256 using your webhook secret
|
||||
4. Compare with `X-Twenty-Webhook-Signature`
|
||||
1. `X-Twenty-Webhook-Timestamp` からタイムスタンプを取得
|
||||
2. 次の文字列を作成: `{timestamp}:{JSON payload}`
|
||||
3. ウェブフックシークレットを使用して HMAC SHA256 を計算
|
||||
4. `X-Twenty-Webhook-Signature` と比較
|
||||
|
||||
### Example (Node.js)
|
||||
### 例（Node.js）
|
||||
|
||||
```javascript
|
||||
const crypto = require("crypto");
|
||||
@@ -101,12 +101,12 @@ const expectedSignature = crypto
|
||||
const isValid = expectedSignature === req.headers["x-twenty-webhook-signature"];
|
||||
```
|
||||
|
||||
## Webhooks vs Workflows
|
||||
## ウェブフック vs ワークフロー
|
||||
|
||||
| Method | Direction | Use Case |
|
||||
| ---------------------------- | --------- | ---------------------------------------------------------- |
|
||||
| **Webhooks** | OUT | Automatically notify external systems of any record change |
|
||||
| **Workflow + HTTP Request** | OUT | Send data out with custom logic (filters, transformations) |
|
||||
| **Workflow Webhook Trigger** | IN | Receive data into Twenty from external systems |
|
||||
| メソッド | 方向 | ユースケース |
|
||||
| ----------------------- | --- | --------------------------- |
|
||||
| **ウェブフック** | OUT | あらゆるレコード変更を外部システムへ自動通知 |
|
||||
| **ワークフロー + HTTP リクエスト** | OUT | カスタムロジック（フィルター、変換）でデータを外部送信 |
|
||||
| **ワークフローのウェブフックトリガー** | IN | 外部システムから Twenty にデータを受信 |
|
||||
|
||||
For receiving external data, see [Set Up a Webhook Trigger](/l/ja/user-guide/workflows/how-tos/connect-to-other-tools/set-up-a-webhook-trigger).
|
||||
外部データの受信については、[Webhook トリガーを設定](/l/ja/user-guide/workflows/how-tos/connect-to-other-tools/set-up-a-webhook-trigger)を参照してください。
|
||||
|
||||
@@ -1,34 +1,34 @@
|
||||
---
|
||||
title: Extend
|
||||
description: Extend Twenty's functionality with APIs, webhooks, and custom apps.
|
||||
title: 拡張
|
||||
description: API、Webhook、カスタムアプリで Twenty の機能を拡張できます。
|
||||
---
|
||||
|
||||
<Frame>
|
||||
<img src="/images/user-guide/integrations/plug.png" alt="AI" />
|
||||
</Frame>
|
||||
|
||||
## Overview
|
||||
## 概要
|
||||
|
||||
Twenty is designed to be extensible. Use our APIs, webhooks, and app framework to integrate with your existing tools and build custom functionality.
|
||||
Twenty は拡張性を念頭に設計されています。 当社の API、Webhook、アプリフレームワークを使用して既存のツールと統合し、カスタム機能を構築できます。
|
||||
|
||||
## What You Can Do
|
||||
## 現在できること
|
||||
|
||||
* **APIs**: Query and modify your CRM data programmatically using REST or GraphQL
|
||||
* **Webhooks**: Receive real-time notifications when events occur in Twenty
|
||||
* **Apps**: Build custom applications that extend Twenty's capabilities - Coming soon!
|
||||
* **API**: REST または GraphQL を使用して、プログラムから CRM データをクエリおよび変更します。
|
||||
* **ウェブフック**: Twenty でイベントが発生したときにリアルタイム通知を受信します。
|
||||
* **アプリ**: Twenty の機能を拡張するカスタムアプリケーションを構築 - 近日公開！
|
||||
|
||||
## Getting Started
|
||||
## 始めに
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="APIs" icon="code" href="/l/ja/developers/extend/capabilities/apis">
|
||||
Connect to Twenty programmatically
|
||||
<Card title="API" icon="コード" href="/l/ja/developers/extend/capabilities/apis">
|
||||
プログラムから Twenty に接続
|
||||
</Card>
|
||||
|
||||
<Card title="Webhooks" icon="bell" href="/l/ja/developers/extend/capabilities/webhooks">
|
||||
Get notified of events in real-time
|
||||
<Card title="ウェブフック" icon="bell" href="/l/ja/developers/extend/capabilities/webhooks">
|
||||
イベントの通知をリアルタイムで受け取る
|
||||
</Card>
|
||||
|
||||
<Card title="Apps" icon="puzzle-piece" href="/l/ja/developers/extend/capabilities/apps">
|
||||
Build customizations as code (Alpha)
|
||||
<Card title="アプリ" icon="puzzle-piece" href="/l/ja/developers/extend/capabilities/apps">
|
||||
カスタマイズをコードとして構築（アルファ版）
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
Reference in New Issue
Block a user