Tham số

Cú pháp {{param}}, kiểu và tuỳ chọn của tham số, enum cho tên cột động, danh sách lấy từ action khác, biến và secret dựng sẵn.

6 phút đọc

Tham số (param) là ô nhập của action. Param được khai báo ở phần Param của tab Định nghĩa và được dùng trong SQL. Form chạy action, ô nhập trong lịch và kiểu dữ liệu gợi ý trong view đều sinh từ danh sách param này.

Cú pháp

Viết param trong SQL bằng hai cặp ngoặc nhọn:

SELECT id, email, status
FROM users
WHERE status = {{status}}
  AND created_at >= {{from}}

Tên param bắt đầu bằng chữ cái hoặc _, chỉ gồm chữ, số và _, dài tối đa 64 ký tự. Bên trong ngoặc được phép có khoảng trắng: {{ status }}.
Một param có thể dùng nhiều lần trong cùng câu SQL.
Mỗi action có tối đa 50 param.

Đối chiếu khai báo với SQL

Khi Publish, máy chủ đối chiếu SQL với danh sách param và chặn publish trong các trường hợp sau:

SQL dùng một {{param}} chưa khai báo. Trình soạn thảo cảnh báo trước bằng dòng “SQL dùng param chưa khai báo: …” kèm nút Thêm N param từ SQL để thêm các param còn thiếu.
Một param được khai báo nhưng không dùng trong SQL.

Xem cách xử lý ở Xử lý sự cố.

Kiểu tham số

Kiểu	Ô nhập trên form	Ghi chú
`string`	Ô chữ
`number`	Ô số	Số thực.
`integer`	Ô số	Số nguyên.
`boolean`	Có / Không
`date`	Ô chọn ngày
`datetime`	Ô chọn ngày và giờ	Giờ được nhập theo múi giờ của trình duyệt; form hiển thị múi giờ đang dùng.
`enum`	Danh sách thả xuống	Bắt buộc có danh sách giá trị, hoặc danh sách lấy từ một action khác.

Tuỳ chọn của mỗi param

Tuỳ chọn	Ý nghĩa
Tên	Tên dùng trong `{{...}}`.
Nhãn	Chữ hiển thị trên form chạy.
Kiểu param	Một trong bảy kiểu ở trên.
bắt buộc	Nếu bỏ trống, form báo lỗi và không gửi yêu cầu chạy.
Giá trị enum	Chỉ cho `enum`: danh sách giá trị, cách nhau bởi dấu phẩy, không trùng nhau (tối đa 200 giá trị).
Mô tả (trong Nâng cao)	Hiện dưới ô nhập ở form chạy.
Giá trị mặc định (trong Nâng cao)	Điền sẵn ở form chạy; phải hợp lệ với kiểu của param.

Enum cho tên cột hoặc tên bảng động

Thông thường, param chỉ đứng ở vị trí giá trị (sau =, trong IN (...), LIMIT…). Khi tên cột hoặc tên bảng thay đổi theo lựa chọn của người dùng (ví dụ cột sắp xếp), param phải có kiểu enum với danh sách giá trị cố định:

SELECT id, email, created_at
FROM users
ORDER BY {{sort_by}}

Với sort_by kiểu enum, giá trị id, email, created_at:

Publish được chấp nhận vì mọi giá trị đều biết trước. Khi publish, giao diện liệt kê các param được nội suy như tên cột.
Lúc chạy, giá trị nằm ngoài danh sách bị từ chối trước khi tới cơ sở dữ liệu.
Nếu param kiểu khác (ví dụ string) đứng ở vị trí tên cột hay tên bảng, publish bị chặn.
Enum lấy danh sách từ action khác không dùng được ở vị trí này, vì danh sách đó có thể thay đổi sau khi publish.

Danh sách lấy từ action khác (master data)

Một param enum có thể lấy danh sách lựa chọn từ một action đã publish, ví dụ danh sách cửa hàng hay danh mục.

Ở param enum, đặt Nguồn giá trị là Lấy từ action.
Chọn action nguồn tại ô Chọn action nguồn đã publish.
Chọn Cột giá trị (giá trị gửi đi khi chạy) và Cột nhãn (chữ hiển thị trong danh sách).

Điều kiện:

Action nguồn được chạy không kèm param, nên không được có param bắt buộc.
Người chạy phải có quyền chạy action nguồn. Nếu không, ô chọn báo “Bạn không có quyền xem danh sách này — liên hệ admin của project.”
Action nguồn phải áp dụng ở môi trường đang chọn, và data source của action nguồn phải có kết nối ở môi trường đó. Nếu không, ô chọn báo “Danh sách này chưa dùng được ở môi trường đang chọn.”
Action đang làm nguồn danh sách cho param của action khác không xoá được cho tới khi gỡ liên kết đó.

Biến, secret và giá trị dựng sẵn

Ngoài param do người dùng nhập, SQL đọc được các giá trị do máy chủ tự điền. Các giá trị này bắt đầu bằng $ và không xuất hiện trên form:

Cú pháp	Giá trị
`{{$var.KEY}}`	Biến `KEY` của môi trường đang chạy.
`{{$secret.KEY}}`	Secret `KEY` của môi trường đang chạy. Chỉ được giải mã trên máy chủ thực thi, ngay trước khi chạy.
`{{$user.id}}`, `{{$user.email}}`	Người đang chạy action.
`{{$env.id}}`, `{{$env.slug}}`, `{{$env.isProduction}}`	Môi trường đang chạy.

SELECT *
FROM tickets
WHERE assignee_email = {{$user.email}}
  AND region = {{$var.DEFAULT_REGION}}

Các giá trị này luôn ở vị trí giá trị và được truyền tách khỏi SQL như param thường; secret không bao giờ bị ghép vào câu lệnh.
$user chỉ có id, email; $env chỉ có id, slug, isProduction. Nếu dùng trường khác, publish bị chặn.
Key của biến và secret chỉ gồm chữ HOA, số và gạch dưới, không bắt đầu bằng số (ví dụ SUPPORT_EMAIL).
JS action đọc được biến nhưng không nhận secret. Secret chỉ dùng trong chính action SQL cần đến nó.

Cách khai báo biến và secret: Biến và secret.

Tham số khi chạy nền, hàng loạt và theo lịch

Chạy hàng loạt (chỉ với action SQL kiểu Ghi dữ liệu): mỗi phần tử của mảng JSON là một bộ param, được kiểm tra theo cùng quy tắc với form (tối đa 10.000 phần tử). Xem Chạy action.
Lịch: không có người điền form, nên param được cố định khi tạo lịch. Xem Job và lịch.
Lịch sử chạy lưu tham số đã nhập. Giá trị của param có tên chứa password, token, secret, api_key… được ẩn.