Conector CSV genérico – Guia de referência técnica (versão prévia)

Este artigo descreve o Conector CSV Genérico (GCSV). O artigo se aplica aos seguintes produtos:

• agente de provisionamento do Microsoft Entra Connect (ECMA2Host)
• Microsoft Identity Manager 2016 (MIM2016)

Para o MIM 2016, o Conector está disponível como um download do Centro de Download da Microsoft.

Para ver esse conector em ação, consulte o artigo Generic SQL Connector step-by-step .

Visão geral do conector CSV genérico

O Conector CSV Genérico (GCSV) permite integrar dados de identidade de usuário e grupo mantidos em arquivos CSV com produtos da Microsoft, como o ECMA2Host (Agente de Provisionamento do Microsoft Entra Connect) e o Microsoft Identity Manager 2016 (MIM2016).

Ele tem vários recursos, como a capacidade de orquestrar o uso do PowerShell para gerenciar dados de identidade antes ou depois de operações de importações ou exportações. Ele oferece suporte para vários tipos de dados, incluindo binários e referências, suporte para valores de cadeia de caracteres qualificadas e cadeias de caracteres com vários valores.

Este artigo descreve os recursos e as funções do Conector CSV Genérico e como configurá-lo para o MIM 2016.

A tabela a seguir lista os recursos aos quais a versão atual do conector dá suporte, de uma perspectiva de alto nível:

