> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudthinker.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Notion

> Kết nối Notion để agent tìm kiếm trang và database, trả lời từ tài liệu của bạn, và giữ runbook cùng postmortem luôn cập nhật

Kết nối Notion để các agent CloudThinker tìm kiếm các trang và database bạn chia sẻ, trả lời câu hỏi từ runbook và sổ tay của bạn, và cập nhật nội dung khi bạn yêu cầu. Kết nối đăng nhập bằng **internal integration secret** của Notion (một token thuộc về một workspace Notion), và chỉ thấy các trang bạn chia sẻ rõ ràng với integration đó.

## Điều kiện tiên quyết

* Một tài khoản Notion có quyền tạo integration trong workspace. Ở hầu hết workspace, đó là **Workspace Owner**.
* Quyền **Full access** hoặc **Can edit** trên các trang và database mà agent cần tiếp cận, để bạn chia sẻ chúng với integration.
* Quyền sửa kết nối trong workspace CloudThinker của bạn.

## Thiết lập

**1. Tạo internal integration trong Notion**

Vào [notion.so/profile/integrations](https://www.notion.so/profile/integrations) và nhấn **New integration**. Đặt tên `cloudthinker`, chọn workspace Notion, giữ loại **Internal** và lưu.

Sao chép **Internal Integration Secret**. Secret bắt đầu bằng `ntn_` (secret cũ bắt đầu bằng `secret_`).

**2. Chọn capability của integration**

Ở tab **Configuration** của integration, trong **Capabilities**, chỉ giữ những gì quy trình của bạn cần. Xem [Quyền yêu cầu](#quyền-yêu-cầu) để biết bộ quyền chỉ đọc và đọc-ghi.

Nếu Resolve sẽ đăng postmortem, hãy bật thêm **Insert content**. Xem [Dùng Notion cho postmortem](#dùng-notion-cho-postmortem).

**3. Chia sẻ trang và database với integration**

Mở tab **Access** của integration và chọn các trang và database mà agent cần tiếp cận. Trang con kế thừa quyền truy cập từ trang cha, nên chia sẻ một trang cấp cao như **Engineering** sẽ bao phủ mọi thứ bên dưới.

Bạn cũng có thể chia sẻ một trang từ chính trang đó: mở menu **•••**, chọn **Connections** và thêm `cloudthinker`.

**4. Thêm kết nối trong CloudThinker**

Trong thanh bên, nhấn **More → Workspace settings → Connections**. Ở tab **Builtin Connections**, tìm **Notion** và nhấn **Connect**.

Dán secret vào **NOTION\_TOKEN** và nhấn **Connect**.

**Trạng thái thành công:** hộp thoại đóng và kết nối Notion hiển thị **Connected**.

> [!NOTE]
>
> Notion kiểm tra secret khi agent gọi lần đầu. Hãy chạy prompt xác minh bên dưới trước khi dựa vào kết nối, để phát hiện ngay secret gõ sai hoặc đã bị thu hồi, thay vì đến giữa một sự cố mới biết.

## Chi tiết kết nối

| Trường | Mô tả | Ví dụ |
| - | - | - |
| **Alias** | Tên ngắn cho kết nối này. Agent và [Rules](https://docs.cloudthinker.io/vi/guide/approvals/rules.md) dùng alias để phân biệt các kết nối | `marketing-wiki` |
| **Description** | Workspace Notion này chứa gì. Agent đọc mô tả để chọn đúng kết nối, nên hãy viết cụ thể | `Marketing team wiki and launch plans` |
| **NOTION\_TOKEN** | Internal Integration Secret từ tab **Configuration** của integration trong Notion | `ntn_<your-secret>` |

Mỗi secret chỉ bao phủ một workspace Notion. Để tiếp cận workspace Notion thứ hai, hãy tạo integration ở đó và thêm thành một kết nối riêng.

## Quyền yêu cầu

Hai yếu tố trong Notion đặt giới hạn trên cho những gì agent làm được: **Capabilities** của integration và các trang trên tab **Access** của nó. CloudThinker không bao giờ tiếp cận được trang chưa được chia sẻ với integration.

| Mục tiêu | Capability cần bật |
| - | - |
| Tìm kiếm và tóm tắt (chỉ đọc) | **Read content** |
| Đọc thảo luận trên trang | Thêm **Read comments** |
| Sửa trang, thêm block, tạo trang hoặc hàng database | Thêm **Update content** và **Insert content** |
| Để lại comment cho nhóm | Thêm **Insert comments** |

Giữ thông tin người dùng ở **No user information** trừ khi một quy trình cần xác định người theo tên. Không có quyền này, agent thấy người trong thuộc tính Person dưới dạng ID, không phải tên.

> [!TIP]
>
> Bắt đầu chỉ đọc với **Read content**, và chỉ chia sẻ các teamspace hoặc trang cấp cao mà agent cần, chẳng hạn runbook và postmortem. Thêm capability ghi sau nếu một quy trình cần.

## Khả năng của agent

CloudThinker chạy MCP server chính thức của Notion (Model Context Protocol, một chuẩn để agent gọi công cụ).

| Khả năng | Agent có thể làm gì |
| - | - |
| **Tìm kiếm** | Tìm trang và database theo tiêu đề và nội dung trong mọi thứ được chia sẻ với integration |
| **Đọc trang** | Đọc thuộc tính và toàn bộ nội dung block của trang, kể cả block lồng nhau |
| **Truy vấn database** | Lọc và sắp xếp hàng database, chẳng hạn postmortem quý trước hoặc action item đang mở |
| **Sửa nội dung** | Cập nhật thuộc tính trang, thêm block, tạo trang hoặc hàng database |
| **Comment** | Đọc comment trên trang và thêm comment mới |

Sửa và comment là thao tác ghi, nên [Approvals](https://docs.cloudthinker.io/vi/guide/approvals/overview.md) quyết định từng thao tác được chạy, phải chờ người duyệt hay bị từ chối. Tìm kiếm và đọc chạy mà không hỏi.

### Dùng Notion cho postmortem

[Resolve](https://docs.cloudthinker.io/vi/guide/incident/overview.md) có thể soạn và đăng postmortem lên Notion sau khi một sự cố được giải quyết. Trong thanh bên, mở **Resolve → Integrations**, chọn **Notion**, bật **Publish postmortems** trong **What Resolve can do**, và nhập **Notion parent page ID**, trang mà các postmortem mới sẽ nằm dưới. Chia sẻ trang cha đó với integration và bật **Insert content**. Xem [tích hợp Resolve](https://docs.cloudthinker.io/vi/guide/incident/integrations.md) để biết thiết lập đầy đủ.

Page ID là chuỗi 32 ký tự ở cuối URL của trang. Bỏ phần tiêu đề phía trước và mọi phần `?v=` hoặc `?pvs=` phía sau. Với `https://www.notion.so/Postmortems-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d?pvs=4`, page ID là `1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d`.

### Xác minh kết nối

```text theme={null}
Search Notion for our on-call runbook and summarize the escalation steps
```

Kết nối hoạt động sẽ nêu tên trang thực tế tìm thấy và trích dẫn nội dung. Câu trả lời báo không tìm thấy trang nào nghĩa là integration chưa được chia sẻ với trang đó. Lỗi ủy quyền nghĩa là secret sai.

### Ví dụ prompt

```text theme={null}
Summarize the postmortems in our Notion Incidents database from the last 90 days and list repeat root causes
Which Notion pages under Engineering → Runbooks haven't been edited in 6 months?
Add a step to the Database failover runbook in Notion: confirm replica lag is under 5 seconds before promoting
Compare the deploy steps in our Notion release checklist with the Production deploy runbook and list the differences
```

## Khắc phục sự cố

> **Mọi yêu cầu thất bại với 401 Unauthorized**
>
> Notion từ chối secret. Secret có thể gõ sai, đã bị thu hồi hoặc thuộc một integration đã bị xóa. Sao chép **Internal Integration Secret** hiện tại từ tab **Configuration** của integration. Trong CloudThinker, mở **Notion** trong **More → Workspace settings → Connections**, nhấn biểu tượng bút chì trên hàng của tài khoản, nhấn **Replace…** trong **Edit Instance**, dán secret và nhấn **Save and test**.

> **Agent không tìm thấy một trang đang tồn tại**
>
> Trang chưa được chia sẻ với integration. Thêm trang ở tab **Access** của integration, hoặc từ menu **••• → Connections** của trang. Chia sẻ trang cha cũng chia sẻ các trang con.

> **Đọc được nhưng sửa thất bại**
>
> Integration thiếu **Update content** hoặc **Insert content**. Bật chúng trong **Capabilities** ở Notion. Nếu bạn muốn giữ kết nối chỉ đọc, lỗi này là kết quả mong đợi.

> **Thao tác sửa đang chờ và không có gì xảy ra**
>
> Thao tác ghi đang chờ một người. Tìm thẻ phê duyệt trong chat và nhấn **Approve**. Nếu thẻ ghi "Waiting for an approver," nhấn **Notify approvers**. Xem [Approvals](https://docs.cloudthinker.io/vi/guide/approvals/overview.md) để thay đổi ai phê duyệt và khi nào.

> **Postmortem không được đăng lên Notion**
>
> Kiểm tra **Notion parent page ID** trong Resolve khớp với một trang được chia sẻ với integration, và **Insert content** đã được bật.

## Bảo mật

* **Quyền tối thiểu** — chỉ cấp các quyền mà agent cần cho trường hợp sử dụng của bạn; bắt đầu với quyền chỉ đọc và mở rộng sau.
* **Chỉ đọc theo mặc định** — sử dụng thông tin xác thực chỉ đọc trừ khi bạn muốn agent thực hiện thay đổi qua kết nối này.
* **Xoay vòng thông tin xác thực** — xoay vòng khóa và token theo lịch trình thông thường của bạn; CloudThinker sẽ lấy giá trị mới khi bạn cập nhật kết nối.
* **Thu hồi khi bàn giao** — xóa thông tin xác thực tại nhà cung cấp khi bạn xóa một kết nối hoặc khi đồng nghiệp rời nhóm.

- **Tab Access là phạm vi của bạn.** Integration chỉ thấy các trang được chia sẻ với integration. Xem lại danh sách đó khi các nhóm sắp xếp lại nội dung.
- **Không đưa secret vào chat.** Chỉ dán secret vào hộp thoại kết nối, không bao giờ vào tin nhắn chat hay repository.
- **Xoay vòng bằng cách làm mới secret.** Làm mới secret trong Notion sẽ vô hiệu secret cũ ngay lập tức, nên hãy thay trong CloudThinker ngay (biểu tượng bút chì → **Replace…** → **Save and test**). Xem [Xoay vòng thông tin xác thực](https://docs.cloudthinker.io/vi/guide/connections/overview.md#xoay-vòng-thông-tin-xác-thực).
- **Thay đổi hiển thị dưới tên integration.** Notion hiển thị thay đổi qua kết nối dưới tên integration `cloudthinker`, nên nhóm bạn phân biệt được chúng với thay đổi của con người.

## Liên quan

> **[Knowledge](https://docs.cloudthinker.io/vi/guide/knowledge.md)**
>
> Tải lên tài liệu để agent tìm kiếm ngay trong CloudThinker

> **[Kết nối Atlassian](https://docs.cloudthinker.io/vi/guide/connections/atlassian.md)**
>
> Kết nối Jira và Confluence cho ticket và tài liệu nhóm


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.