---
title: フィールドマッピング
description: データインポート時のフィールドマッピングの仕組み。
---

import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';

## フィールドマッピングの仕組み

ファイルをアップロードすると、Twenty が列を解析し、既存のフィールドに一致させようとします。

### 自動マッピング

Twenty は次の基準に基づいて列を照合します：

* 列ヘッダー名（完全一致または類似一致）
* データ型の検出（日付、数値、メールアドレス）
* 一般的なフィールドのパターン

<Note>**クイックヒント：** インポートしたいオブジェクトから数行をエクスポートしてください。 エクスポートしたファイルには、Twenty が想定する正確な列名が含まれているため、インポート時の自動マッピングがスムーズになります。</Note>

### 手動マッピングのオプション

各列に対して、次の操作ができます：

* **フィールドにマップ**：ドロップダウンから一致する Twenty のフィールドを選択します
* **マップしない**：その列をスキップします（データはインポートされません）

<Note>**フィールドはインポート前に存在している必要があります。** インポートで作成されるのはフィールドではなくレコードです。 インポート前に **Settings → Data Model** でカスタムフィールドを作成してください。</Note>

## フィールドタイプの互換性

Data Model で利用可能なすべてのフィールドタイプはインポートに対応しています。

`id` 値をインポートして、新規レコードに特定の ID を割り当てるか、既存レコードを更新することもできます。

<img src="/images/user-guide/fields/all-field-types.png" style={{width:'100%'}} />

## データ形式の要件

<Note>**一部のフィールドには特別な書式があります。** インポートの準備をする前にサンプルファイルをダウンロードし、各フィールドタイプに期待される書式を確認することをおすすめします。</Note>

### 住所フィールド

住所は複数の列を持つネストされたフィールドです。 一部は空欄のままにできます。

* **Address / Address 1**：住所の1行目
* **Address / Address 2**：住所の2行目
* **Address / City**：市区町村名
* **Address / State**：州または都道府県
* **Address / Country**：国名
* **Address / Post Code**：郵便番号／ZIP コード

### 配列フィールド

次の形式を使用します：

```
["value1","value2"]
```

### ブール型フィールド

`TRUE` または `FALSE`（大文字）を使用します。`true` や `false` は使用しません

### 通貨フィールド

通貨は 2 列からなるネストされたフィールドで、**両方を必ず入力** する必要があります：

* **Amount / Amount**：数値（例：`1234.56`）
* **Amount / Currency**：通貨コード（例：`USD`、`EUR`）

### 日付フィールド

サポートされている形式：

* `YYYY-MM-DD`（推奨）
* `MM/DD/YYYY`
* `DD/MM/YYYY`
* ISO 8601 形式

### ドメインフィールド

* 重複作成を避けるため、`https://domain.com` の形式を使用することを推奨します。これは、メールボックスおよびカレンダーの同期で作成される Companies オブジェクトでも使用される形式です
* `Domain Label` と `Domain URL` を入力できます。ベストプラクティスは、ラベルには `domain.com`、URL には `https://domain.com` を入力することです
* Companies オブジェクト内でドメインは一意である必要があります
* **インポートするファイル内でもドメインは一意である必要があります**

### メールアドレスフィールド

* 有効なメールアドレス形式である必要があります
* People オブジェクト内でメールアドレスは一意である必要があります
* **インポートするファイル内でもメールアドレスは一意である必要があります**
* 追加のメールアドレスについて：メインのメールには **Emails / Primary Email** を使用し、**Emails / Additional Emails** には次の形式を使用します：

```
["jane@twenty.com","jane.doe@twenty.com"]
```

### ID フィールド

インポート時に `id` を指定するかどうかは任意です。 指定しない場合は、Twenty が自動生成します。

`id` 列をマッピングするユースケース：

* **特定の ID を設定**：新規作成されるレコードの UUID を指定します
* **既存レコードを更新**：既存レコードに照合して、重複を作成せずに更新します。 その場合、他の一意なフィールドはマッピングしないことを推奨します。唯一の一意フィールドのみをマッピングすることで、よりスムーズにインポートできます。

<Note>`id` を指定する場合は UUID 形式（例：`c776ee49-f608-4a77-8cc8-6fe96ae1e43f`）である必要があります。</Note>

### JSON フィールド

有効な JSON 形式を使用します：

```
{"key":"value","key2":"value2"}
```

### リンクフィールド

ドメインフィールドと同様に：

* ラベル列と URL 列の両方を入力します：**Links / Link URL** と **Links / Link Label**
* 完全な URL 形式（`https://example.com`）を使用します
* セカンダリリンクには **Links / Secondary Links** 列を使用し、次の形式で入力します：

```
[{"url":"https://twenty.com","label":"Twenty"}]
```

### マルチセレクトフィールド

表示ラベルではなく **API 名** を使用し、次の形式で指定します：

```
["VALUE1","VALUE2"]
```

API 名の確認方法は[こちら](#finding-api-names-for-select-fields)をご覧ください。

<Note>新しい選択肢はインポートによって自動作成されません。 インポート前に **Settings → Data Model** で追加する必要があります。</Note>

<Warning>
**インポートは追加ではなく上書きです。**

レコードにすでに `VALUE2` と `VALUE3` が選択されている状態で `["VALUE1"]` をインポートすると、インポート後そのレコードは `VALUE1` のみになります。 以前の選択は結合されず、置き換えられます。
</Warning>

### 数値フィールド

* 数値のみ
* 小数点はピリオドを使用：`1234.56`
* 桁区切りは使用しないでください

### 電話番号フィールド

電話は複数の列からなるネストされたフィールドで、**必ず入力** する必要があります

* **Phones / Primary Phone Number**：電話番号（例：`4159095555`）
* **Phones / Primary Phone Country Code**：国コード（例：`US`）
* **Phones / Primary Phone Calling Code**：ダイヤルコード（例：`+1`）

### 評価フィールド

API 名の形式（`RATING_1`、`RATING_2`、`RATING_3`、`RATING_4`、`RATING_5`）を使用します

### リレーションフィールド

詳細は専用記事「[オブジェクト間のリレーションのインポート](/l/ja/user-guide/data-migration/capabilities/import-relations)」をご覧ください

### 選択フィールド

表示ラベルではなく、オプションの **API 名** を使用します：

```
VALUE1
```

API 名の見つけ方は[こちら](#finding-api-names-for-select-fields)を参照してください。
<Note>新しい Select オプションは、インポートによって自動的に作成されません。 インポート前に **設定 → データモデル** で追加する必要があります。</Note>

### テキストフィールド

* 特別な書式設定は不要です
* 先頭と末尾の空白は削除されます

## API 名の見つけ方

事前定義されたオプションを持つ Select、Multi-Select、Array フィールドでは、表示ラベルではなく、必ず **API 名** を使用してください。

### API 名の確認方法

1. **設定 → データモデル** に移動する
2. オブジェクトとフィールドを選択する
3. **詳細モード** を有効にする（設定ページの右下にあるトグル）
4. 各オプションの API 名を確認する

<VimeoEmbed videoId="1144910809" title="デモ動画" />
