Ogólny konektor CSV — Przewodnik techniczny (wersja zapoznawcza)

W tym artykule opisano ogólny łącznik CSV (GCSV). Artykuł dotyczy następujących produktów:

• microsoft Entra Connect Provisioning Agent (ECMA2Host)
• Microsoft Identity Manager 2016 (MIM2016)

W przypadku programu MIM 2016 łącznik jest dostępny do pobrania z Centrum Pobierania Microsoft, .

Aby zobaczyć, jak działa ten łącznik, zapoznaj się z artykułem krok po kroku w sekcji dotyczącej ogólnego łącznika SQL w artykule.

Omówienie ogólnego łącznika CSV

Łącznik ogólnego pliku CSV (GCSV) umożliwia integrację danych tożsamości użytkowników i grup przechowywanych w plikach CSV z produktami firmy Microsoft, takimi jak Microsoft Entra Connect Provisioning Agent (ECMA2Host) i Microsoft Identity Manager 2016 (MIM2016).

Ma ona różne funkcje, takie jak możliwość organizowania używania programu PowerShell do zarządzania danymi tożsamości przed importem lub eksportem. Oferuje obsługę wielu typów danych, w tym plików binarnych i odwołań, obsługę wartości kwalifikowanych ciągów i ciągów wielowartościowych.

W tym artykule opisano funkcje i funkcje ogólnego łącznika CSV oraz sposób konfigurowania go dla programu MIM 2016.

W poniższej tabeli wymieniono funkcje obsługiwane przez bieżącą wersję łącznika z perspektywy wysokiego poziomu:

Warunki wstępne

Przed użyciem łącznika upewnij się, że na serwerze synchronizacji są następujące elementy:

• Microsoft .NET 4.6.2 Framework lub nowszy
• Pliki CSV zawierające żądany schemat dla następujących typów tożsamości:
  • Plik użytkowników (wymagany)
  • Grupy (opcjonalnie)
  • Członkowie grupy (wymagane, jeśli są używane grupy)
• (Opcjonalnie) Skrypty programu PowerShell do zarządzania przetwarzaniem przed i po wykonaniu dla następujących typów zdarzeń operacyjnych:
  • Przed importowaniem — ten skrypt jest wykonywany przed uruchomieniem operacji importowania.
  • Po zaimportowaniu — ten skrypt jest wykonywany po uruchomieniu operacji importowania.
  • Przed wyeksportowanie — ten skrypt jest wykonywany przed uruchomieniem operacji eksportu.
  • Po wyeksportowaniu — ten skrypt jest wykonywany po uruchomieniu operacji eksportowania.

Uprawnienia konta usługi synchronizacji programu MIM

Tworzenie nowego łącznika

Poniższa lista zawiera ogólne omówienie kroków opisanych w tym przewodniku. Aby rozpocząć, należy użyć konta z rolą MIM Syncs Admin, aby wykonywać następujące zadania:

• Otwórz okno Utwórz nowego agenta zarządzania (MA) w oknie programu MIM Sync Service Manager.
• Wybierz Ogólny Łącznik CSV jako typ łącznika.
• Podaj ścieżkę pliku i nazwę pliku CSV do zaimportowania lub wyeksportowania.
• Określ kodowanie pliku, separator wartości, separator wielu wartości i kwalifikator tekstu dla pliku CSV.
• Określ, czy wartości w pierwszym wierszu mają być używane jako pola nagłówka, czy nie.
• Wybierz typy obiektów i atrybuty do zaimportowania lub wyeksportowania z pliku CSV.
• Skonfiguruj partycję, profil działania i szczegóły mapowania dla MA.
• Podaj ścieżki i parametry skryptów programu PowerShell, jeśli istnieją.
• Uruchom narzędzie MA, aby wykonać operacje importowania, synchronizacji lub eksportowania.

Aby utworzyć ogólny łącznik CSV, w usłudze synchronizacji wybierz pozycję Agent zarządzania i Utwórz. Wybierz łącznik Generic CSV (Microsoft).

Łączność

Strona Połączenia zawiera lokalizacje plików CSV Użytkowników, Grup i Członków Grup.

Na poniższej ilustracji przedstawiono przykład strony łączności.

Lokalizacje następujących plików CSV są określone na tej stronie:

• Users File: w pełni kwalifikowana ścieżka pliku CSV, które zawiera rekordy użytkowników i ich wartości atrybutów. Ten plik jest wymagany.
• Plik grup: pełna ścieżka do pliku CSV, który zawiera rekordy grup. Ten plik jest opcjonalny.
• Plik członków: Pełna ścieżka pliku CSV, który zawiera rekordy odwołujące się do członków grupy.

Ekran ustawień łączności jest pierwszym elementem podczas tworzenia łącznika SQL o charakterze ogólnym. Najpierw należy podać informacje dotyczące następującej sekcji:

Możliwości

Na tej stronie opisano możliwości łącznika. Możliwości łącznika są stałe i nie można ich zmieniać, ale wyjaśniono tutaj, aby uzyskać informacje na temat sposobu działania łącznika.

Na poniższej ilustracji przedstawiono przykład strony możliwości.

W poniższej sekcji wymieniono poszczególne konfiguracje i ich znaczenie:

• Styl nazwy wyróżniającej (LDAP): Łącznik GCSV używa składni LDAP (Lightweight Directory Access Protocol) do konstruowania nazwy wyróżniającej w celu unikalnego identyfikowania każdego obiektu użytkownika lub grupy w przestrzeni łącznika. Wszystkie wartości DN są wyrażone w następującym formacie: CN=[ANCHOR_VALUE],Object=[User|Group],O=CSV.
• Potwierdzenie obiektu (normalne): Zwykle silnik synchronizacji zakłada, że może ponownie pobrać obiekt w kolejnym imporcie różnicowym po eksporcie. W ten sposób działa zwykle aparat synchronizacji, ale nie wszystkie połączone systemy działają w ten sposób. To ustawienie Normal gwarantuje brak exported-change-not-reimported ostrzeżenia przy późniejszym imporcie.
• Typ eksportu (MultivaluedReferenceAttributeUpdate): Typ eksportu określa sposób formatowania i wysyłania obiektów do systemu docelowego podczas synchronizacji. MultivaluedReferenceAttributeUpdate to typ eksportu przeznaczony do pracy z identyfikatorem Entra firmy Microsoft. Wysyła tylko atrybuty, które uległy zmianie. W przypadku atrybutów typu wartości używa atrybutu AttributeReplace i atrybutów referencyjnych, używa atrybutu AttributeUpdate.
• Normalizacje (Brak): Normalizacje odnoszą się do standaryzacji danych do spójnego formatu. Brak oznacza, że nie są stosowane żadne określone reguły normalizacji. Dane pozostają as-is bez żadnych dodatkowych przekształceń przez łącznik.

Schemat 1 (konfiguracje formatu pliku CSV)

Łącznik GCSV wykorzystuje trzy rodzaje separatorów (lub ograniczników) do rozdzielania i analizowania pól CSV i ich wartości.

Ta strona zawiera ustawienia wartości znaków dla tych separatorów oraz typ kodowania użyty do utworzenia pliku CSV.

Na poniższej ilustracji przedstawiono obraz strony schematu 1 (konfiguracje formatu plików CSV).

Poniższa sekcja zawiera listę poszczególnych konfiguracji:

• Użyj nagłówków do odnajdywania schematu: po wybraniu tej opcji łącznik instruuje, aby traktować pierwszy rekord każdego pliku CSV jako rekord nagłówka, a nie jako rekord danych tożsamości. Jeśli ta opcja nie jest zaznaczona, łącznik przypisuje nazwę Attribute z dołączoną unikatową wartością całkowitą przyrostową (na przykład Attribute1, Attribute2itp.) i traktuje pierwszy wiersz jako rekord danych tożsamości.
• separator wartości: ten znak oddziela pola (czyli wartości) rekordów CSV. Przecinek (,) jest domyślny, ale dozwolony jest dowolny znak alfanumeryczny, który można wydrukować.
• separatora wielowartościowego: ten typ separatora służy do rozdzielenia poszczególnych wartości ciągu wielowartościowego (na przykład adresów serwera proxy) lub atrybutów referencyjnych (na przykład podrzędnych). Wartość domyślna to średnik (;) ale dowolny znak alfanumeryczny z możliwością drukowania jest akceptowalny.
• kwalifikator tekstu: gdy wartość ciągu zawiera znaki, które w przeciwnym razie będą interpretowane jako ograniczniki (na przykład przecinki), wymaga, aby wartość była kwalifikowana, aby analizator CSV mógł poprawnie interpretować ciąg jako jedno pole. Cudzysłowy (") są domyślne, ale dozwolony jest dowolny znak alfanumeryczny, który można wydrukować.

• kodowanie plików: to ustawienie wskazuje kodowanie używane w plikach CSV dodanych na karcie Łączność. Upewnij się, że jest on zgodny z kodowaniem plików CSV.

Schemat 2 (Konfiguracje pól tożsamości i referencyjnych)

Wartość znacznika jest unikatowym identyfikatorem rekordu w pliku CSV. Odróżnia jeden rekord od innych. Łącznik GCSV używa również tej wartości do utworzenia nazwy wyróżniającej (DN), która identyfikuje powiązany obiekt przestrzeni łącznika.

Na tej stronie ustawienia atrybutów odnośnika są konfigurowane dla każdego z plików CSV wymienionych na stronie Łączność.

Na poniższej ilustracji przedstawiono przykład strony Schema 2 (Identity and Reference Field Configurations).

Poniższa sekcja zawiera listę poszczególnych konfiguracji na tej stronie:

• użytkownika
  • Kotwica użytkownika: pole w pliku Użytkownicy, które służy jako wartość kotwicy dla rekordu użytkownika. Pierwsze pole nagłówka w pliku Users jest wyborem domyślnym.
  • atrybut typu kotwica użytkownika: to jest typ atrybutu wybranej kotwicy.
• grupy
  • kotwica grupy: pole w pliku Grupy, które służy jako wartość zakotwiczająca dla rekordu grupy. Pierwsze pole nagłówka w pliku Grupy jest wyborem domyślnym.
  • typ atrybutu kotwicy grupy: jest to typ atrybutu wybranej kotwicy.
• Członek
  • identyfikator grupy nadrzędnej: pole w pliku Członkowie, które ma tę samą wartość (kotwicę) co grupa nadrzędna w pliku CSV grup. Pierwsze pole w pliku Członkowie jest używane domyślnie.
  • identyfikator elementu członkowskiego: pole w pliku Członkowie, które ma taką samą wartość (kotwicę) jak w pliku CSV Użytkownicy lub Grupy. Drugie pole w pliku Członkowie jest domyślnie zaznaczone.
• typ obiektu członka: pole zawierające wartość typu ciągu znaków "Użytkownik" lub "Grupa", wskazującą typ obiektu członka. To pole jest wymagane tylko wtedy, gdy plik członkowski zawiera więcej niż dwa pola. Pole Typ Obiektu musi zawierać tylko wartość ciągową "Użytkownik" lub "Grupa". Jeśli brakuje tego pola, łącznik zakłada, że rekordy plików członków odwołują się do obiektu użytkownika. Trzecie pole znalezione w pliku Członkowie jest domyślnie zaznaczone.

Schemat 3 (konfiguracje schematu atrybutów plików użytkowników)

Ta strona służy do określania i wyjaśniania typu danych każdego z pól zidentyfikowanych w schemacie pliku CSV użytkowników oraz czy mogą one mieć więcej niż jedną wartość.

Na poniższym obrazie pokazano przykład strony Schema 3 (Konfiguracja schematu atrybutu pliku użytkowników).

W poniższej sekcji wymieniono zagadnienia dotyczące przypisywania typów danych atrybutów.

Obsługiwane typy danych

Łącznik GCSV obsługuje użycie następujących typów danych sekcji:

• wartość logiczna: wartość, która może być prawda lub fałsz.
• binarne: wartość przechowywana jako sekwencja bajtów, zwykle używana do przechowywania danych, takich jak obrazy lub inne pliki.
• liczba całkowita: wartość, która jest liczbą całkowitą bez żadnych miejsc dziesiętnych.
• ciąg: wartość, która jest sekwencją znaków, zwykle używana do przechowywania danych tekstowych.
• odwołanie: wartość, która jest odwołaniem do innego obiektu użytkownika. Aby określić wartość referencyjną w pliku CSV, wypełnij pole wartością zakotwiczenia określonego obiektu użytkownika.

Obsługiwane typy danych Multiple-Value

Łącznik obsługuje używanie atrybutów wielowartościowych tylko dla następujących typów danych:

• Struna

Schemat 4 (grupy konfiguracji schematu atrybutu pliku)

Ta strona służy do określania i wyjaśniania typu danych każdego pola, które są identyfikowane w schemacie pliku CSV grup i czy mogą mieć więcej niż jedną wartość.

Na poniższym obrazie przedstawiono przykład strony schematu Schema 4 (Konfiguracje schematu atrybutów plików Grupy).

Wskazówki oferowane w Schema 3 (Konfiguracja atrybutów plików użytkowników dotyczy również tej sekcji. .

Po uruchomieniu początkowej pełnej operacji importowania przestrzeń łącznika będzie wyglądać podobnie do obrazu na poniższej ilustracji:

Parametry globalne (konfiguracja skryptów programu PowerShell)

Ta strona umożliwia konfigurację skryptów programu PowerShell, które będą uruchamiane przed i/lub po operacjach importowania i/lub eksportowania. Te funkcje umożliwiają wykonywanie szerokiej gamy akcji przetwarzania wstępnego i końcowego na rekordach użytkowników i grup tożsamości.

Poniższa ilustracja to przykład strony parametrów globalnych .

Poniższa sekcja zawiera listę poszczególnych ustawień konfiguracji na tej stronie:

• limit czasu skryptu (w minutach): liczba minut, przez które skrypt zostanie uruchomiony przed automatycznym przerwanie. Wartość domyślna tego ustawienia to 100 i wymaga wartości większej niż zero (0).
• plik skryptu przed importem: pełna ścieżka do skryptu programu PowerShell, który powinien zostać uruchomiony przed importem. To ustawienie jest opcjonalne i nie wymaga wartości.
• Plik skryptu po imporcie: w pełni kwalifikowana ścieżka do skryptu programu PowerShell, który powinien zostać uruchomiony po imporcie. To ustawienie jest opcjonalne i nie wymaga wartości.
• Plik skryptu pre-eksportowego: w pełni kwalifikowana ścieżka do skryptu programu PowerShell, który powinien zostać uruchomiony przed eksportem. To ustawienie jest opcjonalne i nie wymaga wartości.
• plik skryptu po wyeksportowaniu: w pełni kwalifikowana ścieżka do skryptu programu PowerShell, który powinien zostać uruchomiony po wyeksportowaniu. To ustawienie jest opcjonalne i nie wymaga wartości.

Wykonywanie skryptu programu PowerShell i parametry wejściowe

Łącznik GCSV wykonuje każdy ze skonfigurowanych skryptów programu PowerShell we własnej sesji i nie obsługuje przekazywania parametrów między etapami nie jest obsługiwany.

Łącznik przekazuje jeden parametr wejściowy do każdego skryptu o nazwie OperationType. Wartość tego parametru różni się w zależności od wykonywanej operacji Profilu uruchamiania i może być jedną z trzech wartości:

Parametr wejściowy programu PowerShell: OperationType

Mimo że użycie parametrów wejściowych nie jest obsługiwane, łącznik GCSV przekazuje jeden parametr wejściowy do wykonywania każdego skryptu programu PowerShell: OperationType.

• Pełne — ta wartość jest udostępniana podczas operacji pełnego importu lub pełnego eksportu.
• Delta — ta wartość jest dostarczana podczas eksportu.

Tej wartości parametru można użyć w ramach logiki skryptów programu PowerShell, aby określić odpowiednią operację przetwarzania wstępnego/końcowego lub akcję do wykonania.  

Hierarchia Provisioningu

Ponieważ pliki CSV nie przechowują informacji w strukturze hierarchicznej, łącznik GCSV nie obsługuje żadnych hierarchicznych konfiguracji aprowizacji.

Na poniższej ilustracji przedstawiono przykład strony hierarchii aprowizacji.

Partycje i hierarchie

Łącznik GCSV tworzy odrębną nazwę wyróżniającą (DN) dla każdego rekordu użytkownika i grupy w przestrzeni łącznika, zgodnie z następującym formatem LDAP:

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

Na poniższej ilustracji przedstawiono przykład strony Partitions and Hierarchies (Partycje i hierarchie).

Typy obiektów

Łącznik GCSV wymaga, aby wybrany został co najmniej typ obiektu Użytkownik. Wybór typu obiektu Grupa jest opcjonalny.

Na poniższej ilustracji przedstawiono przykład strony Typy obiektów.

Atrybuty

Na tej stronie zostanie wyświetlona znormalizowana lista wszystkich atrybutów we wszystkich wybranych schematach typów obiektów.

Na poniższej ilustracji przedstawiono przykład strony Atrybuty.

Kotwice

Łącznik GCSV nie obsługuje używania złożonych kotwic ani konfiguracji atrybutów kotwicy, które różnią się od odpowiednich pól identyfikatora kotwicy pliku CSV.

Aby zmienić oznaczenia kotwicy wyświetlane na tej stronie, wróć do schematu 2 (Konfiguracje kotwicy).

Na poniższej ilustracji przedstawiono przykład strony Anchors.

Aprowizowanie rekordów CSV

Aby łącznik GCSV mógł dodawać nowe obiekty użytkowników lub grup do odpowiednich plików CSV, należy aprowizować dla niego nowy obiekt obszaru łącznika.

Niezależnie od tego, czy używasz aprowizacji deklaratywnej programu MIM 2016 lub pisania własnych rozszerzeń reguł synchronizacji programu MIM, nowe obiekty obszaru łącznika muszą mieć skonstruowaną nazwę wyróżniającą przy użyciu następującego formatu:

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

Poniższa tabela zawiera szczegółowe informacje dotyczące poszczególnych wartości składników:

Na poniższym obrazie przedstawiono regułę synchronizacji, która pokazuje, jak prawidłowo skonstruować DN podczas wdrażania nowego obiektu użytkownika w łączniku GCSV.

Poniższy kod przedstawia równoważną logikę aprowizacji przy użyciu rozszerzeń reguł Metaverse.

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();
		}
	}
}

