n8n-nodes-larkbase-v3/README.md

n8n node to connect with Larkbase API with UTF-8 support, date filtering, array filter values, text field processing, improved field type handling, pagination fixes, advanced data type conversion, proper date filtering with ExactDate format, updated node

# n8n-nodes-larkbase-v3

This is an n8n community node. It lets you use Larkbase in your n8n workflows.

Larkbase is a database service provided by Lark/Feishu.

[n8n](https://n8n.io/) is a [fair-code licensed](https://docs.n8n.io/reference/license/) workflow automation platform.

[Installation](#installation)  
[Operations](#operations)  
[Credentials](#credentials)  
[Compatibility](#compatibility)  
[Resources](#resources)  
[Version history](#version-history)  

## Installation

### Community Nodes (Recommended)

For users on n8n v0.187+, the easiest way to install this node is through the Community Nodes tab in n8n:

1. Go to **Settings** > **Community Nodes**
2. Click on **Install**
3. Enter `n8n-nodes-larkbase-v3` in the package name field
4. Accept the risks and click **Install**

### Manual Installation

To get started using the node manually:

```bash
# Install the package
cd ~/.n8n/nodes
npm install n8n-nodes-larkbase-v3

# Restart n8n
pm2 restart n8n
```

## Updating

To ensure a successful update to the latest version:

### Method 1: Through n8n UI (Recommended)

1. Go to **Settings** > **Community Nodes**
2. Find `n8n-nodes-larkbase-v3` in the list
3. Click **Update** if available

### Method 2: Manual Update (For troubleshooting)

If you experience issues with the UI update, follow these steps:

```bash
# Access n8n nodes directory
cd ~/.n8n/nodes

# Uninstall current version
npm uninstall n8n-nodes-larkbase-v3

# Clear cache
rm -rf ~/.n8n/.cache

# Install latest version
npm install n8n-nodes-larkbase-v3@0.1.1 --no-cache

# Restart n8n
pm2 restart n8n
```

## Operations

- **Batch Search**: Search for records in a Larkbase table
- **Batch Create**: Create multiple records in a Larkbase table
- **Batch Update**: Update multiple records in a Larkbase table
- **Upsert By Field**: Create or update records based on a field value

## Credentials

To use this node, you need to create an application in the [Lark/Feishu Developer Console](https://open.larksuite.com/app/) and obtain the following credentials:

- **App ID**: The ID of your Lark/Feishu application
- **App Secret**: The secret of your Lark/Feishu application

You also need to:
1. Enable the Bitable API in your application permissions
2. Add your application as a collaborator to your Larkbase tables

## Compatibility

This node has been tested with n8n version 0.187.0 and later.

## Resources

* [n8n community nodes documentation](https://docs.n8n.io/integrations/community-nodes/)
* [Lark/Feishu API documentation](https://open.larksuite.com/document/server-docs/apis/bitable/bitable-overview)

## Version history

### 0.4.1 (2025-03-25)
- Thêm tính năng load fields từ Larkbase để cấu hình dễ dàng hơn
- Cải thiện giao diện cấu hình fields với 3 chế độ mapping: tự động, định nghĩa thủ công, hoặc JSON
- Hỗ trợ tải danh sách fields trực tiếp từ bảng Larkbase để lựa chọn
- Thêm operation "Get Fields" để lấy thông tin về cấu trúc bảng

### 0.4.0 (2025-03-24)
- Hỗ trợ xác thực bằng token thủ công cho tất cả các operations
- Cải thiện cấu trúc mã để dễ dàng bảo trì
- Tăng cường khả năng tương thích giữa các phương thức xác thực
- Tối ưu hóa hiệu suất xử lý dữ liệu

### 0.3.1 (2025-03-23)
- Thêm tùy chọn nhập token thủ công trực tiếp vào Larkbase node
- Tăng cường độ linh hoạt với 3 phương thức xác thực: credentials, từ Auth node, và nhập thủ công
- Cải thiện trải nghiệm người dùng với nhiều tùy chọn xác thực
- Cho phép sử dụng token từ các nguồn khác ngoài Larkbase Auth node

### 0.3.0 (2025-03-23)

- Thêm node Larkbase Auth mới để lấy token xác thực
- Hỗ trợ hai phương thức xác thực: sử dụng credentials hoặc token từ node khác
- Cho phép nhập thông tin xác thực thủ công trong node Larkbase Auth
- Cải thiện tính linh hoạt trong quản lý token xác thực
- Giảm sự phụ thuộc vào credentials được lưu trữ

### 0.2.1 (2025-03-22)

- Tăng giá trị page_size mặc định từ 100 lên 500 để cải thiện hiệu suất
- Giảm số lần gọi API khi lấy dữ liệu lớn
- Tối ưu hóa tốc độ xử lý dữ liệu

### 0.2.0 (2025-03-21)

- Nâng cấp version của node từ 2 lên 3
- Đổi tên hiển thị từ "Larkbase V2" thành "Larkbase V3"
- Cải thiện khả năng tương thích với n8n
- Tăng cường trải nghiệm người dùng với giao diện mới
- Tích hợp tất cả các cải tiến từ phiên bản 0.1.5

### 0.1.5 (2025-03-20)

- Cải thiện xử lý date filter với định dạng ExactDate chuẩn của Larkbase API
- Sửa lỗi phân trang bằng cách truyền page_token và page_size dưới dạng query parameters
- Cải thiện cơ chế phát hiện vòng lặp vô hạn trong phân trang
- Tối ưu hóa hiệu suất khi lấy dữ liệu lớn
- Hỗ trợ tốt hơn cho lọc theo khoảng thời gian

### 0.1.4 (2025-03-19)

- Cải thiện xử lý dữ liệu trả về từ API Larkbase
- Thêm chuyển đổi tự động cho các loại dữ liệu khác nhau (text, number, date)
- Làm sạch cấu trúc dữ liệu phức tạp thành dạng key-value đơn giản
- Tự động chuyển đổi chuỗi ngày tháng thành timestamp
- Xử lý tốt hơn các trường hợp dữ liệu đặc biệt

### 0.1.3 (2025-03-18)

- Sửa lỗi module search khi sử dụng tùy chọn "Return All"
- Cải thiện xử lý phân trang để tránh timeout
- Thêm giới hạn số lần lặp để tránh vòng lặp vô hạn
- Loại bỏ tùy chọn limit không hoạt động đúng
- Tối ưu hóa hiệu suất khi lấy dữ liệu lớn

### 0.1.2 (2025-03-18)

- Added field type handling for batch create operations
- Improved data normalization for different field types
- Enhanced field mapping to correctly process various data types
- Fixed issues with field mappings not being applied correctly
- Added UI options to specify field types for better data handling

### 0.1.1 (2025-03-17)

- Improved filter value handling to support array values
- Fixed text field processing to convert array format to string
- Enhanced access token handling to ensure proper format
- Added support for multiple filter values in UI
- Improved error handling and debugging

### 0.1.0 (2025-03-17)

- Renamed package from n8n-nodes-larkbase-v2 to n8n-nodes-larkbase-v3
- Increased node version to improve update compatibility
- Fixed issues with node updates in n8n
- Enhanced stability and reliability
- Improved user experience

### Previous versions (n8n-nodes-larkbase-v2)

- 0.2.4: Improved update compatibility and stability
- 0.2.3: Enhanced features and performance optimizations
- 0.2.2: Added date filtering option in the UI
- 0.2.1: Added UTF-8 support for Vietnamese characters
- 0.2.0: Renamed from n8n-nodes-larkbase to n8n-nodes-larkbase-v2
- 0.1.2: Changed API endpoints
- 0.1.1: Initial release

## Tổng quan

n8n-nodes-larkbase là một community node cho phép n8n workflows tương tác với Larkbase API (Feishu/Lark Bitable). Node này cho phép người dùng thực hiện các thao tác batch search, batch create, batch update và custom upsert by field với dữ liệu trong Larkbase.

## Tính năng

- **Xác thực**: Kết nối an toàn với Larkbase API sử dụng App ID và App Secret
- **Node xác thực riêng biệt**: Lấy token xác thực từ Larkbase API với nhiều tùy chọn
- **Batch Search**: Tìm kiếm nhiều records cùng lúc với các điều kiện lọc
- **Batch Create**: Tạo nhiều records cùng lúc
- **Batch Update**: Cập nhật nhiều records cùng lúc
- **Custom Upsert by Field**: Tạo mới hoặc cập nhật records dựa trên giá trị của một trường cụ thể
- **Hỗ trợ UTF-8**: Xử lý đúng các ký tự tiếng Việt và các ngôn ngữ khác
- **Lọc theo thời gian**: Tìm kiếm records trong một khoảng thời gian cụ thể
- **Hỗ trợ giá trị lọc dạng mảng**: Cho phép tìm kiếm với nhiều giá trị cùng lúc
- **Xử lý trường text**: Tự động chuyển đổi các trường text từ dạng array về dạng string
- **Phương thức xác thực linh hoạt**: 3 tùy chọn xác thực cho tất cả các thao tác

## Cấu hình

Để sử dụng Larkbase node, bạn cần tạo credentials với các thông tin sau:

- **App ID**: App ID của ứng dụng Feishu/Lark (tìm thấy trong Feishu/Lark Developer Console)
- **App Secret**: App Secret của ứng dụng Feishu/Lark (tìm thấy trong Feishu/Lark Developer Console)

## Ví dụ sử dụng

### Lấy Access Token với Node Larkbase Auth

1. Thêm Larkbase Auth node vào workflow
2. Chọn "Get Access Token" làm operation
3. Chọn phương thức xác thực:
   - "Credentials" để sử dụng thông tin xác thực đã lưu
   - "Manual Input" để nhập thông tin xác thực thủ công
4. Nếu chọn "Manual Input", nhập App ID và App Secret
5. Thực thi node để lấy access token

### Sử dụng Access Token từ Node Larkbase Auth

1. Thêm Larkbase Auth node vào workflow để lấy token
2. Thêm Larkbase node vào workflow
3. Chọn "Access Token" làm phương thức xác thực
4. Sử dụng biểu thức để lấy token từ node trước đó:
   `{{$node["Larkbase Auth"].json["access_token"]}}`
5. Cấu hình các tham số khác và thực thi node

### Sử dụng Token thủ công

1. Thêm Larkbase node vào workflow
2. Chọn "Manual Token" làm phương thức xác thực
3. Nhập access token trực tiếp vào trường "Manual Token"
4. Cấu hình các tham số khác và thực thi node
5. Phương pháp này hữu ích khi bạn đã có sẵn token từ nguồn khác

### Batch Search Records

1. Thêm Larkbase node vào workflow
2. Chọn "Record" làm resource
3. Chọn "Batch Search" làm operation
4. Chọn phương thức xác thực phù hợp (Credentials, Access Token, hoặc Manual Token)
5. Cấu hình App Token, Table ID và các điều kiện lọc
6. Thực thi node để lấy dữ liệu

### Batch Create Records

1. Thêm Larkbase node vào workflow
2. Chọn "Record" làm resource
3. Chọn "Batch Create" làm operation
5. Cấu hình App Token, Table ID và dữ liệu cần tạo
6. Thực thi để tạo records mới

### Batch Update Records

1. Thêm Larkbase node vào workflow
2. Chọn "Record" làm resource
3. Chọn "Batch Update" làm operation
4. Chọn phương thức xác thực phù hợp (Credentials, Access Token, hoặc Manual Token)
5. Cấu hình App Token, Table ID và dữ liệu cần cập nhật
6. Thực thi để cập nhật records

### Custom Upsert by Field

1. Thêm Larkbase node vào workflow
2. Chọn "Record" làm resource
3. Chọn "Upsert by Field" làm operation
4. Chọn phương thức xác thực phù hợp (Credentials, Access Token, hoặc Manual Token)
5. Cấu hình App Token, Table ID, trường làm key và dữ liệu cần upsert
6. Thực thi để tạo mới hoặc cập nhật records

## Tài liệu API

Node được xây dựng dựa trên tài liệu Larkbase API. Các endpoint chính bao gồm:

- `/open-apis/bitable/v1/apps/{app_token}/tables/{table_id}/records/search` - Cho batch search
- `/open-apis/bitable/v1/apps/{app_token}/tables/{table_id}/records/batch_create` - Cho batch create
- `/open-apis/bitable/v1/apps/{app_token}/tables/{table_id}/records/batch_update` - Cho batch update

## Ghi chú phát triển

Node này được phát triển sử dụng n8n community node framework. Cấu trúc tuân theo các best practices cho việc phát triển n8n node:

```
n8n-nodes-larkbase/
├── credentials/                  # Cấu hình xác thực
│   └── LarkbaseApi.credentials.ts
├── nodes/                        # Triển khai node
│   ├── Larkbase.node.ts
│   └── larkbase.svg              # Icon của node
├── dist/                         # Mã đã biên dịch (được tạo tự động)
├── index.js                      # Entry point
├── index.ts                      # Export node và credentials
├── package.json                  # Cấu hình package
└── tsconfig.json                 # Cấu hình TypeScript
```

## Xử lý sự cố

Các vấn đề thường gặp và giải pháp:

1. **Lỗi xác thực**: Đảm bảo App ID và App Secret của bạn chính xác
2. **Giới hạn tốc độ**: API Larkbase có thể có giới hạn tốc độ; cân nhắc thêm độ trễ giữa các thao tác
3. **Vấn đề định dạng dữ liệu**: Kiểm tra cấu trúc dữ liệu nếu gặp lỗi phân tích
4. **Lỗi ký tự đặc biệt**: Đảm bảo dữ liệu tiếng Việt được mã hóa đúng cách
5. **Lỗi định dạng ngày tháng**: Đảm bảo định dạng ngày tháng đúng (ISO 8601) khi sử dụng lọc theo thời gian
6. **Lỗi giá trị lọc dạng mảng**: Đối với toán tử "Is One Of", nhập các giá trị phân cách bằng dấu phẩy

## Cải tiến trong tương lai

Các tính năng dự kiến cho các phiên bản tương lai:

- Hỗ trợ thêm các resource của Larkbase
- Thao tác xóa batch
- Khả năng lọc nâng cao
- Hỗ trợ webhook cho cập nhật dữ liệu real-time

## Đóng góp

Đóng góp để cải thiện node được hoan nghênh. Vui lòng làm theo các bước sau:

1. Fork repository
2. Tạo branch tính năng
3. Thực hiện các thay đổi
4. Gửi pull request

## Giấy phép

Node này được phát hành theo Giấy phép MIT.