Connettore CSV generico - Guida di riferimento tecnico (anteprima)

Questo articolo descrive il connettore CSV generico (GCSV). ed è applicabile ai prodotti seguenti:

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

Per MIM 2016, il connettore è disponibile come download dall'Area download Microsoft.

Per vedere come funziona questo connettore, vedere l'articolo relativo alle istruzioni dettagliate per il connettore SQL generico .

Panoramica del connettore CSV generico

Il connettore GENERIC CSV (GCSV) consente di integrare i dati di identità utente e gruppo gestiti nei file CSV con i prodotti Microsoft, ad esempio Microsoft Entra Connect Provisioning Agent (ECMA2Host) e Microsoft Identity Manager 2016 (MIM2016).

Offre diverse funzionalità, ad esempio la possibilità di orchestrare l'uso di PowerShell per gestire i dati di identità prima o dopo le importazioni o le esportazioni. Offre il supporto per più tipi di dati, inclusi i riferimenti e binari, il supporto per i valori di stringa qualificati e le stringhe multivalore.

Questo articolo descrive le funzionalità e le funzioni del connettore CSV generico e come configurarlo per MIM 2016.

La tabella seguente elenca le funzionalità supportate dalla versione corrente del connettore, dal punto di vista generale:

Funzionalità	Dettagli
Supporto per più prodotti	L'uso di questo connettore è supportato con i prodotti Microsoft seguenti: Microsoft Entra Connect Provisioning Agent (ECMA2Host) Microsoft Identity Manager 2016 (MIM2016)
File CSV supportati	Questo connettore supporta la gestione degli utenti (obbligatori) e dei gruppi (facoltativi), tramite la configurazione di un massimo di tre file CSV: File CSV users (ad esempio Users.csv) File CSV di gruppi (ad esempio Groups.csv) File CSV dei membri del gruppo (ad esempio Members.csv)
Elaborazione preliminare/post-operazione con PowerShell	Questo connettore supporta la configurazione di un massimo di quattro script di PowerShell (4) per facilitare l'elaborazione preliminare o post-elaborazione dei dati di identità utente e gruppo prima o dopo l'importazione o l'esportazione.
Codifica file CSV supportata	Il connettore supporta tutti i tipi di codifica server predefiniti (o installati): (ad esempio Unicode, UTF-8, UTF-7, ASCII e così via)
Tipi di dati di campo CSV supportati	Il connettore supporta i tipi di dati di attributo seguenti: Binary : (come stringhe base64) Boolean : (come True/False) Integer Stringhe/Stringhe multivalore Riferimento
Delimitazione di campi CSV	Supporto per virgole (,) o qualsiasi carattere alfamerico stampabile per qualificare l'inizio e la fine di qualsiasi valore stringa.
Supporto per la qualificazione di stringhe	Supporto per virgolette doppie (") o qualsiasi carattere alfamerico stampabile per qualificare l'inizio e la fine di qualsiasi valore stringa.
Supporto di stringhe multivalore	Supporto per stringhe multivalore
Operazioni del connettore supportate	Il connettore supporta le operazioni seguenti: Importazione completa Esportazione Esportazione completa
SCHEMA	L'individuazione dello schema è dinamica, ma richiede la configurazione manuale per il completamento. I campi vengono identificati in modo dinamico in base a un delimitatore specificato (o noto come "Separatore valore".") I tipi di dati dei campi vengono designati manualmente durante la configurazione.

Prerequisiti

Prima di usare il connettore, assicurarsi di disporre degli elementi seguenti nel server di sincronizzazione:

• Microsoft .NET 4.6.2 Framework o versione successiva
• File CSV che contengono lo schema desiderato per i tipi di identità seguenti:
  • File users (obbligatorio)
  • Gruppi (facoltativo)
  • Membri del gruppo (obbligatorio se vengono usati i gruppi)
• (Facoltativo) Script di PowerShell per gestire la pre-e-post-elaborazione per gli eventi Dei tipi di operazione seguenti:
  • Pre-importazione: questo script viene eseguito prima dell'esecuzione di un'operazione di importazione.
  • Post-importazione: questo script viene eseguito dopo l'esecuzione di un'operazione di importazione.
  • Pre-Esportazione: questo script viene eseguito prima dell'esecuzione di un'operazione di esportazione.
  • Post-Esportazione: questo script viene eseguito dopo l'esecuzione di un'operazione di esportazione.

Autorizzazioni dell'account del servizio di sincronizzazione MIM

Creare un nuovo connettore

L'elenco seguente è una panoramica generale dei passaggi descritti in questa guida. Per iniziare, è necessario usare un account con il ruolo sincronizzazione MIM Amministrazione per eseguire queste attività:

• Aprire la finestra Crea nuovo agente di gestione (MA) dal Service Manager di sincronizzazione MIM.
• Selezionare Il connettore CSV generico come tipo di connettore.
• Specificare il percorso e il nome del file CSV da importare o esportare.
• Specificare la codifica dei file, il separatore di valori, il separatore multivalore e il qualificatore di testo per il file CSV.
• Scegliere se usare o meno i valori nella prima riga come campi di intestazione.
• Selezionare i tipi di oggetto e gli attributi da importare o esportare dal file CSV.
• Configurare la partizione, il profilo di esecuzione e i dettagli del mapping per l'agente di gestione di Microsoft Azure.
• Specificare i percorsi e i parametri degli script di PowerShell, se presenti.
• Eseguire l'agente di gestione di Microsoft per eseguire le operazioni di importazione, sincronizzazione o esportazione.

Per creare un connettore CSV generico, in Servizio di sincronizzazione selezionareAgente di gestione e Crea. Selezionare il connettore CSV generico (Microsoft).

Connettività

La pagina Connettività contiene i percorsi dei file CSV Utenti, Gruppi e Membri del gruppo.

L'immagine seguente è un esempio della pagina Connettività .

I percorsi dei file CSV seguenti vengono specificati in questa pagina:

• File utenti: percorso completo del file CSV che contiene i record utente e i relativi valori di attributo. Questo file è obbligatorio.
• File groups: percorso completo del file CSV che contiene i record di gruppo. Questo file è facoltativo.
• File membri: percorso completo del file CSV che contiene record di riferimento dei membri del gruppo.

La schermata Connectivity è la prima visualizzata quando si crea un nuovo connettore Generic SQL. Per prima cosa è necessario specificare le informazioni della sezione seguente:

Funzionalità

Questa pagina descrive le funzionalità del connettore. Le funzionalità del connettore sono fisse e non possono essere modificate, ma sono illustrate qui per fornire informazioni sul funzionamento del connettore.

L'immagine seguente è un esempio della pagina Funzionalità .

La sezione seguente elenca le singole configurazioni e i relativi significati:

• Stile nome distinto (LDAP): il connettore GCSV usa la sintassi LDAP (Lightweight Directory Access Protocol) per costruire la DN (nome distinto) per identificare in modo univoco ogni oggetto User o Group nello spazio del connettore. Tutti i valori DN vengono espressi nel formato seguente: CN=[ANCHOR_VALUE],Object=[User|Group],O=CSV.
• Conferma oggetto (Normale): normalmente, il motore di sincronizzazione presuppone che possa recuperare nuovamente l'oggetto in un'importazione differenziale successiva dopo un'esportazione. Questo è il funzionamento del motore di sincronizzazione, ma non tutti i sistemi connessi funzionano in questo modo. Questa impostazione di Normal garantisce che non exported-change-not-reimported sia presente alcun avviso nell'importazione di follow-up.
• Tipo di esportazione (MultivaluedReferenceAttributeUpdate): il tipo di esportazione specifica come gli oggetti vengono formattati e inviati al sistema di destinazione durante la sincronizzazione. MultivaluedReferenceAttributeUpdate è un tipo di esportazione progettato per funzionare con Microsoft Entra ID. Invia solo gli attributi che sono stati modificati. Per gli attributi di tipo valore, usa AttributeReplace e per gli attributi di riferimento, usa AttributeUpdate.
• Normalizzazione (Nessuno): le normalizzazione fanno riferimento a dati standardizzabili in un formato coerente. Nessuno significa che non vengono applicate regole di normalizzazione specifiche. I dati rimangono così come sono senza trasformazioni aggiuntive dal connettore.

Schema 1 (configurazioni di formato file CSV)

Il connettore GCSV usa tre tipi di separatori (o delimitatori) per delimitare e analizzare i campi CSV e i relativi valori.

Questa pagina contiene le impostazioni del valore del carattere per questi separatori e il tipo di codifica usato per creare il file come CSV.

L'immagine seguente è un'immagine della pagina Schema 1 (configurazioni di formato file CSV).

La sezione seguente è un elenco delle singole configurazioni:

• Usare le intestazioni per l'individuazione dello schema: quando questa opzione è selezionata, indica al connettore di considerare il primo record di ogni file CSV come record di intestazione e non come record di dati identity. Se questa opzione non è selezionata, il connettore assegna il nome Attributo con un valore intero con incremento univoco aggiunto (ad esempio, Attribute1, Attribute2 e così via) e considera la prima riga di come record di dati identity.
• Separatore valori: questo carattere separa i campi , ovvero i valori, dei record CSV. La virgola (,) è l'impostazione predefinita, ma qualsiasi carattere alfanumerico che può essere stampato è consentito.
• Separatore multivalore: questo tipo di separatore viene usato per delimitare i singoli valori di una stringa multivalore (ad esempio, indirizzi proxy) o attributi di riferimento (ad esempio, subordinati). Il valore predefinito è un punto e virgola (;) ma qualsiasi carattere alfanumerico stampabile è accettabile.
• Qualificatore di testo: quando un valore stringa contiene caratteri che altrimenti verranno interpretati come delimitatori (ad esempio, come virgole), è necessario che il valore sia qualificato in modo che il parser CSV possa interpretare correttamente la stringa come singolo campo. Le virgolette doppie (") sono il valore predefinito, ma qualsiasi carattere alfanumerico che può essere stampato è consentito.

• Codifica file: questa impostazione indica la codifica utilizzata nei file CSV aggiunti nella scheda Connettività. Assicurarsi che corrisponda alla codifica dei file CSV.

Schema 2 (Configurazioni dei campi di riferimento e identità)

Il valore di ancoraggio è un identificatore univoco per un record in un file CSV. Differenzia un record dagli altri. Il connettore GCSV usa anche questo valore per creare il nome distinto (DN) che identifica l'oggetto spazio del connettore correlato.

In questa pagina le impostazioni dell'attributo di ancoraggio vengono configurate per ogni file CSV elencato nella pagina Connettività.

L'immagine seguente è un esempio della pagina Schema 2 (Configurazioni campo di riferimento e identità).

La sezione seguente è un elenco delle singole configurazioni in questa pagina:

• Utente
  • Ancoraggio utente: campo nel file Users che funge da valore di ancoraggio per il record utente. Il primo campo di intestazione nel file Users è la scelta predefinita.
  • Tipo di attributo Di ancoraggio utente: si tratta del tipo di attributo dell'ancoraggio selezionato.
• Gruppo
  • Ancoraggio gruppo: campo nel file Gruppi che funge da valore di ancoraggio per il record di gruppo. Il primo campo di intestazione nel file Gruppi è la scelta predefinita.
  • Tipo di attributo Di ancoraggio di gruppo: si tratta del tipo di attributo dell'ancoraggio selezionato.
• Membro
  • ID gruppo padre: campo nel file Membri con lo stesso valore (ancoraggio) del gruppo padre nel file CSV Gruppi. Il primo campo nel file Membri viene usato per impostazione predefinita.
  • ID membro: il campo nel file Membri con lo stesso valore (ancoraggio) del file CSV Utenti o gruppi. Il secondo campo nel file Membri è selezionato per impostazione predefinita.
• Tipo di oggetto membro: campo contenente un valore stringa "User" o "Group" per indicare il tipo di oggetto del membro. Questo campo è obbligatorio solo se il file Membro contiene più di due campi. Il campo Tipo oggetto deve contenere solo il valore stringa "User" o "Group". Se questo campo è mancante, il connettore presuppone che i record di file Membri faccia riferimento a un membro dell'oggetto User. Il terzo campo trovato nel file Membri è selezionato per impostazione predefinita.

Schema 3 (Configurazioni dello schema degli attributi file degli utenti)

Questa pagina è per specificare e spiegare il tipo di dati di ognuno dei campi identificati nello schema del file CSV Utenti e se possono avere più di un valore.

L'immagine seguente è un esempio della pagina Schema 3 (Configurazioni dello schema degli attributi file degli utenti).

Nella sezione seguente vengono elencate le considerazioni relative all'assegnazione dei tipi di dati degli attributi.

Tipi di dati supportati

Il connettore GCSV supporta l'uso dei tipi di dati della sezione seguente:

• Boolean: valore che può essere true o false.
• Binario: valore archiviato come sequenza di byte, in genere usato per archiviare dati come immagini o altri file.
• Integer: valore intero che è un numero intero, senza posizioni decimali.
• Stringa: valore che rappresenta una sequenza di caratteri, in genere usato per archiviare i dati di testo.
• Riferimento: valore che fa riferimento a un altro oggetto utente. Per specificare un valore di riferimento in un file CSV, popolare il campo con il valore di ancoraggio dell'oggetto utente indicato.

Tipi di dati supportati Multiple-Value

Il connettore supporta l'uso di attributi multivalore solo per i tipi di dati seguenti:

• string

Schema 4 (configurazioni dello schema degli attributi file di gruppi)

Questa pagina è per specificare e spiegare il tipo di dati di ognuno dei campi identificati nello schema del file CSV Gruppi e se possono avere più di un valore.

L'immagine seguente è un esempio della pagina Schema 4 (Configurazioni dello schema di attributi file di gruppi).

Le linee guida offerte nello schema 3 (Le configurazioni degli attributi file degli utenti si applicano anche a questa sezione. .

Dopo l'esecuzione di un'operazione di importazione completa iniziale, lo spazio del connettore sarà simile all'immagine seguente:

Parametri globali (configurazione script di PowerShell)

Questa pagina consente la configurazione degli script di PowerShell che verranno eseguiti prima e/o dopo le operazioni di importazione ed esportazione. Queste funzionalità offrono opportunità di eseguire un'ampia gamma di azioni di pre-e-post elaborazione nei record dell'utente e del gruppo di identità.

L'immagine seguente è un esempio della pagina Parametri globali .

Nella sezione seguente sono elencate le singole impostazioni di configurazione in questa pagina:

• Timeout script (minuti): numero di minuti che verrà eseguito uno script prima che venga interrotto automaticamente. Il valore predefinito per questa impostazione è 100 e richiede un valore maggiore di zero (0).
• File di script di pre-importazione: il percorso completo dello script di PowerShell che deve essere eseguito prima di un'importazione. Questa impostazione è facoltativa e non richiede un valore.
• File di script post-importazione: percorso completo dello script di PowerShell che deve essere eseguito dopo un'importazione. Questa impostazione è facoltativa e non richiede un valore.
• File di script di pre-esportazione: il percorso completo dello script di PowerShell che deve essere eseguito prima di un'esportazione. Questa impostazione è facoltativa e non richiede un valore.
• File di script post-esportazione: il percorso completo dello script di PowerShell che deve essere eseguito dopo un'esportazione. Questa impostazione è facoltativa e non richiede un valore.

Parametri di esecuzione e input di script di PowerShell

Il connettore GCSV esegue ognuno degli script di PowerShell configurati nella propria sessione e non supporta il passaggio di parametri tra le fasi non è supportato.

Il connettore passa un parametro di input a ogni script denominato OperationType. Il valore di questo parametro varia a seconda dell'operazione Run Profile eseguita e può essere uno dei tre valori seguenti:

Parametro di input di PowerShell: OperationType

Anche se l'uso dei parametri di input non è supportato, il connettore GCSV passa un parametro di input all'esecuzione di ogni script di PowerShell: OperationType.

• Full : questo valore viene fornito durante operazioni di importazione completa o esportazione completa.
• Delta : questo valore viene fornito durante le operazioni di esportazione.

Questo valore di parametro può essere usato all'interno della logica degli script di PowerShell per determinare l'operazione o l'azione di pre-elaborazione appropriata da eseguire.  

Gerarchia di provisioning

Poiché i file CSV non archiviano le informazioni in una struttura gerarchica, il connettore GCSV non supporta configurazioni di provisioning gerarchiche.

L'immagine seguente è un esempio della pagina Gerarchia di provisioning .

Partizioni e gerarchie

Il connettore GCSV compila un nome distinto distinto (DN) per ogni record utente e gruppo nello spazio del connettore, seguendo questo formato LDAP:

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

L'immagine seguente è un esempio della pagina Partizioni e gerarchie .

Tipi di oggetto

Il connettore GCSV richiede che sia selezionato almeno il tipo di oggetto User. La scelta del tipo di oggetto Group è facoltativa.

L'immagine seguente è un esempio della pagina Tipi di oggetto .

Attributi

Questa pagina visualizza un elenco normalizzato di tutti gli attributi in tutti gli schemi del tipo di oggetto selezionato.

L'immagine seguente è un esempio della pagina Attributi .

Ancoraggi

Il connettore GCSV non supporta l'uso di ancoraggi complessi né configurazioni di attributi di ancoraggio che differiscono dai campi ID di ancoraggio del file CSV corrispondenti.

Per modificare le designazioni di ancoraggio visualizzate in questa pagina, tornare allo schema 2 (configurazioni di ancoraggio).

L'immagine seguente è un esempio della pagina Ancoraggi .

Provisioning di record CSV

Per consentire al connettore GCSV di aggiungere nuovi oggetti User o Group nei file CSV corrispondenti, è necessario effettuare il provisioning di un nuovo oggetto spazio connettore.

Se si usa il provisioning dichiarativo MIM 2016 o si scrivono estensioni delle regole di sincronizzazione MIM, i nuovi oggetti Spazio connettore devono avere un DN costruito usando il formato seguente:

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

La tabella seguente fornisce informazioni dettagliate su ognuno dei valori del componente:

Componente	Note
CN=[ANCHOR VALUE]	Il nome comune (CN) deve essere un valore univoco a e verrà scritto nel campo di ancoraggio designato del file CSV.
Object=User/Group	Questo componente indica il tipo di oggetto di questo connettore. Supporta solo "User" o "Group".
O=CSV	Componente radice comune a tutti gli oggetti spazio del connettore GCSV.

L'immagine seguente è una regola di sincronizzazione che illustra come costruire un DN correttamente durante il provisioning di un nuovo oggetto User in un connettore GCSV:

Il codice seguente illustra la logica di provisioning equivalente usando le estensioni delle regole 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();
		}
	}
}

