# 快速入門

> 建立權杖、進行第一次 Management API 呼叫、發佈文章並從 Content Delivery API 讀取，全程約十分鐘。

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

本快速入門將引導您從零開始，透過程式碼建立一篇網誌文章，並從您網站的公開 API 讀取該內容。

## 開始之前

- 一個擁有至少一個網站的 Kanorio 帳戶。空白網站即可。
- `curl`，若您想使用 SDK，則需 Node.js 20 或更高版本。

## 1. 建立個人存取權杖

個人存取權杖以 `knr_pat_` 開頭，代表您的身分，並受限於您選擇的網站與權限。

1. 開啟 [帳戶設定 › API 存取](https://app.kanorio.com/account/api-access) 並選擇 **建立金鑰**。
2. 選擇 **其他工具**，選取您要使用的網站，並挑選 **編輯內容** 權限預設集。發佈功能需要 **完整存取** 或發佈權限。
3. 複製權杖。它只會顯示一次。

```bash
export KANORIO_TOKEN="knr_pat_..."
```

請將權杖存放在伺服器端。切勿將其放入瀏覽器程式碼或公開儲存庫中。請參閱 [驗證](https://kanorio.com/zh-HK/developers/authentication) 以了解其他權杖類型。

## 2. 列出您的網站

每個 Management API 請求都會發送到 `https://app.kanorio.com/api/v1`，並將權杖作為 Bearer 憑證。

```bash
curl https://app.kanorio.com/api/v1/sites \
  -H "Authorization: Bearer $KANORIO_TOKEN"
```

列表會以統一的封裝格式回傳。請記下網站的 `id` 及其 `publicUrl`。

```json
{
  "data": [
    {
      "id": "ws_example123",
      "name": "Sourdough Studio",
      "role": "OWNER",
      "isPublished": true,
      "publicUrl": "https://sourdough.kanorio.com"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}
```

## 3. 建立草稿文章

寫入操作會建立草稿。在您發佈之前，網上網站不會有任何變更。

```bash
curl -X POST https://app.kanorio.com/api/v1/sites/ws_example123/posts \
  -H "Authorization: Bearer $KANORIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "How we feed our sourdough starter",
    "excerpt": "The first thing we do every morning.",
    "contentMarkdown": "## Flour and water\n\nEqual weights, twice a day."
  }'
```

回應內容即為該文章本身，包含 `"status": "DRAFT"` 以及如 `post_example01` 的 `id`。

## 4. 發佈文章

```bash
curl -X POST https://app.kanorio.com/api/v1/sites/ws_example123/posts/post_example01/publish \
  -H "Authorization: Bearer $KANORIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

若回應為錯誤代碼 `SITE_NOT_PUBLISHED`，請使用 `POST /sites/{id}/publish` 發佈網站一次後再試。錯誤格式皆相同，詳見 [錯誤](https://kanorio.com/zh-HK/developers/basics/errors)。

## 5. 從 Content Delivery API 讀取文章

已發佈的內容無需權杖即可從您網站的自有網址讀取。請使用步驟 2 中的 `publicUrl`，或在 [網站設定 › 開發者](https://app.kanorio.com/settings/developer) 下顯示的永久系統網址。

```bash
curl "https://sourdough.kanorio.com/api/v1/collections/blog/items?limit=1&fields=title,excerpt"
```

```json
{
  "data": [
    {
      "id": "post_example01",
      "slug": "how-we-feed-our-starter",
      "publishedAt": "2026-11-02T08:00:00.000Z",
      "fieldData": {
        "title": "How we feed our sourdough starter",
        "excerpt": "The first thing we do every morning."
      }
    }
  ],
  "hasMore": false,
  "nextCursor": null,
  "assets": {}
}
```

## 使用 SDK 執行相同操作

```bash
npm install @kanorio/sdk
```

```ts
import { createDeliveryClient, createManagementClient } from "@kanorio/sdk";

const management = createManagementClient({ token: process.env.KANORIO_TOKEN! });
const sites = await management.get("/sites");
const site = sites.data[0]!;

const post = await management.post("/sites/{id}/posts", {
  params: { id: site.id },
  body: { title: "How we feed our sourdough starter", contentMarkdown: "## Flour and water" },
});
await management.post("/sites/{id}/posts/{postId}/publish", { params: { id: site.id, postId: post.id }, body: {} });

const delivery = createDeliveryClient({ siteUrl: site.publicUrl! });
const latest = await delivery.get("/collections/{key}/items", { params: { key: "blog" }, query: { limit: 1 } });
console.log(latest.data[0]?.slug);
```

## 後續步驟

- 從您的前端 [讀取頁面、文章與集合](https://kanorio.com/zh-HK/developers/guides/read-content)。
- 學習 [錯誤](https://kanorio.com/zh-HK/developers/basics/errors)、[分頁](https://kanorio.com/zh-HK/developers/basics/pagination) 與 [速率限制](https://kanorio.com/zh-HK/developers/basics/rate-limits) 的共用規則。
- 瀏覽 [Management API 參考](https://kanorio.com/en/developers/management-api) 或 Kanorio 提供的 [產品](https://kanorio.com/zh-HK/developers/products)。
- 透過 [MCP](https://kanorio.com/zh-HK/developers/mcp) 連接 AI 助理。