Allmänt CSV-anslutningsprogram – Teknisk referensguide (förhandsversion)

Den här artikeln beskriver GCSV-anslutningsappen (Generic CSV). Artikeln gäller för följande produkter:

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

För MIM 2016 är anslutningsappen tillgänglig som en nedladdning från Microsoft Download Center.

Om du vill se den här anslutningsappen i praktiken kan du läsa den allmänna artikeln om SQL Connector steg för steg .

Översikt över den allmänna CSV-anslutningsappen

Med GCSV-anslutningsappen (Generic CSV) kan du integrera användar- och gruppidentitetsdata som underhålls i CSV-filer med Microsoft-produkter, till exempel Microsoft Entra Connect Provisioning Agent (ECMA2Host) och Microsoft Identity Manager 2016 (MIM2016).

Den har olika funktioner, till exempel möjligheten att samordna användningen av PowerShell för att hantera identitetsdata före eller efter import- eller exportåtgärder. Det ger stöd för flera datatyper, inklusive binärfiler och referenser, stöd för värden med kvalificerad sträng och flervärdessträngar.

Den här artikeln beskriver funktionerna i den allmänna CSV-anslutningsappen och hur du konfigurerar den för MIM 2016.

I följande tabell visas de funktioner som den aktuella versionen av anslutningsappen stöder, ur ett övergripande perspektiv:

Funktion	Information
Support för flera produkter	Användning av den här anslutningsappen stöds med följande Microsoft-produkter: Microsoft Entra Connect Provisioning Agent (ECMA2Host) Microsoft Identity Manager 2016 (MIM2016)
CSV-filer som stöds	Den här anslutningsappen stöder hantering av användare (krävs) och grupper (valfritt) genom konfiguration av upp till tre CSV-filer: CsV-fil för användare (till ex. Users.csv) Grupperar CSV-fil (till ex. Groups.csv) CSV-fil för gruppmedlemmar (till ex. Members.csv)
Bearbetning före/efter åtgärd med PowerShell	Den här anslutningsappen stöder konfiguration av upp till fyra (4) PowerShell-skript för att underlätta bearbetning före eller efter bearbetning av användar- och gruppidentitetsdata före eller efter import eller export.
CSV-filkodning stöds	Anslutningsappen stöder alla standard(eller installerade) serverkodningstyper: (t.ex. Unicode, UTF-8, UTF-7, ASCII osv.)
CSV-fältdatatyper stöds	Anslutningsappen stöder följande attributdatatyper: Binär – (som base64-strängar) Booleskt – (som sant/falskt) Heltal Strängar/Flervärdessträngar Referens
CSV-fältgränsning	Stöd för kommatecken (,) eller alfanumeriska tecken som kan skrivas ut för att kvalificera början och slutet av ett strängvärde.
Stöd för strängkvalifikation	Stöd för dubbla citattecken (") eller valfritt alfanumeriskt tecken som kan skrivas ut för att kvalificera början och slutet av ett strängvärde.
Stöd för flervärdessträngar	Stöd för flervärdessträngar
Anslutningsåtgärder som stöds	Anslutningsappen stöder följande åtgärder: Fullständig import Exportera Fullständig export
Schema	Schemaidentifiering är dynamiskt, men kräver manuell konfiguration för slutförande. Fält identifieras dynamiskt baserat på en angiven avgränsare (eller kallas "Värdeavgränsare") Fältdatatyper anges manuellt under konfigurationen.

Förutsättningar

Innan du använder anslutningsappen kontrollerar du att du har följande på synkroniseringsservern:

• Microsoft .NET 4.6.2 Framework eller senare
• CSV-filer som innehåller önskat schema för följande identitetstyper:
  • Användarfil (krävs)
  • Grupper (valfritt)
  • Gruppmedlemmar (krävs om grupper används)
• (Valfritt) PowerShell-skript för att hantera för- och efterbearbetning för följande åtgärdstyper:
  • Före import – Det här skriptet körs innan en importåtgärd körs.
  • Efter import – Det här skriptet körs när en importåtgärd har körts.
  • Före export – Det här skriptet körs innan en exportåtgärd körs.
  • Efter export – Det här skriptet körs när en exportåtgärd har körts.

Behörigheter för MIM-synkroniseringstjänstkonto

Skapa en ny anslutningsapp

Följande lista är en översikt på hög nivå över de steg som beskrivs i den här guiden. För att kunna börja måste ett konto med MIM-synkroniseringar Admin roll användas för att utföra dessa uppgifter:

• Öppna fönstret Skapa ny hanteringsagent (MA) från MIM Sync-Service Manager.
• Välj den allmänna CSV-anslutningsappen som anslutningstyp.
• Ange filsökvägen och namnet på csv-filen som ska importeras eller exporteras.
• Ange filkodning, värdeavgränsare, avgränsare med flera värden och textkvalificerare för CSV-filen.
• Välj om du vill använda värdena på den första raden som rubrikfält eller inte.
• Välj de objekttyper och attribut som ska importeras eller exporteras från CSV-filen.
• Konfigurera partitionen, kör profilen och mappningsinformationen för ma.
• Ange skriptsökvägarna och parametrarna för PowerShell-skripten, om sådana finns.
• Kör MA för att utföra import-, synkroniserings- eller exportåtgärderna.

Om du vill skapa en allmän CSV-anslutning i Synkroniseringstjänsten väljer du Hanteringsagent och Skapa. Välj den allmänna CSV-anslutningsappen (Microsoft).

Anslutning

Sidan Anslutning innehåller filplatserna för CSV-filerna Användare, Grupper och Gruppmedlemmar.

Följande bild är ett exempel på sidan Anslutning .

Platserna för följande CSV-filer anges på den här sidan:

• Användarfil: Den fullständigt kvalificerade sökvägen för CSV-filen som innehåller användarposterna och deras attributvärden. Den här filen krävs.
• Gruppfil: Den fullständigt kvalificerade sökvägen till CSV-filen som innehåller gruppposterna. Den här filen är valfri.
• Medlemsfil: Den fullständigt kvalificerade sökvägen till CSV-filen som innehåller referensposter för gruppmedlemmar.

Skärmen Anslutning är den första när du skapar en ny allmän SQL-anslutningsapp. Du måste först ange följande avsnittsinformation:

Funktioner

Den här sidan beskriver anslutningsappens funktioner. Anslutningsfunktionerna är fasta och kan inte ändras, men de förklaras här för att ge information om hur anslutningsappen fungerar.

Följande bild är ett exempel på sidan Funktioner .

I följande avsnitt visas en lista över de enskilda konfigurationerna och deras betydelser:

• LDAP (Distinguished Name Style): GCSV Connector använder syntaxen LDAP (Lightweight Directory Access Protocol) för att konstruera DN (unikt namn) för att unikt identifiera varje användar- eller gruppobjekt i dess anslutningsutrymme. Alla DN-värden uttrycks i följande format: CN=[ANCHOR_VALUE],Object=[User|Grupp],O=CSV.
• Objektbekräftelse (normal): Normalt förutsätter synkroniseringsmotorn att den kan hämta objektet igen i en efterföljande deltaimport efter en export. Det är så synkroniseringsmotorn vanligtvis fungerar, men inte alla anslutna system fungerar på det här sättet. Den här inställningen för Normal säkerställer att det inte finns någon exported-change-not-reimported varning i uppföljningsimporten.
• Exporttyp (MultivaluedReferenceAttributeUpdate): Exporttypen anger hur objekt formateras och skickas till målsystemet under synkroniseringen. MultivaluedReferenceAttributeUpdate är en exporttyp som är utformad för att fungera med Microsoft Entra ID. Den skickar bara de attribut som har ändrats. För attribut av värdetyp använder den AttributeReplace och för referensattribut använder den AttributeUpdate.
• Normaliseringar (ingen): Normaliseringar refererar till standardisera data till ett konsekvent format. Ingen innebär att inga specifika normaliseringsregler tillämpas. Data förblir som de är utan ytterligare transformeringar av anslutningsappen.

Schema 1 (CSV-filformatskonfigurationer)

GCSV Connector använder tre typer av avgränsare (eller avgränsare) för att avgränsa och parsa CSV-fält och deras värden.

Den här sidan innehåller teckenvärdeinställningarna för dessa avgränsare och den kodningstyp som användes för att skapa filen som CSV.

Följande bild är en bild av sidan Schema 1 (CSV-filformatkonfigurationer).

Följande avsnitt är en lista över de enskilda konfigurationerna:

• Använd rubriker för schemaidentifiering: När det här alternativet väljs instrueras anslutningsappen att behandla den första posten i varje CSV-fil som en rubrikpost och inte identitetsdatapost. Om det här alternativet inte är markerat tilldelar anslutningsappen namnattributet med ett tillagt unikt inkrementellt heltalsvärde (till exempel Attribute1, Attribute2 osv.) och behandlar den första raden i som en identitetsdatapost.
• Värdeavgränsare: Det här tecknet separerar fälten (dvs. värden) för CSV-posterna. Kommatecknet (,) är standard, men alla alfanumeriska tecken som kan skrivas ut tillåts.
• Flervärdesavgränsare: Den här typen av avgränsare används för att avgränsa enskilda värden för en flervärdessträng (till exempel proxyadresser) eller referensattribut (till exempel underordnade.) Standardvärdet är semikolon (;) men alla alfanumeriska tecken som kan skrivas ut är godtagbara.
• Textkvalificerare: När ett strängvärde innehåller tecken som annars skulle tolkas som avgränsare (till exempel kommatecken) kräver det att värdet kvalificeras så att CSV-parsern korrekt kan tolka strängen som ett enda fält. Dubbla citattecken (") är standard, men alla alfanumeriska tecken som kan skrivas ut tillåts.

• Filkodning: Den här inställningen anger den kodning som används på CSV-filerna som lagts till på fliken Anslutning. Kontrollera att den matchar kodningen av dina CSV-filer.

Schema 2 (konfigurationer av identitets- och referensfält)

Ankarvärdet är en unik identifierare för en post i en CSV-fil. Det särskiljer en post från de andra. GCSV Connector använder också det här värdet för att skapa det unika namnet (DN) som identifierar det relaterade anslutningsobjektet.

På den här sidan konfigureras inställningarna för fästpunktsattributet för var och en av CSV-filerna som visas på sidan Anslutning.

Följande bild är ett exempel på sidan Schema 2 (identitets- och referensfältkonfigurationer).

Följande avsnitt är en lista över de enskilda konfigurationerna på den här sidan:

• Användare
  • Användarankare: Fältet i filen Användare som fungerar som ankarvärde för användarposten. Det första rubrikfältet i filen Användare är standardalternativet.
  • Attributtyp för användarankare: Det här är attributtypen för fästpunkten som valts.
• Grupper
  • Gruppankare: Fältet i filen Grupper som fungerar som ankarvärde för gruppposten. Det första rubrikfältet i filen Grupper är standardalternativet.
  • Attributtyp för gruppankare: Det här är attributtypen för fästpunkten som valts.
• Medlem
  • Överordnat grupp-ID: Fältet i filen Medlemmar som har samma värde (fästpunkt) som den överordnade gruppen i CSV-filen Grupper. Det första fältet i medlemsfilen används som standard.
  • Medlems-ID: Fältet i medlemsfilen som har samma värde (fästpunkt) som i CSV-filen Användare eller Grupper. Det andra fältet i medlemsfilen är markerat som standard.
• Medlemsobjekttyp: Fältet som innehåller strängvärdet "Användare" eller "Grupp" för att ange objekttypen för medlemmen. Det här fältet krävs bara om medlemsfilen innehåller fler än två fält. Fältet Objekttyp får bara innehålla strängvärdet "Användare" eller "Grupp". Om det här fältet saknas förutsätter anslutningsappen att filposterna Medlemmar refererar till en medlem i användarobjektet. Det tredje fältet som finns i medlemsfilen är markerat som standard.

Schema 3 (schemakonfigurationer för användarfilattribut)

Den här sidan är till för att ange och förklara datatypen för vart och ett av de fält som identifieras i schemat för CSV-filen Användare och om de kan ha fler än ett värde.

Följande bild är ett exempel på sidan Schema 3 (schemakonfigurationer för användarfilattribut).

I följande avsnitt beskrivs överväganden när du gör tilldelningar av attributdatatyper.

Datatyper som stöds

GCSV Connector stöder användning av följande avsnittsdatatyper:

• Booleskt värde: ett värde som kan vara antingen sant eller falskt.
• Binärt: ett värde som lagras som en sekvens med byte, som vanligtvis används för att lagra data som bilder eller andra filer.
• Heltal: ett värde som är ett heltal, utan decimaler.
• Sträng: ett värde som är en sekvens med tecken, som vanligtvis används för att lagra textdata.
• Referens: ett värde som är en referens till ett annat användarobjekt. Om du vill ange ett referensvärde i en CSV-fil fyller du i fältet med ankarvärdet för det refererade användarobjektet.

Multiple-Value datatyper som stöds

Anslutningsappen stöder användning av flervärdesattribut för endast följande datatyper:

• Sträng

Schema 4 (schemakonfigurationer för gruppers filattribut)

Den här sidan är till för att ange och förklara datatypen för vart och ett av de fält som identifieras i schemat för CSV-filen Grupper och om de kan ha fler än ett värde.

Följande bild är ett exempel på sidan Schema 4 (schemakonfigurationer för gruppers filattribut).

Vägledningen som erbjuds i schema 3 (Konfigurationer av användarfilattribut gäller även för det här avsnittet. .

När du har kört en inledande fullständig importåtgärd ser anslutningsplatsen ut ungefär som bilden på följande bild:

Globala parametrar (Konfiguration av PowerShell-skript)

På den här sidan kan du konfigurera PowerShell-skript som ska köras före och/eller efter import- och/eller exportåtgärder. Dessa funktioner ger möjlighet att utföra en mängd olika åtgärder före och efter bearbetning på dina identitetsanvändare och gruppposter.

Följande bild är ett exempel på sidan Globala parametrar .

I följande avsnitt visas de enskilda konfigurationsinställningarna på den här sidan:

• Tidsgräns för skript (minuter): antalet minuter som ett skript körs innan det avbryts automatiskt. Standardvärdet för den här inställningen är 100 och kräver ett värde som är större än noll (0).
• Skriptfil för förimport: den fullständigt kvalificerade sökvägen till PowerShell-skriptet som ska köras före en import. Den här inställningen är valfri och kräver inget värde.
• Skriptfil efter import: den fullständigt kvalificerade sökvägen till PowerShell-skriptet som ska köras efter en import. Den här inställningen är valfri och kräver inget värde.
• Skriptfil före export: den fullständigt kvalificerade sökvägen till PowerShell-skriptet som ska köras före en export. Den här inställningen är valfri och kräver inget värde.
• Skriptfil efter export: den fullständigt kvalificerade sökvägen till PowerShell-skriptet som ska köras efter en export. Den här inställningen är valfri och kräver inget värde.

PowerShell-skriptkörning och indataparametrar

GCSV-anslutningsappen kör vart och ett av de konfigurerade PowerShell-skripten i sin egen session och stöder inte överföring av parametrar mellan faser.

Anslutningsappen skickar en indataparameter till varje skript med namnet OperationType. Värdet för den här parametern varierar beroende på vilken körningsprofilåtgärd som utförs, och det kan vara ett av tre värden:

PowerShell-indataparameter: OperationType

Även om användningen av indataparametrar inte stöds skickar GCSV-anslutningsappen en indataparameter till körningen av varje PowerShell-skript: OperationType.

• Fullständig – det här värdet anges under åtgärderna Fullständig import eller Fullständig export.
• Delta – det här värdet anges under exportåtgärder.

Det här parametervärdet kan användas i logiken i PowerShell-skripten för att fastställa lämplig åtgärd eller åtgärd som ska vidtas före/efter bearbetning.  

Etableringshierarki

Eftersom CSV-filer inte lagrar information i en hierarkisk struktur stöder GCSV Connector inte några hierarkiska etableringskonfigurationer.

Följande bild är ett exempel på sidan Etableringshierarki .

Partitioner och hierarkier

GCSV Connector skapar ett distinkt unikt namn (DN) för varje användar- och grupppost i dess anslutningsutrymme, enligt detta LDAP-format:

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

Följande bild är ett exempel på sidan Partitioner och hierarkier .

Objekttyper

GCSV-anslutningsappen kräver att minst objekttypen Användare väljs. Valet av gruppobjekttyp är valfritt.

Följande bild är ett exempel på sidan Objekttyper .

Attribut

Den här sidan visar en normaliserad lista över alla attribut för alla markerade objekttypsscheman.

Följande bild är ett exempel på sidan Attribut .

Ankare

GCSV-anslutningsappen stöder inte användning av komplexa fästpunkter eller konfigurationer av fästpunktsattribut som skiljer sig från motsvarande CSV-fils fästpunkts-ID-fält.

Om du vill ändra ankarbeteckningar som visas på den här sidan går du tillbaka till Schema 2 (Fästpunktskonfigurationer).

Följande bild är ett exempel på sidan Fästpunkter .

Etablera CSV-poster

För att GCSV-anslutningsappen ska kunna lägga till nya användar- eller gruppobjekt i motsvarande CSV-filer måste ett nytt kopplingsutrymmesobjekt etableras för det.

Oavsett om du använder antingen MIM 2016 Deklarativ etablering eller skriver egna tillägg för MIM-synkroniseringsregler, måste nya kopplingsutrymmesobjekt ha ett DN konstruerat med följande format:

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

Följande tabell innehåller information om vart och ett av komponentvärdena:

Komponent	Kommentarer
CN=[ANCHOR VALUE]	Det gemensamma namnet (CN) måste vara ett unikt värde för och skrivs i CSV-filens avsedda fästpunktsfält.
Object=User/Group	Den här komponenten anger objekttypen för den här anslutningsappen. Stöder endast "Användare" eller "Grupp".
O=CSV	Rotkomponenten som är gemensam för alla GCSV-anslutningsobjekt.

Följande bild är en synkroniseringsregel som visar hur du skapar ett DN korrekt när du etablerar ett nytt användarobjekt i en GCSV-anslutningsapp:

Följande kod visar motsvarande etableringslogik med metaversumregeltillägg.

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

Observera att funktionen används EcapeDNComponent() i föregående bild för att säkerställa att fästpunktsvärdet är korrekt undantaget för att vara kompatibelt med dess LDAP-syntax.

Exempel på CSV-fältformatering

I följande avsnitt visas exempel på hur du formaterar olika datatyper i CSV-filer. Alla exempel I följande avsnitt förutsätts användningen av anslutningsappens standardinställningar för avgränsare för fält:

• Separat värde: Kommatecken (,)
• Flervärdesavgränsare: Semi-Colon (;)
• Textkvalificerare: Dubbla citattecken (")

Exempel: Textkvalifikation

Om ett strängvärde innehåller tecken som annars skulle tolkas som avgränsare (till exempel kommatecken) kräver det att värdet kvalificeras så att CSV-parsern kan tolka strängen korrekt som ett enda fält.

Följande csv-exempelavsnitt visar hur fältet DisplayName har värden som är formaterade som kvalificerad text:

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

Exempel: Avgränsa flervärdessträngar

Om du vill ange flera strängvärden i ett strängfält avgränsar du värdena med multivärdeavgränsaren. Följande csv-exempelavsnitt visar hur fältet ProxyAddress med flera värden:

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

Exempel: Referensfält

Om du vill ange ett referensvärde i en CSV-fil fyller du i fältet med ankarvärdet för det refererade användarobjektet. I följande csv-exempelavsnitt innehåller fältet Manager fästpunktsvärdet för den användarpost som den refererar till:

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

Exempel: Binära fält

Om du vill uttrycka binära värden i CSV-filer måste de konverteras till base64-strängar som använder samma kodningstyp som CSV-filen. I följande avsnitt visar PowerShell-funktionen hur du kodar ett strängvärde till dess base64-kodade sträng i Unicode:

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

Här är motsvarande funktion i C# som accepterar en indataparameter med namnet text och returnerar en base64-kodad sträng i Unicode.

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

Exempel: Booleska fält

CSV-filer som innehåller booleska fält bör använda antingen sant eller falskt för att ange värdet. Följande avsnitt är ett

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

Kända begränsningar

Följande lista innehåller kända begränsningar för GCSV-anslutningsappen.

• Referensattribut
  • Förutom gruppmedlemsattributet stöds inte flervärdesreferensattribut.
  • Referensvärdet måste referera till användarobjekt. Referenser till gruppobjekt stöds inte.
• Ankare
  • Dubblettankarvärden mellan användar- och gruppobjekt stöds inte.
  • Namnen på fästpunktsattributen måste vara unika för användar- och gruppscheman.
• PowerShell
  • Det går inte att skicka indatavariabler till PowerShell-skript.