Recurso	Detalhes
Suporte a vários produtos	Há suporte para o uso desse conector com os seguintes produtos da Microsoft: agente de provisionamento do Microsoft Entra Connect (ECMA2Host) Microsoft Identity Manager 2016 (MIM2016)
Arquivos CSV com suporte	Esse conector dá suporte ao gerenciamento de usuários (obrigatórios) e grupos (opcional), por meio da configuração de até três arquivos CSV: Arquivo CSV de usuários (por exemplo, Users.csv) Arquivo CSV de grupos (por exemplo, Groups.csv) Arquivo CSV de Membros do Grupo (por exemplo, Members.csv)
Processamento pré/pós-operação com o PowerShell	Esse conector dá suporte à configuração de até quatro (4) Scripts do PowerShell para facilitar o processamento pré ou pós-processamento de dados de identidade de usuário e grupo antes ou depois de importações ou exportações.
Codificação de arquivo CSV com suporte	O conector dá suporte a todos os tipos de codificação de servidor padrão (ou instalados): (por exemplo, Unicode, UTF-8, UTF-7, ASCII etc.)
Tipos de dados de campo CSV com suporte	O conector dá suporte aos seguintes tipos de dados de atributo: Binário – (como cadeias de caracteres base64) Booliano – (como True/False) Inteiros Cadeias de caracteres/cadeias de caracteres com vários valores Referência
Delimitação de campo CSV	Suporte para vírgulas (,) ou qualquer caractere alfanumérico imprimível para qualificar o início e o fim de qualquer valor de cadeia de caracteres.
Suporte à qualificação de cadeia de caracteres	Suporte para aspas duplas (") ou qualquer caractere alfanumérico imprimível para qualificar o início e o fim de qualquer valor de cadeia de caracteres.
Suporte a cadeias de caracteres com vários valores	Suporte para cadeias de caracteres com vários valores
Operações de conector com suporte	O conector dá suporte às seguintes operações: Importação completa Exportação Exportação completa
Esquema	A descoberta de esquema é dinâmica, mas requer configuração manual para conclusão. Os campos são identificados dinamicamente com base em um delimitador especificado (ou conhecido como "Separador de Valor". Os tipos de dados de campo são designados manualmente durante a configuração.

Pré-requisitos

Antes de usar o conector, verifique se você tem o seguinte no servidor de sincronização:

• Microsoft .NET 4.6.2 Framework ou posterior
• Arquivos CSV que contêm o esquema desejado para os seguintes tipos de identidade:
  • Arquivo de Usuários (obrigatório)
  • Grupos (opcional)
  • Membros do grupo (obrigatório se os grupos forem usados)
• (Opcional) Scripts do PowerShell para gerenciar o pré e pós-processamento para os seguintes eventos de Tipos de Operação:
  • Pré-importação – esse script é executado antes da execução de uma operação de importação.
  • Pós-Importação – esse script é executado após a execução de uma operação de importação.
  • Pré-exportação – esse script é executado antes da execução de uma operação de exportação.
  • Pós-exportação – esse script é executado após a execução de uma operação de exportação.

Permissões da conta de serviço de sincronização do MIM

Criar um novo conector

A lista a seguir é uma visão geral de alto nível das etapas descritas neste guia. Para começar, uma conta com a função sincronizações do MIM Administração precisa ser usada para executar estas tarefas:

• Abra a janela Criar AGENTE de Gerenciamento (MA) na Service Manager de Sincronização do MIM.
• Selecione o Conector CSV Genérico como o tipo de conector.
• Forneça o caminho do arquivo e o nome do arquivo CSV a ser importado ou exportado.
• Especifique a codificação de arquivo, o separador de valor, o separador de vários valores e o qualificador de texto para o arquivo CSV.
• Escolha se deseja usar os valores na primeira linha como campos de cabeçalho ou não.
• Selecione os tipos de objeto e os atributos a serem importados ou exportados do arquivo CSV.
• Configure a partição, o perfil de execução e os detalhes de mapeamento para o MA.
• Forneça os caminhos e parâmetros de script para os scripts do PowerShell, se houver.
• Execute o MA para executar as operações de importação, sincronização ou exportação.

Para Criar um conector CSV genérico, em Serviço de Sincronização , selecione Agente de Gerenciamento e Criar. Selecione o Conector CSV Genérico (Microsoft).

Conectividade

A página Conectividade contém os locais de arquivo dos arquivos CSV Usuários, Grupos e Membros do Grupo.

A imagem a seguir é um exemplo da página Conectividade .

Os locais dos seguintes arquivos CSV são especificados nesta página:

• Arquivo de Usuários: o caminho totalmente qualificado do arquivo CSV que contém os registros do usuário e seus valores de atributo. Esse arquivo é necessário.
• Arquivo de Grupos: o caminho totalmente qualificado do arquivo CSV que contém os registros de grupo. Esse arquivo é opcional.
• Arquivo de Membros: o caminho totalmente qualificado do arquivo CSV que contém registros de referência de membro do grupo.

A tela Conectividade é a primeira quando você cria um novo conector SQL genérico. Primeiro, você precisa fornecer as seguintes informações de seção:

Funcionalidades

Esta página descreve os recursos do conector. As funcionalidades do conector são fixas e não podem ser alteradas, mas elas são explicadas aqui para fornecer informações sobre como o conector opera.

A imagem a seguir é um exemplo da página Funcionalidades .

A seção a seguir lista as configurações individuais e seus significados:

• LDAP (Distinguished Name Style): o conector GCSV usa a sintaxe LDAP (Lightweight Directory Access Protocol) para construir o DN (nome diferenciado) para identificar exclusivamente cada objeto User ou Group em seu espaço conector. Todos os valores de DN são expressos no seguinte formato: CN=[ANCHOR_VALUE],Object=[User|Group],O=CSV.
• Confirmação de Objeto (Normal): normalmente, o mecanismo de sincronização pressupõe que ele pode recuperar o objeto novamente em uma importação delta subsequente após uma exportação. É assim que o mecanismo de sincronização geralmente funciona, mas nem todos os sistemas conectados operam dessa maneira. Essa configuração de Normal garante que não haja nenhum exported-change-not-reimported aviso na importação de acompanhamento.
• Tipo de Exportação (MultivaluedReferenceAttributeUpdate): o tipo de exportação especifica como os objetos são formatados e enviados para o sistema de destino durante a sincronização. MultivaluedReferenceAttributeUpdate é um tipo de exportação projetado para funcionar com Microsoft Entra ID. Ele envia apenas os atributos que foram alterados. Para atributos de tipo de valor, ele usa AttributeReplace e, para atributos de referência, ele usa AttributeUpdate.
• Normalizações (Nenhum): normalizações referem-se à padronização de dados para um formato consistente. Nenhum significa que nenhuma regra de normalização específica é aplicada. Os dados permanecem no local em que se encontra sem nenhuma transformação adicional pelo conector.

Esquema 1 (configurações de formato de arquivo CSV)

O Conector GCSV utiliza três tipos de separadores (ou delimitadores) para delimitar e analisar campos CSV e seus valores.

Esta página contém as configurações de valor de caractere para esses separadores e o tipo de codificação que foi usado para criar o arquivo como CSV.

A imagem a seguir é uma imagem da página Esquema 1 (Configurações de Formato de Arquivo CSV).

A seção a seguir é uma lista das configurações individuais:

• Usar cabeçalhos para descoberta de esquema: quando essa opção é selecionada, ele instrui o conector a tratar o primeiro registro de cada arquivo CSV como um registro de cabeçalho e não um registro de dados de identidade. Se essa opção não estiver selecionada, o conector atribuirá o nome Atributo com um valor inteiro incrementado exclusivo acrescentado (por exemplo, Attribute1, Attribute2 etc.) e tratará a primeira linha de como um registro de dados de identidade.
• Separador de valores: esse caractere separa os campos (ou seja, valores) dos registros CSV. A vírgula (,) é o padrão, mas qualquer caractere alfanumérico que pode ser impresso é permitido.
• Separador de vários valores: esse tipo de separador é usado para delimitar os valores individuais de uma cadeia de caracteres de vários valores (por exemplo, endereços proxy) ou atributos de referência (por exemplo, subordinados).) O padrão é um ponto e vírgula (;) mas qualquer caractere alfanumérico imprimível é aceitável.
• Qualificador de texto: quando um valor de cadeia de caracteres contém caracteres que, de outra forma, seriam interpretados como delimitadores (por exemplo, como vírgulas), ele requer que o valor seja qualificado para que o analisador CSV possa interpretar corretamente a cadeia de caracteres como um único campo. As aspas duplas (") são o padrão, mas qualquer caractere alfanumérico que pode ser impresso é permitido.

• Codificação de arquivo: essa configuração indica a codificação usada nos arquivos CSV adicionados na guia Conectividade. Verifique se ele corresponde à codificação dos arquivos CSV.

Esquema 2 (configurações de campo de identidade e referência)

O valor de âncora é um identificador exclusivo para um registro em um arquivo CSV. Ele diferencia um registro dos outros. O Conector GCSV também usa esse valor para criar o DN (nome diferenciado) que identifica o objeto de espaço do conector relacionado.

Nesta página, as configurações de atributo de âncora são configuradas para cada um dos arquivos CSV listados na página Conectividade.

A imagem a seguir é um exemplo da página Esquema 2 (Configurações de Campo de Identidade e Referência).

A seção a seguir é uma lista das configurações individuais nesta página:

• Usuário
  • Âncora do Usuário: o campo no arquivo Usuários que serve como o valor de âncora para o registro do usuário. O primeiro campo de cabeçalho no arquivo Usuários é a opção padrão.
  • Tipo de atributo Âncora do Usuário: esse é o tipo de atributo da âncora selecionada.
• Grupo
  • Âncora de Grupo: o campo no arquivo Grupos que serve como o valor de âncora para o registro de grupo. O primeiro campo de cabeçalho no arquivo Grupos é a opção padrão.
  • Tipo de atributo âncora de grupo: esse é o tipo de atributo da âncora selecionada.
• Membro
  • ID do Grupo Pai: o campo no arquivo Membros que tem o mesmo valor (âncora) que o grupo pai no arquivo CSV grupos. O primeiro campo no arquivo Membros é usado por padrão.
  • ID do membro: o campo no arquivo Membros que tem o mesmo valor (âncora) que no arquivo CSV Usuários ou Grupos. O segundo campo no arquivo Membros é selecionado por padrão.
• Tipo de Objeto membro: o campo que contém um valor de cadeia de caracteres "Usuário" ou "Grupo" para indicar o tipo de objeto do membro. Esse campo só será necessário se o arquivo Membro contiver mais de dois campos. O campo Tipo de Objeto deve conter apenas o valor de cadeia de caracteres "Usuário" ou um "Grupo". Se esse campo estiver ausente, o conector pressupõe que os registros de arquivo Membros se referem a um membro do objeto User. O terceiro campo encontrado no arquivo Membros é selecionado por padrão.

Esquema 3 (Configurações de esquema de atributo de arquivo de usuários)

Esta página serve para especificar e explicar o tipo de dados de cada um dos campos identificados no esquema do arquivo CSV usuários e se eles podem ter mais de um valor.

A imagem a seguir é um exemplo da página Esquema 3 (Configurações de Esquema de Atributo de Arquivo de Usuários).

A seção a seguir lista as considerações ao fazer atribuições de tipo de dados de atributo.

Tipos de dados com suporte

O Conector GCSV dá suporte ao uso dos seguintes tipos de dados de seção:

• Booliano: um valor que pode ser verdadeiro ou falso.
• Binário: um valor armazenado como uma sequência de bytes, normalmente usado para armazenar dados, como imagens ou outros arquivos.
• Inteiro: um valor que é um número inteiro, sem casas decimais.
• Cadeia de caracteres: um valor que é uma sequência de caracteres, normalmente usado para armazenar dados de texto.
• Referência: um valor que é uma referência a outro objeto de usuário. Para especificar um valor de referência em um arquivo CSV, preencha seu campo com o valor de âncora do objeto de usuário referenciado.

Tipos de dados de Multiple-Value com suporte

O conector dá suporte ao uso de atributos de vários valores apenas para os seguintes tipos de dados:

• Cadeia de caracteres

Esquema 4 (configurações de esquema de atributo de arquivo de grupos)

Esta página serve para especificar e explicar o tipo de dados de cada um dos campos identificados no esquema do arquivo CSV grupos e se eles podem ter mais de um valor.

A imagem a seguir é um exemplo da página Esquema 4 (Configurações de Esquema de Atributo de Arquivo de Grupos).

As diretrizes oferecidas no Esquema 3 (Configurações de Atributo de Arquivo de Usuários também se aplicam a esta seção. .

Após a execução de uma operação de importação completa inicial, o espaço do conector será semelhante à imagem da seguinte imagem:

Parâmetros globais (configuração de scripts do PowerShell)

Esta página permite a configuração de scripts do PowerShell que serão executados antes e/ou depois das operações de importação e/ou exportação. Esses recursos oferecem oportunidades para executar uma ampla variedade de ações de pré e pós-processamento em seus registros de usuário e grupo de identidade.

A imagem a seguir é um exemplo da página Parâmetros Globais .

A seção a seguir lista as configurações individuais nesta página:

• Tempo limite do script (Minutos): o número de minutos que um script executará antes de ser anulado automaticamente. O valor padrão dessa configuração é 100 e requer um valor maior que zero (0).
• Arquivo de script de pré-importação: o caminho totalmente qualificado para o script do PowerShell que deve ser executado antes de uma importação. Essa configuração é opcional e não requer um valor.
• Arquivo de script pós-importação: o caminho totalmente qualificado para o script do PowerShell que deve ser executado após uma importação. Essa configuração é opcional e não requer um valor.
• Arquivo de script de pré-exportação: o caminho totalmente qualificado para o script do PowerShell que deve ser executado antes de uma exportação. Essa configuração é opcional e não requer um valor.
• Arquivo de script pós-exportação: o caminho totalmente qualificado para o script do PowerShell que deve ser executado após uma exportação. Essa configuração é opcional e não requer um valor.

Parâmetros de execução e entrada de script do PowerShell

O conector GCSV executa cada um dos scripts do PowerShell configurados em sua própria sessão e não dá suporte à passagem de parâmetros entre estágios.

O conector passa um parâmetro de entrada para cada script chamado OperationType. O valor desse parâmetro varia dependendo da operação Executar Perfil executada e pode ser um dos três valores:

Parâmetro de entrada do PowerShell: OperationType

Embora não haja suporte para o uso de parâmetros de entrada, o conector GCSV passa um parâmetro de entrada para a execução de cada script do PowerShell: OperationType.

• Completo – esse valor é fornecido durante operações de Importação Completa ou Exportação Completa.
• Delta – esse valor é fornecido durante operações de exportação.

Esse valor de parâmetro pode ser usado dentro da lógica dos scripts do PowerShell para determinar a operação ou a ação apropriada de pré/pós-processamento a ser tomada.  

Hierarquia de Provisionamento

Como os arquivos CSV não armazenam informações em uma estrutura hierárquica, o Conector GCSV não dá suporte a nenhuma configuração de provisionamento hierárquico.

A imagem a seguir é um exemplo da página Hierarquia de Provisionamento .

Partições e hierarquias

O Conector GCSV cria um DN (nome diferenciado) distinto para cada registro de usuário e grupo em seu espaço de conector, seguindo este formato LDAP:

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

A imagem a seguir é um exemplo da página Partições e Hierarquias .

Tipos de objeto

O Conector GCSV requer que pelo menos o tipo de objeto User seja selecionado. A escolha do tipo de objeto Group é opcional.

A imagem a seguir é um exemplo da página Tipos de Objeto .

Atributos

Esta página exibe uma lista normalizada de todos os atributos em todos os esquemas de tipo de objeto selecionados.

A imagem a seguir é um exemplo da página Atributos .

Âncoras

O Conector GCSV não dá suporte ao uso de âncoras complexas nem a configurações de atributo de âncora que diferem dos campos de ID de âncora do arquivo CSV correspondentes.

Para alterar as designações de âncora exibidas nesta página, retorne ao Esquema 2 (Configurações de Âncora).

A imagem a seguir é um exemplo da página Âncoras .

Provisionando registros CSV

Para que o conector GCSV adicione novos objetos User ou Group aos arquivos CSV correspondentes, um novo Objeto de Espaço do Conector deve ser provisionado para ele.

Seja usando o Provisionamento Declarativo do MIM 2016 ou gravando suas próprias Extensões de Regras de Sincronização do MIM, novos objetos do Espaço do Conector devem ter um DN construído usando o seguinte formato:

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

A tabela a seguir fornece detalhes sobre cada um dos valores de componente:

Componente	Observações
CN=[VALOR DE ÂNCORA]	O CN (Nome Comum) deve ser um valor exclusivo para e será gravado no campo de âncora designado do arquivo CSV.
Object=User/Group	Esse componente indica o tipo de objeto desse conector. Dá suporte apenas a "Usuário" ou "Grupo".
O=CSV	O componente raiz comum a todos os objetos de espaço do conector GCSV.

A imagem a seguir é uma Regra de Sincronização que demonstra como construir um DN corretamente ao provisionar um novo objeto User em um conector GCSV:

O código a seguir demonstra a lógica de provisionamento equivalente usando extensões de regras do Metaverso.

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 imagem anterior, observe o uso da EcapeDNComponent() função para garantir que o valor da âncora seja escapado corretamente para estar em conformidade com sua sintaxe LDAP.

Exemplos de formatação de campo CSV

As seções a seguir listam exemplos de como formatar diferentes tipos de dados em arquivos CSV. Todos os exemplos A seção a seguir pressupõe o uso das configurações de delimitador de campo padrão do conector:

• Valor separado: vírgula (,)
• Separador de vários valores: Semi-Colon (;)
• Qualificador de texto: aspas duplas (")

Exemplo: Qualificação de Texto

Se um valor de cadeia de caracteres contiver caracteres que, de outra forma, seriam interpretados como delimitadores (por exemplo, vírgulas), ele exigirá que o valor seja qualificado para que o analisador CSV possa interpretar corretamente a cadeia de caracteres como um único campo.

O exemplo CSV da seção a seguir mostra como o campo DisplayName tem valores formatados como texto qualificado:

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

Exemplo: Delimitando cadeias de caracteres multivalor

Para fornecer vários valores de cadeia de caracteres dentro de um campo de cadeia de caracteres, delimita os valores com o separador Multivalue. O exemplo CSV da seção a seguir mostra como o campo ProxyAddress com vários valores:

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

Exemplo: Campos de referência

Para especificar um valor de referência em um arquivo CSV, preencha seu campo com o valor de âncora do objeto de usuário referenciado. No exemplo CSV da seção a seguir, o campo Gerenciador contém o valor de âncora do registro de usuário ao qual se refere:

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

Exemplo: campos binários

Para expressar valores binários em arquivos CSV, eles devem ser convertidos em cadeias de caracteres base64 que usam o mesmo tipo de codificação que o arquivo CSV. A seguinte seção a função do PowerShell demonstra como codificar um valor de cadeia de caracteres em sua cadeia de caracteres codificada em base64 em Unicode:

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

Aqui está a função equivalente em C# que aceita um parâmetro de entrada chamado texto e retorna uma cadeia de caracteres codificada em base64 em Unicode.

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

Exemplo: Campos boolianos

Os Arquivos CSV que contêm campos boolianos devem usar o texto True ou False para indicar seu valor. A seção a seguir é uma

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

Limitações conhecidas

A lista a seguir contém as limitações conhecidas do conector GCSV.

• Atributo de referência
  • Além do atributo Membro do grupo, não há suporte para atributos de referência de vários valores.
  • O valor de referência deve se referir a objetos de usuário. Não há suporte para referências a objetos de grupo.
• Âncoras
  • Não há suporte para valores de âncora duplicados entre objetos de usuário e grupo.
  • Os nomes dos atributos de âncora devem ser exclusivos entre esquemas de usuário e grupo.
• PowerShell
  • Não há suporte para a passagem de variáveis de entrada para scripts do PowerShell.