---
title: "Airtable 连接器"
description: "完整的 Airtable 集成指南，通过 Tajo 将数据库、表和记录与 Brevo 联系人和列表同步。"
url: https://tajo.io/zh-cn/docs/connectors/custom/airtable/
markdown: https://tajo.io/zh-cn/docs/connectors/custom/airtable.md
lang: zh-CN
robots: noindex
---

申请抢先体验

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

# Airtable 连接器

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

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

通过 Tajo 将您的 Airtable 数据库连接到 Brevo，实现 CRM 同步、产品目录管理和基于结构化数据的营销自动化工作流。

## 概览

| 属性 | 值 |
| --- | --- |
| **平台** | Airtable |
| **类别** | 自定义 |
| **设置复杂度** | 简单 |
| **官方集成** | 否 |
| **同步数据** | 记录、表、用户 |
| **API 类型** | REST API |
| **认证方式** | 个人访问令牌 / OAuth 2.0 |
| **基础 URL** | `https://api.airtable.com/v0/` |

## 功能

- **表到列表同步** - 将 Airtable 表记录直接同步到 Brevo 联系人列表
- **产品目录桥接** - 使用 Airtable 表作为邮件推荐的产品目录
- **CRM 同步** - Airtable CRM 与 Brevo 联系人的双向同步
- **表单提交事件** - 将 Airtable 表单提交作为 Brevo 事件转发
- **基于视图的过滤** - 将特定 Airtable 视图同步到目标 Brevo 列表
- **Webhook 自动化** - 当 Airtable 记录变更时触发 Brevo 活动

## 前提条件

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

1. Airtable 账户（免费计划或以上）
2. 已配置个人访问令牌或 OAuth 应用
3. 访问要同步的数据库和表
4. 具有 API 访问权限的 Brevo 账户
5. 具有有效订阅的 Tajo 账户

## 认证

Airtable 支持个人访问令牌和 OAuth 2.0。

### 选项 1：个人访问令牌（推荐）

