Универсальный соединитель CSV — пошаговое руководство по использованию (предварительная версия)

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

• Microsoft Identity Manager 2016 (MIM2016);

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

Примечание

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

Подготовка примеров CSV-файлов

На сервере, на котором запущен сервер синхронизации MIM, создайте папку C:\GCSV и скопируйте в нее следующие CSV-файлы, найденные в приложении A — Примеры CSV-файлов . Не забудьте предоставить учетной записи службы синхронизации MIM разрешения на чтение и запись в эту папку.

Скопируйте следующий CSV-файл в папку C:\GCSV\SCRIPTS :

• Пример CSV-файла пользователей (Users.csv)
• Пример CSV-файла групп (Groups.csv)
• Пример CSV-файла членов (Members.csv)

Примечание

В этом руководстве предполагается, что CSV-файлы находятся по следующему пути на сервере синхронизации MIM: C:\GCSV и сохраняются с использованием указанных имен файлов. Если вы установите их в другом расположении или переименуете эти файлы, вам потребуется внести соответствующие изменения с помощью сброса в этом руководстве.

Подготовка примеров сценариев PowerShell

На сервере, на котором запущен сервер синхронизации MIM, создайте папку C:\GCSV\SCRIPTS и скопируйте в нее примеры скриптов PowerShell, расположенные в приложении Б . Примеры файлов PowerShell . Убедитесь, что учетная запись службы синхронизации MIM имеет соответствующие разрешения PowerShell ExecutePolicy для выполнения скриптов.

Скопируйте следующие скрипты PowerShell в папку C:\GCSV\SCRIPTS :

• Пример скрипта перед импортом (Pre-Import.ps1)
• Пример скрипта после импорта (Post-Import.ps1)
• Пример скрипта предварительного экспорта (Pre-Export.ps1)
• Пример скрипта после экспорта (Post-Export.ps1)

Примечание

В этом руководстве предполагается, что CSV-файлы находятся по следующему пути на сервере синхронизации MIM: C:\GCSV\SCRIPTS. Если вы устанавливаете их в другом расположении, вам потребуется внести соответствующие изменения с помощью сброса, описанного в этом руководстве.

Важно!

Для выполнения примеров сценариев PowerShell учетной записи службы синхронизации MIM требуются соответствующие разрешения ExecutePolicy PowerShell на сервере синхронизации MIM.

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

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

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

Начнем!

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

Укажите имя соединителя (например, Универсальный CSV-файл) и нажмите кнопку Далее .

Соединение

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

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

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

Имя параметра	Значение параметра	Примечания
Файл пользователей	C:\GCSV\USERS.CSV	(Используется полный путь и имя файла.)
Файл групп	C:\GCSV\GROUPS.CSV	(Используется полный путь и имя файла.)
Файл members	C:\GCSV\MEMBERS.CSV	(Используется полный путь и имя файла.)

Убедившись, что параметры соответствуют указанным значениям, нажмите кнопку Далее .

Возможности

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

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

Подробное описание этих параметров возможностей см. в руководстве По техническому справочнику по универсальному соединителю CSV.

После просмотра конфигураций нажмите кнопку Далее .

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

Соединитель Generic CSV (GCSV) использует три типа разделителей (или разделителей) для разделения и анализа полей CSV и их значений: разделители значений, многозначные разделители и текстовые квалификаторы. Дополнительные сведения об этих типах разделителей см. в руководстве по универсальному соединителю CSV— техническому справочнику.

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

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

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

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

Примечание

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

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

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

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

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

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

Имя параметра	Значение параметра
Поле идентификатора записи пользователей	EmployeeID
Тип атрибута поля идентификатора записи пользователя	String
Поле идентификатора записи группы	GroupID
Тип атрибута поля идентификатора записи группы	String
Идентификатор родительской группы	Parentid
Идентификатор участника	MemberID
Тип объекта-члена	ObjectType

Убедившись, что параметры соответствуют указанным значениям, нажмите кнопку Далее .

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

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

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

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

Имя параметра	Значение параметра	Примечания
Тип атрибута DisplayName	String	Примеры полных строк приведены в этом поле.
DisplayName является многозначным	false	--
Тип атрибута AccountName	String	--
AccountName является многозначным	false	--
Тип атрибута CountryCode	Целое число	--
Код страны является многозначным	false	--
Тип атрибута диспетчера	Справочные материалы	Содержит значения атрибутов привязки записей пользователя назначенных руководителей (например, E001).
Диспетчер является многозначным	false	--
Тип атрибута ProxyAddresses	String	--
ProxyAddresses является многозначным	TRUE	Содержит примеры разделения многозначных строк
Тип атрибута IsActive	Boolean	--
IsActive является многозначным	false	--
Тип атрибута ProfilePic	Двоичный	--
ProfilePic является многозначным	false	--

Убедившись, что параметры соответствуют указанным значениям, нажмите кнопку Далее .

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

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

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

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

