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

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

• Агент предоставления Microsoft Entra Connect (ECMA2Host)
• Microsoft Identity Manager 2016 (MIM2016)

Для MIM 2016 соединитель доступен для загрузки из Центра загрузок Microsoft.

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

Заметка

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

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

Соединитель Generic CSV (GCSV) позволяет интегрировать данные удостоверений пользователей и групп, поддерживаемые в CSV-файлах, с продуктами Microsoft, такими как агент подготовки 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) Логический — (как Истина/Ложь) Целые числа Строки / многозначные строки Ссылка
Делимитация полей CSV	Поддержка запятых (,) или любого печатного буквенно-цифрового символа для квалификации начала и конца любого строкового значения.
Поддержка строковой квалификации	Поддержка двойных кавычек (") или любого печатного буквенно-цифрового символа для квалификации начала и конца любого строкового значения.
Поддержка многозначной строки	Поддержка многозначных строк
Поддерживаемые операции подключения	Соединитель поддерживает следующие операции: Полный импорт Экспорт Полный экспорт
Схема	Обнаружение схемы является динамическим, но требует ручной настройки для завершения. Поля динамически определяются на основе указанного разделителя (также известного как «разделитель значений»). Типы данных полей назначаются вручную во время настройки.

Необходимые условия

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

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

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

Важный

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

Создайте новый соединитель

В следующем списке представлен общий обзор шагов, описанных в этом руководстве. Чтобы начать, необходимо использовать учетную запись с ролью MIM Syncs Admin для выполнения следующих задач:

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

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

Связь

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

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

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

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

Важно

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

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

Возможности

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

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

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

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

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

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

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

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

Ниже приведен список отдельных конфигураций.

• Использовать заголовки для обнаружения схем. При выборе этого параметра соединитель указывает соединителю обрабатывать первую запись каждого CSV-файла как запись заголовка, а не запись данных удостоверений. Если этот параметр не выбран, соединитель назначает имя Атрибут с добавленным уникальным увеличенным целым числом (например, Атрибут1, Атрибут2и т. д.) и обрабатывает первую строку как запись идентификационных данных.
• разделитель значений: этот символ разделяет поля (то есть значения) записей CSV. Запятая (,) — это значение по умолчанию, но разрешен любой буквенно-цифровой символ, который можно распечатать.
• разделитель многозначных значений: этот тип разделителя используется для разделителя отдельных значений многозначной строки (например, прокси-адресов) или ссылочных атрибутов (например, подчиненных).) По умолчанию используется точка с запятой (;) но любой печатный буквенно-цифровой символ является допустимым.
• квалификатор текста. Если строковое значение содержит символы, которые в противном случае интерпретируются как разделители (например, запятые), требуется, чтобы значение было квалифицировано таким образом, чтобы средство синтаксического анализа CSV правильно интерпретировало строку как одно поле. Двойные кавычки (") — это значение по умолчанию, но разрешен любой буквенно-цифровой символ, который можно распечатать.

Заметка

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

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

Заметка

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

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

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

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

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

Ниже приведен список отдельных конфигураций на этой странице:

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

Важный

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

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

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

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

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

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

Подключение GCSV поддерживает использование следующих типов данных этого раздела:

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

Важный

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

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

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

• Струна

Заметка

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

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

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

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

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

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

пространства соединителя

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

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

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

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

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

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

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

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

Важный

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

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

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

• Full — это значение предоставляется во время операций полного импорта или полного экспорта.
• 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 добавлял новые объекты пользователя или группы в соответствующие CSV-файлы, для него необходимо подготовить новый объект пространства соединителя.

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

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

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

Компонент	Примечания
CN=[ЗНАЧЕНИЕ ПРИВЯЗКИ]	Общее имя (CN) должно быть уникальным значением и будет записано в поле привязки CSV-файла.
Объект=Пользователь/Группа	Этот компонент указывает тип объекта этого соединителя. Поддерживает только "пользователя" или "группу".
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-файла в поле "Диспетчер" содержится значение привязки записи пользователя, к которой он ссылается:

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

Пример: двоичные поля

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

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

Ниже приведена эквивалентная функция в C#, которая принимает входной параметр, называемый текстом, и возвращает строку в кодировке 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.

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