---
title: "Notion 连接器"
description: "完整的 Notion 集成指南，通过 Tajo 将数据库、页面和工作区内容与 Brevo 同步。"
url: https://tajo.io/zh-cn/docs/connectors/custom/notion/
markdown: https://tajo.io/zh-cn/docs/connectors/custom/notion.md
lang: zh-CN
robots: noindex
---

申请抢先体验

请输入您的名字和公司电子邮箱地址。我们会发送确认 Tajo 访问申请的链接。

# Notion 连接器

连接器状态: 计划中 尚未构建。Tajo 目前不运行此连接器。

| 来源字段 | 目标字段 | 示例值 |
| --- | --- | --- |
| `record.id` | `source_id` | `record_1042` |
| `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` |
| `record.value` | `value` | `sample_value` |

通过 Tajo 将您的 Notion 工作区连接到 Brevo，实现内容驱动的营销工作流、CRM 数据库同步和自动通知。

## 概览

| 属性 | 值 |
| --- | --- |
| **平台** | Notion |
| **类别** | 自定义 |
| **设置复杂度** | 简单 |
| **官方集成** | 否 |
| **同步数据** | 数据库、页面、用户 |
| **API 类型** | REST API |
| **认证方式** | 内部集成令牌 / OAuth 2.0 |
| **基础 URL** | `https://api.notion.com` |
| **API 版本** | `2022-06-28`（通过 `Notion-Version` 头部） |

## 功能

- **数据库同步** - 将 Notion 数据库条目同步到 Brevo 联系人和列表
- **CRM 桥接** - 使用 Notion 数据库作为轻量级 CRM，同步到 Brevo
- **内容通知** - 当 Notion 页面发布时触发 Brevo 活动
- **属性映射** - 将 Notion 数据库属性映射到 Brevo 联系人属性
- **页面监控** - 追踪页面更新并作为 Brevo 事件转发
- **用户目录同步** - 将 Notion 工作区成员同步到 Brevo 联系人

## 前提条件

开始之前，请确保您已具备：

1. 具有管理员权限的 Notion 工作区
2. Notion 内部集成或 OAuth 应用
3. 已与集成共享数据库页面
4. 具有 API 访问权限的 Brevo 账户
5. 具有有效订阅的 Tajo 账户

## 认证

Notion 支持两种认证方式。

### 选项 1：内部集成（推荐用于单工作区）

