Kết Nối Notion

Level: L7 — MCP, API & Connectors (Bài 8/11 theo thứ tự sản xuất — · Đối tượng: Người đã học bài 65-70 (đã kết nối tích hợp thật đầu tiên

1. Mục tiêu học tập

Sau bài này, bạn có thể:

Giải thích 4 khái niệm dữ liệu cốt lõi của Notion: Pages, Databases, Views, Blocks.
Phân biệt 3 kiểu xác thực Notion hỗ trợ, đối chiếu đúng với API key/ OAuth (đào sâu ở bài 74).
Thiết kế luồng xuất bản tóm tắt từ Notes App (dự án tích lũy) sang 1 trang Notion.
Chọn đúng kiểu xác thực (Personal Token vs OAuth) phù hợp với quy mô dự án của bạn.

2. Khái niệm cốt lõi

Bước 1 — Concept: bài 70 dạy Notes App nhập nội dung từ bên ngoài (Google Docs → Notes App). Bài này dạy chiều ngược lại: xuất bản nội dung Notes App tạo ra (ví dụ: bản tóm tắt AI đã tạo ở bài 64) ra 1 nơi người khác dễ xem/chia sẻ hơn — Notion.

Bước 2/3 — Real implementation (áp dụng chuẩn REST đã học bài 65 + khái niệm OAuth sẽ đào sâu ở bài 74, với mô hình dữ liệu đặc thù của Notion): 1 Notion integration (“connection”) kết nối workspace với công cụ bên ngoài, “cho phép tự động hóa workflow qua code” [S110] — về bản chất là cấp quyền cho ứng dụng của bạn đọc/sửa nội dung trong workspace Notion của người dùng.

3 kiểu xác thực Notion hỗ trợ [S110] — đối chiếu trực tiếp với khái niệm sẽ đào sâu ở bài 74:

Personal Access Token (PAT) — token tĩnh, tương đương khái niệm API key (đào sâu ở bài 74), kế thừa quyền của người tạo — phù hợp script/CLI cá nhân, dự án nhỏ như Notes App.
Internal Connection — cũng dùng token tĩnh, giới hạn trong 1 workspace — phù hợp tự động hóa nội bộ.
Public Connection — dùng luồng OAuth 2.0 đầy đủ (đào sâu ở bài 74) — cho ứng dụng phục vụ nhiều workspace khác nhau, người dùng chọn trang nào chia sẻ khi cài đặt.

4 khái niệm dữ liệu cốt lõi (điểm đặc thù quan trọng nhất bài này) [S110]:

Pages — tài liệu riêng lẻ, tạo/đọc/cập nhật được.
Databases — tập hợp có thuộc tính (property) và mục (entry) có cấu trúc — gần giống 1 bảng dữ liệu, nhưng linh hoạt hơn database truyền thống (bài 73).
Views — hiển thị đã lọc/sắp xếp của nội dung database.
Blocks — đơn vị nhỏ nhất cấu thành nội dung 1 trang (đoạn văn, tiêu đề, danh sách…) — khác hẳn “1 trường dữ liệu” quen thuộc từ REST API thông thường.

3. Tại sao nội dung này quan trọng

Notion là ví dụ đầu tiên trong Level 7 có mô hình dữ liệu không giống REST “tài nguyên đơn giản” đã quen từ bài 65 — hiểu đúng Pages/Blocks/ Databases là điều kiện để không viết sai logic khi tích hợp: “tạo 1 trang mới” và “thêm 1 mục vào database” là 2 thao tác khác nhau, dù cả 2 đều “thêm nội dung vào Notion.”

4. Cơ chế hoạt động

Luồng xuất bản tóm tắt Notes App sang Notion (áp dụng đúng khái niệm đã học, cụ thể hóa cho Notion):

Chọn kiểu xác thực: với dự án cá nhân như Notes App, Personal Access Token đủ dùng — không cần luồng OAuth đầy đủ (đó là cho ứng dụng đa workspace, ví dụ 1 sản phẩm SaaS thương mại).
Xác định đích đến: xuất ra 1 Page độc lập, hay thêm 1 entry vào 1 Database đã có sẵn (ví dụ database “Ghi chú đã tóm tắt”)?
Cấu hình “capabilities” cho connection (đọc/tạo/cập nhật) đúng nhu cầu — áp dụng nguyên tắc scope tối thiểu (đào sâu ở bài 74).
Gọi API tạo nội dung — dữ liệu gửi lên cần đúng cấu trúc Block (không chỉ là 1 chuỗi văn bản đơn giản).

5. Mental model

Nếu bài 65 dạy “tài liệu = 1 tài nguyên đơn giản” (giống 1 tờ giấy), mô hình Notion giống 1 cuốn sổ có thể vừa viết tự do (Blocks trong 1 Page) vừa kẻ bảng có cột rõ ràng (Database với Property) — cùng 1 cuốn sổ, nhưng 2 cách tổ chức thông tin khác nhau, tùy bạn chọn trang tự do hay bảng có cấu trúc.

6. Hướng dẫn từng bước

Checklist kết nối Notes App với Notion (tổng hợp của người viết, dựa trên S110 + bài 74):

Xác định quy mô: dự án cá nhân (Notes App) → Personal Access Token là đủ, không cần luồng OAuth Public Connection phức tạp hơn.
Xác định đích đến: 1 Page độc lập hay 1 entry trong Database có sẵn?
Cấu hình capabilities đúng nhu cầu (ví dụ: chỉ cần “insert content,” không cần “read content” nếu chỉ xuất bản 1 chiều).
Với Database: xác định đúng property (cột) cần điền — không phải mọi Database có cùng cấu trúc.
Lưu token đúng cách (biến môi trường, bài 63/L6).

7. Ví dụ thực tế

Vendor example cụ thể: dự án Notes App tạo 1 tool (bài 67) “Xuất bản sang Notion” — khi người dùng nói “chia sẻ bản tóm tắt này lên Notion,” AI gọi tool này, tool tạo 1 Page mới trong Notion chứa nội dung tóm tắt (dùng đúng cấu trúc Block: 1 khối tiêu đề + 1 khối đoạn văn) — biến ghi chú cá nhân thành tài liệu chia sẻ được, đúng tinh thần đã đặt ra ở kế hoạch Level 6 cho tính năng AI tóm tắt.

8. Prompt/template/workflow

Khung thiết kế tích hợp Notion (tái sử dụng):

Kiểu xác thực: [Personal Access Token / Internal / Public Connection]
Đích đến: [1 Page độc lập / 1 entry trong Database "tên database"]
Capabilities cần: [read / insert / update — chọn tối thiểu]
Cấu trúc Block cần tạo: [tiêu đề, đoạn văn, danh sách...]

9. Visual hoặc diagram cần thiết

Hình 7.7 — Notion: Page/Block (tự do) và Database/Property (có cấu trúc).

10. Bài tập thực hành

Tra cứu tài liệu Notion API — xác định capabilities cần cho việc chỉ tạo mới nội dung (không cần đọc/sửa nội dung đã có).
Thiết kế 1 tool (bài 67) “Xuất bản ghi chú sang Notion” theo khung mục 8.
Viết ra: nếu Notes App cần vừa đọc lại nội dung đã xuất bản trước đó (để tránh trùng lặp), capabilities nào cần thêm?

11. Checklist

Giải thích được 4 khái niệm Pages/Databases/Views/Blocks.
Phân biệt được 3 kiểu xác thực Notion, đối chiếu đúng với API key/OAuth (bài 74).
Thiết kế được luồng xuất bản Notes App sang Notion.
Chọn đúng kiểu xác thực phù hợp quy mô dự án cá nhân.

12. Lỗi thường gặp

(Suy luận từ nguyên tắc [S110] + bài 65/74, không phải quan sát độc lập.)

Dùng luồng OAuth Public Connection cho 1 dự án cá nhân — phức tạp hơn cần thiết; Personal Access Token đã đủ cho quy mô đó.
Nhầm “tạo 1 Page” với “thêm 1 entry vào Database” — 2 thao tác có cấu trúc dữ liệu khác nhau, dễ gây lỗi nếu lẫn lộn.
Gửi văn bản thô thay vì cấu trúc Block đúng định dạng — API sẽ từ chối hoặc tạo nội dung sai định dạng.
Xin capability “read” khi chỉ cần “insert” — vi phạm nguyên tắc least privilege (đào sâu ở bài 74).

13. Giới hạn & khi nào KHÔNG nên áp dụng

Bài này không dạy chi tiết đầy đủ cấu trúc từng loại Block (có nhiều loại: paragraph, heading, bulleted list…) — tra cứu tài liệu chính thức khi triển khai thật.
Không dạy lại cơ chế OAuth (bài 74) — chỉ áp dụng, chọn đúng kiểu phù hợp quy mô.
Với dự án thương mại phục vụ nhiều workspace khách hàng khác nhau, Public Connection (OAuth đầy đủ) là bắt buộc — Personal Access Token chỉ phù hợp dự án cá nhân/nội bộ như Notes App.

14. An toàn & quản trị (Safety/Governance)

Personal Access Token kế thừa toàn bộ quyền của người tạo ra nó [S110] — đây là điểm cần cẩn trọng: khác OAuth (nơi scope giới hạn rõ ràng theo từng lần cấp quyền), 1 PAT có thể có quyền truy cập rộng hơn bạn tưởng nếu người tạo nó có quyền truy cập nhiều nội dung trong workspace. Luôn kiểm tra capabilities đã cấu hình đúng mức tối thiểu cần thiết (bài 74), và với dữ liệu nhạy cảm, cân nhắc dùng 1 tài khoản Notion riêng, giới hạn quyền, thay vì dùng token của tài khoản cá nhân chính.

15. Best practices

Chọn Personal Access Token cho dự án cá nhân/nội bộ; chỉ dùng Public Connection (OAuth) khi thực sự cần phục vụ nhiều workspace khách hàng.
Cấu hình capabilities đúng tối thiểu cần thiết ngay khi tạo connection.
Phân biệt rõ đích đến (Page độc lập vs entry trong Database) trước khi viết code gọi API.
Với PAT, cân nhắc dùng tài khoản/workspace giới hạn quyền thay vì tài khoản chính nếu dữ liệu nhạy cảm.

16. Nội dung nâng cao (không bắt buộc)

Notion API còn hỗ trợ tìm kiếm (search) toàn bộ nội dung workspace mà connection có quyền truy cập — hữu ích nếu Notes App cần chủ động tìm 1 trang cũ để cập nhật thay vì luôn tạo trang mới, nhưng đòi hỏi capability “read content” rộng hơn — cần cân nhắc đánh đổi giữa tiện lợi và nguyên tắc least privilege đã học.

17. Nguồn tham khảo

[S110] Getting Started, Notion API Docs — developers.notion.com — 3 kiểu xác thực, mô hình dữ liệu Pages/Databases/Views/Blocks.
Dẫn chiếu (không trích dẫn mới): bài 65 (REST cơ bản); bài 67 (Tool Calling); bài 70 (Google Workspace, đối chiếu mô hình đa dịch vụ vs 1 sản phẩm); bài 74 (Authentication, đối chiếu PAT với API key/OAuth).

18. Ngày kiểm chứng

Nội dung kiểm chứng qua nguồn Tier 1 (S110) ngày 2026-07-13. Mô hình dữ liệu (Pages/Databases/Blocks) và 3 kiểu xác thực là kiến trúc nền tảng tương đối ổn định; chi tiết cấu trúc từng loại Block có thể mở rộng theo thời gian — khuyến nghị re-verify trước khi triển khai thật.