Na poprzedniej ilustracji zwróć uwagę na użycie funkcji EcapeDNComponent() w celu zapewnienia, że wartość kotwicy jest poprawnie przetworzona zgodnie ze składnią LDAP.

Przykłady formatowania pól CSV

W poniższych sekcjach wymieniono przykłady formatowania różnych typów danych w plikach CSV. Wszystkie przykłady W poniższej sekcji założono użycie domyślnych ustawień ogranicznika pola łącznika:

• Oddzielna wartość: przecinek (,)
• Separator wielowartościowy: Semi-Colon (;)
• Kwalifikator tekstu: cudzysłowy podwójne (")

Przykład: kwalifikacja tekstu

Jeśli wartość ciągu zawiera znaki, które w przeciwnym razie będą interpretowane jako ograniczniki (na przykład przecinki), wymaga, aby wartość była kwalifikowana, aby analizator CSV mógł poprawnie interpretować ciąg jako jedno pole.

W poniższej sekcji przykład pliku CSV pokazano, jak pole DisplayName ma wartości sformatowane jako kwalifikowany tekst:

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

Przykład: ograniczanie ciągów wielowartościowych

Aby podać wiele wartości ciągu w jednym polu ciągu, ogranicz wartości separatorem wielowartościowym . Poniższy przykład pliku CSV pokazuje, jak pole ProxyAddress może mieć wiele wartości:

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

Przykład: Pola referencyjne

Aby określić wartość referencyjną w pliku CSV, wypełnij pole wartością zakotwiczenia określonego obiektu użytkownika. W poniższym przykładzie sekcji CSV pole Menedżer zawiera wartość kotwicy rekordu użytkownika, do którego się odwołuje.

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

Przykład: Pola binarne

Aby wyrazić wartości binarne w plikach CSV, należy je przekonwertować na ciągi base64, które używają tego samego typu kodowania co plik CSV. W poniższej sekcji funkcja programu PowerShell pokazuje, jak zakodować wartość ciągu do zakodowanego ciągu base64 w formacie Unicode:

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

Oto równoważna funkcja w języku C#, która akceptuje parametr wejściowy o nazwie text i zwraca ciąg zakodowany w formacie Base64 w formacie Unicode.

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

Przykład: pola logiczne

Pliki CSV zawierające pola logiczne powinny używać tekstu Prawda lub Fałsz, aby wskazać ich wartość. Poniższa sekcja to

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

Znane ograniczenia

Poniższa lista zawiera znane ograniczenia łącznika GCSV.

• Atrybuty referencyjne
  • Z wyjątkiem atrybutu członka grupy , atrybuty odwołań wielowartościowych nie są obsługiwane.
  • Wartość referencyjna musi odwoływać się do obiektów użytkownika. Nieobsługiwane są odwołania do obiektów grupowych.
• Anchors
  • Zduplikowane wartości kluczy identyfikacyjnych między obiektami użytkownika i grupy nie są obsługiwane.
  • Nazwy atrybutów centralnych muszą być unikalne w schematach użytkowników i grup.
• PowerShell
  • Przekazywanie zmiennych wejściowych do skryptów programu PowerShell nie jest obsługiwane.