Массовый импорт КЕ

Массовый импорт рассчитан на заливку больших объёмов — до миллиона КЕ за один файл. Он работает рядом с обычным импортом из диалога реестра КЕ и не заменяет его: небольшие файлы по-прежнему удобнее загружать оттуда.

Расположение в системе: В левом боковом меню перейдите по пути: Главная → Настройки → СРМ → Массовый импорт КЕ.

Как это работает

1. Приём. Файл передаётся потоком и по мере поступления раскладывается в промежуточные таблицы. Он нигде не сохраняется целиком, поэтому ограничения на размер нет. Ответ приходит после того, как файл принят и разобран: в нём уже видно, сколько строк принято.
2. Проверка. Значения приводятся к типу атрибута и проверяются по его json-схеме. Строки с ошибками отсеиваются и попадают в отчёт, остальные идут дальше.
3. Порядок (только для графа). Композиционные связи раскладываются по уровням: сначала создаются КЕ-владельцы, затем их части. Порядок узлов в файле значения не имеет.
4. Идентификация. Для каждой строки проверяется, нет ли в БДКЕ совпадающей КЕ — по тем же правилам идентификации, что и при создании КЕ вручную.
5. Запись. КЕ создаются пакетно, имена формируются по правилам наименования их ТКЕ. Затем обрабатываются записи, помеченные на удаление, и создаются остальные связи графа.
6. Завершение. Исход каждой записи складывается в результат, по которому отдающая система забирает идентификаторы КЕ.

Задания выполняются по одному: пока идёт импорт, следующее ждёт в очереди со статусом «В очереди». Это защищает от дублей, которые появились бы, если бы два файла по одному ТКЕ заливались одновременно.

Форматы файлов

Формат файла проверяется дважды: диалог не даёт выбрать файл не того расширения и заглядывает в его начало, а сервис отказывается от него на первом же блоке приёма. Для плоского списка берётся только CSV, для графа — только JSON; у плоского списка хотя бы одна колонка заголовка должна быть атрибутом выбранного ТКЕ — кроме файла из одних колонок ci_id и ci_deleted, которым КЕ удаляют по идентификатору. Файл, который этому не отвечает, не импортируется, а задание получает статус «Отклонено» с причиной.

Плоский список (CSV)

Файл описывает КЕ одного типа, тип выбирается в диалоге импорта. Первая строка — заголовок с именами атрибутов. Две колонки служебные и атрибутами не считаются:

Колонка	Назначение
ci_id	Идентификатор создаваемой КЕ. Если не задан, назначается автоматически.
composed_of_ci_id	Идентификатор композирующей КЕ — она должна уже существовать в БДКЕ.

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

Если КЕ с указанным ci_id уже есть в БДКЕ, строка не отклоняется, а сливается с этой КЕ по выбранному действию при совпадении — так же, как с совпадением, найденным по правилам идентификации. Правила при этом сильнее: указанная КЕ берётся только тогда, когда они ничего не нашли. Строка отклоняется в двух случаях: КЕ с этим идентификатором другого ТКЕ либо композирована не в ту КЕ, что указана в строке — перевешивать КЕ на другого владельца импорт не умеет.

ci_id,name,composed_of_ci_id
,SRV-APP-01,1f4c9d02-8e31-4a7b-b0c5-77e2d1a29ab2

Граф (JSON)

Формат тот же, что у экспорта графа: объект с массивами nodes и links. Узел ссылается на уже существующую КЕ, если вместо атрибутов у него указано поле existing_ci_id — такой узел сам ничего не импортирует и нужен только для того, чтобы привязать граф к тому, что уже есть в БДКЕ.

{
  "nodes": [
    {
      "relative_id": "c1d90f88-9231-43b8-846b-4fbb67e26891",
      "ci_type_name": "server",
      "attribute_values": [{ "attribute_name": "name", "value": "SRV-APP-01" }]
    },
    {
      "relative_id": "c1d90f88-9231-43b8-846b-4fbb67e26892",
      "existing_ci_id": "1f4c9d02-8e31-4a7b-b0c5-77e2d1a29ab2"
    },
    {
      "relative_id": "c1d90f88-9231-43b8-846b-4fbb67e26893",
      "ci_type_name": "server",
      "ci_deleted": true,
      "attribute_values": [{ "attribute_name": "name", "value": "SRV-APP-02" }]
    }
  ],
  "links": [
    {
      "relative_src_id": "c1d90f88-9231-43b8-846b-4fbb67e26892",
      "relative_dst_id": "c1d90f88-9231-43b8-846b-4fbb67e26891",
      "link_name": "composition"
    }
  ]
}