Имя параметра	Значение параметра	Примечания
Тип атрибута DisplayName	String	--
DisplayName является многозначным	false	Пример полных строковых значений.
Тип атрибута Description	String	--
Описание является многозначным	false	--
Тип атрибута владельца	Справочные материалы	Пример ссылочных значений.
Владелец является многозначным	false	--

Убедившись, что параметры соответствуют указанным значениям, нажмите кнопку Далее .

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

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

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

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

Имя параметра	Значение параметра	Примечания
Файл перед импортом	C:\GCSV\SCRIPTS\PRE-IMPORT.CSV	Этот скрипт выполняется перед полным импортом
Файл после импорта	C:\GCSV\SCRIPTS\POST-IMPORT.CSV	Этот скрипт выполняется после полного импорта
Файл перед экспортом	C:\GCSV\SCRIPTS\PRE-EXPORT.CSV	Этот скрипт выполняется перед полным экспортом или (разностным) экспортом
Файл после экспорта	C:\GCSV\SCRIPTS\POST-EXPORT.CSV	Этот скрипт выполняется перед полным экспортом или (разностным) экспортом

Убедившись, что параметры соответствуют указанным значениям, нажмите кнопку Далее .

Выполнение скрипта PowerShell

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

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

Важно!

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

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

Аналогичным образом, если операция после импорта или экспорта встречает исключение, это приводит к сбою состояния операции.

Ошибки, возникшие во время выполнения скрипта PowerShell, будут входить в *Событие *Журнал сервера синхронизации MIM.

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

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

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

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

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

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

Убедившись, что параметры соответствуют указанным значениям, нажмите кнопку Далее .

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

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

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

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

Убедившись, что параметры соответствуют указанным значениям, нажмите кнопку Далее .

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

Для универсального соединителя CSV требуется, чтобы был указан по крайней мере тип объекта User. Выбор типа объекта Group является необязательным.

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

Убедившись, что параметры соответствуют указанным значениям, нажмите кнопку Далее .

Атрибуты

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

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

Убедившись, что параметры соответствуют указанным значениям, нажмите кнопку Далее .

Примечание

Атрибуты привязки всегда требуются для правильной работы соединителя GCSV.

Привязки

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

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

После просмотра параметров по умолчанию на странице нажмите кнопку Далее .

Фильтры соединителей

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

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

После просмотра параметров по умолчанию на странице нажмите кнопку Далее .

Правила соединения и проекции

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

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

После просмотра параметров по умолчанию на странице нажмите кнопку Далее .

Поток атрибутов

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

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

Убедившись, что параметры соответствуют значениям по умолчанию, нажмите кнопку Далее .

Deprovisioning

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

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

Убедившись, что параметры соответствуют значениям по умолчанию, нажмите кнопку Далее .

Создание профиля выполнения полного импорта

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

Чтобы создать профиль выполнения полного импорта, выполните следующие действия.

• Назад в Service Manager синхронизации.
• Выберите агент управления GCSV.
• Щелкните его правой кнопкой мыши и выберите Настроить профили запуска.
• Щелкните Создать профиль.

Откроется окно Настройка профиля запуска.

Назовите профиль запуска

На странице Имя профиля введите имя Полный импорт.

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

Убедившись, что параметры соответствуют указанным значениям, нажмите кнопку Далее .

Укажите тип

На странице Шаг настройки выберите Тип: Полный импорт.

Фильтрация соединителя работает в соединителе GCSV так же, как и в любом другом соединителе ECMA.

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

Убедившись, что параметры соответствуют указанным значениям, нажмите кнопку Далее .

Тип конфигурации агента управления

На странице Тип конфигурации агента управления убедитесь, что выбран раздел O=CSV .

Оставьте остальные параметры в значениях по умолчанию. Нажатие кнопки Готово приведет к созданию профиля запуска.

Проверка результатов

В этом разделе подробно описаны действия, необходимые для проверки результатов создания нового соединителя GCSV и импорта записей пользователей и групп из примеров CSV-файлов.

Полный импорт

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

• Назад в Service Manager синхронизации.
• Выберите агент управления GCSV.
• Щелкните его правой кнопкой мыши и выберите выполнить.
• Выберите Полный импорт и нажмите кнопку ОК.

Проверка результатов операции полного импорта

Должно быть пять (5) добавлений на основе содержимого примеров CSV-файлов:

На следующем рисунке показан пример результатов успешного импорта содержимого примеров CSV-файлов:

Изучение пространства соединителя GCSV

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

• Назад в Service Manager синхронизации.
• Выберите агент управления соединителем GCSV .
• Щелкните его правой кнопкой мыши и выберите Поиск Пространство соединителя.
• Оставьте для область значение по умолчанию Subtree и нажмите кнопку Поиск.

На следующем рисунке показан пример отображаемого окна Поиск пространства соединителя.

Проверка объекта пользователя

Выберите один из объектов пользователя для проверки. На следующем рисунке показан пример объекта пространства соединителя GCSV пользователя:

Проверка поля DisplayName показывает, как была правильно проанализирована квалифицированная строка.

Нажатие кнопки в записи ProxyAddresses показывает, что многозначная строка также правильно проанализирована в отдельные значения:

Проверка объекта group

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

Нажатие кнопки в записи Участник показывает, как связанные записи-члены группы записей с файлом Members были должным образом загружены в качестве членов:

Проверка журналов выполнения PowerShell

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

Расположение по умолчанию для этого журнала —C:\GCSV\PS_Run_Ledger.csv.

При открытии журнала отображается:

"DateTime","Stage","Name","Type","Description"

"3/17/2024 1:05:44 PM","Pre","Import","Full","The Pre-Import PowerShell script was executed successfully."
"3/17/2024 1:05:46 PM","Pre","Import","Full","The Post-Import PowerShell script was executed successfully."

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

Приложение А. Примеры CSV-файлов

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

Пример CSV-файла пользователей

В конфигурации соединителя в этом руководстве предполагается имя файла USERS.CSV.

EmployeeID,DisplayName,AccountName,CountryCode,Manager,ProxyAddresses,IsActive,ProfilePic
E001,"Smith, John",JS001,1,,SMTP:john.smith@contoso.com;smtp:js001@contoso.com,True,SgBTADAAMAAxAA==
E002,"Doe, Jane",JD003,1,E001,SMTP:jane.doe@contoso.com;smtp:jd002@contoso.com,True,SgBEADAAMAAyAA==
E003,"Perez, Juan",JP003,1,E001,SMTP:juan.perez@contoso.com;smtp:jp003@contoso.com,False,SgBEADAAMAAyAA==

Csv-файл примеров групп

В конфигурации соединителя в этом руководстве предполагается имя файла GROUPS.CSV.

GroupID,DisplayName,Description,Owner
G001,Test Group (G001),"This group is for teams A, B, and C",E002
G002,Test Group (G002),"This group is for teams D, E, and F",E003

Пример CSV-файла членов

В конфигурации соединителя в этом руководстве предполагается имя файла MEMBERS.CSV.

ParentID,MemberID,ObjectType
G001,E001,USER
G001,E002,USER
G001,E003,USER
G002,E001,USER
G002,E002,USER
G002,E003,USER
G002,G001,GROUP
G003,E001,USER
G003,E002,USER
G003,E003,USER
G003,G001,GROUP

Приложение Б. Примеры файлов PowerShell

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

Важно!

Любое использование write-hostкоманд в скриптах PowerShell приведет к сбою выполнения скрипта.

Пример скрипта PowerShell перед импортом

В конфигурации соединителя в этом руководстве предполагается имя файла PRE-IMPORT.PS1.

param ([string]$OperationType)

[string]$stage = "Pre"
[string]$operation = "Import"
[string]$filePath = "C:\GCSV\PS_Run_Ledger.csv"

# Create a new record
$record = [PSCustomObject]@{
    "DateTime" = (Get-Date).ToString()
    "Stage" = $stage
    "Type" = $OperationType
    "Name" = $operation
    "Description" = "The $stage-$operation PowerShell script was successfully executed before a $OperationType-$operation."
}

$record | Export-Csv -Path $FilePath -NoTypeInformation -Append

Пример скрипта PowerShell после импорта

В конфигурации соединителя в этом руководстве предполагается имя файла POST-IMPORT.PS1.

param ([string]$OperationType)

[string]$stage = "Post"
[string]$operation = "Import"
[string]$filePath = "C:\GCSV\PS_Run_Ledger.csv"

# Create a new record
$record = [PSCustomObject]@{
    "DateTime" = (Get-Date).ToString()
    "Stage" = $stage
    "Type" = $OperationType
    "Name" = $operation
    "Description" = "The $stage-$operation PowerShell script was successfully executed after a $OperationType-$operation."
}

$record | Export-Csv -Path $FilePath -NoTypeInformation -Append

Пример скрипта PowerShell перед экспортом

В конфигурации соединителя в этом руководстве предполагается имя файла PRE-EXPORT.PS1.

param ([string]$OperationType)

[string]$stage = "Pre"
[string]$operation = "Export"
[string]$filePath = "C:\GCSV\PS_Run_Ledger.csv"

# Create a new record
$record = [PSCustomObject]@{
    "DateTime" = (Get-Date).ToString()
    "Stage" = $stage
    "Type" = $OperationType
    "Name" = $operation
    "Description" = "The $stage-$operation PowerShell script was successfully executed before a $OperationType-$operation."
}

$record | Export-Csv -Path $FilePath -NoTypeInformation -Append

Пример скрипта PowerShell после экспорта

В конфигурации соединителя в этом руководстве предполагается имя файла POST-EXPORT.PS1.

param ([string]$OperationType)

[string]$stage = "Post"
[string]$operation = "Export"
[string]$filePath = "C:\GCSV\PS_Run_Ledger.csv"

# Create a new record
$record = [PSCustomObject]@{
    "DateTime" = (Get-Date).ToString()
    "Stage" = $stage
    "Type" = $OperationType
    "Name" = $operation
    "Description" = "The $stage-$operation PowerShell script was successfully executed after a $OperationType-$operation."
}

$record | Export-Csv -Path $FilePath -NoTypeInformation -Append