Output Schema là gì?
Output Schema là định nghĩa cấu trúc dữ liệu mà một workflow hoặc task sẽ trả về sau khi hoàn thành. Nó xác định các trường, kiểu dữ liệu, và định dạng của đầu ra, giúp đảm bảo rằng dữ liệu được trả về có cấu trúc đúng và nhất quán. Output Schema hoạt động như một hợp đồng dữ liệu giữa workflow và các hệ thống tiêu thụ nó.
Vai trò của Output Schema trong workflow
Output Schema đóng vai trò quan trọng trong việc xác thực và chuẩn hóa dữ liệu đầu ra. Khi một workflow hoặc task được thực thi, output schema được áp dụng để kiểm tra xem dữ liệu trả về có khớp với định nghĩa đã được quy định trước không.
Các tác dụng chính của Output Schema bao gồm:
- Xác thực dữ liệu trước khi trả về cho các hệ thống khác
- Đảm bảo tính nhất quán trong cấu trúc dữ liệu giữa các lần chạy workflow
- Hỗ trợ tích hợp với các hệ thống khác thông qua giao diện API và OpenAPI
- Phát hiện lỗi sai về cấu trúc dữ liệu sớm trong quá trình thực thi
Output Schema hoạt động như thế nào trong thực tế
Output Schema thường được định nghĩa bằng JSON Schema, một tiêu chuẩn mô tả cấu trúc dữ liệu JSON. Trong nhiều nền tảng automation workflow, bạn có thể chỉ định một URL trỏ đến file JSON Schema hoặc định nghĩa cấu trúc trực tiếp trong workflow definition.
Quy trình hoạt động thường như sau:
- Workflow hoặc task hoàn thành và tạo ra dữ liệu đầu ra
- Hệ thống kiểm tra dữ liệu đầu ra so với Output Schema đã định nghĩa
- Nếu dữ liệu khớp với schema, workflow hoàn thành thành công
- Nếu dữ liệu không khớp, có thể xảy ra lỗi hoặc cảnh báo, tùy thuộc vào cài đặt
failOnValidationErrors
Trong các nền tảng như Orkes Conductor, Output Schema có thể được thêm ở ba cấp độ:
- Workflow level: Xác thực đầu ra của toàn bộ workflow
- Task definition level: Xác thực đầu ra cho tất cả các instance của một task
- Task configuration level: Xác thực đầu ra cho một task cụ thể trong một workflow
Những lưu ý quan trọng về Output Schema
Khi sử dụng Output Schema, có một số điểm cần lưu ý. Nếu bạn đặt failOnValidationErrors thành false, workflow sẽ không dừng lại khi dữ liệu đầu ra không khớp với schema, điều này có thể hữu ích trong các tình huống muốn workflow tiếp tục dù có sai lệch nhỏ.
Output Schema cũng rất hữu ích để tạo tài liệu OpenAPI tự động. Khi workflow có Output Schema, nền tảng có thể sinh ra file OpenAPI mô tả cách workflow hoạt động, giúp các nhà phát triển khác hiểu được đầu ra mà workflow sẽ cung cấp.
Cần phân biệt giữa Output Schema và Input Schema. Trong khi Input Schema xác thực dữ liệu đầu vào trước khi workflow bắt đầu chạy, Output Schema kiểm tra dữ liệu đầu ra sau khi workflow kết thúc. Cả hai đều quan trọng để đảm bảo tính toàn vẹn của dữ liệu trong toàn bộ quá trình tự động hóa.
Các thuật ngữ liên quan đến Output Schema
Các khái niệm sau đây liên quan chặt chẽ đến Output Schema và thường được sử dụng cùng nhau:
- Input Schema: Định nghĩa cấu trúc dữ liệu đầu vào mà workflow hoặc task yêu cầu trước khi thực thi.
- JSON Schema: Tiêu chuẩn để mô tả cấu trúc, kiểu dữ liệu, và quy tắc xác thực cho dữ liệu JSON.
- Data Validation: Quá trình kiểm tra dữ liệu để đảm bảo nó tuân theo các quy tắc và cấu trúc đã định nghĩa trước.
- Payload: Phần dữ liệu thực tế được gửi đi hoặc nhận về trong một request hoặc response của workflow hoặc task.
Các câu hỏi thường gặp
Tôi có bắt buộc phải sử dụng Output Schema không?
Không bắt buộc, nhưng rất nên sử dụng Output Schema để đảm bảo tính nhất quán của dữ liệu. Nếu không sử dụng Output Schema, dữ liệu đầu ra có thể không đồng nhất, khó dự đoán, và gây ra lỗi khi tích hợp với các hệ thống khác. Sử dụng Output Schema giúp tránh các vấn đề này.
Điều gì xảy ra nếu dữ liệu đầu ra không khớp với Output Schema?
Hành động phụ thuộc vào cài đặt failOnValidationErrors của Output Schema. Nếu đặt thành true, workflow sẽ dừng và báo lỗi. Nếu đặt thành false, workflow vẫn sẽ hoàn thành nhưng có thể ghi log cảnh báo về sự không khớp.
Khác gì giữa Output Schema và Input Schema?
Input Schema xác thực dữ liệu trước khi workflow bắt đầu chạy, còn Output Schema xác thực dữ liệu sau khi workflow hoàn thành. Cả hai đều dùng JSON Schema nhưng áp dụng vào các giai đoạn khác nhau của vòng đời workflow.
Output Schema có hỗ trợ tạo tài liệu API tự động không?
Có, khi workflow có Output Schema, nền tảng có thể tự động tạo ra file OpenAPI mô tả cấu trúc đầu ra của workflow. Điều này giúp các nhà phát triển khác hiểu rõ về dữ liệu mà workflow sẽ cung cấp mà không cần phải đọc source code.