Giao diện
@digiforce-nc/plugin-workflow-json-query
Plugin đăng ký node query JSON trong workflow, mở rộng plugin-workflow. Sử dụng JMESPath hoặc JSONPath để lọc, tìm kiếm, và trích xuất dữ liệu từ object JSON phức tạp.
Plugin này làm gì?
Node JSON Query nhận một object hoặc mảng JSON, áp dụng biểu thức query (JMESPath/JSONPath) để lọc và trích xuất dữ liệu. Phù hợp khi cần tìm phần tử trong mảng, lọc theo điều kiện, hoặc reshape dữ liệu JSON.
So với Get JSON Field (lấy đúng 1 field theo path), JSON Query hỗ trợ:
- Lọc mảng theo điều kiện:
items[?status == 'active'] - Projection (chỉ lấy field cần):
items[*].name - Aggregate:
max_by(items, &price)
Cấu hình
| Tham số | Kiểu | Mô tả |
|---|---|---|
source | string | Biến workflow chứa JSON data nguồn |
engine | string | Engine query: JMESPath hoặc JSONPath |
expression | string | Biểu thức query (ví dụ: items[?price > 100].name) |
defaultValue | any | Giá trị mặc định khi query không có kết quả |
Input / Output
| Hướng | Dữ liệu | Mô tả |
|---|---|---|
| Input | source | Object hoặc mảng JSON cần query |
| Input | expression | Biểu thức JMESPath/JSONPath |
| Output | result | Dữ liệu khớp query (có thể là array, object, hoặc scalar) |
| Output | count | Số phần tử kết quả (nếu result là array) |
Tính năng chính
| # | Tính năng | Chi tiết |
|---|---|---|
| 1 | JMESPath | Query language mạnh mẽ cho JSON (filter, projection, multiselect) |
| 2 | JSONPath | Cú pháp quen thuộc kiểu XPath cho JSON |
| 3 | Filter điều kiện | Lọc phần tử theo điều kiện phức tạp |
| 4 | Projection | Chỉ lấy các field cần thiết từ kết quả |
| 5 | Nested query | Truy vấn vào nhiều cấp lồng nhau |
Trường hợp sử dụng
| # | Kịch bản | Mô tả |
|---|---|---|
| 1 | Lọc sản phẩm | Lấy tất cả items có status == "active" từ API response |
| 2 | Tìm phần tử | Tìm user có email cụ thể trong mảng users |
| 3 | Reshape data | Chuyển mảng objects thành mảng chỉ chứa field name |
| 4 | Aggregate đơn giản | Tính max_by(items, &price) bằng JMESPath built-in |
| 5 | Multi-select | Lấy nhiều field cùng lúc: items[*].[name, price] |
Ví dụ biểu thức
| Engine | Expression | Mô tả |
|---|---|---|
| JMESPath | items[?status == 'active'] | Lọc items active |
| JMESPath | items[*].name | Lấy tất cả tên |
| JMESPath | max_by(items, &price) | Item có giá cao nhất |
| JSONPath | $.items[?(@.price > 100)] | Items giá trên 100 |
| JSONPath | $.items[*].name | Lấy tất cả tên |
Lưu ý quan trọng
- JMESPath và JSONPath có cú pháp khác nhau - chọn đúng engine
- JMESPath mạnh hơn (hỗ trợ function, multiselect, pipe), JSONPath đơn giản hơn
- Query trên mảng lớn (hàng ngàn phần tử) có thể chậm - cân nhắc filter ở tầng DB
- Kết quả filter trả về mảng rỗng (không phải null) khi không có phần tử khớp
- Expression lỗi cú pháp sẽ throw error - test kỹ expression trước khi dùng
Dependencies
| Package | Vai trò |
|---|---|
@digiforce-nc/plugin-workflow | Workflow engine (peer) |
@digiforce-nc/server | Server framework (peer) |