Thay đổi sơ đồ dữ liệu CSV của đồng hồ đo: Hợp đồng Phiên bản cho Nhập khẩu An toàn

Hợp đồng phiên bản lược đồ CSV dữ liệu công tơ xác định ý nghĩa của từng cột, các giá trị được phép và những phiên bản bộ nhập dữ liệu nào có thể đọc tệp một cách an toàn. Trước khi thay đổi dữ liệu xuất, hãy thống nhất hợp đồng này với hệ thống tiếp nhận, kiểm tra cả các ví dụ tương thích và không tương thích, đồng thời bảo đảm các phiên bản không xác định sẽ được báo lỗi rõ ràng. Việc một tệp mở thành công trong phần mềm bảng tính không chứng minh rằng các phép đo điện trong đó sẽ được diễn giải chính xác.

Hướng dẫn này đề cập đến thỏa thuận giữa một hệ thống xuất dữ liệu bên ngoài và một hệ thống nhập dữ liệu. Hướng dẫn không quy định chức năng CSV tích hợp sẵn cho bất kỳ công tơ nào. Trong một hệ thống lắp đặt công nghiệp, các phép đo có thể đi qua cổng kết nối, ứng dụng giám sát hoặc dịch vụ báo cáo trước khi tệp CSV được tạo ra.

Phân biệt cú pháp tệp với ý nghĩa của phép đo

CSV mô tả cách sắp xếp văn bản, chứ không thể hiện đầy đủ ý nghĩa kỹ thuật của nội dung bên trong. RFC 4180 quy định các quy ước CSV phổ biến, bao gồm bản ghi, trường dữ liệu và cách đặt dấu ngoặc kép. Đây là tài liệu mang tính thông tin; nó không xác định mã định danh công tơ, chiều năng lượng, mã chất lượng dữ liệu hoặc ranh giới thời gian của bạn. Hai tệp có thể tuân theo cùng một quy ước đặt dấu ngoặc kép nhưng lại biểu diễn những phép đo hoàn toàn khác nhau.

The Mô hình dữ liệu dạng bảng của W3C cung cấp sự phân biệt hữu ích giữa các giá trị dạng bảng và siêu dữ liệu giúp mô tả hoặc xác thực các giá trị đó. Hãy sử dụng sự phân biệt này khi xây dựng quy định trao đổi dữ liệu của riêng bạn. Cần ghi rõ cả cách một giá trị được biểu diễn và những kết luận mà hệ thống tiếp nhận được phép rút ra từ giá trị đó.

Ví dụ, một cột có tên energy có thể biểu thị chỉ số tích lũy của thanh ghi hoặc lượng điện năng tiêu thụ trong một khoảng thời gian. Đổi tên cột ít ảnh hưởng hơn so với việc thay đổi ý nghĩa của nó mà không có hợp đồng mới. Hãy nêu rõ ranh giới đo lường, chiều năng lượng và đơn vị. Nếu không, hệ thống nhập dữ liệu có thể tạo ra một biểu đồ có vẻ hợp lý nhưng lại dựa trên đại lượng không chính xác.

Xác định hợp đồng trước khi xử lý các hàng dữ liệu

Gán một mã định danh ổn định cho định dạng và một số hiệu chỉnh sửa được kiểm soát cho cách diễn giải dữ liệu. Ghi lại vị trí mà hệ thống tiếp nhận lấy các thông tin này: bản ghi siêu dữ liệu đi kèm, cấu trúc bao bọc tệp đã được thống nhất hoặc một cột được chỉ định rõ ràng. Chỉ sử dụng tên tệp làm căn cứ khi quy trình tiếp nhận xác thực tên đó và duy trì mối liên kết tương ứng trong suốt quá trình xử lý.

Không suy đoán phiên bản hiệu chỉnh dựa trên số lượng cột. Các phiên bản hiệu chỉnh khác nhau có thể có cùng số lượng trường. Tương tự, không phỏng đoán dựa trên ngày gần đây trong tên tệp. Ngày đó có thể biểu thị thời điểm trích xuất dữ liệu thay vì phiên bản theo đó dữ liệu được tạo ra.