1. 前往 [notion.so/my-integrations](https://www.notion.so/my-integrations)
2. 点击**新建集成**
3. 命名为”Tajo Integration”
4. 选择您的工作区
5. 设置功能：

```
Content Capabilities:
  Read content: ✓
  Update content: ✓
  Insert content: ✓

User Capabilities:
  Read user information: ✓
```

6. 复制**内部集成密钥**（以 `ntn_` 开头）

需要共享页面

内部集成只能访问与其明确共享的页面和数据库。通过”…”菜单 > “连接” > 选择您的集成，将每个目标数据库与集成共享。

### 选项 2：OAuth 2.0（公共集成）

对于服务多个工作区的集成，使用 OAuth 2.0 流程：

1. 将集成注册为公共集成
2. 将用户重定向至：`https://api.notion.com/v1/oauth/authorize?client_id=...`
3. 在 `/v1/oauth/token` 处将授权码换取访问令牌

### 连接到 Tajo

```bash
tajo connectors install notion \
  --token $NOTION_TOKEN
```

## 配置

### 基础设置

```yaml
connectors:
  notion:
    enabled: true
    api_version: "2022-06-28"

    sync:
      databases: true
      pages: false
      users: true

    databases:
      - id: "abc123def456"
        name: "Customers"
        sync_to_list: 25
      - id: "ghi789jkl012"
        name: "Leads"
        sync_to_list: 26
```

### 字段映射

将 Notion 数据库属性映射到 Brevo 联系人属性：

```yaml
field_mapping:
  # Notion property -> Brevo attribute
  Name:
    type: title
    target: FIRSTNAME
  Email:
    type: email
    target: email
  Phone:
    type: phone_number
    target: SMS
  Company:
    type: rich_text
    target: COMPANY
  Status:
    type: select
    target: LEAD_STATUS
  Deal Value:
    type: number
    target: DEAL_VALUE
  Last Contact:
    type: date
    target: LAST_CONTACT_DATE
  Tags:
    type: multi_select
    target: TAGS
```

## API 端点

Tajo 集成以下 Notion API 端点：

| 端点 | 方法 | 用途 |
| --- | --- | --- |
| `/v1/databases/{id}/query` | POST | 查询数据库条目 |
| `/v1/databases/{id}` | GET | 检索数据库架构 |
| `/v1/pages` | POST | 创建新页面 |
| `/v1/pages/{id}` | GET | 检索页面属性 |
| `/v1/pages/{id}` | PATCH | 更新页面属性 |
| `/v1/blocks/{id}/children` | GET | 检索块子项 |
| `/v1/users` | GET | 列出所有工作区用户 |
| `/v1/users/{id}` | GET | 检索用户 |
| `/v1/search` | POST | 在工作区中搜索 |

## 代码示例

### 初始化连接器

```javascript
import { TajoClient } from '@tajo/sdk';

const tajo = new TajoClient({
  apiKey: process.env.TAJO_API_KEY,
  brevoApiKey: process.env.BREVO_API_KEY
});

await tajo.connectors.connect('notion', {
  token: process.env.NOTION_TOKEN
});
```

### 将数据库同步到 Brevo

```javascript
// Sync a Notion database to a Brevo list
await tajo.connectors.sync('notion', {
  type: 'full',
  resources: ['databases'],
  databaseId: 'abc123def456',
  targetList: 25
});

const status = await tajo.connectors.status('notion');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-03-15T14:30:00Z',
//   databasesSynced: 2,
//   pagesTracked: 1450,
//   usersCount: 32
// }
```

### 查询和过滤

```javascript
// Query Notion database with filters
const results = await tajo.connectors.query('notion', {
  databaseId: 'abc123def456',
  filter: {
    property: 'Status',
    select: { equals: 'Active' }
  },
  sorts: [
    { property: 'Last Contact', direction: 'descending' }
  ]
});
```

### 从 Brevo 事件创建页面

```javascript
// Create a Notion page when a Brevo contact reaches a milestone
tajo.events.on('contact.attribute_updated', async (event) => {
  if (event.attribute === 'LIFECYCLE_STAGE' && event.value === 'customer') {
    await tajo.connectors.create('notion', {
      databaseId: 'ghi789jkl012',
      properties: {
        Name: { title: [{ text: { content: event.contact.name } }] },
        Email: { email: event.contact.email },
        'Converted Date': { date: { start: new Date().toISOString() } }
      }
    });
  }
});
```

## 速率限制

Notion 按集成实施速率限制：

| 限制类型 | 值 |
| --- | --- |
| **速率限制** | 每集成每秒 3 个请求 |
| **突发限制** | 允许短时突发，随后限流 |
| **页面大小** | 每次分页请求最多 100 条 |

基于游标的分页

Notion 使用基于游标的分页。Tajo 自动处理此操作，使用 `next_cursor` 参数迭代所有页面，直到 `has_more` 返回 `false`。

超出速率限制时，Notion 返回 `429 Too Many Requests`，并附带 `Retry-After` 头部。

## 故障排除

### 常见问题

| 问题 | 原因 | 解决方案 |
| --- | --- | --- |
| 401 Unauthorized | 令牌无效或已过期 | 重新生成集成令牌 |
| 403 Forbidden | 页面未与集成共享 | 通过”连接”将页面/数据库共享给集成 |
| 404 Object not found | 数据库 ID 错误或未共享 | 验证数据库 ID 和共享设置 |
| 属性缺失 | 架构不匹配 | 重新同步数据库架构并更新字段映射 |
| 超出速率限制 | 请求过于频繁 | 降低同步频率或批次大小 |

### 调试模式

```yaml
connectors:
  notion:
    debug: true
    log_level: verbose
    log_api_calls: true
```

### 测试连接

```bash
tajo connectors test notion
# ✓ API authentication successful
# ✓ Database access verified
# ✓ User list accessible
# ✓ Search operational
# ✓ Page creation available
```

## 最佳实践

1. **明确共享数据库** - 内部集成只能看到共享内容
2. **使用数据库查询而非搜索** - 对于已知数据库，查询更快且更可靠
3. **谨慎映射属性类型** - Notion 有多种属性类型；将其与 Brevo 属性类型匹配
4. **处理分页** - 始终迭代所有游标页面以获取完整数据
5. **增量同步** - 使用 `last_edited_time` 过滤器只同步已变更的条目
6. **设置轮询计划** - Notion 原生不支持 Webhook；定期按时间间隔轮询

## 安全

- **Bearer 令牌认证** - 集成密钥和 OAuth 令牌
- **仅 HTTPS** - 所有 API 通信通过 TLS 1.2+ 加密
- **范围访问** - 集成只能访问明确共享的内容
- **OAuth 2.0** - 公共集成的安全授权流程
- **加密存储** - 令牌在 Tajo 中静态加密
- **工作区隔离** - 每个集成限定于单个工作区

## 相关资源

- [Airtable 连接器](https://tajo.io/zh-cn/docs/connectors/custom/airtable)
- [GitHub 连接器](https://tajo.io/zh-cn/docs/connectors/custom/github)
- [Linear 连接器](https://tajo.io/zh-cn/docs/connectors/custom/linear)
- [Brevo 联系人 API](https://tajo.io/zh-cn/docs/contact-management)