Изменения схемы данных CSV для счетчиков: контракт версии для безопасных импортов
Контракт схемы данных CSV для счетчика определяет, что означает каждый столбец, какие значения допустимы и какие версии импортера могут безопасно читать файл. Перед изменением экспорта согласуйте этот контракт с принимающей системой, протестируйте как совместимые, так и несовместимые примеры, и сделайте так, чтобы неизвестные версии выдавали явную ошибку. Успешное открытие файла в таблице не является доказательством того, что его электрические измерения будут интерпретированы правильно.
Это руководство охватывает соглашение между внешним экспортером данных и импортером. Оно не предписывает встроенную функцию CSV для какого-либо счетчика. Для промышленной установки измерения могут проходить через шлюз, управляющее приложение или отчетную службу до появления файла CSV.
Отделите синтаксис файла от значения измерения
CSV описывает текстовую структуру, а не полное инженерное значение его содержимого. RFC 4180 документирует общие соглашения по CSV, включая записи, поля и кавычки. Он носит информационный характер; он не определяет идентификаторы счетчика, направление энергии, коды качества или временные границы. Два файла могут следовать одному и тому же соглашению по кавычкам, при этом представляя совершенно разные измерения.
Земля Модель табличных данных W3C предоставляет полезное различие между табличными значениями и метаданными, которые помогают описывать или проверять их. Используйте это различие при указании собственного обмена. Документируйте как способ записи значения, так и то, что приемная система может из него вывести.
Например, столбец под названием энергия может представлять собой кумулятивный регистр или интервал потребления. Переименование его менее существенно, чем изменение этого значения без нового контракта. Ясно укажите границы измерения, направление и единицу измерения. Иначе импортёр может создать правдоподобную диаграмму по неправильному количеству.
Определите контракт перед обработкой строк
Назначьте стабильный идентификатор формату и контролируемую редакцию его интерпретации. Зафиксируйте, откуда принимающая система получает их: сопутствующая метаданные, согласованный файл-оболочка или явно указанный столбец. Имя файла само по себе подходит только в случае, если рабочий процесс принимает его и сохраняет связь на протяжении всей обработки.
Не делайте вывод о редакции по количеству столбцов. Разные редакции могут иметь одинаковое число полей. Аналогично, не делайте предположений по недавней дате в имени файла. Дата может указывать время извлечения, а не версию, под которой были произведены данные.
Держите версию программного обеспечения экспортера отдельно от версии контракта обмена. Обновление программного обеспечения может оставить файл без изменений; настройка конфигурации может изменить значение поля без обновления исполняемого файла. Контракт должен описывать фактический обмен, а отдельная запись о происхождении указывает, что его создало.
Запишите минимальное соглашение по полям
Создайте короткий управляемый документ, который второй инженер сможет использовать без обращения к оригинальному автору. Для каждого поля зафиксируйте его стабильное имя, значение, тип, допустимое пустое состояние и правило проверки. Включите примеры, раскрывающие неоднозначность, а не только показывающие самый простой случай.
| Пункт контракта | Запишите явно | Отвергайте или изолируйте, когда |
|---|---|---|
| Идентификатор счетчика | Идентификатор стабильного актива и утвержденное отображение | Идентификатор неизвестен или отображается на несколько активов |
| Количество | Физическая величина, направление и граница измерения | Значение отличается от утвержденного расчета |
| Unit and scale | Единица измерения, множитель и место применения | Масштабирование будет применено дважды или его невозможно установить |
| Время | Зона, интервал, соглашение и интерпретация временной метки | Временная метка не может быть однозначно назначена |
| Отсутствие показания | Разница между отсутствием, недопустимым значением и нулевым измерением | Пустое значение будет тихо интерпретировано как ноль |
| Качество | Разрешенные коды и обработка на следующем этапе | Новый код не имеет согласованной интерпретации |
| Версия | Поддерживаемые идентификаторы контрактов и правило перехода | Получатель не распознает версию |
Это проверки проектного дизайна, а не универсальные спецификации счетчика. Указанный выше синтаксис и метаданные поддерживают различие; фактические допустимые значения берутся из вашей документации по установке и принимающему приложению.
Классифицировать изменение по его влиянию на получателя
Дополнительное необязательное поле может быть совместимо с приемником, который выбирает известные столбцы по имени и намеренно игнорирует одобренные дополнительные. Это может нарушить работу приемника, ожидающего точную позиционную разметку. Поэтому необязательный не означает автоматически безопасный. Совместимость — это свойство пары производитель-потребитель, задокументированной в спецификации.
Удаление обязательного поля, изменение единицы измерения, изменение направления энергии или изменение границы интервала обычно требуют явных миграционных работ. Обращайтесь с изменением значения кода качества так же внимательно, как и с изменением числового поля. Число может остаться неизменным, при этом его допустимое использование изменится.
Переупорядочивание столбцов заслуживает отдельного теста. Если контракт обещает отображение по имени, убедитесь, что приемник выполняет это обещание. Если обмен происходит по позициям, отклоните неожиданные последовательности. Никогда не полагайтесь на то, что человек заметит, что заголовок таблицы переместился.
Создайте небольшой, но целенаправленный набор тестов
Храните один одобренный файл для каждой поддерживаемой версии и отдельный набор намеренно отклоненных примеров. Включайте кавычки с запятыми, пустое поле, неизвестный идентификатор актива, неподдерживаемый код качества и отметку времени, которая проверяет выбранную временную конвенцию. Обозначайте придуманные тестовые данные как тестовые и держите их отдельно от производственной загрузки.
Для изменения единицы измерения выберите синтетический пример, чье неправильное толкование очевидно. Сравните ожидаемое интерпретированное значение с фактическим выводом приемника, а не только сообщение об успешном импорте. Тест, который доказывает только, что файл был принят, ничего не говорит о сохранении измерений.
Также протестируйте границу перехода. Партия может содержать файлы, созданные до и после изменения. Решите, могут ли обе версии сосуществовать, используют ли они отдельные очереди, и как обрабатываются исправленные исторические файлы. Сохраните решение вместе с доказательствами теста, чтобы повторный импорт не полагался на память.
Практический пример миграции
Предположим, что внешняя отчетная служба в настоящее время отправляет кумулятивную энергию, а запланированное обновление добавляет энергию по интервалам. Сохраните смысл кумулятивного поля и дайте дополнительной величине отдельное имя. Укажите ее единицу измерения, длительность интервала, границу отметки времени и поведение при отсутствии данных до того, как кто-либо обновит отчет.
Запустите одобренный образец через не производственный приемник. Проверьте, что существующий дисплей кумулятивных данных остается без изменений и что новая серия интервалов рассчитывается или сохраняется в соответствии с контрактом. Затем отправьте намеренно неправильно маркированный образец и убедитесь, что импортёр отклоняет его с полезным объяснением.
Если предлагаемое обновление заменяет исходное поле, а не добавляет новое, не используйте старый идентификатор контракта. Подготовьте миграционную схему и решите, какие исторические выводы требуют маркера версии. Этот пример описывает дизайн обмена; он не устанавливает функцию экспорта, рейтинг точности или одобрение для конкретного инструмента.
Сохраняйте исходные доказательства при отклонении
Отклонённый файл должен оставаться доступным в контролируемом месте хранения доказательств, вместе с причиной, версией программного обеспечения для приёма и идентификатором попытки контракта. Сохраните полученные байты. Если предоставлен исправленный файл, присвойте ему отдельную редакцию и зафиксируйте, что он заменяет, а не перезаписывайте отклонённый оригинал.
Получатель должен различать синтаксические ошибки от ошибок контракта и ошибок инженерной проверки. Несовпадающая кавычка отличается от неподдерживаемой единицы измерения, и обе отличаются от неправдоподобного чтения. Разделённые причины помогают правильному человеку решить проблему без многократных изменений в валидном исходном файле.
Для связанных контролей используйте руководство по целостности экспортного файла счётчика для сохранения полученных файлов и руководство по заголовкам CSV и кодировке для решения вопросов интерпретации текста. Эти проверки дополняют контракт версии; ни один из них не устанавливает семантическую совместимость сам по себе.
Назначьте одобрение и операционное владение
Укажите владельца конфигурации экспортёра, правила приёма и электрическую интерпретацию. Один человек может выполнять несколько ролей, но запись об одобрении должна отвечать на каждый вопрос. Специалист по данным может проверить типы полей без права утверждать изменение границы измерения.
Установите дату перехода и точку принятия решения о возврате. Зафиксируйте, что происходит с файлами, ожидающими в очереди во время изменения. Если получатель возвращён, определите, остаются ли новые файлы в карантине или требуют отдельной валидированной конвертации. Никогда не интерпретируйте их молча под старым контрактом, потому что старое программное обеспечение случайно принимает их формат.
Передача поддержки должна включать одобренный контракт, образцы файлов, ожидаемые результаты, известные сообщения об отклонении и текущую матрицу совместимости. Это делает будущие изменения тестируемыми и снижает вероятность того, что заменяющий интегратор обратным проектированием восстановит формат из одного удобного файла.
Свяжите обмен с фактически установленным счётчиком
Начинайте с правильного устройства и его задокументированных настроек. Страница продукта многофункционального прибора BY194 является эталоном продукта для этой статьи. Подтвердите точный заказанный вариант и доступные измерения отдельно; фотография продукта не может установить экспортный формат, функцию шлюза или возможность архивации.
Используйте Обзор трёхфазного электросчётчика для контекста измерений, затем проследите каждое внешнее поле через утверждённое отображение точек. Хорошо написанный контракт CSV не может исправить неправильное соотношение трансформатора тока или несоответствие интерпретации регистра на верхнем уровне.
Следующий урок Computerphile объясняет условия гонки в совместных процессах. Это концептуальный фон для координации изменений производителя и потребителя, а не процедура конфигурации, специфичная для счётчика, или замена тестам, описанным здесь.
Часто задаваемые вопросы
Требует ли каждый новый необязательный столбец обязательного пересмотра версии контракта?
Регистрируйте изменения в соответствии с установленной политикой управления версиями, даже если они обратно совместимы. Возможность получателя принимать новый столбец зависит от документированного сопоставления полей и поведения при проверке данных. Проверяйте это поведение с помощью фактического тестирования, а не исходите из предположения, что каждый импортёр безопасно игнорирует дополнительные поля.
Может ли принимающая сторона автоматически определить неизвестную версию CSV-файла?
Автоматическое определение формата может привести к неверной интерпретации чисел, которые внешне выглядят корректными. Помещайте файлы с неизвестной версией в карантин и указывайте доказательства, необходимые для проверки. Преобразование может быть одобрено позднее, но оно должно быть явно заданным, протестированным и отслеживаемым до исходного файла.
Достаточно ли контрольной суммы, чтобы подтвердить совместимость?
Контрольная сумма помогает обнаружить изменение байтов относительно доверенного эталона. Однако она не описывает значение полей, единицы измерения или поддержку формата принимающей стороной. Сохраняйте подтверждения целостности данных и проверяйте контракт как отдельные этапы.
Следует ли переписывать исторические файлы при изменении контракта?
Сохраняйте оригинальные доказательства и их исходную связь с контрактом. Если требуется нормализованная копия, зафиксируйте её преобразование, версию и связь с исходным файлом. Перед принятием решения о необходимости повторной генерации любых исторических производных результатов ознакомьтесь с обязательствами по хранению и отчётности.