Hãy tách biệt phiên bản phần mềm xuất dữ liệu với phiên bản hợp đồng trao đổi dữ liệu. Một bản vá phần mềm có thể không làm thay đổi tệp; một điều chỉnh cấu hình có thể làm thay đổi ý nghĩa của trường dữ liệu mà không cập nhật tệp thực thi. Hợp đồng phải mô tả nội dung trao đổi thực tế, trong khi một bản ghi nguồn gốc riêng biệt xác định thành phần đã tạo ra dữ liệu đó.

Xây dựng thỏa thuận tối thiểu về các trường dữ liệu

Tạo một tài liệu ngắn có kiểm soát mà một kỹ sư khác có thể sử dụng mà không cần hỏi tác giả ban đầu. Đối với mỗi trường dữ liệu, hãy ghi lại tên ổn định, ý nghĩa, kiểu dữ liệu, trạng thái rỗng được phép và quy tắc xác thực. Bao gồm các ví dụ làm rõ những điểm mơ hồ thay vì chỉ đưa ra những ví dụ đơn giản nhất.

Đây là các bước kiểm tra thiết kế của dự án, không phải thông số kỹ thuật chung cho mọi loại công tơ. Cú pháp và các tham chiếu siêu dữ liệu nêu trên giúp phân biệt các trường hợp; các giá trị thực tế được phép sử dụng phải căn cứ vào tài liệu lắp đặt và ứng dụng tiếp nhận đã được lập thành văn bản của bạn.

Phân loại thay đổi dựa trên tác động của chúng đối với hệ thống tiếp nhận

Một trường tùy chọn bổ sung có thể tương thích với bộ nhận biết chọn các cột đã biết theo tên và cố ý bỏ qua các phần mở rộng đã được phê duyệt. Nó có thể làm hỏng bộ nhận biết mong đợi một bố cục chính xác theo vị trí. Do đó, tùy chọn không tự động có nghĩa là an toàn. Tính tương thích là một đặc tính của cặp nhà sản xuất và người tiêu dùng đã được tài liệu hóa.

Việc loại bỏ một trường bắt buộc, thay đổi đơn vị, đảo ngược hướng năng lượng hoặc thay đổi giới hạn khoảng thời gian thường yêu cầu công việc di chuyển rõ ràng. Xử lý ý nghĩa của mã chất lượng đã thay đổi cũng cẩn thận như thay đổi một trường số. Số có thể vẫn giữ nguyên trong khi cách sử dụng được phép của nó thay đổi.

Thứ tự lại cột xứng đáng có bài kiểm tra riêng. Nếu hợp đồng hứa hẹn ánh xạ dựa trên tên, xác minh rằng bộ nhận biết tôn trọng lời hứa đó. Nếu trao đổi theo vị trí, từ chối một chuỗi không mong đợi. Không bao giờ dựa vào người nào đó nhận thấy tiêu đề bảng tính đã di chuyển.

Xây dựng một bộ kiểm tra nhỏ nhưng có chủ đích

Giữ một tệp đã được phê duyệt cho mỗi phiên bản hỗ trợ và một bộ các ví dụ bị từ chối có chủ đích riêng biệt. Bao gồm dấu phẩy trong trích dẫn, một trường trống, một định danh tài sản không rõ, một mã chất lượng không được hỗ trợ và một dấu thời gian kiểm tra theo quy ước thời gian đã chọn. Ghi nhãn các dữ liệu thử nghiệm sáng tạo là dữ liệu thử nghiệm và giữ chúng xa khỏi quá trình nhập dữ liệu sản xuất.

Đối với một thay đổi đơn vị, chọn một ví dụ tổng hợp mà hiểu sai rõ ràng. So sánh số lượng dự kiến được giải thích với đầu ra của bộ nhận biết thực tế, không chỉ là thông điệp thành công nhập khẩu. Một bài kiểm tra chỉ chứng minh rằng một tệp đã được chấp nhận không nói lên điều gì về việc các phép đo của nó có được bảo tồn hay không.

