# 冪等性與安全寫入

> 在不產生重複數據的情況下重試建立請求，避免覆寫他人的編輯內容，並確保 Webhook 傳遞僅處理一次。

> Markdown version of https://kanorio.com/zh-HK/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

網絡請求可能會在中途失敗。這三種機制讓您可以在不產生重複數據或遺失他人工作成果的情況下進行重試。

## 冪等性權杖 (Idempotency keys)

重複執行成本較高的建立操作會接受 `Idempotency-Key` 標頭。API 參考文件會標記這些操作，且 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` 引數傳遞。

## 樂觀併發控制 (Optimistic concurrency)

頁面、全站頁首與頁尾，以及其他使用者也會在後台編輯的內容，均使用樂觀併發控制，以確保您的指令碼不會在無意間覆寫他人的變更。

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" }]
}
```

API 參考文件會顯示哪些操作支援 `ifUnmodifiedSince`。

## 草稿優先

大多數寫入操作會變更草稿，並透過獨立的發佈操作使其生效。頁面、全域內容與文章皆以此方式運作。集合項目會立即發佈，除非您傳送 `publish: false`。因此，失敗或重複的寫入幾乎不會影響訪客看到的內容。

## Webhook 傳遞

Kanorio 可能會多次傳遞相同的事件，例如在逾時後，或當有人從後台重新傳送時。每次傳遞都會帶有一個 `X-Kanorio-Delivery` ID，該 ID 在重試過程中保持不變。請儲存您已處理的 ID，並對重複的請求回傳 `200`。請參閱 [Webhooks](https://kanorio.com/zh-HK/developers/webhooks)。