Руководство пользователя

Модуль обеспечивает интеграцию с ФГИС «Национальная система пространственных данных» (далее НСПД) с целью выполнения требований Постановления Правительства РФ от 07.06.2022 г. № 1040 «О федеральной государственной информационной системе «Единая цифровая платформа «Национальная система пространственных данных».

Принцип работы аудита

Аудит объектов настраивается автоматически при первом запуске сервиса. При этом ему необходимы следующие настройки:

• Monitor.Projects – список проектов, необходимых для осуществления аудита для отправки сведений в НСПД;

• Monitor.PrimaryImport – список алиасов объектов, для которых нужно осуществить первичный импорт.

Порядок действий при разворачивании аудита:

1. Создайте схемы integration_nspd.

2. Создайте таблицы для хранения данных аудита и служебных данных по таблицам отслеживаемых объектов.

3. Заполните таблицы отслеживаемых объектов на основании сведений метаданных конкретного проекта.

4. Создайте триггерные функции.

5. Создайте триггеры для тех таблиц, для которых предусмотрен аудит.

6. Заполните сведения первичного импорта.

Первичный импорт

В качестве объектов для первичного импорта выбираются объекты, удовлетворяющие следующим критериям:

• относятся к указанному типу объектов;

• существующие (sys_status = 0);

• имеется действующая запись в таблице геометрий;

• отсутствуют ранее занесенные сведения в таблицу аудита.

Первичный импорт может быть регулируемым, т.к. список алиасов объектов выносится в настройки Monitor.PrimaryImport. Чтобы добавить новый вид объектов в список импорта, достаточно указать его алиас в списке первичного импорта. Тогда при перезапуске сервиса в таблицу аудита будет добавлена первичная выборка объектов этого типа.

Невозможно первично импортировать те объекты, алиасы которых отсутствуют в файле настроек переноса ObjectConvertRules.json. Это помогает избежать ошибок при заведении алиасов для первичного импорта.

Порядок и особенности добавления в аудит объектов

Объект попадает в аудит при следующих обстоятельствах:

• объект создан как карточка в системе;

• объекту присвоена геометрия;

• изменены атрибутивные свойства объекта (любые);

• изменена геометрия объекта;

• объект удален из системы;

• удалена геометрия объекта.

При этом действует следующая логика:

1. Объект создан – добавляется в таблицу с операцией INSERT.

2. Объект изменен / добавлена геометрия / изменена геометрия – добавляется в таблицу с операцией UPDATE.

3. Объект удален – добавляется в таблицу с операцией DELETE.

4. Удалена последняя действующая геометрия объекта – добавляется в таблицу с операцией DELETE.

5. Удалена геометрия объекта, но есть иная действующая – добавляется в таблицу с операцией UPDATE.

Так как данные любого объекта содержатся в двух таблицах (атрибутивная и пространственная), то триггеры отслеживания расставляются на каждую из них. В случае, когда какой-то объект удаляется из списка отслеживаемых, триггер с данных таблиц также пропадает, если не существует активного объекта из этой же таблицы.

Порядок удаления аудита

Чтобы удалить аудит из базы, достаточно выполнить следующие действия:

1. Очистить файл ObjectConvertRules.json (оставить пустой json).

2. Перезапустить сервис.

3. Удалить схему integration_nspd.

Так как при каждом перезапуске триггеры обновляются (удаляются и расставляются заново), то при очистке файла настроек триггеры будут удалены и не заведены заново. Таким образом, любое отслеживание данных проекта будет прекращено.

Важно

Список проектов должен быть непустым и актуальным для данного проекта.

Принцип переноса объектов из ГИСОГД в НСПД

Для переноса объекта из ГИСОГД в НСПД следует создать на стороне НСПД объект реестра и объект категории. Для объекта реестра заполняются соответствующие атрибуты реестра. После этого между объектом реестра и объектом категории устанавливается связь.

Получение данных, необходимых для переноса объекта из ГИСОГД в НСПД, на стороне ГИСОГД всегда сводится к получению информации об объекте по одному методу jet API GetFeature по соответствующему ID объекта в соответствующем проекте.