Cũng kiểm tra giới hạn chuyển tiếp. Một lô có thể chứa các tệp được tạo ra trước và sau khi thay đổi. Quyết định xem cả hai phiên bản có thể tồn tại cùng nhau hay không, chúng có sử dụng hàng đợi riêng biệt hay không, và cách xử lý các tệp lịch sử đã được chỉnh sửa. Lưu trữ quyết định cùng bằng chứng kiểm tra để sau này việc nhập lại không dựa vào trí nhớ.

Một ví dụ di chuyển thực tế

Giả sử dịch vụ báo cáo bên ngoài hiện gửi năng lượng tích lũy và một cập nhật dự kiến thêm năng lượng theo khoảng. Giữ nguyên ý nghĩa của trường tích lũy và đặt tên riêng cho lượng bổ sung. Xác định đơn vị, khoảng thời gian, giới hạn dấu thời gian và hành vi xử lý dữ liệu thiếu trước khi ai đó cập nhật báo cáo nhận.

Chạy một mẫu đã được phê duyệt qua bộ nhận không sản xuất. Kiểm tra xem hiển thị tích lũy hiện tại có giữ nguyên hay không và chuỗi khoảng mới có được tính hoặc lưu theo hợp đồng hay không. Sau đó gửi một mẫu bị gán nhãn sai cố ý và xác nhận rằng trình nhập khẩu từ chối nó kèm giải thích hữu ích.

Nếu cập nhật đề xuất thay thế trường gốc thay vì thêm một trường mới, không sử dụng lại định danh hợp đồng cũ. Chuẩn bị một bản đồ di chuyển và quyết định các đầu ra lịch sử cần có dấu phiên bản. Ví dụ này mô tả thiết kế trao đổi; nó không thiết lập một tính năng xuất khẩu, xếp hạng độ chính xác hoặc phê duyệt hóa đơn cho một công cụ cụ thể.

Bảo vệ bằng chứng gốc trong quá trình từ chối

Một tập tin bị từ chối nên vẫn còn khả dụng tại một vị trí chứng cứ được kiểm soát, cùng với lý do, phiên bản phần mềm nhận và mã hợp đồng đã thử. Giữ nguyên các byte đã nhận. Nếu cung cấp một tập tin đã chỉnh sửa, hãy đặt nó thành một phiên bản khác biệt và ghi lại những gì nó thay thế thay vì ghi đè lên tập tin bị từ chối ban đầu.

Người nhận nên phân biệt lỗi cú pháp với lỗi hợp đồng và lỗi xác nhận kỹ thuật. Một trích dẫn không phù hợp khác với một đơn vị không được hỗ trợ, và cả hai khác với một phép đo không hợp lý. Các lý do phân biệt giúp người đúng giải quyết vấn đề mà không cần sửa đổi liên tục một tập tin nguồn hợp lệ.

Đối với các điều khiển liên quan, sử dụng hướng dẫn toàn vẹn tập tin xuất khẩu đồng hồ để bảo vệ các tập tin đã nhận và hướng dẫn tiêu đề CSV và mã hóa để xử lý diễn giải văn bản. Những kiểm tra này bổ sung cho hợp đồng phiên bản; không cái nào thiết lập khả năng tương thích về mặt ngữ nghĩa một mình.

Chỉ định quyền phê duyệt và vận hành

Đặt tên chủ sở hữu của cấu hình bộ đếm, quy tắc nhập khẩu nhận và diễn giải điện. Một người có thể đảm nhận nhiều vai trò, nhưng hồ sơ phê duyệt vẫn cần trả lời từng câu hỏi. Một chuyên gia dữ liệu có thể xác nhận kiểu trường mà không cần được ủy quyền phê duyệt thay đổi giới hạn đo lường.

Đặt ngày chuyển đổi và điểm quyết định quay lại. Ghi lại những gì xảy ra với các tập tin đang chờ trong hàng đợi trong quá trình thay đổi. Nếu người nhận được hoàn nguyên, xác định xem các tập tin mới hơn có còn trong vùng cách ly hay cần chuyển đổi được xác nhận riêng biệt. Không bao giờ diễn giải lại chúng một cách im lặng theo hợp đồng cũ vì phần mềm cũ tình cờ chấp nhận hình dạng của chúng.

