Групов импорт

Груповият импорт създава или обновява много потребители от един CSV файл. Той минава през две стъпки и нищо в Active Directory не се променя преди втората:

Качване и преглед. Vertex прочита файла, проверява всеки ред спрямо директорията и показва какво би направил всеки ред: create (създаване), update (обновяване) или invalid (невалиден, с причините).
Прилагане. Потвърждавате с парола (step-up); Vertex прилага валидните редове и пропуска невалидните. Файл с резултата изброява изхода от всеки ред.

Импортите изискват ролята Tenant admin и превключвателя за промени потребители.

Уеб интерфейсът е в разработка

Извикванията на API са дадени в скоби (Vertex API).

Файлът

Кодиране: UTF-8. Маркер за ред на байтовете (BOM, какъвто записва Excel) е допустим.
Разделител: ; или ,, разпознава се от заглавния ред (който се среща по-често там). Стойности, които съдържат разделителя, кавички или нови редове, се заграждат с ", както е обичайно в CSV.
Заглавен ред: задължителен, първият ред. Имената на колоните не зависят от главни и малки букви; редът им няма значение.
Редове: най-много 10 000 потребители на файл (заявката е най-много 5 MB). Празните редове се пропускат. Номерата на редовете броят заглавния ред като ред 1.
Стойностите се изчистват от интервали в началото и края, освен паролите, които запазват интервалите си.

Шаблонът (GET …/imports/template) показва често използваните колони:

sAMAccountName;password;givenName;sn;displayName;ou;mail;department;title;groups;enabled;mustChangePassword
ipetrov;Change-Me-2026!;Ivan;Petrov;Ivan Petrov;OU=Students,OU=School,DC=school,DC=local;[email protected];10A;Student;Students;true;true

Колони

Колона	Синоними	Значение
`sAMAccountName`	`sam`, `username`, `login`, `logon`	Името за вход. Задължителна. Тя идентифицира потребителя: редовете се свързват със съществуващите потребители по нея. Най-много 20 знака, без `" / \ [ ] : ; \| = , + * ? < > @`.
`password`		Паролата. По желание; вижте Стойности по подразбиране. Най-много 256 знака.
`ou`	`path`	DN на OU за нов потребител или към която да се премести съществуващ. Трябва да е управлявана OU или под нея.
`name`	`cn`	CN на нов потребител (най-много 64 знака). Не се използва за съществуващи потребители.
`givenName`	`firstName`	Собствено име.
`sn`	`surname`, `lastName`	Фамилия.
`displayName`		Показвано име.
`userPrincipalName`	`upn`	UPN (`name@suffix`).
`enabled`		`true`/`false` (вижте по-долу).
`mustChangePassword`	`changePasswordAtLogon`	Смяна на паролата при следващо влизане: `true`/`false`.
`groups`	`memberOf`	Групи, в които да бъде добавен потребителят, разделени с `;` (вижте Групи).
`email`		Записва се в `mail`.
често използвани атрибути		Могат да се използват с LDAP имената си: `mail`, `description`, `department`, `title`, `company`, `telephoneNumber`, `mobile`, `homePhone`, `ipPhone`, `physicalDeliveryOfficeName`, `employeeID`, `employeeNumber`, `employeeType`, `initials`, `streetAddress`, `l`, `st`, `postalCode`, `co`, `c`, `manager`, `info`, `wWWHomePage`, `homeDirectory`, `homeDrive`, `profilePath`.
`attr:<ldapName>`		Всеки друг атрибут с LDAP името си, например `attr:extensionAttribute1` или `attr:employeeType`. Двоичните стойности – като `b64:<base64>`. Атрибутите от забранения списък се отказват.

Име на колона, което Vertex не познава, спира качването (unknown_columns; използвайте attr:<ldapName> за други атрибути); същото важи за колона, която се среща два пъти (duplicate_column), липсваща колона sAMAccountName (missing_column) и забранена колона attr: (invalid_column).
Всяка колона с атрибут дава една стойност. Празна клетка оставя атрибута такъв, какъвто е.
Булеви стойности (enabled, mustChangePassword): true, yes, y, 1, on, да или false, no, n, 0, off, не (без значение от главните букви); празна клетка означава „не е зададено“.

Групи

Клетката groups изброява групи, разделени с ;. Всяка група може да е зададена с DN, име или име за вход (без значение от главните букви). Могат да се използват само групи под управляваните OU, които не са защитени; всяко друго име прави реда невалиден (unknown group …). Най-много 100 групи на ред.

Когато самият файл е разделен с ;, клетка с няколко групи трябва да е в кавички:

sAMAccountName;givenName;sn;groups
mivanova;Maria;Ivanova;"Students;Class 10A"

Групите само се добавят: импортът никога не премахва потребител от група.

Режими

Режим	Ново име за вход	Съществуващо име за вход
`create`	Създава се	Невалиден (a user with this logon name exists)
`update`	Невалиден (no user with this logon name)	Обновява се
`upsert`	Създава се	Обновява се