В получаемом объекте должны передаваться все необходимые на стороне НСПД поля и их значения, именованные согласно протоколу.

Для ссылочных полей именование полей, содержащих их текстовое представление, должно содержать в окончании «_знч».

Для справочных полей на текущий момент должно передаваться их числовое значение, заключённое в кавычки (возможно код), с аналогичным окончанием «_знч».

В целом тип передаваемых значений должен соответствовать типу, описанному в протоколе.

Примечание

Если передается значение в текстовом виде, а на стороне НСПД ожидается числовое значение, то при попытке обновления возникнет ошибка.

Feature, получаемая из jet API, отличается от Feature, передаваемой в НСПД, поэтому производится переформатирование объекта и приведение к виду, необходимому НПСД.

Для создания объекта категории всегда требуется знать подкатегорию, которая, согласно последнему сообщению со стороны НСПД, будет определяться на основе «Код объекта». Кроме того, нужно указать систему координат и externalKey (внешний ключ) в Properties.

Получение подкатегории

Поскольку конкретного описания получения подкатегории для объектов на текущий момент со стороны НСПД не предоставлено, то можно отталкиваться только от предположений.

Выбор соответствующей подкатегории для объекта будет осуществляться путем сопоставления текстового значения, указанного в настройках поля [subcategory_field] (чаще всего «Код объекта»), с возможными значениями (текстовыми) подкатегории соответствующего объекта НСПД. Если таковой не будет найден, то на текущий момент будет выбрана первая попавшаяся подкатегория, доступная в данной категории.

Описание операций переноса объектов из ГИСОГД в НСПД

В рамках сервиса взаимодействия ГИСОГД и НСПД реализовано четыре основных вида операций:

• INSERT – создание новой записи;

• UPDATE – обновление атрибутов реестра;

• UPDATE GEOMETRY – обновление геометрии объекта категории;

• DELETE – полное удаление объекта из НСПД.

Поскольку на стороне НСПД создание, обновление или удаление объектов может проходить в несколько стадий, возможно возникновение ошибок на одной из этих стадий.

Например, операция по созданию объекта НСПД включает четыре стадии:

• создание объекта реестра,

• заполнение объектов атрибута реестра,

• создание объекта категории,

• установка связи между объектом реестра и объектом категории.

Для возобновления той или иной операции в случае ошибки на конкретном шаге существует поле [send_stage]. Если операция прервется на одном из шагов, то в базу данных в поле [nspd_error] будет внесена соответствующая ошибка, а поле [send_stage] заполнится текущей стадией отправки. При этом date_process, являющийся «маркером» окончания обработки записи, не будет заполнена. При повторном цикле работы сервиса попытка обработать данную запись повторится с указанного шага. На данный момент поведение с использованием стадий актуально для операции INSERT.

В начале выполнения операции, отличной от INSERT, будет осуществлён поиск ранее успешно выполненной операции INSERT в целях получения всех необходимых данных:

• внешний ключ,

• ключ объекта реестра,

• ключ объекта категории.

Если не будет найдено ранее выполненной операции INSERT с заполненной датой обработки, то выполнится следующая логика в зависимости от текущей операции:

• Если для обрабатываемой записи выполняется операция UPDATE, UPDATE GEOMETRY и существует запись INSERT без даты отправки, то текущая запись будет пропущена до следующего цикла.

• Если для обрабатываемой записи выполняется операция UPDATE или UPDATE GEOMETRY и не существует запись INSERT, то операция для текущей записи будет изменена на INSERT.

• Если для обрабатываемой записи выполняется операция DELETE и не существует запись INSERT, то операция для текущей записи будет пропущена, date_process будет заполнен, а в поле с ошибкой попадет запись: «Не найдена ранее обработанная запись на создание по ключу ГИСОГД».

• Если для обрабатываемой записи выполняется операция DELETE и существует запись INSERT без даты отправки, то для текущей записи, записи на INSERT и всех записей на обновление во временном промежутке с момента создания записи INSERT до создания записи DELETE будет заполнена date_process, а в поле с ошибкой попадет соответствующая запись: «Для данной записи существует запись на удаление, добавленная до обработки текущей. Операция отменена».