Việc bàn giao hỗ trợ nên bao gồm hợp đồng đã được phê duyệt, các tập tin mẫu, kết quả mong đợi, các thông báo từ chối đã biết và ma trận khả năng tương thích hiện tại. Điều này giúp các thay đổi trong tương lai dễ kiểm thử hơn và giảm khả năng một nhà tích hợp thay thế đảo ngược kỹ thuật định dạng từ một tập tin thuận tiện.

Liên kết trao đổi với bộ đếm đã lắp đặt thực tế

Bắt đầu với thiết bị chính xác và các cài đặt đã được ghi chép. The Trang sản phẩm thiết bị đa chức năng BY194 là tham chiếu sản phẩm cho bài viết này. Xác nhận chính xác biến thể đặt hàng và các phép đo có sẵn riêng biệt; một bức ảnh sản phẩm không thể xác định định dạng xuất khẩu, chức năng cổng hoặc khả năng lưu trữ.

Sử dụng Tổng quan về đồng hồ điện ba pha để xác định ngữ cảnh đo lường, sau đó theo dõi từng trường bên ngoài qua bản đồ điểm đã được phê duyệt. Một hợp đồng CSV viết tốt không thể sửa chữa tỷ lệ biến áp dòng điện sai hoặc diễn giải đồng hồ không phù hợp phía trên.

Bài học Computerphile sau đây giải thích về các điều kiện đua trong các quá trình chia sẻ. Đây là nền tảng khái niệm để phối hợp các thay đổi của nhà sản xuất và người tiêu dùng, không phải là thủ tục cấu hình cụ thể của đồng hồ hoặc thay thế cho các bài kiểm tra được mô tả ở đây.

Xem bài học hướng dẫn

Các câu hỏi thường gặp

Liệu một cột tùy chọn mới có luôn yêu cầu sửa đổi hợp đồng mới không?

Ghi lại sự thay đổi theo chính sách kiểm soát phiên bản của bạn ngay cả khi nó tương thích ngược. Khả năng chấp nhận cột của người nhận phụ thuộc vào ánh xạ và hành vi xác thực đã được tài liệu hóa của nó. Xác minh hành vi đó bằng một thử nghiệm thực tế thay vì giả định rằng mọi trình nhập khẩu đều bỏ qua các trường bổ sung một cách an toàn.

Hệ thống nhận dữ liệu có thể tự động nhận diện một phiên bản CSV không xác định hay không?

Việc tự động phỏng đoán có nguy cơ gán sai ý nghĩa cho những con số trông có vẻ hợp lệ. Hãy cách ly phiên bản không xác định và báo cáo các bằng chứng cần thiết để xem xét. Việc chuyển đổi có thể được phê duyệt sau đó, nhưng phải được thực hiện một cách rõ ràng, được kiểm thử và có thể truy xuất nguồn gốc về tệp ban đầu.

Chỉ sử dụng mã kiểm tra (checksum) có đủ để chứng minh tính tương thích không?

Mã kiểm tra tổng (checksum) giúp phát hiện sự thay đổi về byte so với một tham chiếu đáng tin cậy. Tuy nhiên, nó không mô tả ý nghĩa của các trường dữ liệu, đơn vị đo lường hoặc việc bên nhận có hỗ trợ định dạng đó hay không. Hãy lưu giữ bằng chứng về tính toàn vẹn và xác thực hợp đồng dữ liệu như hai bước riêng biệt.

Các tệp lịch sử có nên được ghi đè khi hợp đồng thay đổi không?

Bảo toàn bằng chứng gốc và mối liên kết của bằng chứng đó với hợp đồng ban đầu. Nếu cần tạo bản sao đã chuẩn hóa, hãy ghi lại quá trình chuyển đổi, phiên bản và mối quan hệ với nguồn dữ liệu. Rà soát các nghĩa vụ về lưu trữ và báo cáo trước khi quyết định liệu có cần tạo lại bất kỳ kết quả dẫn xuất nào trong quá khứ hay không.