Съществуващ потребител извън управляваните OU или защитен прави реда си невалиден във всеки режим.

Стойности по подразбиране

Опциите на импорта попълват това, което файлът пропуска:

Опция	За	По подразбиране
OU по подразбиране (`default_ou`)	Нови потребители без `ou`	OU по подразбиране за потребители от настройките. Без нито една от двете редът е невалиден.
UPN суфикс (`upn_suffix`)	Нови потребители без `userPrincipalName`	UPN суфиксът от настройките: `<име за вход>@<суфикс>`.
Включен (`enabled`)	Нови потребители без стойност за `enabled`	Включен, когато е дадена парола, иначе изключен. При зададена опция потребителят е включен само ако опцията е включена и редът има парола.
Смяна на паролата (`must_change_password`)	Нови потребители без колоната	Да.

За нов потребител името (CN) е name, иначе „собствено име фамилия“, иначе името за вход. Стойност true за enabled без парола прави реда невалиден (an enabled new user needs a password).

Обновяване на съществуващ потребител:

атрибутите, UPN, собственото, фамилното и показваното име се записват само там, където се различават от директорията (ред без разлика завършва като unchanged);
password сменя паролата;
mustChangePassword и enabled се прилагат, когато са дадени;
ou, различна от тази на потребителя, го премества там;
groups добавя потребителя в групите, в които още не е;
name се пренебрегва (съществуващите потребители не се преименуват).

Преглед

Качете файла (POST …/imports с csv, filename, mode и options). Отговорът е валидираният импорт с броячите му: total, invalid, to_create и to_update. Редовете му (GET …/imports/{importID}/rows, с филтри по action и status) показват всеки ред така, както е прочетен, без паролата (has_password казва дали е дадена), действието му и проблемите му, например:

sAMAccountName is invalid, the same sAMAccountName as line 7;
ou … is outside the managed OUs, no ou (and no default OU);
userPrincipalName is invalid, name is invalid, password is too long;
unknown group Teachers;
attribute "info" value too long;
4 values for 3 columns.

Прегледът се проверява спрямо огледалото на Vertex; пуснете синхронизация първо, ако директорията е била променяна извън Vertex. Качването се записва в одитния журнал (directory.import.create).

Все още нищо не е записано. Поправете файла и го качете отново или отменете импорта (POST …/imports/{importID}/cancel), което го изхвърля заедно с паролите му.

Прилагане

Прилагането (POST …/imports/{importID}/commit със step_up_token) прилага валидните редове; невалидните редове се отбелязват като skipped. Импорт може да се приложи веднъж и само до 24 часа след качването (иначе import_not_validated).

Редовете се изпращат на конектора на партиди до 200 потребители (операции bulk.users), които се изпълняват една след друга. Всяка партида може да върви до един час.
Приложеният импорт е едно потвърдено действие: той не се брои към ограниченията на промените в минута. Собственият лимит на конектора обаче важи: всяка партида се брои като толкова записа, колкото реда има; стойността по подразбиране от 1000 записа в минута побира пълна партида (Локалната защита).
Всеки ред завършва като created, updated, unchanged, failed (с error_code и error, например password_policy или already_exists) или skipped. Един неуспешен ред не спира останалите.
Броячите на импорта (created, updated, unchanged, failed) растат, докато партидите приключват, а събитието vertex.import от потока на живо обявява всяка промяна. Когато не остане чакащ ред, импортът е completed или failed, ако всеки приложен ред е неуспешен.
Ако цяла партида е неуспешна (например защитата на конектора я откаже или тя изтече, преди конекторът да я изпълни), всички нейни редове се отбелязват като failed с кода на грешката на партидата.
Паролите се пазят криптирани, докато импортът не бъде приложен или отменен, предават се на конектора веднъж за всяка партида и никога не се показват отново.

Файл с резултата

GET …/imports/{importID}/result.csv връща всеки ред с изхода му. Той е разделен с ;, в UTF-8 с BOM (отваря се в Excel) и никога не съдържа пароли:

line;sAMAccountName;action;status;problems;error_code;error;objectGUID
2;ipetrov;create;created;;;;3f1c…
3;mivanova;update;unchanged;;;;9a0b…
4;gdimitrov;invalid;skipped;unknown group Teachers;;;

Клетки, които електронна таблица би прочела като формула (започващи с =, +, -, @), получават отпред '.

Ограничения

Ограничение	Стойност
Потребители на файл	10 000
Размер на заявката	5 MB
Потребители на партида на конектора	200
Групи на ред	100
Време за прилагане след качването	24 часа
Партида чака конектора най-много	6 часа
Партида се изпълнява най-много	1 час

Файлът​

Колони​

Групи​

Режими​

Стойности по подразбиране​

Преглед​

Прилагане​

Файл с резултата​

Ограничения​