Операция INSERT (значение INSERT в поле [operation])

Операция INSERT включает в себя четыре шага и четыре соответствующих API метода на стороне НСПД:

1. Создание объекта реестра в соответствующем реестре на основе файла настроек.

2. Заполнение всей атрибутивной информации объекта реестра на основе файла настроек.

3. Создание объекта геометрии в соответствующей категории с определением соответствующей подкатегории.

4. Связывание объекта геометрии и объекта реестра.

По завершении операции запись аудита INSERT получает:

• дату обработки (date_process);

• внешний ключ, формируемый по ключу, полученному из Jet API (external_key);

• ключ объекта реестра (category_obj_key),

• ключ объекта категории (register_object_key).

Операция UPDATE (значение UPDATE в поле [operation])

Во время операции будет вызван метод на стороне НСПД, который получает набор атрибутов объекта реестра посредством запроса объекта из jet Api и дальнейшего преобразования на основании файла настроек. В результате получается json объект, содержащий в себе набор id атрибутов объекта реестра и их значений.

Важно помнить, что система не разделяет, какой именно атрибут обновился. Это значит, что операция обновит все атрибуты по текущему состоянию.

Атрибуты обновляются списком, тогда как при создании записи отдельным запросом устанавливается значение для каждого передаваемого атрибута. Такая реализация обусловлена тем, что при первичной передаче вероятность передачи некорректных значений выше, чем при их последующем обновлении.

Операция UPDATE GEOMETRY (значение UPDATE в поле [operation] и установлен флаг в поле [geom_changed])

При вызове операции UPDATE GEOMETRY будет вызван всего один соответствующий метод на стороне НСПД, который принимает объект Feature Collection.

Важно помнить, что всегда передаем один Feature в Feature Collection. Объект Feature перед передачей подвергается преобразованиям, описанным выше.

Операция DELETE (значение DELETE в поле [operation])

При выполнении операции будет вызван метод удаления объекта реестра, который, судя по описанию API НСПД, должен удалить объект целиком, то есть объект категории, объект реестра и связи между ними.

На момент написания документации метод не работает как нужно на стороне НСПД. Это значит, что иногда операция завершается ошибкой.

В сервисе работы с API НСПД написаны методы, которые позволят выполнять операции поочерёдно, а именно удалять связи, удалять объекты категории и реестра. Но на текущий момент они не задействованы.

Описание стандартного набора таблицы аудита

• primary_key – guid для идентификации записи;

• gisogd_key – ключ записи, с которой должна совершаться операция;

• operation – операция, может принимать значения INSERT, UPDATE, DELETE;

• geom_changed – флаг, передающий информацию о том, что была совершена операция обновления с изменением геометрии;

• schema – поле, указывающее принадлежность записи к той или иной схеме;

• alias – алиас передаваемого объекта;

• external_key – ключ геометрии для созданного объекта категории на стороне НСПД (для дальнейшего поиска);

• category_obj_key – ключ созданного объекта категории;

• register_object_key – ключ созданного объекта реестра;

• date_insert – дата добавления записи;

• date_process – дата обработки той или иной записи;

• send_stage – стадия, на которой на текущий момент находится обработка записи;

• nspd_error – поле для хранения ошибки, возникшей в процессе обработки записи.

На стороне сервиса работы с НСПД организовано получение различного рода справочных значений с последующим сохранением их в файлы.

Так на текущий момент реализован метод, запрашивающий все доступные категории с доступными подкатегориями и последующим их сохранением в файл в соответствии с прописанными настройками, а также получение всех доступных реестров, их атрибутов с указанием ID и прочей информации, также сохраняемый в отдельный файл. Кроме того, реализовано получение всех доступных справочников, однако этот метод на данный момент не нашёл своего применения.