Совпадения с существующими КЕ

Действие при совпадении выбирается один раз на всё задание:

• Слить с существующей — значения из файла записываются в найденную КЕ, новая не создаётся. Поведение по умолчанию, при нём повторная заливка того же файла не плодит дубли. Строка, все значения которой уже совпадают со значениями найденной КЕ, ничего не меняет: такие строки считаются отдельно — «Без изменений» — и в отчёт не попадают. Если строка совпала сразу с несколькими КЕ (по разным правилам идентификации), значения сливаются в самую раннюю из них, а остальные помечаются удалёнными как дубли, их связи переносятся на неё. Каждая такая КЕ есть в отчёте отдельной строкой.
• Пропустить строку — существующая КЕ не меняется, строка отмечается как пропущенная.
• Считать ошибкой — строка не импортируется и попадает в отчёт.

По тем же правилам объединяются строки, совпавшие между собой внутри одного файла.

к сведению

Импорт создаёт и обновляет КЕ, а удаляет только те, которые файл помечает признаком ci_deleted. КЕ, которых в файле нет, он не трогает: режима полной синхронизации у механизма нет.

Удаление КЕ записями файла

Запись файла может не импортировать КЕ, а удалять её. В CSV для этого служит колонка ci_deleted, в графе — одноимённое поле узла; значением считается true/1 или false/0, пустое значение — то же, что false.

КЕ такой записи находится так же, как и совпадение при обычном импорте: по правилам идентификации, а если правила ничего не нашли — по идентификатору, который назвал сам файл (ci_id в CSV, existing_ci_id в графе). Правила сильнее: указанный идентификатор берётся только там, где они не сработали. Из значений записи разбираются только те, что участвуют в идентификации: удаление ничего не записывает, и ошибка в неключевом значении его не отменяет. Если идентифицировать запись нечем — не заполнены ни ключевые значения, ни идентификатор, — запись попадает в отчёт с ошибкой.

Найденная КЕ помечается удалённой, вместе со своими составными частями — тем же каскадом по композиции, каким работает удаление КЕ из реестра. Физически КЕ удаляется позже, по сроку хранения своего ТКЕ. Связи удалённой КЕ остаются: они уходят вместе с ней, когда она удаляется физически.

Удаление идемпотентно и независимо от остального пакета:

• КЕ не нашлась — это не ошибка, а исход «Не найдено»: запись справочника, которой в БДКЕ нет, просто пропускается, и повторная присылка того же пакета проходит так же;
• КЕ уже помечена удалённой — ничего не происходит, срок хранения не начинается заново, исход записи всё равно «Удалено»;
• совпало несколько КЕ — помечаются все, и по каждой в отчёте есть своя строка.

Записи на удаление обрабатываются после создания и слияния, уровнями композиции сверху вниз. Поэтому пакет, который одну и ту же запись и создаёт, и удаляет, заканчивается удалением, а части, созданные этим же пакетом, каскад заберёт вместе с их владельцем. Файл может состоять только из колонок ci_id и ci_deleted — колонки атрибутов в таком файле не нужны.

Обычные колонки заголовка в файле на удаление разрешены и игнорируются, поэтому один и тот же пакет может и импортировать, и удалять записи.

Запуск импорта

Для доступа к странице требуется функция СРМ → Импорт → КЕ (srm.ci.@import). Она разрешает читать задания, отчёты и результаты, выгружать их в CSV, запускать и отменять импорт, а также скачивать шаблон CSV. Без неё пункт скрыт в навигации, страница по прямой ссылке недоступна, а сервер отклоняет запросы массового импорта. Отдельного режима только для чтения нет.

Страница разделена на две части: слева список заданий, справа выбранное задание с отчётом. Границу между ними можно перетащить, ширина запоминается.

1. Нажмите кнопку «Новый импорт» в заголовке страницы.
2. Выберите тип импорта: «Плоский список (CSV)» или «Граф (JSON)». Для плоского списка выберите ТКЕ, для графа это поле недоступно — типы берутся из узлов файла.
3. Выберите файл и действие при совпадении с существующей КЕ.
4. Нажмите «Начать импорт». Файл передаётся потоком, поэтому окно нужно держать открытым до конца приёма. Когда файл принят, окно закрывается, а задание открывается на странице.

Заготовку файла для плоского списка можно получить кнопкой «Скачать шаблон CSV»: выберите ТКЕ и нажмите «Скачать». В шаблоне есть колонка ci_id и колонки атрибутов ТКЕ. Колонок composed_of_ci_id и ci_deleted в нём нет: для ТКЕ, входящих в композицию, и для удаления записей их нужно добавить самостоятельно.