Nell'immagine precedente si noti l'uso della funzione per assicurarsi che il valore di EcapeDNComponent() ancoraggio venga eseguito correttamente in modo da essere conforme alla sintassi LDAP.

Esempi di formattazione dei campi CSV

Le sezioni seguenti elencano esempi di come formattare diversi tipi di dati nei file CSV. Tutti gli esempi La sezione seguente presuppone l'uso delle impostazioni predefinite del delimitatore di campo del connettore:

• Valore separato: virgola (,)
• Separatore multivalore: Semi-Colon (;)
• Qualificatore di testo: virgolette doppie (")

Esempio: Qualifica del testo

Se un valore stringa contiene caratteri che altrimenti verranno interpretati come delimitatori (ad esempio, virgole), è necessario che il valore sia qualificato in modo che il parser CSV possa interpretare correttamente la stringa come singolo campo.

Nell'esempio csv della sezione seguente viene illustrato come il campo DisplayName contiene valori formattati come testo qualificato:

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

Esempio: Delimitazione di stringhe multivalore

Per fornire più valori di stringa all'interno di un campo stringa, delimitare i valori con il separatore Multivalue. Nell'esempio csv della sezione seguente viene illustrato come il campo ProxyAddress con più valori:

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

Esempio: Campi di riferimento

Per specificare un valore di riferimento in un file CSV, popolare il campo con il valore di ancoraggio dell'oggetto utente indicato. Nell'esempio CSV della sezione seguente, il campo Manager contiene il valore di ancoraggio del record utente a cui fa riferimento:

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

Esempio: Campi binari

Per esprimere i valori binari nei file CSV, devono essere convertiti in stringhe base64 che usano lo stesso tipo di codifica del file CSV. La sezione seguente di PowerShell illustra come codificare un valore stringa nella stringa codificata base64 in Unicode:

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

Ecco la funzione equivalente in C# che accetta un parametro di input denominato testo e restituisce una stringa codificata base64 in Unicode.

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

Esempio: Campi booleani

I file CSV che contengono campi booleani devono usare il testo True o False per indicare il valore. La sezione seguente è un

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

Limitazioni note

L'elenco seguente contiene le limitazioni note del connettore GCSV.

• Attributi del riferimento
  • Oltre all'attributo Member del gruppo, gli attributi di riferimento multivalore non sono supportati.
  • Il valore di riferimento deve fare riferimento agli oggetti utente. I riferimenti agli oggetti di gruppo non sono supportati.
• Ancoraggi
  • I valori di ancoraggio duplicati tra gli oggetti utente e gruppo non sono supportati.
  • I nomi degli attributi di ancoraggio devono essere univoci tra gli schemi utente e di gruppo.
• PowerShell
  • Il passaggio di variabili di input negli script di PowerShell non è supportato.