Файлы, содержащие детальную информацию об объектах категории и объектах реестра, требуются для того, чтобы в дальнейшем составить корректный файл настроек переноса. Поскольку, не зная текущие ID объектов реестра, ID атрибутов реестра и ID категорий и подкатегорий, перенос настроить невозможно.

Также файл с доступными категориями используется для определения подкатегории, которая должна передаваться при создании объекта категории.

Описание файла настроек переноса

Файл настроек переноса ObjectConvertRules содержит в себе информацию по переносу каждого объекта (по алиасу) в следующем виде:

• name – наименование объекта категории/реестра на стороне НСПД;

• category_id – id соответствующей категории;

• category_convert_rules – объект со свойствами (потенциально избыточно) в соответствии с протоколом (служит для передачи свойств объекта категории), где:

  • ключ: алиас из протокола;

  • значение: ключ из PROPERTIES Feature полученного из jet Api;

• subcategory_field – поле, по которому будет определяться значение подкатегории;

• register_id – id соответствующего реестра;

• register_convert_rules – набор правил переноса полей в атрибуты объекта реестра:

  • attribute_id – id соответствующего атрибута;

  • alias – алиас из протокола НСПД;

  • gisogd_key – ключ из PROPERTIES Feature, полученного из jet Api для получения конкретного значения;

  • nspd_key – соответсвующий ключ (название атрибута) в НСПД;

• gisogdType – алиас в ГИСОГД (потенциально избыточно);

• nspdType – алиас в соответствии с протоколом (потенциально избыточно).

Примечание

Вышеописанные настройки должны быть адаптированы под конкретную систему на основе настроенных объектов реестра, объектов категории и сведений ГИСОГД конкретного региона.

Поля, отмеченные фразой «потенциально избыточно», в будущем, возможно, будут удалены, т.к. не потребуются для определения тех или иных правил переноса. На момент написания данного руководства оптимизация данного файла настроек нерациональна, т.к. протоколы видоизменяются, а разработчики НСПД обещали изменить свое АПИ с целью ухода от «поиска по строкам» и использования Id в пользу использования стабильных алиасов.

Описание файла основных настроек

Файл основных настроек appsettings содержит в себе следующие поля:

• DbConnectionString – строка подключения к базе данных (используется для аудита);

• DbWorkerConfig – блок настроек для обработки записей аудита. Пока содержит одно поле [MaxCountRecordsToProcess], определяющее количество обрабатываемых записей за одну итерацию работы сервиса;

• NspdUrl – основной адрес АПИ НСПД;

• NspdAuthorizationService – блок настроек авторизационного сервиса НСПД:

  • Name;

  • TokenUrl;

  • ClientId;

  • ClientSecret;

  • UserName;

  • Password;

  • GrantType;

  • NumberOfAttemptsAuthorization (количество попыток авторизации);

  • PeriodBetweenAttempts (время между попытками);

• JetApiSettongs - блок настроек JetApi;

  • JetApiUrl - основной url запросов;

  • DefaultCrs - наименование системы координат (согласно протоколу);

  • ApiVersion - версия Api;

  • WFSVersion - версия WFS;

• JetApiAuthorizationService – блок настроек авторизационного сервиса JetApi(поля аналогичны настройкам НСПД);

• SettingsPath – путь сохранения настроек (в том числе файлов с доступными категориями, реестрами, справочниками);

• RulesFilePath – путь сохранения настроек (в том числе файлов с доступными категориями, реестрами, справочниками);

• Monitor – настройка сервиса мониторинга:

  • ServicePeriod – время повторного запуска сервиса (в минутах);

• Serilog – стандартный блок настроек логирования.

Для проверки созданной сервисом записи потребуются следующие методы коллекции для Postman

1. Метод получения геометрии по внешнему ключу. Для запроса потребуется изменить Id категории (берется из файла настроек) и внешний ключ (external_key – можно взять из базы) на ранее полученные.

2. Метод получения полной информации по объекту реестра. Для запроса потребуется Id реестра (берется из файла настроек), ключ объекта реестра (register_object_key – можно взять из базы), а также желаемые для отображения Id атрибутов реестра (берутся из файла настроек).