Query Parameter là gì?
Query Parameter là cặp key-value được gắn vào cuối URL sau dấu ? để truyền thông tin bổ sung cho server mà không thay đổi endpoint chính. Nó thường dùng để lọc, sắp xếp hoặc phân trang dữ liệu trong các yêu cầu GET. Cú pháp cơ bản: https://example.com/api/users?role=admin&page=2, với các tham số phân cách bằng dấu &.
Vai trò của Query Parameter trong tích hợp hệ thống
Query Parameter đóng vai trò quan trọng trong việc tùy chỉnh yêu cầu API, giúp workflow automation lấy dữ liệu chính xác mà không cần thay đổi đường dẫn chính. Trong hệ thống như n8n hoặc các công cụ workflow, nó cho phép node HTTP Request truyền điều kiện lọc động từ dữ liệu trước đó. Ví dụ, khi tích hợp với API bên thứ ba, Query Parameter giúp workflow xử lý dữ liệu lớn hiệu quả hơn bằng cách chỉ lấy phần cần thiết.
Các tình huống sử dụng phổ biến bao gồm:
- Lọc dữ liệu theo điều kiện:
?status=active&role=admin. - Phân trang:
?page=2&limit=10để tránh tải toàn bộ dữ liệu. - Sắp xếp kết quả:
?sort=name&order=asc. - Tìm kiếm:
?keyword=johntrong chức năng search.
Query Parameter hoạt động như thế nào trong thực tế?
Query Parameter được thêm vào URL theo cấu trúc ?key1=value1&key2=value2, server sẽ phân tích query string để xử lý yêu cầu. Trong automation workflow, bạn cấu hình nó trong node HTTP Request bằng cách map dữ liệu từ node trước, ví dụ sử dụng expression như {{ $json.role }} để tạo ?role={{ $json.role }}. Server nhận URL đầy đủ, parse query string và áp dụng logic tương ứng, trả về response phù hợp.
Một số ví dụ thực tế:
- API users:
GET /api/users?role=admin&limit=5trả về danh sách admin với 5 item. - Deep linking:
https://app.example.com?campaign=summer&userId=123để mở màn hình cụ thể. - Tracking:
?utm_source=newslettertheo dõi nguồn traffic.
Những lưu ý quan trọng về Query Parameter
Query Parameter chỉ phù hợp với dữ liệu đơn giản, không mã hóa phức tạp vì nó làm URL dài và dễ lộ thông tin. URL có giới hạn độ dài (thường 2048 ký tự tùy browser/server), nên tránh nhồi dữ liệu lớn vào đây. Luôn URL-encode giá trị đặc biệt như khoảng trắng (%20) hoặc dấu & (%26) để tránh lỗi parse.
Các lỗi phổ biến cần tránh:
- Nhầm lẫn với Path Parameter:
?userId=123thay vì/users/123(Path dùng cho tài nguyên cụ thể). - Dùng cho dữ liệu lớn: Không nên truyền JSON phức tạp qua Query, hãy dùng Body cho POST/PUT.
- Bỏ qua encoding:
?name=Nguyễn Văn Acó thể lỗi nếu không encode thành?name=Nguy%E1%BB%85n%20V%C4%83n%20A. - Quên phân trang: Gọi API không có
?pagevà?limitdễ gây timeout hoặc overload.
Các thuật ngữ liên quan đến Query Parameter
Dưới đây là một số thuật ngữ thường liên quan trực tiếp đến Query Parameter trong automation và API:
- Path Parameter: Tham số nhúng trong đường dẫn URL như
/users/{id}, dùng chỉ định tài nguyên cụ thể. - Request Body: Dữ liệu gửi trong phần body của request (JSON/XML), phù hợp cho POST/PUT với dữ liệu lớn.
- Query String: Phần toàn bộ sau dấu
?chứa tất cả Query Parameter, được server parse để lọc dữ liệu. - URL Encoding: Quá trình mã hóa ký tự đặc biệt trong Query Parameter để tránh lỗi parse, ví dụ
%20cho khoảng trắng.
Các câu hỏi thường gặp
Query Parameter khác Path Parameter như thế nào?
Query Parameter dùng cho lọc/tìm kiếm (?role=admin), trong khi Path Parameter chỉ định tài nguyên cụ thể (/users/123). Query linh hoạt cho điều kiện động, Path cố định theo RESTful design. Chọn Query khi cần xem điều kiện qua URL, Path cho ID duy nhất.
Khi nào nên dùng Query Parameter thay vì Body?
Dùng Query Parameter cho GET request với dữ liệu lọc đơn giản như phân trang hoặc search. Body phù hợp POST/PUT với dữ liệu cấu trúc lớn, vì Query không hỗ trợ tốt dữ liệu phức tạp. Query dễ debug qua URL log, nhưng tránh nếu URL vượt giới hạn độ dài.
Làm sao tránh lỗi URL quá dài với Query Parameter?
Áp dụng phân trang (page và limit) và chỉ truyền tham số cần thiết. Sử dụng POST với Body nếu dữ liệu lớn, hoặc nén giá trị bằng encoding. Kiểm tra giới hạn server (thường 2KB) trước khi build workflow.
Query Parameter có an toàn cho dữ liệu nhạy cảm không?
Không an toàn vì nó lộ rõ trong URL log, browser history và referrer header. Dùng Header (như Authorization) hoặc Body cho token/password. Luôn HTTPS để mã hóa, nhưng tránh Query cho thông tin bí mật.