# ルートとダミーデータ (/ja/docs/mocks/routes)

ルートは、メソッドとパス、そしてモックがそこで返す応答です。まだ仕様がないとき、開発やテストのために数個のエンドポイントが必要なとき、仕様とは異なる応答をパスに返したいときに、ルートを手書きで作成します。
ボディは送信されるとおりにJSON、XML、テキストで書き、リクエストごとに作り直されるダミーデータを含められます。

手書きのルートは、モックの[JavaScriptのルート](/docs/mocks/scripted-routes)の後、仕様を提供している場合はその仕様のオペレーションの前に応答します。[リクエストが受け取るレスポンス](/docs/mocks#which-response-a-request-gets)を参照してください。

## ルートを作成する [#making-a-route]

[モックページ](/docs/mocks)で**新規モック**を選んでモックを作成する（最初に、5人分のダミーのユーザーを返す`GET /users`ルートが含まれます）か、既存のモックを開きます。**ルート**カードに、そのモックのルートが一覧表示されます。

- チェックボックスで、ルートを削除せずにオフにできます。オフのルートは何も応答しません。
- ルートをクリックすると、リストの下で編集できます。
- **ルートを追加**は、選択したルートの後に新しいルートを追加します。
- ルートを右クリックすると、**複製**、**リクエストを作成**、**アドレスをコピー**（モックの動作中）、**上へ移動**、**下へ移動**、**ルートを削除**を選べます。

変更はすべてすぐに保存され、動作中のモックにもすぐに反映されます。**編集 › 取り消す**で、ルートの削除も含め、どの変更も元に戻せます。
オンの2つのルートが同じメソッドとパスを持つ場合、カードに警告が表示されます。応答するのは最初のルートだけです。

<Shot id="mocks-route-editor" alt="ルートGET /users/{id}のエディタ。メソッド、パス、概要、レスポンス200 OK（デフォルト）と404 Not found、OKレスポンスのコンテントタイプ、{{$randomUUID}}を値とするX-Request-Idヘッダー、request.params.idとダミーの値を含むJSONボディが表示されている" />

### メソッド、パス、概要 [#method-path-and-summary]

- **ルート**：メソッド（**GET**、**POST**、**PUT**、**PATCH**、**DELETE**、**HEAD**、**OPTIONS**、またはすべてのメソッドを表す**ANY**）とパス。`HEAD`リクエストは、ボディなしで**GET**ルートに渡されます。
- **パスパラメータ**は`{id}`または`:id`と書き、パスの1つの部分につき1つ使います。`/users/{id}`、`/files/{name}.json`のようになります。`:id`は`{id}`として保存されます。固定の部分を持つルートはパラメータを持つルートより優先されるため、`/users/me`は`/users/{id}`より先に応答します。
- **概要**は、ルートの用途を説明します。ルートから作成したリクエストは、これを名前にします。

## レスポンス [#responses]

ルートには1つ以上のレスポンスがあります。<strong>レスポンス</strong>の下のチップで切り替え、<strong>+</strong>で追加します。各レスポンスには次の項目があります。

| フィールド | 内容 |
| --- | --- |
| **名前** | リクエストやルールがそれを指す名前。`OK`や`Not found`など。名前はルート内で一意です。 |
| **ステータス** | ステータスコード（100〜999）。 |
| **Content-Type** | 送信される`Content-Type`。`application/json`や`application/xml`など。横のメニューによく使うタイプが並んでいます。空の場合は送信しません。ボディ内の値のエスケープ方法も、これで決まります。 |
| **ヘッダー** | 一緒に送信されるヘッダー。ボディと同じように、値にダミーデータやリクエストの一部を含められます。 |
| **ルール** | デフォルトの代わりにこのレスポンスが応答する条件。[レスポンスの選択](#choosing-a-response)を参照してください。 |
| **ボディ** | 送信される内容。JSON、XML、HTMLでは行番号と色が付きます。 |

チェックマークが付いたレスポンスがルートの**デフォルト**で、別のレスポンスの**デフォルトにする**で変更できます。ゴミ箱ボタンで、レスポンスを削除します。

### レスポンスの選択 [#choosing-a-response]

ルートへのリクエストは、次の順序でレスポンスを受け取ります。

1. リクエストが指定したレスポンス：`Prefer: example=Not found`または`Prefer: code=404`ヘッダー、またはPostmanの`x-mock-response-name`と`x-mock-response-code`ヘッダー。
2. すべてのルールに合致する最初のレスポンス。
3. ルートのデフォルト：**デフォルトにする**でデフォルトにしたレスポンス（ルールにかかわらず）。デフォルトを選んでいないルートでは、ルールに合致しなかった最初のレスポンスは、ルールのない最初のレスポンスに道を譲ります。そのため、先頭に置いた「発送済みの注文には409」が、ほかのすべての注文に応答することはありません。

**ルール**は、リクエストの1つの部分を調べます。

| ルール | 名前 | 例 |
| --- | --- | --- |
| **パスパラメータ** | パスのパラメータ | `id`が`0` |
| **クエリパラメータ** | クエリパラメータ | `page`が`*` |
| **ヘッダー** | ヘッダー（大文字と小文字は区別しません） | `X-Role`が`admin` |
| **ボディのフィールド** | JSONボディへのキーのパス。リストの項目は数字で指定し、ボディ全体なら空 | `user.plan`が`pro`、`items.0.sku`が`TNT-MH-2P` |

値は、その部分が持つべきテキストです。`*`は、何かしらの値があれば何でもよいことを表し、空の値は、その部分が存在しないことを表します。
複数のルールを持つレスポンスは、すべてのルールに合致したときだけ応答します。名前のないルールは、名前を付けるまでスキップされます。

たとえば、`GET /users/{id}`ルートはデフォルトでユーザーとともに`200`を返し、ルール**パスパラメータ** `id`が`0`の`404`レスポンスを持たせられます。

```sh
curl -i http://127.0.0.1:4010/users/42    # 200, the user
curl -i http://127.0.0.1:4010/users/0     # 404
```

<Shot id="mocks-route-rule" alt="GET /users/{id}の404 Not foundレスポンスと「デフォルトにする」、およびそのルール：パスパラメータidが0" />

## ダミーデータを含むボディ [#bodies-with-fake-data]

ボディやヘッダーの値にある`{{ }}`の中身は、リクエストが届いたときに埋め込まれるため、リクエストごとに新しいデータを返せます。ボディのそれ以外の部分は、書いたとおりに送信されます。

```json
{
  "id": "{{request.params.id}}",
  "name": "{{$randomFullName}}",
  "email": "{{$randomEmail}}",
  "company": "{{$randomCompanyName}}",
  "joined": "{{$randomDatePast}}"
}
```

### ダミーの値 [#fake-values]

`{{$randomFirstName}}`、`{{$randomEmail}}`、`{{$randomCity}}`、`{{$randomPrice}}`、`{{$randomUUID}}`など約120種類があります。
名前と職業、インターネット、住所、電話番号、会社、金融、商品、日付、単語、ロレムイプサム、ファイル、画像、データベースに分かれています。
名前はPostmanの動的変数と同じなので、Postman向けに書いたテンプレートがそのまま使えます。
引数を取るものもあります：`{{$randomInt(1, 100)}}`、`{{$randomPrice(5, 50)}}`、`{{$randomLoremWords(5)}}`、`{{$randomElement(active, paused, closed)}}`。
すべての一覧は[動的な値](/docs/reference/dynamic-values#fake-data)にあります。

ボディの上の**値を挿入**は、カーソルの位置にダミーの値を挿入します。**ダミーデータ**にグループ別に並んでいます。

同じ値はリクエストでも使え、送信のたびに作成されます。[動的な値](/docs/requests/dynamic-values)を参照してください。

### リクエストの一部 [#parts-of-the-request]

| トークン | 内容 |
| --- | --- |
| `{{request.params.id}}` | パスパラメータ。 |
| `{{request.query.page}}` | クエリパラメータ。ない場合は空。 |
| `{{request.headers.X-Trace}}` | ヘッダー（大文字と小文字は区別しません）。 |
| `{{request.body.user.name}}` | JSONボディのフィールド。キーのパスで指定します（リストの項目は`items.0.sku`）。テキストはそのまま、数値、`true`、`false`、オブジェクト、リストはJSONで挿入されます。 |
| `{{request.body}}` | ボディ全体をテキストで。 |
| `{{request.method}}` | メソッド。`POST`など。 |
| `{{request.path}}` | パス。`/users/42`など。 |

**値を挿入 › リクエスト**に、そのルート自身のパスパラメータとともに並んでいます。

### リスト [#lists]

`{{#repeat 10}}`…`{{/repeat}}`は、その間の内容を指定した回数だけ書き出します。`{{#repeat 2 8}}`は、2つの数の間の回数を、リクエストごとに選んで書き出します。
JSONボディでは、項目の区切りのカンマが自動的に付きます。
内側では、`{{@number}}`が1から数えた項目の番号、`{{@index}}`が0から数えた番号になります。繰り返しの中に繰り返しを入れられます。

```json
[
  {{#repeat 5}}
  {
    "id": {{@number}},
    "name": "{{$randomProductName}}",
    "price": {{$randomPrice}}
  }
  {{/repeat}}
]
```

`{{#repeat}}`や`{{/repeat}}`だけの行は、空行を残しません。

### エスケープ [#escaping]

値は埋め込まれる場所に合わせてエスケープされるため、引用符を含む名前でもJSONが壊れることはありません。

- JSONボディ（`json`を含む`Content-Type`）では、文字列の中の値はJSONとしてエスケープされます。`{{$randomInt}}`や`{{@number}}`のように引用符の外にある値は、そのまま入ります。
- XMLとHTML（`xml`または`html`を含む`Content-Type`）では、`&`、`<`、`>`、引用符がどこでもエスケープされます。
- 三重の波括弧はエスケープしません：`{{{request.body}}}`は、リクエストのJSONボディをJSONとして入れます。

```json
{ "received": {{{request.body}}}, "at": "{{$isoTimestamp}}" }
```

Echolotが知らないトークンは、書いたままになります。`{{$randomInt(9, 1)}}`のように値を作れない場合も書いたままになり、[ログ](/docs/mocks#the-log)に理由が表示されます。
ボディは16 MB、繰り返しは10,000項目で止まります。

ボディはそれ以外を一切読み取りません。ワークスペースの変数、環境、シークレット、ファイルは使えないため、ネットワークで応答するモックから漏れることはありません。

### 固定データ：生成 [#fixed-data-generate]

`{{ }}`の値は、リクエストごとに新しいデータを返します。毎回同じデータで応答するには、ボディの上の<strong>生成…</strong>をクリックします。

- **リストを作成：ボディを1つの項目とします**を選ぶと、ボディが、ボディから作成した**項目数**の項目を持つJSONのリストになります。
- 選ばない場合は、ボディの値が一度だけ埋め込まれます。

**生成**はボディを結果で置き換えます。**編集 › 取り消す**でテンプレートに戻せます。ターミナルからは、[`echolot fake`](/docs/cli/fake)で同じことができます。

## ルートからのリクエスト [#requests-from-routes]

**ルート**カードの**リクエストを作成**は、モックの名前を付けたフォルダを作成し、オンのすべてのルートに対するリクエストを入れます。ルートのコンテキストメニューの**リクエストを作成**は、そのルートだけのリクエストを作成します。Echolotは最初のリクエストを開きます。

- フォルダには、モックのアドレスを設定した変数`baseUrl`があり、すべてのURLがそれで始まります：`{{baseUrl}}/users/{{id}}`。あとで`baseUrl`を実際のAPIに向ければ、同じリクエストがそちらに送信されます。
- パスパラメータはリクエストの変数になり、デフォルトのレスポンスのパスのルールが値を指定していなければ`1`になります。
- リクエストには、ルートの概要が名前として付きます。
- ルートのリクエストボディも一緒に入ります。

### ルートのリクエストボディ [#the-request-body-of-a-route]

ルートの下部の**リクエストボディ**には、そのルートから作成するリクエストのボディと**Content-Type**を設定します。`POST /users`が受け取るJSONなどです。
モックの応答は変わりません。ボディのフィールドに対するルールは、実際に送信されたリクエストを読み取ります。

## エージェントと使う [#with-agents]

**モック**ツールセットをオンにすると、エージェントと[アシスタント](/docs/ai/assistant)もルートを作成できます。必要なことを頼んでください。

- 「注文の一覧、取得、作成のルートをダミーデータ付きで持つモックを作って、開始して」
- 「idが0のときの404を`GET /users/{id}`に追加して」
- 「モックのルートからリクエストを作って」

エージェントは、`create_mock`（名前とルートを指定します。仕様は不要です）、`save_mock_route`、`delete_mock_route`、`generate_fake_data`、`list_fake_values`、`create_requests_from_mock`を使います。
`save_mock_route`は、[履歴](/docs/workspaces/history)のレスポンスをルートにすることもできます。コピーされる内容は、エージェントが読み取るほかのものと同じようにマスクされます。
エージェントがルートを削除するときは、最初に確認が表示されます。[エージェント](/docs/ai/agents)を参照してください。

## ワークスペース内では [#in-the-workspace]

ルートはモックのファイル`mocks/<name>.toml`に、`[[routes]]`とその`[[routes.responses]]`として保存されます。差分で読みやすく、Gitで共有できます。[ワークスペースのファイル](/docs/reference/workspace-files#mocks)を参照してください。