1. 前往 [airtable.com/create/tokens](https://airtable.com/create/tokens)
2. 点击**创建新令牌**
3. 命名为”Tajo Integration”
4. 添加范围：

```
data.records:read
data.records:write
data.recordComments:read
schema.bases:read
webhook:manage
```

5. 添加对特定数据库或所有数据库的访问
6. 点击**创建令牌**

### 选项 2：OAuth 2.0

对于多用户集成，使用 OAuth 2.0 流程：

1. 在 [airtable.com/create/oauth](https://airtable.com/create/oauth) 注册您的集成
2. 配置重定向 URI：`https://app.tajo.io/callbacks/airtable`
3. 请求与上述相同的范围

令牌范围

个人访问令牌可以限定到特定数据库。为安全起见，只授予集成所需数据库的访问权限，而不是选择”所有当前和未来的数据库”。

### 连接到 Tajo

```bash
tajo connectors install airtable \
  --token $AIRTABLE_TOKEN
```

## 配置

### 基础设置

```yaml
connectors:
  airtable:
    enabled: true

    sync:
      records: true
      comments: false

    tables:
      - base_id: "appXXXXXXXXXXXXXX"
        table_name: "Customers"
        view: "Active Customers"
        sync_to_list: 28
      - base_id: "appXXXXXXXXXXXXXX"
        table_name: "Products"
        sync_as: "catalog"
```

### 字段映射

将 Airtable 字段映射到 Brevo 联系人属性：

```yaml
field_mapping:
  # Airtable field -> Brevo attribute
  Name: FIRSTNAME
  Email: email
  Phone: SMS
  Company: COMPANY
  Status: LEAD_STATUS
  Revenue: TOTAL_REVENUE
  "Last Contact": LAST_CONTACT_DATE
  Tags: TAGS
  Notes: NOTES
  "Created Time": SIGNUP_DATE
```

### 基于视图的同步

```yaml
views:
  - base_id: "appXXXXXXXXXXXXXX"
    table_name: "Customers"
    view: "High Value"
    sync_to_list: 29
    filter_by_view: true

  - base_id: "appXXXXXXXXXXXXXX"
    table_name: "Customers"
    view: "Churned"
    sync_to_list: 30
    filter_by_view: true
```

## API 端点

Tajo 集成以下 Airtable Web API 端点：

| 端点 | 方法 | 用途 |
| --- | --- | --- |
| `/v0/{baseId}/{tableIdOrName}` | GET | 列出表中的记录 |
| `/v0/{baseId}/{tableIdOrName}` | POST | 创建记录 |
| `/v0/{baseId}/{tableIdOrName}` | PATCH | 更新记录 |
| `/v0/{baseId}/{tableIdOrName}` | DELETE | 删除记录 |
| `/v0/{baseId}/{tableIdOrName}/{recordId}` | GET | 检索单条记录 |
| `/v0/meta/bases` | GET | 列出可访问的数据库 |
| `/v0/meta/bases/{baseId}/tables` | GET | 列出数据库中的表 |
| `/v0/{baseId}/{tableIdOrName}/listRecordComments` | GET | 列出记录评论 |
| `/v0/bases/{baseId}/webhooks` | POST | 创建 Webhook |
| `/v0/bases/{baseId}/webhooks` | GET | 列出 Webhook |

## 代码示例

### 初始化连接器

```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('airtable', {
  token: process.env.AIRTABLE_TOKEN
});
```

### 将表同步到 Brevo

```javascript
// Sync an Airtable table to a Brevo list
await tajo.connectors.sync('airtable', {
  type: 'full',
  resources: ['records'],
  baseId: 'appXXXXXXXXXXXXXX',
  tableName: 'Customers',
  view: 'Active Customers',
  targetList: 28
});

const status = await tajo.connectors.status('airtable');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-03-15T15:00:00Z',
//   recordsSynced: 2340,
//   tablesMonitored: 2,
//   basesConnected: 1
// }
```

### 处理 Webhook

```javascript
// Airtable webhooks notify of changes; fetch details with cursor
app.post('/webhooks/airtable', async (req, res) => {
  const { base, webhook, timestamp } = req.body;

  // Fetch changed records using webhook cursor
  const changes = await tajo.connectors.getWebhookPayloads('airtable', {
    baseId: base.id,
    webhookId: webhook.id,
    cursor: timestamp
  });

  for (const change of changes) {
    await tajo.connectors.handleEvent('airtable', {
      type: change.actionType,
      payload: change
    });
  }

  res.status(200).send('OK');
});
```

### 从 Brevo 创建记录

```javascript
// Create an Airtable record when a Brevo contact converts
tajo.events.on('contact.attribute_updated', async (event) => {
  if (event.attribute === 'LIFECYCLE_STAGE' && event.value === 'customer') {
    await tajo.connectors.create('airtable', {
      baseId: 'appXXXXXXXXXXXXXX',
      tableName: 'Customers',
      fields: {
        Name: event.contact.name,
        Email: event.contact.email,
        Status: 'Customer',
        'Converted Date': new Date().toISOString().split('T')[0]
      }
    });
  }
});
```

## 速率限制

Airtable 按数据库执行速率限制：

| 限制类型 | 值 |
| --- | --- |
| **API 速率限制** | 每个数据库每秒 5 个请求 |
| **每次请求记录数** | 列表最多 100 条，创建/更新最多 10 条 |
| **Webhook 负载** | 每次 `listWebhookPayloads` 调用最多 50 个 |
| **请求大小** | 负载最大约 2MB |

批量操作

Airtable 允许每次请求创建或更新最多 10 条记录。Tajo 会自动将较大的操作分批处理为多个请求，同时遵守速率限制。

## 故障排除

### 常见问题

| 问题 | 原因 | 解决方案 |
| --- | --- | --- |
| 401 Unauthorized | 令牌无效或已过期 | 重新生成个人访问令牌 |
| 403 Forbidden | 令牌缺少数据库访问权限 | 将数据库添加到令牌的范围 |
| 404 Not Found | 数据库或表 ID 无效 | 验证数据库 ID 和表名 |
| 422 Invalid Request | 字段类型不匹配 | 检查 Airtable 字段类型是否与数据匹配 |
| 超出速率限制 | 每个数据库超过 5 请求/秒 | 降低同步频率或错开数据库同步 |

### 调试模式

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

### 测试连接

```bash
tajo connectors test airtable
# ✓ API authentication successful
# ✓ Base access verified
# ✓ Table schema readable
# ✓ Record listing operational
# ✓ Webhook registration available
```

## 最佳实践

1. **将令牌限定到特定数据库** - 非必要不授予所有数据库访问权限
2. **使用视图进行过滤同步** - 同步特定视图而非完整表以减少数据量
3. **批量记录操作** - 每批 10 条分组创建和更新
4. **处理分页** - Airtable 每页返回 100 条记录；使用 `offset` 迭代
5. **使用 Webhook 实现实时** - 注册 Webhook 而非轮询变更
6. **精确映射字段类型** - 将 Airtable 字段类型（选择、数字、日期）与 Brevo 属性类型匹配

## 安全

- **个人访问令牌** - 限定到特定数据库和操作
- **OAuth 2.0** - 带刷新令牌的安全授权流程
- **仅 HTTPS** - 所有 API 通信通过 TLS 1.2+ 加密
- **数据库级访问控制** - 令牌限定到单个数据库
- **加密存储** - 令牌在 Tajo 中静态加密
- **Webhook HMAC 验证** - 验证 Webhook 通知的真实性

## 相关资源

- [Notion 连接器](https://tajo.io/zh-cn/docs/connectors/custom/notion)
- [GitHub 连接器](https://tajo.io/zh-cn/docs/connectors/custom/github)
- [客户同步技能](https://tajo.io/zh-cn/docs/skills/data-sync/customer-sync)
- [Brevo 联系人 API](https://tajo.io/zh-cn/docs/contact-management)