Универсальный соединитель CSV — техническое руководство (предварительная версия)

В этой статье описывается универсальный соединитель CSV (GCSV). Статья относится к следующим продуктам:

• агент подготовки Microsoft Entra Connect (ECMA2Host)
• Microsoft Identity Manager 2016 (MIM2016);

Для MIM 2016 соединитель доступен для скачивания в Центре загрузки Майкрософт.

Чтобы увидеть, как работает этот соединитель, см. раздел Универсальный соединитель SQL: пошаговое руководство.

Примечание

Служба подготовки Azure AD теперь предоставляет упрощенное решение на основе агента для подготовки пользователей в CSV-файлах без полного развертывания синхронизации MIM. Мы рекомендуем оценить, соответствует ли он вашим потребностям. Подробнее.

Обзор универсального соединителя CSV

Соединитель generic CSV (GCSV) позволяет интегрировать данные удостоверений пользователей и групп, хранящейся в CSV-файлах, с продуктами Майкрософт, такими как агент подготовки Microsoft Entra Connect (ECMA2Host) и Microsoft Identity Manager 2016 (MIM2016).

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

В этой статье описываются функции и функции универсального соединителя CSV, а также способы его настройки для MIM 2016.

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

Компонент	Сведения
Поддержка нескольких продуктов	Использование этого соединителя поддерживается в следующих продуктах Майкрософт: агент подготовки Microsoft Entra Connect (ECMA2Host) Microsoft Identity Manager 2016 (MIM2016);
Поддерживаемые CSV-файлы	Этот соединитель поддерживает управление пользователями (обязательно) и группами (необязательно) с помощью настройки до трех CSV-файлов: CSV-файл пользователей (например, Users.csv) CSV-файл групп (например, Groups.csv) CSV-файл участников группы (например, Members.csv)
Обработка до и после операции с помощью PowerShell	Этот соединитель поддерживает конфигурацию до четырех (4) скриптов PowerShell для упрощения предварительной или последующей обработки данных удостоверений пользователей и групп до или после импорта или экспорта.
Поддерживается кодировка CSV-файла	Соединитель поддерживает все типы кодирования сервера по умолчанию (или установленные): (например, Юникод, UTF-8, UTF-7, ASCII и т. д.).
Поддерживаемые типы данных полей CSV	Соединитель поддерживает следующие типы данных атрибутов: Binary — (в виде строк base64) Логическое значение — (true или false) Целые числа Строки / Многозначные строки Ссылка
Разделитель полей CSV	Поддержка запятых (,) или любого печатного буквенно-цифрового символа для указания начала и конца любого строкового значения.
Поддержка строковой квалификации	Поддержка двойных кавычек (") или любого печатаемого буквенно-цифрового символа для указания начала и конца любого строкового значения.
Поддержка многозначных строк	Поддержка многозначных строк
Поддерживаемые операции соединителя	Соединитель поддерживает следующие операции: полный импорт; Экспорт Полный экспорт
схема	Обнаружение схемы является динамическим, но для завершения требуется настройка вручную. Поля динамически идентифицируются на основе указанного разделителя (или называется разделителем значений). Типы данных полей назначаются вручную во время настройки.

Предварительные требования

Перед использованием соединителя убедитесь, что на сервере синхронизации есть следующее:

• Microsoft .NET 4.6.2 Framework или более поздней версии
• CSV-файлы, содержащие требуемую схему для следующих типов удостоверений:
  • Файл users (обязательно)
  • Группы (необязательно)
  • Участники группы (обязательно, если используются группы)
• (Необязательно) Скрипты PowerShell для управления предварительной и последующей обработкой для следующих типов операций:
  • Предварительный импорт — этот скрипт выполняется перед выполнением операции импорта.
  • После импорта — этот скрипт выполняется после выполнения операции импорта.
  • Предварительный экспорт — этот скрипт выполняется перед выполнением операции экспорта.
  • После экспорта — этот скрипт выполняется после выполнения операции экспорта.

Разрешения учетной записи службы синхронизации MIM

Важно!

Учетная запись службы синхронизации MIM 2016 — это контекст безопасности, который выполняет операции с файлами с CSV-файлами и выполняет скрипты PowerShell до и после обработки. Этой учетной записи службы требуются разрешения на чтение и запись для всех настроенных ФАЙЛОВ CSV и PowerShell. Ему также требуются соответствующие разрешения ExecutePolicy PowerShell для выполнения любых настроенных скриптов.

Создание нового соединителя

Ниже приведен общий обзор действий, описанных в этом руководстве. Для начала необходимо использовать учетную запись с ролью Администратор синхронизации MIM для выполнения следующих задач:

• Откройте окно Создание агента управления (MA) в Service Manager синхронизации MIM.
• Выберите универсальный соединитель CSV в качестве типа соединителя.
• Укажите путь к файлу и имя CSV-файла для импорта или экспорта.
• Укажите кодировку файла, разделитель значений, разделитель нескольких значений и квалификатор текста для CSV-файла.
• Укажите, следует ли использовать значения в первой строке в качестве полей заголовка.
• Выберите типы объектов и атрибуты для импорта или экспорта из CSV-файла.
• Настройте раздел, профиль запуска и сведения о сопоставлении для ma ma.
• Укажите пути к скриптам и параметры для сценариев PowerShell, если таковые есть.
• Запустите ma для выполнения операций импорта, синхронизации или экспорта.

Чтобы создать универсальный соединитель CSV, в разделе Служба синхронизации выберите Агент управления и Создать. Выберите универсальный соединитель CSV (Майкрософт).

Соединение

Страница Подключение содержит расположения CSV-файлов пользователей, групп и членов групп.

На следующем рисунке показан пример страницы "Подключение ".

На этой странице указаны расположения следующих CSV-файлов:

• Users File (Файл пользователей): полный путь к CSV-файлу, который содержит записи пользователей и их значения атрибутов. Этот файл необходим.
• Файл групп. Полный путь к CSV-файлу, который содержит записи группы. Этот файл является необязательным.
• Файл членов. Полный путь к CSV-файлу, который содержит ссылочные записи членов группы.

Важно!

Учетная запись службы синхронизации MIM должна иметь разрешения на чтение и запись для всех назначенных CSV-файлов. Как упоминалось ранее, файлы групп и членов не нужны, если настроены только пользователи.

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

Возможности

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

На следующем рисунке показан пример страницы "Возможности ".

В следующем разделе перечислены отдельные конфигурации и их значения.

• Стиль различающегося имени (LDAP). Соединитель GCSV использует синтаксис LDAP (протокол доступа к упрощенным каталогам), чтобы создать DN (различающееся имя) для уникальной идентификации каждого объекта User или Group в пространстве соединителя. Все значения DN выражаются в следующем формате: CN=[ANCHOR_VALUE],Object=[Пользователь|Group],O=CSV.
• Подтверждение объекта (обычный): обычно обработчик синхронизации предполагает, что может снова получить объект при последующем разностном импорте после экспорта. Так обычно работает подсистема синхронизации, но не все подключенные системы работают таким образом. Этот параметр "Обычный " гарантирует отсутствие exported-change-not-reimported предупреждений при последующем импорте.
• Тип экспорта (MultivaluedReferenceAttributeUpdate): тип экспорта указывает, как объекты форматируются и отправляются в целевую систему во время синхронизации. MultivaluedReferenceAttributeUpdate — это тип экспорта, предназначенный для работы с Microsoft Entra ID. Он отправляет только измененные атрибуты. Для атрибутов типа значения используется AttributeReplace, а для ссылочных атрибутов — AttributeUpdate.
• Нормализации (нет). Нормализации относятся к стандартизации данных в согласованном формате. Нет означает, что определенные правила нормализации не применяются. Данные остаются как есть без каких-либо дополнительных преобразований соединителем.

Схема 1 (конфигурации формата CSV-файла)

Соединитель GCSV использует три типа разделителей (или разделителей) для разделения и анализа полей CSV и их значений.

Эта страница содержит параметры символьного значения для этих разделителей и тип кодирования, который использовался для создания файла в формате CSV.

На следующем рисунке показана страница Схема 1 (конфигурации формата CSV-файла).

В следующем разделе приведен список отдельных конфигураций.

• Использование заголовков для обнаружения схемы. Если выбран этот параметр, соединителю предписывается обрабатывать первую запись каждого CSV-файла как запись заголовка, а не запись данных удостоверения. Если этот параметр не выбран, соединитель назначает имя Attribute с добавлением уникального добавочного целочисленного значения (например, Attribute1, Attribute2 и т. д.) и обрабатывает первую строку как запись данных удостоверения.
• Разделитель значений. Этот символ разделяет поля (т. е. значения) записей CSV. Запятая (,) является значением по умолчанию, но допускается любой буквенно-цифровой символ, который может быть напечатан.
• Разделитель с несколькими значениями. Этот тип разделителя используется для разделения отдельных значений строки с несколькими значениями (например, прокси-адресов) или ссылочных атрибутов (например, подчиненных). По умолчанию используется точка с запятой (;) но допускается любой печатный буквенно-цифровой символ.
• Текстовый квалификатор. Если строковое значение содержит символы, которые в противном случае будут интерпретироваться как разделители (например, запятые), необходимо, чтобы значение было квалифицировано, чтобы средство синтаксического анализа CSV правильно интерпретировать строку как одно поле. Двойные кавычки (") используются по умолчанию, но допускается любой буквенно-цифровой символ, который может быть напечатан.

Примечание

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

• Кодировка файлов. Этот параметр указывает кодировку, используемую в CSV-файлах, добавленных на вкладке Подключение. Убедитесь, что он соответствует кодировке CSV-файлов.

Примечание

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

Схема 2 (конфигурации полей идентификации и ссылок)

Значение привязки — это уникальный идентификатор записи в CSV-файле. Он отличает одну запись от других. Соединитель GCSV также использует это значение для создания различающегося имени (DN), которое идентифицирует связанный объект пространства соединителя.

На этой странице параметры атрибута привязки настраиваются для каждого CSV-файла, указанного на странице Подключение.

На следующем рисунке показан пример страницы Схема 2 (конфигурации полей удостоверений и ссылок).

В следующем разделе приведен список отдельных конфигураций на этой странице.

• Пользователь
  • Привязка пользователя: поле в файле Users, которое служит значением привязки для записи пользователя. По умолчанию выбрано первое поле заголовка в файле Users.
  • Тип атрибута привязки пользователя. Это тип атрибута выбранной привязки.
• Группа
  • Привязка группы: поле в файле Groups, которое служит значением привязки для записи группы. По умолчанию выбрано первое поле заголовка в файле Groups.
  • Тип атрибута привязки группы. Это тип атрибута выбранной привязки.
• Член
  • Идентификатор родительской группы. Поле в файле Members, которое имеет то же значение (привязка), что и родительская группа в CSV-файле Групп. Первое поле в файле Members используется по умолчанию.
  • Идентификатор члена: поле в файле Members, которое имеет то же значение (привязка), что и в CSV-файле Пользователи или группы. Второе поле в файле Members выбрано по умолчанию.
• Тип объекта-члена: поле, содержащее строковое значение "Пользователь" или "Группа", указывающее тип объекта элемента. Это поле является обязательным, только если файл member содержит более двух полей. Поле Тип объекта должно содержать только строковое значение User илиGroup. Если это поле отсутствует, соединитель предполагает, что записи файла Members относятся к элементу объекта User. Третье поле в файле Members выбрано по умолчанию.

Важно!

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

Схема 3 (конфигурации схемы атрибутов файла пользователей)

Эта страница предназначена для указания и объяснения типа данных каждого из полей, определенных в схеме CSV-файла Users, а также о том, могут ли они иметь несколько значений.

На следующем рисунке показан пример страницы Schema 3 (Users File Attribute Schema Configurations).

В следующем разделе приведены рекомендации по назначению типов данных атрибутов.

Поддерживаемые типы данных

Соединитель GCSV поддерживает использование следующих типов данных раздела:

• Логическое значение: значение, которое может иметь значение true или false.
• Binary: значение, которое хранится в виде последовательности байтов, обычно используется для хранения данных, таких как изображения или другие файлы.
• Integer: значение, представляющее собой целое число без десятичных разрядов.
• Строка: значение, представляющее собой последовательность символов, обычно используемую для хранения текстовых данных.
• Ссылка: значение, которое является ссылкой на другой объект пользователя. Чтобы указать ссылочные значения в CSV-файле, заполните его поле значением привязки указанного объекта пользователя.

Важно!

Атрибуты ссылки пользователя или группы можно использовать только для ссылки на объекты пользователя. Это не относится к атрибуту Member объектов Group, которые могут содержать ссылки как на пользователя, так и на группы, если указано поле типа объекта.

Поддерживаемые типы данных Multiple-Value

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

• Строка

Примечание

Если схема объектов User и Group имеет атрибут (без привязки) с одинаковым именем, между ними могут не назначаться разные типы данных. Они оба должны иметь один и тот же тип данных.

Схема 4 (конфигурации схемы атрибутов файла групп)

Эта страница предназначена для указания и объяснения типа данных каждого из полей, определенных в схеме CSV-файла групп, а также о том, могут ли они иметь несколько значений.

На следующем рисунке показан пример страницы Схема 4 (Конфигурации схемы атрибутов файла групп).

Руководство, предлагаемое в схеме 3 (Конфигурации атрибутов файла пользователей ), применяется и к этому разделу. .

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

Глобальные параметры (конфигурация сценариев PowerShell)

На этой странице можно настроить скрипты PowerShell, которые будут выполняться до и (или) после операций импорта и экспорта. Эти функции позволяют выполнять широкий спектр действий до и после обработки записей пользователей и групп удостоверений.

На следующем рисунке показан пример страницы глобальных параметров .

В следующем разделе перечислены отдельные параметры конфигурации на этой странице.

• Время ожидания скрипта (в минутах) — количество минут, в течение которых скрипт будет выполняться до его автоматического прерывания. Значение по умолчанию для этого параметра равно 100 и требует значения больше нуля (0).
• Файл скрипта перед импортом: полный путь к скрипту PowerShell, который должен выполняться перед импортом. Этот параметр является необязательным и не требует значения.
• Файл скрипта после импорта: полный путь к скрипту PowerShell, который должен выполняться после импорта. Этот параметр является необязательным и не требует значения.
• Файл скрипта перед экспортом: полный путь к скрипту PowerShell, который должен выполняться перед экспортом. Этот параметр является необязательным и не требует значения.
• Файл скрипта после экспорта: полный путь к скрипту PowerShell, который должен выполняться после экспорта. Этот параметр является необязательным и не требует значения.

Выполнение скрипта PowerShell и входные параметры

Соединитель GCSV выполняет каждый из настроенных скриптов PowerShell в своем сеансе и не поддерживает передачу параметров между этапами.

Соединитель передает один входной параметр в каждый скрипт с именем OperationType. Значение этого параметра зависит от выполняемой операции запуска профиля и может иметь одно из трех значений:

Важно!

Динамическое создание CSV-файлов перед операциями импорта или экспорта не поддерживается. Все CSV-файлы должны присутствовать перед выполнением любого из профилей запуска.

Входной параметр PowerShell: OperationType

Хотя использование входных параметров не поддерживается, соединитель GCSV передает один входной параметр при выполнении каждого скрипта PowerShell: OperationType.

• Полный — это значение предоставляется во время операций полного импорта или полного экспорта.
• Delta — это значение предоставляется во время операций экспорта.

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

Иерархия подготовки

Поскольку CSV-файлы не хранят информацию в иерархической структуре, соединитель GCSV не поддерживает конфигурации иерархической подготовки.

На следующем рисунке показан пример страницы "Иерархия подготовки ".

Секции и иерархии

Соединитель GCSV создает отдельное различающееся имя (DN) для каждой записи пользователя и группы в пространстве соединителя в следующем формате LDAP:

CN=[ANCHOR_VALUE],Object=User|Group,O=CSV

На следующем рисунке показан пример страницы Секции и иерархии .

Типы объектов

Соединитель GCSV требует, чтобы был выбран по крайней мере тип объекта User. Тип объекта Group является необязательным.

На следующем рисунке показан пример страницы "Типы объектов ".

Атрибуты

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

На следующем рисунке показан пример страницы Атрибуты .

Примечание

Атрибут Member будет существовать только в том случае, если выбраны группы и будет содержать ссылки на объекты, которые хранятся в CSV-файлах членов группы.

Привязки

Соединитель GCSV не поддерживает использование сложных привязок и конфигураций атрибутов привязки, которые отличаются от полей идентификатора привязки соответствующего CSV-файла.

Чтобы изменить обозначения привязки, отображаемые на этой странице, вернитесь к схеме 2 (конфигурации привязки).

На следующем рисунке показан пример страницы "Привязки ".

Подготовка записей CSV

Чтобы соединитель GCSV добавлял новые объекты User или Group в соответствующие CSV-файлы, для него должен быть подготовлен новый объект пространства соединителя.

При использовании декларативной подготовки MIM 2016 или написания собственных расширений правил синхронизации MIM новые объекты Connector Space должны иметь DN, созданное в следующем формате:

CN=[ANCHOR_VALUE],Object=User|Group,O=CSV

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

Компонент	Примечания
CN=[ЗНАЧЕНИЕ ПРИВЯЗКИ]	Общее имя (CN) должно быть уникальным значением для и будет записано в назначенное поле привязки CSV-файла.
Object=User/Group	Этот компонент указывает тип объекта данного соединителя. Поддерживает только "Пользователь" или "Группа".
O=CSV	Корневой компонент, общий для всех объектов пространства соединителя GCSV.

На следующем рисунке показано , как правильно создать DN при подготовке нового объекта User в соединителе GCSV:

В следующем коде показана эквивалентная логика подготовки с помощью расширений правил метавселенной.

void IMVSynchronization.Provision(MVEntry mventry)
{
	if (mventry["employeeID"].IsPresent)
	{
		ConnectedMA GCSVConnector = = mventry.ConnectedMAs["Generic CSV Conenctor"];

		if (GCSVConnector.Connectors.Count == 0)
		{
			CSEntry csentry = GCSVConnector.Connectors.StartNewConnector("user");

			//Sets DN to "CN=[ANCHOR_VALUE],OBJECT=[User|Group],O=CSV"
			csentry.DN = GCSVConnector.EscapeDNComponent("CN=" + mventry["employeeID"].Value).Concat("OBJECT=User,O=CSV");

			csentry["AccountName"].StringValue = mventry["accountName"].StringValue;
			csentry["CountryCode"].IntegerValue = 1;
			csentry["DisplayName"].Value = mventry["displayName"].Value;
			csentry["ProxyAddresses"].Value = mventry["proxyAddressCollection"].Value;
			csentry["IsActive"].BooleanValue = true;
			csentry["Manager"].Value = mventry["manager"].Value;
			csentry["ProfilePic"].Value = mventry["pic"].Value;

			csentry.CommitNewConnector();
		}
	}
}

На предыдущем рисунке обратите внимание на использование функции для обеспечения правильного EcapeDNComponent() экранирования значения привязки в соответствии с синтаксисом LDAP.

Важно!

Неправильное экранирование значения привязки при создании DN приведет к ошибке invalid‑dn .

Примеры форматирования полей CSV

В следующих разделах перечислены примеры форматирования различных типов данных в CSV-файлах. Все примеры. В следующем разделе предполагается использование параметров разделителя полей соединителя по умолчанию:

• Отдельное значение: запятая (,)
• Разделитель с несколькими значениями: Semi-Colon (;)
• Квалификатор текста: двойные кавычки (")

Пример. Квалификация текста

Если строковое значение содержит символы, которые в противном случае были бы интерпретированы как разделители (например, запятые), необходимо, чтобы средство синтаксического анализа CSV правильно интерпретировать строку как одно поле.

В следующем примере CSV-файла раздела показано, как поле DisplayName содержит значения, отформатированные как полный текст:

EmployeeID,DisplayName
E001,"Smith, John"
E002,"Doe, Jane"
E003,"Perez, Juan"

Пример: разделители многозначных строк

Чтобы указать несколько строковых значений в одном строковом поле, разделите значения с помощью разделителя многозначных значений. В следующем примере CSV-файла раздела показано, как поле ProxyAddress с несколькими значениями:

EmployeeID,DisplayName,ProxyAddresses
E001,"Smith, John",SMTP:john.smith@contoso.com;smtp:js001@contoso.com
E002,"Doe, Jane",SMTP:jane.doe@contoso.com;smtp:jd002@contoso.com

Примечание

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

Пример. Поля ссылок

Чтобы указать значение ссылки в CSV-файле, заполните его поле значением привязки указанного объекта пользователя. В следующем примере CSV-файла раздела поле Manager содержит значение привязки записи пользователя, на которую оно ссылается:

EmployeeID,DisplayName,Manager
E001,"Smith, John",
E002,"Doe, Jane",E001
E003,"Doe, Jane", 
E004,"Perez, Juan",

Пример. Двоичные поля

Чтобы выразить двоичные значения в CSV-файлах, их необходимо преобразовать в строки base64, использующие тот же тип кодирования, что и CSV-файл. В следующем разделе функции PowerShell показано, как кодировать строковое значение в строку в кодировке Base64 в Юникоде.

function ConvertTo-Base64([string]$text) 
{
    $bytes = [System.Text.Encoding]::Unicode.GetBytes($text)
    $encodedText = [System.Convert]::ToBase64String($bytes)
    return $encodedText
}

Ниже приведена эквивалентная функция в C#, которая принимает входной параметр text и возвращает строку в кодировке Base64 в Юникоде.

public static string ConvertToBase64(string text)
{
    byte[] bytes = System.Text.Encoding.UTF8.GetBytes(text);
    string encodedText = System.Convert.ToBase64String(bytes);
    return encodedText;
}

Пример. Логические поля

CSV-файлы, содержащие логические поля, должны использовать текст True или False для указания их значения. Следующий раздел —

EmployeeID,DisplayName,IsActive
E001,"Smith, John",true
E002,"Doe, Jane",true
E003,"Perez, Juan",false

Известные ограничения

В следующем списке приведены известные ограничения соединителя GCSV.

• Ссылочные атрибуты
  • Кроме атрибута group Member , многозначные ссылочные атрибуты не поддерживаются.
  • Значение ссылки должно ссылаться на пользовательские объекты. Ссылки на объекты группы не поддерживаются.
• Привязки
  • Повторяющиеся значения привязки между объектами пользователя и группы не поддерживаются.
  • Имена атрибутов привязки должны быть уникальными для схем пользователей и групп.
• PowerShell
  • Передача входных переменных в скрипты PowerShell не поддерживается.