Список заданий

Задания идут от новых к старым и разделены по дням. Над списком — пресеты и поиск по имени файла:

• «Все» — все задания;
• «Активные» — файл ещё принимается, задание ждёт в очереди или выполняется;
• «С ошибками» — задания, завершённые с ошибками, прерванные, отклонённые и с оборванным приёмом. Отменённые задания сюда не попадают: отмена — действие пользователя, а не сбой;
• «Мои» — задания, запущенные вами.

Пресеты и поиск отбирают задания среди всех, а не только среди уже загруженных. Следующие задания подгружаются при прокрутке списка.

Каждое задание показано в три строки. В первой — имя файла, статус и время запуска, во второй — ТКЕ (для графа — «Граф»), формат, кто запустил и сколько длится задание. Третья зависит от статуса:

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

Щелчок по заданию открывает его справа. Выбранное задание, пресет и строка поиска сохраняются в адресе страницы, поэтому ссылка открывает тот же вид. Если задание не выбрано, открывается выполняющееся или ожидающее, а если таких нет — самое новое.

Ход процесса и отчёт

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

Счётчики по записям не пересекаются: запись файла попадает ровно в один из них, а их сумма равна числу строк в файле — включая записи, которые не удалось разобрать. Проблемы по связям графа считаются отдельно, потому что связь записью файла не считается: своей строки в результате у неё нет.

По завершении задания приходит оповещение: в нём имя файла, сколько строк было в файле, сколько КЕ создано, слито, осталось без изменений и пропущено, сколько удалено и не найдено, сколько ошибок, а у отклонённого или прерванного задания — причина. Оповещение приходит на любой исход, в том числе на отмену и на файл, отклонённый при приёме.

Под карточкой — таблица проблемных строк: ссылка на запись файла, статус, этап, КЕ в БДКЕ и сообщение.

Первая колонка называет запись так, как её ищут в файле. У CSV это «Строка файла» — номер строки, как его показывает редактор: заголовок — строка 1, пустые строки и переводы строк внутри значений в кавычках тоже считаются. У графа это «Элемент» — «узел N» или «связь N»: узлы и связи нумеруются с единицы, каждые в своём массиве.

У плоского списка рядом стоит колонка «Запись» — сквозной номер записи, тот же, что в результате. В графе он совпадает с номером элемента, поэтому там колонки нет.

Колонка «КЕ в БДКЕ» показывает КЕ, о которой запись: с которой совпала строка, которую слияние пометило удалённой как дубль, которую создала совпавшая строка того же файла, или на которую ссылается файл. Если совпадений несколько, у каждой КЕ своя запись отчёта — «(1 из 2)», «(2 из 2)», не больше десяти. Показывается текущее имя КЕ и её ТКЕ; щелчок по имени открывает карточку КЕ поверх отчёта. У КЕ, помеченной удалённой, имя остаётся, но карточка не открывается. Если КЕ нет в БДКЕ или у вас нет права на её чтение, вместо имени — идентификатор КЕ и пометка «не найдена» или «нет доступа».

Строка отчёта разворачивается в запись файла — так, как она пришла в файле:

• у CSV — значения, подписанные колонками заголовка, и сама строка; колонка, о которой сообщение, подсвечена, значение сверх заголовка подписано «лишнее значение»;
• у графа — объект с отступами, где подсвечен атрибут из сообщения, и переключатель «Как в файле», показывающий исходный текст; объект, который не удалось разобрать, показывается как есть.

Сохраняется не больше 8 КБ записи: у более длинной показано начало и её полный размер, остальное можно найти в файле по номеру строки или элемента. У заданий, выполненных до появления этой возможности, текста записи нет.

• «Ошибка» — строка не импортирована, причина указана в сообщении.
• «Конфликт» — строка совпала с существующей КЕ или с другой строкой файла и по выбранному действию слита или пропущена. Совпадения, которые ничего не поменяли, в отчёт не пишутся — их видно по счётчику «Без изменений».

Без сортировки строки идут в порядке файла, у графа — сначала узлы, затем связи. Отсортировать таблицу можно по номеру записи, статусу или этапу, строки с одинаковым значением остаются в порядке файла. Над таблицей переключатель «Все» / «Ошибки» / «Конфликты» и выбор этапа. Строки подгружаются при прокрутке; длинное сообщение в ячейке обрезано, целиком оно видно в подсказке при наведении.

Кнопка «Отчёт об ошибках» в карточке выгружает все проблемные строки задания одним файлом <имя исходного файла>_issues.csv с колонками:

