notion-api 是做什麼的？
此技能提供透過 REST API 與 Notion 互動的完整指南。當使用者要求讀取、建立、更新或刪除頁面、資料庫、區塊、評論或其他 Notion 內容時，應使用此技能。技能涵蓋驗證、所有可用端點、分頁、錯誤處理及最佳實務。
驗證
所有 API 請求都需要使用 Integration Token 進行驗證。在你的 Notion 整合設定頁面中取得 Token，並在每個請求的 Authorization 標頭中以 Bearer Token 形式傳送：
Authorization: Bearer secret_abc123...
端點
頁面
- 讀取頁面:
GET /v1/pages/{page_id} - 建立頁面:
POST /v1/pages - 更新頁面屬性:
PATCH /v1/pages/{page_id} - 刪除（封存）頁面:
PATCH /v1/pages/{page_id}搭配"archived": true
資料庫
- 讀取資料庫:
GET /v1/databases/{database_id} - 查詢資料庫:
POST /v1/databases/{database_id}/query - 建立資料庫:
POST /v1/databases - 更新資料庫:
PATCH /v1/databases/{database_id}
區塊
- 讀取區塊:
GET /v1/blocks/{block_id} - 讀取區塊子項:
GET /v1/blocks/{block_id}/children - 附加區塊子項:
PATCH /v1/blocks/{block_id}/children - 更新區塊:
PATCH /v1/blocks/{block_id} - 刪除區塊:
DELETE /v1/blocks/{block_id}
評論
- 讀取評論:
GET /v1/comments - 建立評論:
POST /v1/comments
使用者
- 讀取使用者:
GET /v1/users/{user_id} - 列出所有使用者:
GET /v1/users
搜尋
- 搜尋:
POST /v1/search
分頁
使用 cursor-based 分頁。回應中的 next_cursor 欄位可用於取得下一頁：
{
"results": [...],
"next_cursor": "abc123",
"has_more": true
}
錯誤處理
| 狀態碼 | 描述 |
|---|---|
| 400 | 請求格式錯誤 |
| 401 | 未經授權（Token 無效） |
| 403 | 禁止（無此權限） |
| 404 | 找不到資源 |
| 409 | 衝突（例如重複建立） |
| 429 | 請求過多（速率限制） |
| 500 | 內部伺服器錯誤 |
最佳實務
- 在請求間加入延遲以避免觸發速率限制（每分鐘最多 3 個請求）。
- 對所有請求使用適當的錯誤處理（重新嘗試 429 錯誤）。
- 使用
start_cursor迭代通過大型結果集。 - 在更新時僅傳送需要變更的屬性。
- 使用唯一的
Idempotency-Key標頭確保冪等性。 - 使用 Notion API 官方文件 (
https://developers.notion.com/reference) 查閱端點與屬性。
注意事項
- 所有請求必須使用
Content-Type: application/json標頭。 - Notion API 版本使用
Notion-Version標頭指定（目前最新版本為2022-06-28）。 - 回應格式為 JSON，包含
object、id、created_time、last_edited_time等欄位。 - 頁面是資料庫中的項目；資料庫是頁面集合。