Giới thiệu

Trước khi bạn kết nối workflow thực sự đầu tiên trong n8n, bạn cần hiểu một điều có thể gây nhầm lẫn cho hầu hết người mới bắt đầu: n8n không truyền tệp thô hay luồng giữa các nút. Nó truyền các items. Mọi thứ — payload webhook, một hàng cơ sở dữ liệu, phản hồi API — được đóng gói thành một item có cấu trúc trước khi di chuyển đến nút tiếp theo. Hiểu đúng mô hình tư duy này từ sớm sẽ làm cho việc gỡ lỗi trở nên dễ dàng hơn rất nhiều.

Một mục là gì?

Một mục là đơn vị dữ liệu cơ bản trong n8n. Mỗi nút nhận một mảng các items và xuất ra một mảng các items. Mỗi item là một đối tượng JavaScript có khóa json bắt buộc, chứa dữ liệu payload thực của bạn dưới dạng một đối tượng JSON. Tùy chọn, một item cũng có thể mang dữ liệu nhị phân (cho tập tin, hình ảnh, v.v.), nhưng điều này được đề cập riêng biệt.

Một mục duy nhất có cấu trúc lõi như sau:

{
  "json": {
    "id": 42,
    "name": "Alice",
    "email": "alice@example.com"
  }
}

Khi một nút như HTTP Request lấy danh sách người dùng từ một API, n8n sẽ không chuyển cho nút tiếp theo một mảng lớn duy nhất. Nó tách mảng đó ra và cấp cho nút tiếp theo một item cho mỗi người dùng. Điều này có nghĩa là nếu API của bạn trả về 10 người dùng, nút đằng dưới sẽ chạy 10 lần — mỗi lần cho một item. Hành vi đó là nền tảng cho cách n8n suy nghĩ.

Cách JSON luân chuyển giữa các nút

Khi bạn tham chiếu dữ liệu từ một nút trước đó, bạn luôn truy cập vào khóa json của một item. Trong các biểu thức, n8n sử dụng cú pháp dưới đây để truy cập đầu ra của nút trước:

{{ $json.fieldName }}

Nếu bạn muốn lấy dữ liệu từ một nút được đặt tên cụ thể chứ không phải nút trước đó ngay tức thì, bạn sẽ sử dụng:

{{ $node["NodeName"].json.fieldName }}

Trong thực tế, nếu bạn có một nút Set tạo ra một mục có cấu trúc như đã trình bày ở trên, nút tiếp theo có thể tham chiếu email của người dùng như sau:

{{ $json.email }}

Điểm mấu chốt cần nắm rõ: bạn không bao giờ làm việc với nội dung phản hồi HTTP thô ở dạng chuỗi. Đến khi dữ liệu đến phần biểu thức của bạn, n8n đã phân tích nó thành đối tượng json. Bạn không cần tự gọi JSON.parse()

Mô hình Thực thi

n8n xử lý các mục một lần qua từng nút, theo trình tự. Khi một nút nhận được nhiều mục, nó tự động lặp lại chúng — bạn sẽ không viết vòng lặp. Điều này được gọi là mô hình thực thi dựa trên mục.

Hãy xem xét một workflow đọc 50 hàng từ cơ sở dữ liệu, biến đổi từng hàng và gửi email cho mỗi hàng. Bạn không viết "for each row, send email." Bạn chỉ cần kết nối các nút. n8n sẽ xử lý việc lặp lại.

Điều này có ý nghĩa quan trọng:

Đầu tiên, mỗi nút trong chuỗi sẽ chạy một lần cho mỗi mục theo mặc định. Một nút bổ sung trường thời gian sẽ chạy 50 lần cho 50 mục, tạo ra 50 mục đầu ra.

Thứ hai, một số nút cố ý ghép hoặc tách số lượng mục. Nút Merge có thể kết hợp các luồng. Nút SplitInBatches có thể gom nhóm các mục. Nút Code có thể định hình lại toàn bộ mảng nếu cần. Việc nhận thức được cách số lượng mục thay đổi khi thực hiện workflow là chìa khóa để tránh hành vi không mong muốn.

Thứ ba, nếu bất kỳ nút nào gặp lỗi trên một mục, theo mặc định toàn bộ quá trình thực thi sẽ dừng lại. Bạn có thể cấu hình xử lý lỗi theo nút để thay đổi điều này, nhưng mặc định là fail-fast.

Ví dụ thực tiễn

Đây là cách một mảng item thực sự trông như thế nào khi nó đi vào một nút Code. Bạn có thể tự kiểm tra điều này bằng trình gỡ lỗi tích hợp bằng cách nhấp vào bảng đầu ra của bất kỳ nút nào.

[
  {
    "json": {
      "orderId": "ORD-001",
      "amount": 120.5,
      "status": "pending"
    }
  },
  {
    "json": {
      "orderId": "ORD-002",
      "amount": 89.0,
      "status": "shipped"
    }
  }
]

Nếu bạn đặt một nút Code sau cái này và muốn thêm một cờ xử lý cho mỗi item, bạn sẽ viết:

for (const item of items) {
  item.json.processed = true;
}
return items;

Lưu ý bạn lặp qua các item ngay bên trong nút Code — đó là ngoại lệ duy nhất với quy tắc "n8n tự động lặp". Nút Code sẽ trả về cho bạn toàn bộ mảng và mong đợi toàn bộ mảng ở lại.

Tóm tắt

Mọi dữ liệu trong n8n được đóng gói trong một item với khóa json. Các nút nhận và phát ra các mảng item, và theo mặc định mỗi nút chạy một lần cho mỗi item — bạn không quản lý vòng lặp ngoài nút Code. Các biểu thức như $json.fieldName là cách bạn tiếp cận dữ liệu item. Hiểu mô hình thực thi này là nền tảng cho mọi thứ khác: biến đổi, phân nhánh, hợp nhất và xử lý lỗi đều xây dựng trực tiếp trên nền tảng này.