Колонка	Содержимое
line или element	Запись файла: у CSV — номер строки, у графа — путь элемента для jq, нумерация с нуля: .nodes[16] — узел 17
level, stage	Статус и этап
ci_id, ci_name	КЕ в БДКЕ и её текущее имя; имя пустое, если КЕ нет или она вам недоступна
message	Сообщение
source	Текст записи файла

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

Обычный для большого файла исход — «Завершено с ошибками»: корректные строки записаны, а остальные перечислены в отчёте. Это не сбой импорта, а повод исправить перечисленные строки и догрузить их отдельным файлом.

Кнопка «Отменить импорт» видна, пока задание не завершено. Отмена срабатывает между пачками: уже созданные КЕ остаются в БДКЕ.

Результат по каждой записи

Отчёт перечисляет только проблемные записи. Результат — это все записи файла, по строке на каждую: что с записью стало и какая КЕ за ней стоит. Он нужен прежде всего внешним системам, поэтому на экране таблицей не показывается — его забирают кнопкой «Выгрузить результат» в карточке завершённого задания, файлом <имя исходного файла>_results.csv.

Записи нумеруются сквозным номером записи с единицы: в CSV это номер записи данных (заголовок и пустые строки его не получают, а запись, которую не удалось разобрать, — получает), в графе — номер элемента в массиве nodes. Пропусков в нумерации нет никогда, поэтому результат можно сопоставлять с исходными записями по порядку. Связи графа записями файла не считаются и в результат не попадают — их проблемы видны в отчёте.

Колонки файла: номер записи, строка файла, relative_id (идентификатор узла внутри файла; у CSV заполнен, только если файл сам назвал ci_id), ci_id, исход и текст ошибки. Исход — один из:

Исход	Что значит
CREATED	КЕ создана; её идентификатор — в результате
MERGED	Запись слита с существующей КЕ
UNCHANGED	Запись совпала с КЕ, которую не меняет: слияния не было
SKIPPED	Совпадение с существующей КЕ, пропущено по действию задания
REFERENCE	Узел-ссылка: сам ничего не импортирует, в результате — КЕ, на которую он ссылается
DELETED	Запись помечена на удаление, КЕ помечена удалённой
NOT_FOUND	Запись на удаление, которой в БДКЕ ничего не соответствует — это не ошибка
ERROR	Запись не импортирована; текст причины идёт вместе с результатом
NOT_PROCESSED	До записи не дошли: задание упало или было отменено

Идентификатор КЕ заполнен у CREATED, MERGED, UNCHANGED, DELETED и REFERENCE.

Результат снимается один раз при завершении задания — при любом исходе, включая отмену, сбой и задание, брошенное умершим обработчиком. Поэтому у выполняющегося задания результата ещё нет, а у завершённого он есть всегда. Хранится он столько же, сколько само задание, и удаляется вместе с ним. Внешние системы читают его постранично с отбором по исходу — см. Swagger.

Разрез по типам КЕ

Те же исходы можно посмотреть в разрезе ТКЕ: вкладка «По типам КЕ» в карточке задания, по строке на каждый тип, встретившийся в пакете, со счётчиками созданных, слитых, неизменённых, пропущенных, удалённых, ненайденных и ошибочных записей. Для плоского списка тип один на всё задание, а для графа это основной способ понять, по каким типам импорт прошёл, а по каким нет.

Тип берётся из самой записи, поэтому в разрезе видны и типы, которых в модели нет — именно у них и стоит смотреть число ошибок. Записи, тип которых неизвестен, собираются в строку «Тип не определён»: так выглядят неразобранные записи графа и узлы-ссылки. Сортировать разрез можно по имени типа. Как и результат, он считается при завершении задания.

к сведению

Задания, их отчёты и результаты хранятся ограниченное время и удаляются периодической задачей «Удаление устаревших заданий массового импорта КЕ» (clean_bulk_import_jobs), её расписание настраивается на странице Периодические задания. Срок хранения задаётся параметром SRM_BULK_IMPORT_KEEP_HOURS (по умолчанию 72 часа).

Ограничения

• Лимит КЕ по лицензии проверяется дважды. При приёме файла задание отклоняется, только если лимит уже исчерпан: число строк файла с лимитом не сравнивается, потому что слитые с существующими КЕ строки и узлы-ссылки графа новых КЕ не создают. Во время записи импорт ведёт счёт созданных КЕ и, если очередная пачка превысила бы лимит, останавливается со статусом «Ошибка». КЕ из уже записанных пачек остаются в БДКЕ, остальные строки не импортируются.
• Кодировка файла — только UTF-8.
• На время массового импорта пересчёт TQL для мониторинга приостанавливается и запускается один раз сразу после его завершения.