# 冪等性と安全な書き込み

> 重複を作成せずに作成リクエストを再試行し、他者の編集を上書きすることを防ぎ、Webhook配信を正確に一度だけ処理する方法について説明します。

> Markdown version of https://kanorio.com/ja/developers/basics/idempotency. Append `.md` to any developer docs URL for this format. Index: https://kanorio.com/llms.txt · MCP: https://app.kanorio.com/api/mcp
>
> Translated from the English original: https://kanorio.com/en/developers/basics/idempotency.md

ネットワークはリクエストの途中で失敗することがあります。以下の3つのメカニズムを使用することで、重複を作成したり、他者の作業を上書きしたりすることなく、リクエストを再試行できます。

## 冪等性キー

繰り返し実行すると負荷がかかる操作では、`Idempotency-Key` ヘッダーを受け付けます。リファレンスではこれらがマークされており、OpenAPIドキュメントでは `x-kanorio-idempotent: true` が設定されています。

```bash
curl -X POST https://app.kanorio.com/api/v1/sites/ws_example123/collections/projects/items \
  -H "Authorization: Bearer $KANORIO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: import-2026-11-02-row-17" \
  -d '{ "slug": "riverside-bakery", "fieldData": { "title": "Riverside Bakery" } }'
```

- キーは1〜200文字の間で任意に選択してください。UUIDや、自社システム内のIDなどが適しています。
- 同じキーとボディで再試行すると、元の結果が返され、新しいデータは作成されません。
- 同じキーで異なるボディを指定すると、`409 IDEMPOTENCY_CONFLICT` が返されます。
- 最初の処理がまだ実行中の場合、再試行すると `409 IDEMPOTENCY_IN_PROGRESS` が返されます。少し待ってから再試行してください。
- キーはサイトおよび操作ごとにスコープが設定され、24時間後に期限切れとなります。

MCP経由の場合は、ツールの `idempotencyKey` 引数としてキーを渡してください。

## 楽観的並行性制御

ページ、サイト全体のヘッダーとフッター、その他管理画面で編集可能なコンテンツには、楽観的並行性制御が採用されています。これにより、スクリプトが他者の変更を意図せず上書きすることを防ぎます。

1. リソースを読み取り、そのタイムスタンプを保持します（ページの場合は `updatedAt`、グローバルコンテンツの場合は `contentUpdatedAt`）。
2. 書き込み時に `ifUnmodifiedSince` としてその値を送信します。
3. その間にリソースが変更されていた場合、書き込みは `409 CONFLICT` で失敗し、`details` に現在のタイムスタンプが返されます。再度読み取り、変更をマージしてから再試行してください。

```json
{
  "ifUnmodifiedSince": "2026-11-02T08:00:00.000Z",
  "sections": [{ "id": "sec_hero_1", "type": "page-main-visual", "title": "Fresh bread daily" }]
}
```

どの操作が `ifUnmodifiedSince` を受け付けるかはリファレンスで確認できます。

## ドラフト優先

ほとんどの書き込み操作はドラフトを変更するものであり、個別の公開操作によってライブ状態になります。ページ、グローバル、投稿はすべてこの仕組みで動作します。コレクションアイテムは、`publish: false` を送信しない限り即座に公開されます。そのため、書き込みの失敗や重複が訪問者に影響を与えることはほとんどありません。

## Webhookの配信

Kanorioは、タイムアウト後や管理画面からの再送時など、同じイベントを複数回配信する場合があります。すべての配信には `X-Kanorio-Delivery` IDが含まれており、これは再試行時も変わりません。処理済みのIDを保存し、重複したリクエストに対しては `200` を返してください。詳細は [Webhooks](https://kanorio.com/ja/developers/webhooks) を参照してください。